[kixelated]

Partial progress on quest/m0/worktree-agents.md. This PR makes the guidance changes the quest had already settled, and records the user's 2026-10-26 decisions on the Claude and Codex lifecycle integration. The hooks themselves stay in the quest for a later PR.

Changes

• Guide (assets/AGENTS.md, Workspace):
  • Work in your own worktree, reusing a suitable one you already own. Read-only discovery needs no new checkout when context or an owned checkout answers it.
  • Expensive builds and test suites go through quest gate <command>. Agents never poll the load average and never cap agents by core count.
  • Run no more sub-agents at once than the harness allows; queue the rest. This is the harness limit from kixelated/quest#227, stated once in the guide so it covers both /quest-spawn and /quest-complete.
• Skills: /quest-spawn and /quest-complete drop their "limit active agents to the core count" rules (decision 5).
• Quests:
  • quest/m0/worktree-agents.md records each decision with its reason, and now lists only the remaining work:
    • the hook subcommand;
    • quest init and quest uninstall managing the hook entries;
    • the derived defaults;
    • Codex through quest agent;
    • the live exercise.
  • The two helpers quests that linked here no longer say this quest removes the load-average rules.
• m0 Plan (quest/m0/README.md): amends the 2026-09-26 "Nothing is vendored" bullet, dated 2026-10-26 (user), so that quest init can install the hook stubs (decision 2).

The guide's checkpoint guidance came from kixelated/quest#223's Workspace section, so this PR no longer adds its own. main was merged in three times, never rebased.

Evidence

This repository's main checkout held 65 Claude subagent worktrees under .claude/worktrees/ (8.2 GB) on 2026-10-23. On 2026-10-26, after manual cleanup, it still held 20 (6.5 GB). The oldest are from 2026-10-07. Finished workers are not reclaimed today.

Decisions (settled by the user, 2026-10-26)

1. How Claude integrates.
   • ✅ (a) A WorktreeCreate/WorktreeRemove hook pair backed by quest worktree create/remove. SubagentStop releases the stopped subagent's checkout, which covers both completion and a suspended decision, and SubagentStart restores it on resume.
   • (b) Keep Claude's native worktrees, and have a SubagentStop hook prune ignored build output in place.
   • (c) Prose only: the worker deletes its own scratch before its final report.
2. Where the hooks live.
   • ✅ The repository's .claude/settings.json, written by quest init.
   • User settings, with quest init printing the snippet.
   • This conflicted with m0's Plan, "Nothing is vendored… Upgrading never rewrites repository files" (2026-09-26). The user resolved it two ways:
     • ✅ Static hook stubs: quest init writes fixed hook entries that only call a quest subcommand (for example quest worktree hook <event>). All the logic stays in the binary, as with the skill stubs, so upgrades never rewrite them.
     • In the user's words, "we can have quest init install vendored stuff".
   • How I read it, for the user to correct: quest init may install static stubs into a repository, and upgrading still never rewrites repository files. The m0 bullet now reads that quest init installs only static stubs:
     • one-line skill stubs;
     • one reference line;
     • the one .gitattributes line it already writes for the merge driver;
     • Claude hook entries in .claude/settings.json that only call quest.
   • I did not read it as allowing vendored logic or files that need rewriting on upgrade.
3. Reservation, scratch, and capacity for hook-created checkouts.
   • ✅ Derived defaults:
     • Scratch is the main checkout's top-level ignored entries, excluding .worktrees/, .claude/worktrees/ and nested repositories.
     • Reserve is the main checkout's disk usage.
     • An unset capacity admits whatever the free-space check admits.
4. Codex.
   • ✅ quest agent runs the harness inside quest worktree run, which releases on exit and restores on resume. Codex app threads stay on Codex's native archive.
5. Agent-count caps.
   • ✅ (a) Drop the core count and keep only the harness limit, stated once in the guide (as this PR does). The 2026-10-15 quest decision stands over kixelated/quest#227's wording.
   • (b) Keep docs(guide): newest decision wins, never rebase, hand off PRs others push #227's spawn line and drop "or cap agents by core count" from the guide.

Choices made without asking

