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:

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:

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.
Fix and re-review any Critical/Important finding.
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.
Run fresh integrated worker focused/full tests and typecheck; run backend focused tests using the generated-file workaround below.
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:

docs/superpowers/plans/2026-07-10-spoon-phase2-runtime-unification.md — 12 tasks.
docs/superpowers/plans/2026-07-10-spoon-phase3-dev-box-surface.md — 11 tasks.
docs/superpowers/plans/2026-07-10-spoon-phase4-sync-correctness.md — 12 tasks.
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:

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:

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:

Run a broad whole-branch review against the design spec and all five plans.
Fix all Critical/Important findings in one coordinated pass and re-review.
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.
Use the finishing-development-branch workflow; do not merge, push, or open a PR unless the user explicitly requests it.

9.3 KiB Raw Blame History