# Spoon implementation handoff for Claude

## Objective

Continue and complete every task in the five plans indexed by
`docs/superpowers/plans/2026-07-10-spoon-implementation-plan-index.md`.
The plans contain 63 tasks and must be executed in phase order. Use the
project `AGENTS.md`, test-first implementation, a task-scoped review after
each task, and a whole-branch review at the end.

## Canonical workspace

- Integration worktree: `/home/gib/.codex/worktrees/Spoon/spoon-stabilize-unify-build`
- Integration branch: `codex/spoon-stabilize-unify-build`
- Current integration HEAD before this handoff commit: `8af33fc`
- Original checkout: `/home/gib/Documents/Code/Spoon`, still on `main` at
  `8aa9140`. Do not implement in the original checkout.
- `main` was already two commits ahead of `origin/main` when work began.
  Preserve it and the original checkout's untracked `.agents/` directory.

## Current state

Phase 1 Tasks 1-5 and 7-13 are implemented, independently reviewed, fixed
where required, integrated, and verified with focused static/unit checks.
The durable scratch ledger is
`/home/gib/.codex/worktrees/Spoon/spoon-stabilize-unify-build/.superpowers/sdd/progress.md`.

Integrated Phase 1 commits, newest first:

```text
8af33fc fix(worker): always release stopped workspaces
00f96a1 fix(agent-jobs): close maintenance jobs after decision
1e1435e fix(agent-jobs): recover failed claim decryption
cf45404 fix(agent-jobs): validate claims before claiming
926008f fix(workspace): skip queries for missing jobs
2beeeb1 fix(app): handle nullable detail consumers
ed21126 fix(app): add friendly not-found handling
c4d0f52 fix(terminal): use real TTY exec and resize
906f906 fix(backend): use generated import extension
bdb2964 fix(sync): honor per-spoon auto-sync settings
57c175a fix(worker): contain workspace paths against symlinks
2bc090c chore: remove terminal task scratch report
d4a3856 fix(workspace): key shell by job
020ffbf fix(worker-auth): unify token checks and bind job environment
feb3723 fix(terminal): preserve animation-frame first fit
75d0639 fix(terminal): refit after fonts load
0b5a2c0 fix(worker): ensure reconciled boxes before acquire
284f7ea fix(worker): serialize box failure and idle reaping
490c053 chore: remove implementation scratch report
0a4461e fix(agent-jobs): prevent terminal status resurrection
9e7a872 fix(worker): make user-box lifecycle concurrency-safe
daec4d6 fix(worker): make workspace cleanup layout-aware
```

## Immediate next action: finish Phase 1 Task 6

Task 6 is complete on its isolated branch/worktree but has not had its final
post-fix review and has not been integrated.

- Worktree: `/home/gib/.codex/worktrees/Spoon/phase1-task6`
- Branch: `codex/phase1-task6`
- Commits to review and integrate:
  - `bdebacc fix(agent-jobs): add heartbeat cancel and stale recovery`
  - `233032a fix(worker): make cancellation teardown failure-safe`
- Report: `/tmp/spoon-phase1-task6-report.md`
- Requirements brief:
  `/home/gib/.codex/worktrees/Spoon/spoon-stabilize-unify-build/.superpowers/sdd/task-6-brief.md`

The first review found that Codex was not actually killed on cancellation and
that fallible event/status operations could bypass timer and ownership cleanup.
Commit `233032a` addresses those findings with:

- a job-specific in-box Codex process session;
- PID plus `/proc/<pid>/environ` marker validation before isolated TERM/KILL;
- serialized heartbeat cancellation so ticks cannot overlap;
- failure-safe explicit stop, draft-PR, cancellation, and claim-failure cleanup;
- worker regressions for Codex kill, duplicate ticks, and teardown rejection;
- expanded backend stale-recovery matrix tests.

Reported checks on that exact branch: worker format/lint/typecheck and 51/51
unit tests pass; backend 47/47 unit tests pass; stale-recovery matrix 8/8.
The timeout-not-requeue policy is explicitly documented as the plan's deliberate
deferral. Live Docker/Podman isolation remains untested.

Resume sequence:

1. Dispatch a fresh read-only reviewer for Task 6 over both commits and the
   updated report. Recheck the two prior findings, job-specific kill safety,
   timer serialization, all teardown paths, recovery thresholds/statuses, and
   tests.
2. Fix and re-review any Critical/Important finding.
3. Cherry-pick `bdebacc` and `233032a` into the integration worktree. Expect
   possible conflicts in `worker.ts` and `agentJobs.ts` because Task 7 was
   integrated afterward. Preserve Task 7's `finally`-based workspace release
   semantics while retaining Task 6's heartbeat cleanup.
4. Run fresh integrated worker focused/full tests and typecheck; run backend
   focused tests using the generated-file workaround below.