• I counted "command admission is integrated" as met once the shared guide sends expensive commands through quest gate. Nothing gates disk per checkout yet; that comes with decision 3's implementation.
• I edited assets/AGENTS.md and assets/skills/ under the quest's own plan. The user approved these edits by picking /quest-iterate.
• I resized the quest from [M] to [L]. What remains spans a hook subcommand, settings merging in init/uninstall, derived defaults, Codex wiring, and a live exercise of two harnesses.

Validation

On the pushed head, all of the following pass locally:

• just check
• just test (Vitest: 508 passed with 2 skipped, and 360 passed; plus the shell, lifecycle, and Worker suites)
• quest check --base origin/main (55 documents)

Suggested follow-ups

• /quest-spawn api headless agents are not harness sub-agents, so with the core-count cap gone nothing caps their count. Each one takes a checkout that nothing gates on disk until the derived defaults land.
• Consider splitting the quest's Codex quest agent integration into its own quest, since it is independent of the Claude hooks.
• Clean up the leftover .claude/worktrees/agent-* checkouts in this repository once their PRs merge.

🤖 Generated with Claude Code

(Written by Claude Opus 5.5)

[kixelated]

Design change: after merging main, this PR no longer adds checkpoint guidance, since the Workspace section from #223 already covers it. Its remaining guide lines (owned-checkout reuse, read-only discovery, quest gate) moved to Workspace. The harness sub-agent limit from #227 is now stated once in the guide for both /quest-spawn and /quest-complete, and the core-count cap is dropped. Whether to drop that cap is listed as decision 5 in the body.

(Written by Claude Opus 5.5)

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	🔄 Running since 2026-10-26T18:38:11.809442Z	a577b93	Manual request
🔒 Security Review	✅ Completed 2026-10-26T18:41:39.527517Z	a577b93	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[kixelated]

Automated review by review (OpenAI)

Reviewed commit: a577b931523798b19eddaa32eed6f6f315167b0d.

No actionable new findings in this seven-file documentation diff. Overall direction is sound: one shared harness-limit rule and the existing quest gate are simpler than duplicated per-skill CPU limits, while the quest explicitly retains the unimplemented lifecycle work. The uncapped /quest-spawn api checkout exposure is already acknowledged in the PR's follow-ups, not a new finding.

Verification: GitHub-only static inspection of the diff, surrounding guidance, and existing gate/worktree code; no local tests or live harness exercises run. Check was still in progress. Rechecked open/non-draft state, head, reviews and threads immediately before posting: no prior published findings to classify as fixed/open, and the independent Codex reviews were still running.

(written by review (OpenAI))

[kixelated]

@codex review

(Written by Claude Opus 5.5)

[chatgpt-codex-connector]

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: a577b93152

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[kixelated]

Landing a577b93 (squash).

Review: On 2026-10-26 the user approved landing a577b93 ("Land now, I approve"), counting their approval in place of Codex's code review, which had been stuck on "running" for nearly 4 hours. The approval covers only this head.

Checks:

• All 6 required checks pass on a577b93.
• The optional native Windows (windows-11-arm) job fails in test/gate.test.ts, as it does on main; kixelated/quest#233 fixes that.
• Codex's security review is clean.
• quest check --base origin/main --branch quest/m0/worktree-agents passes on the head against origin/main at 84b5255 (55 documents).

What lands:

• The guide's Workspace section sends expensive builds and test suites through quest gate, reuses an owned worktree, and caps sub-agents only by the harness limit.
• /quest-spawn and /quest-complete drop the core-count agent cap.
• quest/m0/worktree-agents.md records the user's 2026-10-26 lifecycle decisions and keeps only the remaining hook, init/uninstall, derived-default, Codex, and live-exercise work.
• The m0 Plan's "Nothing is vendored" bullet now lets quest init install static hook stubs.

Suggested follow-ups (for /quest-plan):

• Nothing caps headless /quest-spawn api agents now that the core-count cap is gone.
• Consider splitting the Codex quest agent integration into its own quest.
• Clean up leftover .claude/worktrees/agent-* checkouts once their PRs merge.

(Written by Claude Opus 5.5)