[Spec 1134] afx whoami + ship /arch-init command (multi-architect identity)

[waleedkadous]

Summary

Adds afx whoami — a fail-loud identity diagnostic reporting the current terminal's agent (workspace, type, name) from Tower/global.db's perspective — and ships the /arch-init architect identity-adoption command with codev via the skeleton, replacing the fragile personal ps -p $PPID ancestry-matching command.

Closes#1134

Changes

• afx whoami (commands/whoami.ts + cli.ts registration): precedence builder-worktree cwd match (reuses detectCurrentBuilderId, incl. the afx send: detectCurrentBuilderId silently falls back to bare worktree name on state.db read failure → builder messages misroute to main #1094 no-fallthrough rule) → CODEV_ARCHITECT_NAME → exit 1 with explanation. Never implicitly main. --json support; builders carry architect: (spawning architect) when recorded; workspace display name from known_workspaces with basename fallback; best-effort architect-row cross-check warns on stderr only. Strictly read-only: lookupBuilderSpawningArchitect gains an optional db? handle (default getDb(), existing callers unaffected). Works without Tower.
• /arch-init skill byte-identical in codev-skeleton/.claude/skills/arch-init/ and .claude/skills/arch-init/: validated explicit [name] (architect-name rule, path-traversal guarded) or afx whoami resolution; STOP-and-ask when neither resolves; state recovery from codev/state/<name>.md excluding builder *_thread.md files; the four architect guardrails; workspace-agnostic.
• Docs: afx whoami sections in resources/commands/agent-farm.md and afx SKILL.md in BOTH trees (identical section content). Drive-by: three stale "state.db" wordings in send.ts now say "global.db" (post-Consolidate state.db tables into global.db (single user-global database) to eliminate the cwd-dependent fragmentation that causes "missing architect state after restart" #1118).

Testing

• 20 new whoami unit tests (spec scenarios 1–8, 10, 11 + JSON shapes, fixture pattern from bugfix-774)
• Skill-text assertion tests (cross-tree byte equality, required/forbidden content) + first-ever copySkills() regression tests (install path for scenario 9)
• Full unit suite green: 3470 passed / 48 pre-existing skips
• Manual smokes: afx whoami from this builder worktree → builder-spir-1134 + architect: main; from /tmp → exit 1 fail-loud; /arch-init skill confirmed loading in Claude Code
• CMAP: all three implement phases unanimously approved (Gemini/Codex/Claude)

Spec

Link: codev/specs/1134-afx-whoami-ship-arch-init-comm.md

Review

Link: codev/reviews/1134-afx-whoami-ship-arch-init-comm.md

[waleedkadous]

Architect Integration Review

Excellent work — this is a clean, well-composed change. Independent integration review (Claude): APPROVE / HIGH confidence, no key issues, on top of the unanimous CMAP at every phase.

Highlights from the integration pass:

• Backward compatibility verified: all 8 existing callers of lookupBuilderSpawningArchitect (2 production in tower-messages.ts, 6 in tests) use 1–2 args — the optional db? param is fully additive.
• Resource lifecycle correct: the read-only db handle closes on every return path; the BuilderIdResolutionError path never opens it at all.
• Fail-loud semantics preserved end-to-end: no fallthrough from a builder worktree to the env check (afx send: detectCurrentBuilderId silently falls back to bare worktree name on state.db read failure → builder messages misroute to main #1094 rule), no implicit main anywhere.
• The copySkills() regression tests are a gift beyond scope — first coverage for the whole skill-delivery pipeline, and the skill-text-assertion pattern (declarative artifact as the testable unit) is a reusable recipe.

Non-blocking notes for the record (both already scoped out deliberately, agreed):

• describeStateDbOpenFailure name still says StateDb — future cosmetic drive-by.
• whoami→send.ts command-to-command import — extract to a shared identity module when a third consumer appears.

[waleedkadous]

@amrmelsayed I've requested your review on this one as the final pass — would value your opinion, especially since afx whoami reads directly from the global.db layout your state-consolidation work (PR #1127) put in place. Areas where your eye would help most:

• The read-only access pattern into global.db (openReadonlyGlobalDb + the optional db? handle on lookupBuilderSpawningArchitect) — does this fit how you'd want readers to consume the consolidated db?
• The identity precedence (builder-worktree cwd → CODEV_ARCHITECT_NAME → fail loud) and whether any multi-workspace edge cases from the consolidation are missed.
• Anything else that stands out.

No rush — the merge waits on your review. Thanks!

[amrmelsayed]

Review

Approving. I verified this against today's main rather than the July 3 base, since the branch predates #1149, #1150, and the #855 monorepo restructure: the merge is clean, tsc --noEmit on the merged tree is clean (confirming the db? param is fully additive against all current callers), and all four test files pass on the merged tree (59 tests). Schema references (architect, known_workspaces, and the #1118 composite-PK builders) all match the current GLOBAL_SCHEMA.

On the two areas you flagged:

Read-only access into global.db: this fits how I'd want readers to consume the consolidated db. Identity never depends on the handle (only enrichment does), the connection closes on every path including the fall-through to the fail-loud throw, and crucially whoami never triggers getDb(), so a diagnostic command can never take a write lock or kick off a migration mid-crash-recovery. That's the right property for the environments whoami serves. One note for later: the db default param creates mixed ownership semantics (singleton must not be closed, passed handle is caller-owned). Documented and fine at two consumers; when a third read-only consumer appears, promote openReadonlyGlobalDb into db/index.ts rather than copying it, same "third consumer" rule this PR already applies to the identity helpers.

Identity precedence / multi-workspace edges: handled correctly. The builder enrichment passes workspaceRoot, so the composite-PK lookup disambiguates same-id builders across repos, and both whoami queries normalize through normalizeWorkspacePath, which is the same helper state.ts aliases as canonicalize, so readers and writers agree on the symlink-dereferenced form. Two behavioral edges worth having on the record, neither a change request:

• cwd beats env: an architect who cd's into a builder worktree and runs afx whoami is reported as the builder. That's the spec's precedence, /arch-init handles it safely (type: builder → STOP), and "never cd into a builder worktree" is already a guardrail.
• Env inheritance: with CODEV_ARCHITECT_NAME inherited into subshells, whoami from an unrelated git repo reports type: architect with that repo's basename as workspace. The rowMissing stderr warning covers this adequately.

One follow-up this PR surfaces (non-blocking, spec 1134 scoped state-file lifecycle out deliberately): /arch-init promotes architect state files (codev/state/<name>.md) from a private convention into a shipped concept, but codev currently takes no stance on their versioning: they're neither tracked nor gitignored today. Unlike builder threads (committed, land on main at merge), architect state files are inherently per-person: every team member working the same repo has their own main architect, so a committed main.md collides across members, and each /arch-init would resume from whoever pushed last. They should be gitignored while keeping builder threads tracked:

codev/state/*.md
!codev/state/*_thread.md

and that rule should be embedded across the codev CLI surface, not just documented: codev init and codev adopt scaffold it into the generated .gitignore, codev update backfills it for existing installs, and codev doctor warns when the rule is missing or an architect state file is already tracked. Will file a follow-up issue.

Also noting the copySkills() regression tests are first-ever coverage for the skill-delivery install path, and the cross-tree byte-equality test is the right enforcement for the skeleton/instance invariant.

Good to merge from my side.

[amrmelsayed]

Formal approval per my full review in #1136 (comment). Verified against current main (clean merge, clean typecheck, 59 tests passing on the merged tree). Good to merge.