5. Append Task 6 to `.superpowers/sdd/progress.md`, mark Phase 1 complete, and
   perform a broad Phase 1 review before starting Phase 2.

## Remaining work

After Task 6, implement all tasks in these plans in order:

1. `docs/superpowers/plans/2026-07-10-spoon-phase2-runtime-unification.md`
   — 12 tasks.
2. `docs/superpowers/plans/2026-07-10-spoon-phase3-dev-box-surface.md`
   — 11 tasks.
3. `docs/superpowers/plans/2026-07-10-spoon-phase4-sync-correctness.md`
   — 12 tasks.
4. `docs/superpowers/plans/2026-07-10-spoon-phase5-notifications-polish.md`
   — 15 tasks.

The Phase 2 plan has been preflight-read and no conflict with the implemented
Phase 1 APIs was identified. Do not overwrite Phase 1 task briefs in
`.superpowers/sdd/` until Task 6 is fully reviewed and integrated; the
`task-brief` helper uses generic task numbers.

## Required execution/review workflow

- Use a fresh implementer per task and a fresh task-scoped reviewer after each
  task. Fix all Critical and Important findings, then re-review.
- Isolate concurrent tasks in separate worktrees/branches. Never let agents
  commit concurrently in the same worktree.
- Before cherry-picking an isolated commit, inspect `git show --stat` and ensure
  it contains only project files. Two earlier agents accidentally committed
  `.superpowers/sdd/task-*-report.md`; those scratch reports were removed by
  `490c053` and `2bc090c`. Put future reports under `/tmp`.
- After review approval, cherry-pick into the canonical integration worktree,
  run fresh controller-side focused checks, and update the scratch ledger.
- Preserve unrelated changes and never edit
  `packages/backend/convex/_generated/**` or `packages/backend/convex/http.ts`.
- Commits must use a simple `git commit -m "message"` with no AI attribution.
- Use conventional commit messages and minimal comments.
- Run `bun typecheck`, not a production build, for routine validation.

## Environment and validation limitations

The local server, local database, Docker-backed worker, and Convex deployment
are unavailable. Continue implementation and static/unit checks as requested;
record live/manual checks for later.

Root `bun install --frozen-lockfile` fails on the untouched baseline because
Bun 1.3.10 wants to rewrite the lockfile. The integration worktree currently
uses a root `node_modules` symlink to the original checkout. Do not commit any
dependency artifacts or lockfile rewrite merely to work around this.

Convex codegen cannot run without `CONVEX_SELF_HOSTED_URL` plus admin key or
`CONVEX_DEPLOYMENT`. For backend unit tests/typecheck that do not require newly
generated API declarations, temporarily link the ignored generated snapshot:

```bash
cd packages/backend
ln -s /home/gib/Documents/Code/Spoon/packages/backend/convex/_generated convex/_generated
bun run test:unit -- <focused-test>
bun run typecheck
rm convex/_generated
```

Never commit that symlink and do not claim fresh codegen succeeded. New API
typing may remain unavailable until deployment credentials return.

For Next component tests in a worktree, temporarily make the Vitest workspace
package resolve inside that worktree:

```bash
mkdir -p apps/next/node_modules/@spoon
ln -s ../../../../tools/vitest apps/next/node_modules/@spoon/vitest-config
cd apps/next
bun run test:component
cd ../..
rm apps/next/node_modules/@spoon/vitest-config
rm -r apps/next/node_modules/.vite apps/next/node_modules/.vite-temp 2>/dev/null || true
rmdir apps/next/node_modules/@spoon apps/next/node_modules 2>/dev/null || true
```

## Known deferred/manual checks

- Inspect a live `spoon-box-*` and confirm Docker `HostConfig.Init` is true.
- Verify real terminal resize, glyph rendering, and tmux reconnect in a browser.
- Verify Task 6 cancellation kills only the selected job's Codex process group
  under real Docker and Podman.
- Run each phase's plan-specific live/manual checks when the local stack returns.
- Task 9 has one non-blocking review note: worker-auth tests assert
  `ConvexError` type but not both exact error strings. Consider covering this
  during final review.
- The realpath containment design has the documented validation-to-I/O TOCTOU
  window; descriptor-relative elimination was outside the approved plan.

## Final completion requirements

After all 63 tasks:

1. Run a broad whole-branch review against the design spec and all five plans.
2. Fix all Critical/Important findings in one coordinated pass and re-review.
3. When the environment is available, run `bun typecheck`,
   `SKIP_E2E=1 bun run ci:check`, `bun test:e2e`, container smoke, and the
   documented live runtime/manual checks. Until then, report them as deferred,
   not passing.
4. Use the finishing-development-branch workflow; do not merge, push, or open a
   PR unless the user explicitly requests it.