feat(mobile): epic charter and Now-inbox ranking/snapshot schema seam (refs OpenCoven/psyche-build#208)

[CompleteDotTech]

Outcome

Epic charter + Now-inbox ranking/snapshot schema seam for Bead psyche-i7c (OpenCoven/psyche-build#208, "[psyche-i7c] Mobile multiproject and multipane cockpit", P1 epic, in_progress):

• docs/mobile/COCKPIT-EPIC-CHARTER.md — the epic charter: objective (universal iPhone/iPad cockpit opening into a cross-project Now inbox, adaptive one/two-pane terminal workspaces, complete pane lifecycle via the paired host), four architecture invariants (protocol-v3 typed control envelopes over the paired TLS/Bonjour bridge; one canonical multiproject workspace snapshot to the Swift WorkspaceStore; only one or two attached terminal streams; reuse existing host file/action/lifecycle logic), constraints (protocol-v2 compatibility, self-signed certificate pinning, published-workspace-resource scope, visibly stale offline state, iPhone + iPad validation), success-criteria mapping to the epic's phases, and canonical outcome Deliver the Psyche Build iOS internal beta and continuity loop #200.
• src/mobile/nowInboxRanking.ts (model v1) — pure, deterministic TS contract seam for the canonical workspace snapshot that the paired host publishes (mobile.workspace.snapshot.result → Swift WorkspaceStore): typed projection projectNowInboxEntries(), nowInboxBucketOf(), rankNowInbox() (Needs You → Running → Recent per the epic's acceptance criteria, recency then code-unit tie-breakers, bounded result with pre-truncation bucket counts), and validateWorkspaceSnapshot() (strict, fail-closed: unknown fields rejected, canonical enums/timestamps enforced, bounded sizes checked before enumeration).
• __tests__/nowInboxRanking.test.ts — 25 tests covering bucket assignment, ordering, determinism (including input-order permutation), result bounds/limit clamping/malformed-limit rejection, and validator accept/reject cases (including the canonical WORKSPACE_SNAPSHOT_FIXTURE).

Upstream PR/issue writes are token-denied for this pipeline's credentials (verified: push/PR-create/comment 403 on OpenCoven), so this PR runs on the fork CompleteDotTech/psyche-build with real CI. The branch is ready for a maintainer one-click PR to upstream.

Scope and boundaries

Additive only: three new files (docs/mobile/COCKPIT-EPIC-CHARTER.md, src/mobile/nowInboxRanking.ts, __tests__/nowInboxRanking.test.ts) plus this working record. No existing file modified — no runtime, protocol, security, or behavior change.

Not done (owned by their phase children): Now-inbox UI; pairing/Bonjour wiring (#216); terminal-stream attach/detach; pane lifecycle actions (#217, #218–#221); workspace cache (#210); stale/live reconciliation (#211); accessibility (#212); performance/acceptance matrix (#213); product/architecture docs (#214); final review/handoff (#215). Phase 10's plan and gate module live on the #209 branch (src/mobile/phase10Gate.ts, docs/mobile/PHASE-10-RECOVERY-PLAN.md) — no file collision with this slice.

Seam decisions: the module imports canonical snapshot types from src/workspace/snapshot.ts via import type (erased at runtime; the module is I/O-free) instead of duplicating the snapshot shape; NOW_INBOX_RUNNING_STATUSES mirrors the host's private isRunning() list with a provenance comment. The validator checks shape/types/bounds only — it does not police identity semantics (duplicates), which the canonical snapshot builder owns.

Risk class

• R1 — documentation or isolated tests (additive pure module + tests + charter; no consumer code changed)
• R2 — product behavior
• R3 — authority, security, protocol, persistence, recovery, or consequential actions
• R4 — release, governance, credentials, generated-source ownership, cross-repo identity

Validation and evidence

All commands run from the worktree on branch psyche/issue-208-mobile-cockpit-contract (base origin/main @ a4546f4; deliverable commit 17980247aaa753bb7df0c14e785fa2e66678336e; working record added in the follow-up commit):

• npx pnpm install --frozen-lockfile → Done in 470ms using pnpm v10.34.5 (exit 0)
• npx pnpm exec vitest --run __tests__/nowInboxRanking.test.ts → Tests 25 passed (25)
• npx pnpm exec vitest --run __tests__/nowInboxRanking.test.ts __tests__/bridge/mobileControlGateway.test.ts __tests__/bridge/mobileControlProtocol.test.ts → Test Files 3 passed (3), Tests 77 passed (77) (adjacent suites unaffected)
• npx pnpm exec tsc --noEmit → exit 0
• npx pnpm exec tsc -p tsconfig.test.json --noEmit → exit 0
• git diff --check → clean

Explicit gaps: no iOS/Swift/simulator evidence on this host (no Xcode tooling) — Swift-side equivalence of the snapshot contract is a design claim from the shared canonical shape, not runtime-verified here; no tmux/Rust/paired-host evidence (not applicable to this pure-TS slice); full scripts/agent-check gate not run on this host (requires tmux) — CI supplies Linux runner evidence; the ranking is not yet consumed by any UI or bridge code (wiring belongs to phase children). Per the epic's implementation notes, the full Vitest suite has three pre-existing unrelated environment failures (pnpm version drift, BSD-stat checks); not reproduced/fixed here.

Working record

docs/working-records/issue-208-mobile-cockpit-contract.md — outcome, scope/boundaries, risk class, exact commands + observed results, test counts, proof gaps, rollback notes.

Generated outputs

None. No generated artifact (src/utils/generated-agents-doc.ts, Tauri bundles, Xcode project, dist/**) was created or modified.

Security and privacy

• No credentials, tokens, private keys, certificate or signing material, raw prompts, unrestricted terminal output, private repository contents, environment dumps, private infrastructure URLs, or unredacted personal paths are introduced by this change.
• New validation code fails closed on unknown fields, wrong types, and oversized payloads; fixtures use synthetic, non-sensitive identifiers (/repo, %3, coven:review).

Review focus

1. rankNowInbox ordering contract (bucket → recency → project id → worktree path → pane id) matches the epic acceptance criterion "Now inbox ranks Needs You, Running, and Recent across projects" — including Needs-You-wins-over-Running and unknown-timestamps-last.
2. validateWorkspaceSnapshot strictness: unknown-field rejection (even when undefined, matching the canonical fixture encoding), canonical Z-form ISO timestamps, and bounds-before-enumeration behavior on hostile input.
3. Bound/limit choices (NOW_INBOX_ENTRY_LIMIT 256; projects 64; worktrees 64; panes/container 128; total panes 4096; string limits) — documented constants, easy to tune before any consumer lands.
4. Charter fidelity to the Beads source and the phase split ([psyche-i7c.10] Phase 10: recovery, persistence, accessibility, and acceptance #209/[psyche-i7c.9] Phase 9: full lifecycle merge, PR, stop, close, and cleanup #217 own their slices; phases 1–8 closed history).

Release and support impact

None: no shipped behavior, protocol, dependency, or support-matrix change. This is a contract/charter slice that phase children (#209/#217/#216 and children) will build on; availability claims stay with gh-200 and the support matrix.

Refs #208

[vercel]

@CompleteDotTech is attempting to deploy a commit to the 0xBuns Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
psyche-build-docs	Ready	Preview	Aug 30, 2026 3:02pm

[BunsDev]

Closing because this epic charter plus parallel TypeScript ranking model cannot complete #208 and duplicates current Swift product state. Keep the roadmap issue authoritative and deliver focused native slices.