fix(#13371): make character select post-onboarding only

[lalalune]

Summary

Fixes #13371 by separating two first-run completion signals that had been sharing one ref:

• completionCommittedRef remains the durable recovery signal seeded from eliza:first-run-complete.
• completionJustCommittedRef is a new in-memory one-shot handoff for the immediate post-onboarding character-select route.

Startup hydration now consumes only the one-shot ref for character-select, so a cold relaunch with persisted first-run completion lands on the normal default tab instead of replaying character select every launch.

Evidence

Added .github/issue-evidence/13371-character-select-once.md.

Commands run locally from /tmp/eliza-13371:

• bun run --cwd packages/ui test src/state/startup-phase-hydrate.character-select.test.ts src/state/first-run-completion-persist.test.tsx
  • 2 files passed, 9 tests passed.
• bunx @biomejs/biome check packages/ui/src/state/useFirstRunState.ts packages/ui/src/state/useFirstRunCallbacks.ts packages/ui/src/state/startup-phase-hydrate.ts packages/ui/src/state/AppContext.tsx packages/ui/src/state/first-run-completion-persist.test.tsx packages/ui/src/state/startup-phase-hydrate.character-select.test.ts --no-errors-on-unmatched
  • Passed.
• bun run --cwd packages/ui typecheck
  • Passed.
• git diff --check
  • Passed.

Audit / device evidence gap

• Real iOS simulator relaunch walkthrough/video was not captured in this local pass.
• bun run --cwd packages/app audit:app was attempted but failed before screenshots because the local Node executable is too old:
  • /opt/homebrew/bin/node is v23.3.0
  • /usr/local/bin/node is v18.13.0
  • app-core requires Node.js 24+ and reported Invalid ELIZA_NODE_PATH=/opt/homebrew/bin/node: Node.js 23.3.0 is too old.

This PR should not be merged as fully evidenced until app audit and/or simulator relaunch evidence is captured on a Node 24-capable runner.

[greptile-apps]

Your trial has ended. Reactivate Greptile to resume code reviews.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bd876401-6e9b-405a-bdd8-b795077e9160

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/13371-ios-character-select-once

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[lalalune]

Code review on current head: the implementation direction matches #13371. completionCommittedRef remains the durable persisted-completion signal, while the new completionJustCommittedRef is consumed as a one-shot post-onboarding route handoff. The hydration tests cover both the cold-relaunch case and the immediate character-select handoff.

Local validation:

• bunx @biomejs/biome check packages/ui/src/state/useFirstRunState.ts packages/ui/src/state/useFirstRunCallbacks.ts packages/ui/src/state/startup-phase-hydrate.ts packages/ui/src/state/AppContext.tsx packages/ui/src/state/first-run-completion-persist.test.tsx packages/ui/src/state/startup-phase-hydrate.character-select.test.ts --no-errors-on-unmatched -> passed.
• git diff --check origin/develop...HEAD && git diff --check -> clean.

Sparse-worktree limit:

• bun run --cwd packages/ui test src/state/startup-phase-hydrate.character-select.test.ts src/state/first-run-completion-persist.test.tsx could not start because this sparse checkout lacks react/package.json for the UI Vitest config.

I am leaving auto-merge off. The PR body is correct that this UI behavior still needs packages/app audit:app and/or a simulator relaunch walkthrough on a Node 24-capable runner before merge.

[lalalune]

Additional local validation on current head 536c84b74f86938a981b2c654faad2fc0d8d122a after merging onto current develop.

Results:

• bunx @biomejs/biome check packages/ui/src/state/useFirstRunState.ts packages/ui/src/state/useFirstRunCallbacks.ts packages/ui/src/state/startup-phase-hydrate.ts packages/ui/src/state/AppContext.tsx packages/ui/src/state/first-run-completion-persist.test.tsx packages/ui/src/state/startup-phase-hydrate.character-select.test.ts --no-errors-on-unmatched - clean
• git diff --check - clean
• After temporarily adding plugins/plugin-native-bun-runtime to this sparse checkout, bun run --cwd packages/ui test src/state/startup-phase-hydrate.character-select.test.ts passed: 1 file / 2 tests.

Local blockers / gaps:

• The combined test command still fails here because src/state/first-run-completion-persist.test.tsx hits the duplicate-React invalid-hook-call path (useFirstRunState imports React from dist/node_modules/react, while the renderer path is under node_modules/.bun/react-dom). The non-hook tests in that file pass, but the two renderHook(() => useFirstRunState()) cases fail before their assertions.
• bun run --cwd packages/ui typecheck is still blocked by unrelated existing drizzle-orm declaration / implicit-any errors in packages/cloud/shared and plugins/plugin-sql.
• I did not run packages/app audit:app or an iOS relaunch walkthrough, so the PR still needs the app/simulator evidence noted in the PR body before it is fully merge-ready.

[lalalune]

Disabled auto-merge again. The code-level fix and focused startup-phase test are good, but the merge-quality evidence gap remains: no packages/app audit:app artifacts and no simulator/device relaunch walkthrough proving a cold relaunch no longer lands on Character Select. This is user-visible app startup behavior, so it should stay out of auto-merge until that evidence is attached or explicitly marked N/A with a concrete reason.

[lalalune]

Local review for head 536c84b74f86938a981b2c654faad2fc0d8d122a:

• Read packages/ui/CLAUDE.md and packages/app/CLAUDE.md.
• Inspected the state handoff change. The split between durable completionCommittedRef and one-shot completionJustCommittedRef matches the bug: persisted completion no longer replays character-select, while immediate post-onboarding completion is consumed once.
• bunx @biomejs/biome check packages/ui/src/state/useFirstRunState.ts packages/ui/src/state/useFirstRunCallbacks.ts packages/ui/src/state/startup-phase-hydrate.ts packages/ui/src/state/AppContext.tsx packages/ui/src/state/first-run-completion-persist.test.tsx packages/ui/src/state/startup-phase-hydrate.character-select.test.ts --no-errors-on-unmatched passed.
• git diff --check origin/develop...HEAD && git diff --check passed.

Local blockers/caveats:

• Initial focused test run needed generated i18n data; after node packages/shared/scripts/generate-keywords.mjs --target ts, bun run --cwd packages/ui test src/state/startup-phase-hydrate.character-select.test.ts src/state/first-run-completion-persist.test.tsx ran but failed the hook test locally due duplicate React resolution. The stack shows useReducer coming from /home/shaw/milady/eliza/dist/node_modules/react/cjs/react.development.js while React DOM comes from the Bun-installed React, which matches the known local dist/node_modules pollution in this checkout. The pure startup-phase-hydrate.character-select.test.ts passed; the first-run-completion-persist.test.tsx hook assertions did not execute cleanly here.
• bun run --cwd packages/ui typecheck is blocked by the same broad local declaration-resolution noise from /home/shaw/milady/eliza/dist/node_modules (drizzle-orm, pg, etc.).
• Required bun run --cwd packages/app audit:app was attempted. It built plugin views and then failed before screenshots/manual review during @elizaos/core#build declaration generation with the same local dist/node_modules resolution class (drizzle-orm, yaml, fs-extra, mammoth, markdown-it, file-type, dotenv, @noble/*).

I did not find an implementation issue in the handoff logic, but this local environment did not provide clean focused hook-test or audit proof.

[lalalune]

Maintainer review note: this branch must be rebased before merge or further verification.

After refreshing origin/develop to a068344d0c1, git diff origin/develop..origin/pr/13396 is polluted with unrelated deletions from current develop, including .github/issue-evidence/* artifacts, workflow files, benchmark/cloud/shared/script changes, and other UI work. The actual intended first-run state diff is small, but the branch as currently shaped would remove unrelated current-tree content.

I attempted to disable auto-merge because the PR body itself says it is missing app audit / iOS simulator relaunch evidence, but GitHub returned: Can not disable auto-merge for this pull request. Branch protection should still block while mergeability is unknown/stale.

Please rebase onto current origin/develop, keep only the character-select-once changes plus evidence, and capture the missing simulator/app-audit evidence before merge. I did not run the focused tests because the branch shape is currently unsafe.

[lalalune]

Post-merge iOS cold-relaunch evidence for #13405 is now in #13513. It includes the simulator recording, before/after screenshots, build/simulator metadata, host/native logs, and structured relaunch proof showing home/chat after cold relaunch instead of Character Select.

[github-actions]

❌ PR title does not match the required pattern. Please use one of these formats:

• 'type: description' (e.g., 'feat: add new feature')
• 'type(scope): description' (e.g., 'chore(core): update dependencies')
  Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert, release