claude-code-session-manager 0.98.0 → 0.101.0

package/plugins/session-manager-dev/skills/develop/standards.md

@@ -10,10 +10,6 @@
 
 - State the time and space complexity of any non-trivial algorithm in a comment.
 - Flag any nested loop over user-scaled data as a complexity hazard.
-- Prefer O(n) solutions over O(n log n) only when n is provably small or constant.
-- Lay out hot data contiguously and traverse it in memory order.
-- Prefer arrays of structs or structs of arrays based on actual access patterns.
-- Avoid pointer-chasing in inner loops on large datasets.
 
 ## Debugging approach
 
@@ -70,22 +66,21 @@ a higher-priority source exists:
 
 ## Execution discipline (headless runs)
 
-Data-driven from 400+ scheduler runs: long hangs (not bad code) are the dominant real failure, and "exited clean but left a red test" is the top verifier downgrade. These rules run at execution time — they are inlined into every PRD because the headless executor reads nothing else.
+Data from 400+ scheduler runs: long hangs, not bad code, cause most failures, and "exited clean but left a red test" is the top verifier downgrade. The PRD body carries a one-line pointer to this file, never a copy. The dev-lead persona and the scheduler's finish protocol carry the per-run rules; this file gives the reasons behind them. Run order: orient → red → build → finish protocol (review → verify the `# Gate` commands → commit exact paths → verdict line).
 
-- **Bound every command.** Wrap every test/build/dev-server/deploy/poll command in a hard timeout: `timeout 300 <typecheck|unit>`, `timeout 120 <one e2e spec>`, `curl --max-time 15`. Never run a bare `playwright test`/`vite`/`pnpm dev`, a full e2e suite, or an endpoint-polling publish — those are the SIGTERM/4h-watchdog tail.
-- **Verify before done.** Run the acceptance test command once before declaring success. If it's red, fix it or `exit 1` with the failure — never end the run on a failing test (that trips the verifier's `transcript_errors` downgrade).
-- **Fail loud, fail fast.** On any step failure, print one diagnostic line and `exit 1`; don't swallow with `|| true` or spin in a silent retry. A `rateLimited` exit-1 is the scheduler's benign auto-pause (auto-resumes next window) — not a failure to engineer around.
-- **Stay in the AC.** Do not add work past the acceptance checklist ("while we're here" generators/fixtures are the post-AC-overrun incident). Body must be clean UTF-8 — no NUL/control bytes.
-- **You ARE the executor — never re-queue or self-schedule.** A headless PRD run must perform its own acceptance criteria directly. Do NOT invoke `/develop` or any queue-authoring skill from inside a run — those are interactive main-loop skills that author a *new* PRD and return, so the run exits 0 having done nothing (no commit, no sentinel → `needs_review` with `no_verdict_sentinel`). Do NOT call `ScheduleWakeup`/set a tracking loop either — the process exits when the run ends and nothing re-invokes it. This applies just as much to spawning your own review agents and waiting on them: do NOT invoke `/code-review`, `/security-review`, `requesting-code-review`, or any other skill/subagent as a background/async step and then end your turn with something like "I'll wait for the review agents to complete" — a headless run has no next turn, so that line is the run's last output, no verdict sentinel prints, and the job parks in `needs_review` even though the actual work already landed. If a PRD's acceptance criteria call for a second review pass, run it **synchronously, inline, before the finish protocol** — call the reviewer and read its result in the same turn, don't fire-and-wait. If the PRD's work looks large, decompose and execute it inline within this run; never delegate it back to the queue. (Incidents: PRD 460 invoked `/develop`, spawned a duplicate PRD 461, and exited 0 with no work. PRD 479 landed its commit correctly but then backgrounded `/code-review --fix` + `/security-review` and called `ScheduleWakeup` to "wait" for them — same class of failure, different entry point.)
-- **Never `git stash`, `git reset`, `git checkout -- <path>`, or `git clean` against working-tree state you did not create — there is no polite version of this.** You are normally already isolated in your own `git worktree` on branch `sm-job/<slug>` (`src/main/lib/gitWorktree.cjs` — dirty base trees no longer disable this isolation, and the scheduler salvages any uncommitted diff on teardown, so you don't need to touch shared state to preserve your own work). Confirm you're isolated with `git rev-parse --git-common-dir` (a worktree's common-dir differs from its own `.git`) or by checking your cwd, before assuming otherwise. If you find yourself in a SHARED tree with pre-existing dirty tracked files anyway, work *around* them — scope `git add`/commits to only the paths you touched — or stop and report the conflict; never discard, stash, or revert someone else's uncommitted changes to get a clean checkout. A shared tree may be feeding a **running service** reading its config straight from the working tree (the trading repo's `data/spread_config.json` is live input, not a local scratch file) — reverting it is a production change, not a local inconvenience, and read-only inspection (`git diff`, `git status`) is always fine. The scheduler also runs a shared-tree stash guard as a backstop (`scheduler.cjs` `checkSharedTreeGuard`/`evaluateSharedTreeGuard`) that auto-restores a stash your run created and flags any baseline-dirty path that went clean with no commit — but that guard exists to catch a mistake, not to license one. (Incidents: PRD 477 stashed a concurrent job's rAF-throttle-revert WIP to get its own checkout and exited without restoring it, orphaning it in `stash@{0}` with no record of whose it was. 2026-09-01: a headless executor in the trader repo ran a blanket `git stash` against an operator's uncommitted LIVE TRADING CONFIG edit and exited without restoring it — `stash@{0}` "WIP on fix/trade-log-reconciliation-out-of-band-closes", `data/spread_config.json` — the third incident of this class.)
-- **`gh pr edit --body` can fail on repos with legacy GitHub Projects (classic) boards** — the underlying GraphQL query fetches `repository.pullRequest.projectCards`, a field GitHub is sunsetting, and errors with `GraphQL: Projects (classic) is being deprecated ... (repository.pullRequest.projectCards)` even though the edit itself would otherwise succeed. This is a known `gh` CLI quirk, not a defect in your work. Prefer `gh api -X PATCH repos/<owner>/<repo>/pulls/<n> -f body="$(cat body.md)"` for updating a PR description headlessly — it doesn't touch the deprecated field. If you do use `gh pr edit` and it fails this way, don't leave the bare GraphQL error as the last thing in that step (it reads as an unrecovered error in the final-20%-of-transcript verifier heuristic): immediately retry with the `gh api` form and print one line noting the known-bug fallback, so the recovery is adjacent to the error.
-- **`gh pr checks`/`gh run watch` exit non-zero while CI is merely *pending*, not failed — don't let that surface as a bare error.** Polling `gh pr checks <n>` before checks finish returns a non-zero exit (e.g. 8) with output like `check  pending  0  <url>` — this is normal, documented `gh` CLI behavior, not a failure. If you retry with a *differently-worded* command (e.g. dropping a `sleep N &&` prefix, or switching to `gh run watch <id> --exit-status`), the verifier's self-recovery detector pairs retries by exact command-description match and may not recognize the differently-worded retry as the same recovery, leaving the original pending-state error looking unrecovered in the transcript (incident: `745-pr188-ci-lint-docs-integrity`, a fully green, committed, pushed run flagged `needs_review` over exactly this). Prefer polling with the *same* command/description each time (e.g. loop `gh pr checks <n>` unchanged, or use `gh run watch <id> --exit-status` from the start rather than switching mid-poll) so a later success is recognized as recovering the earlier pending-state failure.
-- **Negative-assertion checks must exit 0 when clean.** A check that verifies the *absence* of something (a `grep` that should find nothing, "no leftover X", `diff` expecting no change) must return exit 0 on the clean case. A bare `grep` exits **1 on no-match** — so the *success* path surfaces as `is_error=true` and the verifier downgrades a perfect run to `needs_review`. Always invert: `if <detector>; then echo "HALT: <what was found>"; exit 1; fi; echo clean`. Never let the no-match/empty path carry the non-zero exit.
-- **Recover or annotate every error — don't strand a Traceback in the transcript.** The verifier downgrades an otherwise-perfect run to `needs_review` when a `Traceback`/`Error` appears with *no visible recovery within ~10 lines* (the `transcript_errors` heuristic — the single most common false-positive on green deliverables). Two executor habits cause it: (1) **throwaway probes that error** — an inline `python -c` with a quoting/f-string slip, a wrong kwarg, a bad path. When a probe errors, immediately re-run the corrected version *or* print one line `# expected/handled: <why>` right after, so recovery is adjacent. Don't move on leaving a bare error as the last thing in that step. Prefer a small temp `.py` file over a fragile multi-quote `python -c` one-liner (inline f-string errors are the top source of stranded tracebacks). (2) See the timeout rule below.
-- **An *expected* bounded-timeout (exit 124) must be annotated, not bare.** `timeout`-capping a genuinely long task you expect to hit the cap (a full-universe ingest, a long scan) is correct — but a bare `Exit code 124` reads as a failure to the verifier. Wrap it so the cap is a success-with-note: `timeout 120 <cmd> || { rc=$?; [ $rc -eq 124 ] && echo "hit time cap — idempotent/partial, rows persist incrementally; OK" || { echo "HALT: <cmd> failed rc=$rc"; exit 1; }; }`. (Distinguish 124 = expected cap from a real non-zero.) For work that legitimately needs longer than a safe cap, run it in the background and poll a bounded number of times rather than capping the foreground command.
-- **Polling remote CI/job status: never `sleep N && <cmd>`, and annotate the pending exit code.** The harness hard-blocks a `sleep` chained to another command (`Blocked: sleep 90 followed by: gh pr checks ...`) and that block lands in the transcript as a bare `is_error=true` — usually in the last 20% of the run, right where the verifier weighs errors most. To wait for a remote run, use the tool's own blocking watcher under a hard cap: `timeout 600 gh run watch <run-id> --repo <owner>/<repo> --exit-status`. Also note `gh pr checks` is a **negative-assertion-shaped command**: it exits `8` while checks are pending and `1` when a check failed or none are reported — so the ordinary "still running" path is non-zero. Wrap it so the expected cases print a clean token rather than a bare error: `if out=$(timeout 60 gh pr checks <n> --repo <r> 2>&1); then echo "CI GREEN"; else rc=$?; echo "gh pr checks rc=$rc (8=pending, 1=fail/none) — expected/handled"; fi`. (Incident: PRD 745 fixed PR #188's Lint + Docs-integrity failures, pushed, and CI went fully green — but its `sleep 20 && gh pr checks` (exit 8) and `sleep 90 && gh pr checks` (harness-blocked) sat unannotated at the very end of the transcript and the run was flagged despite a truthful PASS and a landed commit.)
-- **Finish so the verifier auto-clears you.** The scheduler appends a finish protocol that requires you to COMMIT your work and emit `SCHEDULER_VERDICT: PASS` (or `FAIL <reason>` + `exit 1`) as the literal last line. Honor it exactly: a *truthful* PASS plus a commit that landed during the run is what lets the verifier override incidental transcript noise (a grep hit containing "Error", a TDD red-phase run, a debug Traceback) instead of parking the job in `needs_review` for a human. A job that exits 0 with **uncommitted** changes, or with no PASS sentinel, is the #1 cause of needless `needs_review`. Never print PASS on a red gate — a lying PASS turns the verifier into a silent-failure shipper.
-- **Don't leak expected-error text into tool output.** The verifier pattern-matches transcript content for `Traceback`/`FAIL`/`Error:`. When a step is *expected* to error (a TDD red-phase test, an availability/existence probe, a "should raise" assertion), don't let the raw exception land verbatim — capture it and surface a clean token instead: `if python -c '…' 2>/dev/null; then echo PROBE_OK; else echo PROBE_ABSENT; fi`, or pipe the noisy run through a matcher that prints only `RED (expected)` / `GREEN`. When you retry a transient failure, re-run the **same command with the same description** — the verifier's self-recovery detector pairs a failed call with a later identical-description call that succeeds and clears it.
-- **End green: run the acceptance/test gate LAST, and let nothing error after it.** The post-run verifier scans the transcript and downgrades to `needs_review` on error markers — and weighs the *final* portion of the run most heavily (a tool error in the last ~20% trips it even if everything actually passed). So order the run so the last command is the green AC gate: do any intentionally-failing step (e.g. a TDD red test, an expected-nonzero probe) **early**, never after the gate. If you must demonstrate a failure late, capture it so it doesn't surface as a raw `is_error`/`Traceback` (`… 2>&1 | tail` inside a conditional, or assert on the captured text) rather than letting it hit the transcript bare.
-- **The verdict sentinel is your authoritative "I passed" signal — emit it truthfully.** The scheduler appends a FINISH PROTOCOL that ends by printing `SCHEDULER_VERDICT: PASS` once the AC gate is green and the commit has landed (or `SCHEDULER_VERDICT: FAIL <reason>` + `exit 1` otherwise). The verifier treats `PASS` + a commit that landed during the run as **authoritative** and overrides incidental transcript markers — so a *deliberately reproduced* red test (systematic-debugging) or a grep result containing the word "Error" will **not** false-trip `needs_review`, as long as the run genuinely ends green and committed. Never print `PASS` when the gate is red — that's the one thing that turns a safety net into a silent-failure machine.
-- **If your own AC gate failed on a SIBLING job's in-flight file — not your own change — say so with the right verdict, not a lying FAIL.** When you are running in a shared or WIP-carrying tree (the prompt discloses this in a `--- FOREIGN WORKING-TREE STATE ---` section, if present) and your gate failure is confined to paths that section already told you are not your work, print `SCHEDULER_VERDICT: BLOCKED_BY_FOREIGN_WIP` (and `exit 1`) instead of `FAIL`, followed by a `FOREIGN_WIP_PATHS: <path1>, <path2>, ...` line naming exactly the failing paths. The scheduler independently validates every listed path against the exact manifest it disclosed to you — list a path you were never told is foreign, or claim this verdict for a regression you actually introduced, and the whole verdict is downgraded straight back to `FAIL`, rejected. This is not an escape hatch: it exists so a correctly-diagnosed "not my regression" outcome gets auto-requeued once the sibling clears its WIP, instead of triggering a fix-plan investigation into someone else's unfinished work.
+- **Bound every command.** Wrap every test, build, dev-server, deploy, or poll command in a hard timeout, e.g. `timeout 300 <typecheck|unit>` or `curl --max-time 15`. Why: a bare `playwright test`, `vite`, `pnpm dev`, full e2e suite, or endpoint-polling publish hangs until the 4-hour watchdog kills it with SIGTERM.
+- **Verify before done.** Run the acceptance test once before declaring success. Why: ending the run on a failing test trips the verifier's `transcript_errors` downgrade — fix it or `exit 1` with the failure instead.
+- **Fail loud, fail fast.** On any step failure, print one diagnostic line and `exit 1`. Do not swallow it with `|| true` or retry silently. Exception: a `rateLimited` exit-1 is the scheduler's own benign auto-pause — it resumes next window on its own, so do not engineer around it.
+- **Stay in the AC.** Do not add work past the acceptance checklist — "while we're here" extras are how runs overrun. Keep the body clean UTF-8, with no NUL or control bytes.
+- **You ARE the executor — never re-queue or self-schedule.** Do the acceptance criteria yourself. Why: `/develop` or any queue-authoring skill just writes a *new* PRD and returns — the run exits 0 having done nothing, with no commit and no verdict line (`needs_review` with `no_verdict_sentinel`). The same applies to calling `ScheduleWakeup`, or backgrounding a review agent (`/code-review`, `/security-review`, `requesting-code-review`) and ending your turn with something like "I'll wait for the review agents to complete": a headless run has no next turn, so nothing ever resumes it — no verdict line prints, and the job parks in `needs_review` even though the work already landed. Run a required second review pass synchronously, inline, before the finish protocol — call the reviewer and read its result in the same turn. If the work is too big for one run, do not queue more work; see the timeout rule below. (Incidents: PRD 460 invoked `/develop` and exited 0 with no work. PRD 479 landed its commit, then backgrounded `/code-review --fix` + `/security-review` and called `ScheduleWakeup` to "wait" — same failure, different entry point.)
+- **Never `git stash`, `git reset`, `git checkout -- <path>`, or `git clean` against working-tree state you did not create.** There is no polite version of this. You are normally isolated in your own `git worktree` on branch `sm-job/<slug>` (`src/main/lib/gitWorktree.cjs`), and the scheduler salvages any uncommitted diff of yours on teardown — so you never need to touch shared state to protect your own work. Confirm isolation with `git rev-parse --git-common-dir` (a worktree's common-dir differs from its own `.git`) or by checking your cwd; `git diff`/`git status` are always safe. If you land in a SHARED tree with pre-existing dirty tracked files anyway, work around them — scope `git add`/commits to only the paths you touched — or end with `SCHEDULER_VERDICT: FAIL <reason>` (`SCHEDULER_VERDICT: BLOCKED_BY_FOREIGN_WIP` only when your gate failed on those files, as the finish protocol says); never discard, stash, or revert someone else's uncommitted changes to get a clean checkout. A shared tree may be feeding a running service that reads its config straight from the working tree, so reverting it is a production change, not a local inconvenience. The scheduler runs a shared-tree stash guard as a backstop (`scheduler.cjs`'s `checkSharedTreeGuard`/`evaluateSharedTreeGuard`), but that guard exists to catch a mistake, not to license one. (Incidents: PRD 477 stashed a sibling job's WIP to get its own checkout and never restored it. 2026-09-01: a headless executor in the trader repo ran a blanket `git stash` against an operator's uncommitted live trading-config edit and exited without restoring it — the third incident of this class.)
+- **`gh pr edit --body` can fail on repos with legacy GitHub Projects (classic) boards.** It queries the deprecated `repository.pullRequest.projectCards` field and errors with a `GraphQL: Projects (classic) is being deprecated` message even though the edit itself would otherwise succeed — a known `gh` CLI quirk, not a defect in your work. Prefer `gh api -X PATCH repos/<owner>/<repo>/pulls/<n> -f body="$(cat body.md)"` instead; it skips that field. If `gh pr edit` fails this way anyway, retry immediately with the `gh api` form and print one line noting the fallback — don't leave the bare GraphQL error as the step's last output, or the verifier reads it as unrecovered.
+- **`gh pr checks`/`gh run watch` exit non-zero while CI is merely *pending*, not failed — don't let that read as a bare error.** `gh pr checks <n>` returns a non-zero exit (e.g. 8) with output like `check  pending  0  <url>` before checks finish — normal, documented `gh` CLI behavior, not a failure. Poll with the exact same command and description every time; the verifier's self-recovery detector pairs a failure with a later success only when the wording matches, so switching wording mid-poll (e.g. dropping a `sleep N &&` prefix) can leave the earlier pending-state error looking unrecovered. (Incident: `745-pr188-ci-lint-docs-integrity` — a fully green, committed, pushed run was flagged `needs_review` over exactly this.)
+- **Negative-assertion checks must exit 0 when clean.** A check for the *absence* of something (a `grep` that should find nothing, a `diff` expecting no change) must exit 0 on the clean case. Why: a bare `grep` exits 1 on no-match, so the success path surfaces as `is_error=true` and the verifier downgrades a perfect run. Invert it: `if <detector>; then echo "HALT: <what was found>"; exit 1; fi; echo clean` — never let the clean path carry a non-zero exit.
+- **Recover or annotate every error — don't strand a Traceback in the transcript.** The verifier's `transcript_errors` heuristic downgrades an otherwise-perfect run when a `Traceback`/`Error` has no visible recovery within ~10 lines — the single most common false-positive on green work. The top cause is a throwaway probe that errors (a quoting/f-string slip in an inline `python -c`, a wrong kwarg, a bad path): when a probe errors, immediately re-run the corrected version, or print `# expected/handled: <why>` right after it so the recovery sits next to the error. Prefer a small temp `.py` file over a fragile multi-quote one-liner. (The timeout rule below is the other cause.)
+- **An *expected* bounded timeout (exit 124) must be annotated, not left bare.** Capping a genuinely long task (a full-universe ingest, a long scan) at its expected limit is correct, but a bare `Exit code 124` reads as a failure to the verifier. Wrap it so the cap reads as success-with-note: `timeout 120 <cmd> || { rc=$?; [ $rc -eq 124 ] && echo "hit time cap — OK" || { echo "HALT: rc=$rc"; exit 1; }; }` — distinguish the expected 124 from a real non-zero. If the work needs longer than a safe cap, the PRD is too big: end with `SCHEDULER_VERDICT: FAIL <reason>` so the planner splits it. Never run it in the background.
+- **Never `sleep N && <cmd>` to poll remote CI/job status.** The harness hard-blocks a `sleep` chained to another command, and that block itself lands in the transcript as a bare error — usually in the last 20% of the run, right where the verifier weighs errors most. Use the tool's own blocking watcher under a hard cap instead: `timeout 600 gh run watch <run-id> --repo <owner>/<repo> --exit-status`. `gh pr checks` is itself negative-assertion-shaped (exits 8 pending, 1 failed/none-reported — see above), so wrap it the same way. (Incident: PRD 745 landed a truthful PASS and a fully green CI run, but an unannotated `sleep 20 && gh pr checks` and a harness-blocked `sleep 90 && gh pr checks` sat at the end of the transcript and the run was flagged anyway.)
+- **Don't leak expected-error text into tool output.** The verifier pattern-matches the transcript for `Traceback`/`FAIL`/`Error:`. When a step is *expected* to error (a TDD red-phase test, an existence probe), capture it and print a clean token instead of letting the raw exception land verbatim — e.g. `if <probe> 2>/dev/null; then echo PROBE_OK; else echo PROBE_ABSENT; fi`, or filter a noisy run down to `RED (expected)` / `GREEN`. When retrying a transient failure, re-run the exact same command with the same description — the self-recovery detector only pairs a failure with a later success when the wording matches.
+- **End green: run the AC gate LAST, and let nothing error after it.** The verifier weighs the final ~20% of the run most heavily — a tool error there trips a downgrade even when everything actually passed. Order the run so any intentionally-failing step (a TDD red test, an expected-nonzero probe) runs early, never after the gate. If you must demonstrate a failure late anyway, capture it (`… 2>&1 | tail` inside a conditional, or assert on the captured text) instead of letting it hit the transcript bare.
+- **The verdict line is your authoritative "I passed" signal — emit it truthfully.** The scheduler's finish protocol ends by printing `SCHEDULER_VERDICT: PASS` once the AC gate is green and the commit has landed (or `SCHEDULER_VERDICT: FAIL <reason>` + `exit 1` otherwise). `PASS` plus a landed commit is authoritative: it overrides incidental transcript markers, so a deliberately reproduced red test or a grep result containing "Error" will not false-trip `needs_review`, as long as the run genuinely ends green and committed. Exiting 0 with uncommitted changes, or with no verdict line at all, is the #1 cause of needless `needs_review`. Never print `PASS` when the gate is red — that turns a safety net into a silent-failure machine.
+- **If your own AC gate failed on a SIBLING job's in-flight file, say so with the right verdict — don't print a lying FAIL.** If the prompt disclosed a `--- FOREIGN WORKING-TREE STATE ---` section and your gate failure is confined to paths that section named as not your work, print `SCHEDULER_VERDICT: BLOCKED_BY_FOREIGN_WIP` (and `exit 1`) plus a `FOREIGN_WIP_PATHS: <path1>, <path2>, ...` line naming exactly the failing paths. The scheduler validates every listed path against the manifest it disclosed to you — list a path it never named, or claim this verdict for your own regression, and it is rejected back to `FAIL`. This is not an escape hatch: it exists so a correctly-diagnosed "not my regression" gets auto-requeued once the sibling clears its WIP, instead of spawning a fix-plan investigation into someone else's unfinished work.

package/scripts/README.md

@@ -8,7 +8,7 @@ scripts/lib was moved into src/main/lib (2026-09); nothing under src/ may requir
 
 | script | invoked by | shipped on npm |
 | --- | --- | --- |
-| audit-ops-hygiene.cjs | manual; named in `ops-sweep` + `develop` SKILL.md | yes |
+| audit-ops-hygiene.cjs | manual; named in `ops-sweep` SKILL.md | yes |
 | bench/main-bench.cjs | `npm run bench` (main-process micro-benches, plain Node); renderer half is `npm run bench:renderer` (`tests/bench/`, `vitest.bench.config.ts`, not in `test:unit`) | no |
 | check-conditional-hooks.cjs | `npm run lint:hooks` (in `lint`) | no |
 | check-epic-transcripts.cjs | manual read-only diagnostic (`--json`); also surfaced as a non-fatal warning in `npm run health` | no |
@@ -17,17 +17,13 @@ scripts/lib was moved into src/main/lib (2026-09); nothing under src/ may requir
 | check-main-ts-check.cjs | `npm run lint:main-ts-check` (in `lint`) — `tsconfig.main.json` `include` ⇔ `// @ts-check` first line, both directions; explicit list only, `checkJs` false | no |
 | check-renderer-storage.cjs | `npm run lint:renderer-storage` (in `lint`) — ratchet-bans `localStorage.`/`sessionStorage.` in `src/renderer` outside an explicit ALLOWLIST (Epic stateless-ui-review) | no |
 | check-tracked-filenames.cjs | `npm run lint:filenames` (in `lint`) — fails on tracked paths with Windows-illegal chars, trailing dot/space, or reserved device names | no |
-| check-unregistered-tests.cjs | `npm run lint:unregistered-tests` (in `lint`) | no |
 | check-unstable-selectors.cjs | `npm run lint:selectors` (in `lint`) | no |
-| cleanup-nested-queue-stubs.cjs | manual one-shot; dispatches to cleanup-worktree-ops-stubs.cjs | no |
-| cleanup-worktree-ops-stubs.cjs | via cleanup-nested-queue-stubs.cjs | no |
 | health.sh | manual; `local-project-health` skill's lookup path (`npm run health` uses src/main/health.cjs) | no |
-| install-scheduler-mcp-user-scope.sh | manual; named in `develop` SKILL.md | no |
+| install-scheduler-mcp-user-scope.sh | manual (`seedSchedulerMcp.cjs` does the same on first boot, or on the next boot after its marker file is deleted) | no |
 | install-scheduler-watchdog.sh | manual; installs the systemd user timer (cron fallback) | no |
-| mint-epic.cjs | `develop` SKILL.md and PRD_AUTHORING.md manual-write fallback | yes |
+| mint-epic.cjs | manual; joins an existing Epic and prints its prds dir | yes |
 | ops-sweep.cjs | `ops-sweep` SKILL.md (`node "$SM_ROOT/scripts/ops-sweep.cjs" <cwd>`) | yes |
 | postinstall.cjs | npm `postinstall` | yes |
-| probe-electron-helper-comm.cjs | manual probe (Linux, xvfb) | no |
 | refresh-vad-assets.mjs | `npm run refresh:vad-assets` | no |
 | replay-verdicts.cjs | manual, dev-only, read-only | no |
 | scheduler-mcp-server.cjs | registered as an MCP server (`seedSchedulerMcp.cjs`, `send-feedback` SKILL.md) | yes |
@@ -52,10 +48,6 @@ The four `hooks/guard-*.cjs` are adopted by reference, not copied: `src/main/lib
 - `ops-sweep.cjs` is the portable sweep: it requires a target-project cwd argument and works on any project's ops folder.
 - `audit-ops-hygiene.cjs` holds this repo's own patterns and is not portable.
 
-## Cleanup dispatch
-
-`cleanup-nested-queue-stubs.cjs` removes nested queue shards and then dispatches to `cleanup-worktree-ops-stubs.cjs` (its `main()`), which handles the worktree-side stubs.
-
 Bench numbers are machine-relative — compare runs on the same machine only; there are no pass/fail thresholds.
 
 ## npm shipping

package/scripts/audit-ops-hygiene.cjs

@@ -19,8 +19,8 @@
  * anything is actually lost.
  *
  * Pattern E — PRDs authored outside the sanctioned `scheduler_create_prd` MCP
- * tool (the /develop skill's manual-write fallback is meant to be a rare,
- * flagged last resort — see CLAUDE.md's "PRD authoring is API-only"). Every
+ * tool (a hand-written PRD file is never sanctioned — see CLAUDE.md's "PRD
+ * authoring is API-only"). Every
  * API-created PRD gets a `prd_create` record in the machine-wide audit log
  * (`~/.claude/session-manager/audit-log.jsonl`, `src/main/lib/auditLog.cjs`)
  * keyed by cwd+slug. This check is deliberately narrow: it only inspects PRD
@@ -231,7 +231,7 @@ function auditPatternE() {
     unattributed,
     verdict: unattributed.length === 0
       ? 'CLEAN: every untracked (not-yet-committed) PRD has a matching prd_create record.'
-      : 'INVESTIGATE: untracked PRD(s) with no matching prd_create audit event — likely hand-authored via the /develop manual-write fallback (bypassing scheduler_create_prd). Confirm the bypass was reported and verify the file by hand.',
+      : 'INVESTIGATE: untracked PRD(s) with no matching prd_create audit event — likely hand-authored, bypassing scheduler_create_prd. Hand-writing a PRD is never sanctioned; confirm how this file was created.',
   };
 }
 

package/scripts/hooks/lib/guard-prd-writes-policy.cjs

@@ -78,7 +78,7 @@ function decide(payload) {
     const reason = [
       `Direct ${toolName} to a session-manager-operations/scheduler/ path is blocked.`,
       `PRDs must be authored through the scheduler API, not a raw file write — use the "${suggested}" MCP tool instead.`,
-      'If the Session Manager app is not running (the admin API this MCP tool talks to only exists while it is), the degraded fallback documented in the develop skill applies: hand-write the file as a last resort and say so visibly in your report.',
+      'If the Session Manager app is not running (the admin API this MCP tool talks to only exists while it is), stop: ask the human to start the app, then retry the MCP tool. Never hand-write a PRD file.',
     ].join(' ');
     return buildDeny(reason);
   } catch (e) {

package/scripts/hooks/lib/guard-self-schedule-policy.cjs

@@ -17,7 +17,7 @@ const ALWAYS_DENY_TOOLS = new Set(['ScheduleWakeup', 'CronCreate']);
 const BACKGROUNDABLE_AGENT_TOOLS = new Set(['Task', 'Agent']);
 
 const STANDARDS_QUOTE = 'You ARE the executor — never re-queue or self-schedule.';
-const STANDARDS_CITE = 'plugins/session-manager-dev/skills/develop/standards.md:85 (Execution discipline)';
+const STANDARDS_CITE = 'plugins/session-manager-dev/skills/develop/standards.md (Execution discipline)';
 
 function buildAllow() {
   return { continue: true };

package/scripts/mint-epic.cjs

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
 /**
- * mint-epic.cjs — CLI wrapper over lib/epicMint.cjs's JOIN path, for PRD
- * authors working without the app's admin API (the /develop skill's
- * manual-write fallback).
+ * mint-epic.cjs — CLI wrapper over lib/epicMint.cjs's JOIN path, for joining
+ * an existing Epic without the app's admin API running.
  *
  * This script never creates an Epic. It only resolves an EXISTING Epic's
  * prds/ write directory. An Epic comes into existence in exactly one place —

package/scripts/scheduler-mcp-server.cjs

@@ -12,6 +12,7 @@
  *   feedback_open_session({ ... }) -> POST /admin/feedback/open-session
  *
  *   project_home_write({ cwd?, html }) -> POST /admin/project-home/write
+ *   project_demo_video_write({ cwd?, html }) -> POST /admin/project-home/demo-video/write
  *
  * This is a separate process from the Electron app — it only ever reaches
  * it over the token-authed loopback HTTP API in admin-api.json, never by
@@ -133,7 +134,7 @@ const TOOLS = [
       type: 'object',
       properties: {
         slug: { type: 'string', description: 'PRD slug of the job to reset' },
-        force: { type: 'boolean', description: 'Required to reset a job whose status is already "completed"' },
+        force: { type: 'boolean', description: 'Required to reset a job whose status is already "completed" or "skipped"' },
         cwd: { type: 'string', description: 'Optional: the PRD project cwd, narrows/speeds the search' },
       },
       required: ['slug'],
@@ -162,13 +163,21 @@ const TOOLS = [
       properties: {
         title: { type: 'string', description: 'One-line human-readable title' },
         cwd: { type: 'string', description: 'Absolute path to the target project (where claude -p will run). Optional inside an Epic session — the server resolves the real project from the calling session (originClaudeSessionId/sourcePromptId) when omitted.' },
-        estimateMinutes: { type: 'number', description: 'Integer wall-clock estimate in minutes' },
+        estimateMinutes: { type: 'number', description: 'Integer wall-clock estimate in minutes. Most PRDs take 5-10; never over 15 (split instead)' },
         goal: { type: 'string', description: '2-4 sentences: what the executor will build and why' },
         acceptanceCriteria: {
           type: 'array', items: { type: 'string' },
           description: 'Each entry is one verifiable checklist line',
         },
         implementationNotes: { type: 'string', description: 'File paths, patterns, and constraints the executor needs' },
+        gate: {
+          type: 'array', items: { type: 'string' },
+          description: 'REQUIRED. Commands that prove this PRD is done. The scheduler re-runs them without a shell. One command per entry, run in order; each must exit 0. Start each && step with `timeout <seconds>`. Join steps with &&. Outside single quotes, no | < > ; & ` $ \\ * ? [ ] ( ) { } or !. Use ["none"], exactly, only for docs or config with no runnable check.',
+        },
+        files: {
+          type: 'array', items: { type: 'string' },
+          description: 'REQUIRED. Repo-relative files or folders (end a folder with /) this PRD may change. No absolute paths, .. or . segments, globs, backslashes or backticks. PRDs that run at the same time must not share files; chain them with dependsOn instead.',
+        },
         outOfScope: { type: 'array', items: { type: 'string' }, description: 'Optional: what NOT to build' },
         slug: { type: 'string', description: 'Optional kebab-case slug; derived from title if omitted' },
         parallelGroup: { type: 'number', description: 'DEPRECATED and ignored (PRD 832): numbers are strictly unique per project; use dependsOn for ordering' },
@@ -194,7 +203,7 @@ const TOOLS = [
           description: 'Optional: set true only when this PRD\'s acceptance criteria are wall-clock/timing measurements (frame time, performance fences) that CPU contention from concurrent jobs would invalidate. The scheduler dispatches it only once zero other jobs are running machine-wide, and holds every other job off the whole slot pool for its run — a whole-machine exclusive lease, not a per-project one. If the machine never goes quiet within the configured wait window (default 30 minutes), it dispatches anyway and is marked degraded. Opt-in only; omit for ordinary PRDs.',
         },
       },
-      required: ['title', 'estimateMinutes', 'goal', 'acceptanceCriteria', 'implementationNotes'],
+      required: ['title', 'estimateMinutes', 'goal', 'acceptanceCriteria', 'implementationNotes', 'gate', 'files'],
     },
   },
   {
@@ -367,6 +376,25 @@ const TOOLS = [
       required: ['html'],
     },
   },
+  {
+    name: 'project_demo_video_write',
+    description: descriptionFor('project_demo_video_write'),
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cwd: { type: 'string', description: "Optional: absolute path to the target project. Defaults to the calling session's own project root (SM_PROJECT_ROOT or process.cwd()) when omitted." },
+        html: {
+          type: 'string',
+          description: 'The complete self-contained HTML/JS document for a 30-second-or-less demo video (<= 2MB). '
+            + 'It is rejected for: being empty; <script src>, <link href=http*>, @import, or url(http*) (no remote references); '
+            + 'fetch/XMLHttpRequest/WebSocket/EventSource/sendBeacon/dynamic import/importScripts/<iframe>/<object>/<embed>/window.open/'
+            + 'any http(s)/// src or href (no network-capable APIs — the document is CSP-fenced after it is written); '
+            + 'or missing a <meta name="sm-demo-duration" content="N"> tag with 5 <= N <= 30.',
+        },
+      },
+      required: ['html'],
+    },
+  },
   {
     name: 'session_manager_help',
     description: descriptionFor('session_manager_help'),
@@ -490,6 +518,18 @@ async function handleCallTool(request) {
           + 'If more work is genuinely needed, say so in your final result text — the authoring Epic decides whether to queue it.',
         );
       }
+      // Required-fields refusal (gate-and-files-in-PRD-body unit): checked
+      // right after the headless-refusal check above, before any payload
+      // forwarding — 74% of parked jobs had no gate the scheduler could
+      // read, so the tool itself refuses a call missing either field rather
+      // than letting an ungated PRD reach disk.
+      if (!Array.isArray(args?.gate) || args.gate.length === 0 || !Array.isArray(args?.files) || args.files.length === 0) {
+        return errorResult(
+          'scheduler_create_prd needs "gate" (the commands that prove this PRD is done, with each && step '
+          + 'starting with "timeout <seconds>", or ["none"]) and "files" (the repo-relative files this PRD may change). '
+          + 'Add both and call again.',
+        );
+      }
       // If the caller (the model) didn't pass sourcePromptId, forward this
       // process's own SM_CHAT_SESSION_ID (set by chatRunner.cjs on the
       // parent claude -p process this MCP server inherited its env from) so
@@ -515,11 +555,20 @@ async function handleCallTool(request) {
         ? ' — PRD file written; the queue row is derived on the next scheduler reconcile pass, not by this call.'
         : '';
       let text = JSON.stringify(result) + note;
-      // Sizing warnings (PRD 1403) are advisory only — never block the write,
-      // just surfaced here so the authoring session can decide to split the
-      // PRD before confirming it. See prdSizing.cjs.
+      // Warnings (PRD 1403 sizing + gate-and-files-in-PRD-body absent/none-gate
+      // warnings) are advisory only — never block the write, just surfaced
+      // here so the authoring session can decide to split or re-queue before
+      // confirming it. See prdSizing.cjs and prdGateFiles.cjs.
       if (Array.isArray(result?.warnings) && result.warnings.length > 0) {
-        text += `\nSizing warnings:\n${result.warnings.map((w) => `- ${w}`).join('\n')}`;
+        text += `\nWarnings:\n${result.warnings.map((w) => `- ${w}`).join('\n')}`;
+      }
+      // Echo the gate and files the API actually recorded, same honesty
+      // standard as `note` above — not a repeat of the caller's own input.
+      if (result?.gate) {
+        text += `\nGate (${result.gate.source}): ${result.gate.commands.join(' && ')}`;
+      }
+      if (Array.isArray(result?.files)) {
+        text += `\nFiles: ${result.files.join(', ')}`;
       }
       return { content: [{ type: 'text', text }] };
     }
@@ -570,6 +619,14 @@ async function handleCallTool(request) {
       const result = await adminRequest('POST', '/admin/project-home/write', { cwd, html: args.html });
       return { content: [{ type: 'text', text: JSON.stringify(result) }] };
     }
+    if (name === 'project_demo_video_write') {
+      if (!args || typeof args.html !== 'string' || args.html.length === 0) {
+        return errorResult('missing required argument: html');
+      }
+      const cwd = resolveCwdArg(args);
+      const result = await adminRequest('POST', '/admin/project-home/demo-video/write', { cwd, html: args.html });
+      return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    }
     if (name === 'session_manager_help') {
       const toolName = args && typeof args.tool === 'string' ? args.tool : null;
       const topic = args && typeof args.topic === 'string' ? args.topic : null;

package/src/main/agentLibrary.cjs

@@ -66,8 +66,13 @@ function decodeLine(s) {
  * instruction that button sends into the new session, and `actionLabel`
  * overrides the button's caption (defaults to the persona name). Claude Code
  * ignores all three; only this app reads them.
+ *
+ * `seedVersion` is seedAgentPersonas.cjs's bundled-persona stamp — an
+ * integer, present only on the four bundled personas. Written through
+ * unchanged (not Claude-Code-visible either) so a save from the Agent
+ * Library editor never erases the stamp a hand-edit should keep intact.
  */
-function serializePersona({ name, description, tools, model, effort, color, tags, projects, action, actionLabel, title, body }) {
+function serializePersona({ name, description, tools, model, effort, color, tags, projects, action, actionLabel, title, seedVersion, body }) {
   const lines = ['---', `name: ${name}`];
   if (description) lines.push(`description: ${description}`);
   if (tools && tools.length) lines.push(`tools: ${tools.join(', ')}`);
@@ -79,6 +84,7 @@ function serializePersona({ name, description, tools, model, effort, color, tags
   if (action) lines.push(`action: ${encodeLine(action)}`);
   if (actionLabel) lines.push(`actionLabel: ${encodeLine(actionLabel)}`);
   if (title) lines.push(`title: ${title}`);
+  if (typeof seedVersion === 'number' && Number.isFinite(seedVersion)) lines.push(`seedVersion: ${seedVersion}`);
   lines.push('---', '');
   return lines.join('\n') + (body || '').trim() + '\n';
 }
@@ -142,6 +148,7 @@ async function savePersona({
   action,
   actionLabel,
   title,
+  seedVersion,
   body,
   projectName,
   globalDir = path.join(os.homedir(), '.claude', 'agents'),
@@ -156,7 +163,19 @@ async function savePersona({
     return saveOverlay({ name, projectName, model, effort, loadSessions, validatePath, writeTextAtomic });
   }
   const target = validatePath(path.join(globalDir, `${name}.md`));
-  const text = serializePersona({ name, description, tools, model, effort, color, tags, projects, action, actionLabel, title, body });
+  // The Agent Library editor's form has no `seedVersion` field, so a save
+  // through it never passes one explicitly — carry over whatever stamp the
+  // existing file already has rather than silently erasing it. An explicit
+  // `seedVersion` argument (e.g. the seeder's own future callers) still wins.
+  let resolvedSeedVersion = seedVersion;
+  if (resolvedSeedVersion === undefined) {
+    try {
+      const existing = splitFrontmatter(fsSync.readFileSync(target, 'utf8'));
+      const existingVersion = Number(existing.fm.seedVersion);
+      if (Number.isFinite(existingVersion)) resolvedSeedVersion = existingVersion;
+    } catch { /* no existing file (or unreadable) — nothing to carry over */ }
+  }
+  const text = serializePersona({ name, description, tools, model, effort, color, tags, projects, action, actionLabel, title, seedVersion: resolvedSeedVersion, body });
   await writeTextAtomic(target, text);
   if (originalName && originalName !== name) {
     const oldReal = validatePath(path.join(globalDir, `${originalName}.md`));
@@ -301,6 +320,7 @@ async function listPersonas({
       action: decodeLine(fm.action) || null,
       actionLabel: decodeLine(fm.actionLabel) || null,
       title: fm.title || null,
+      seedVersion: fm.seedVersion !== undefined && Number.isFinite(Number(fm.seedVersion)) ? Number(fm.seedVersion) : null,
       path: real,
       body: body.trim(),
       overridingProjects,

package/src/main/build-info.json

@@ -1,8 +1,8 @@
 {
-  "version": "0.98.0",
-  "gitSha": "a733808122aabbe14f7b37834196eb78bb0c339f",
-  "gitShortSha": "a7338081",
+  "version": "0.101.0",
+  "gitSha": "c57a278f1ec1bf0c508ff6a1fcc260195febd6e3",
+  "gitShortSha": "c57a278f",
   "gitBranch": "HEAD",
-  "builtAt": "2026-09-26T00:17:48.074Z",
+  "builtAt": "2026-10-03T17:17:40.599Z",
   "dirty": false
 }

package/src/main/chatRunner.cjs

@@ -30,7 +30,7 @@
  *   chat:run:queued     { tabId, sessionId, position }   — waiting behind a busy lane
  *   chat:run:started    { tabId, sessionId }
  *   chat:run:output     { tabId, delta }
- *   chat:run:tool-use   { tabId, id, kind, label }
+ *   chat:run:tool-use   { tabId, id, kind, label, detail }
  *   chat:run:complete   { tabId, sessionId, finalMessage }
  *   chat:run:needs-input { tabId, sessionId, questions, raw }
  *   chat:run:error      { tabId, sessionId, message }
@@ -736,9 +736,10 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume, silent, onSilentRes
             if (!silent) broadcast('chat:run:output', { tabId, delta: block.text });
           } else if (block.type === 'tool_use' && typeof block.name === 'string') {
             const classified = classifyToolUse(block);
-            recentToolUses.push({ ...classified, detail: describeToolUseInput(block) });
+            const detail = describeToolUseInput(block);
+            recentToolUses.push({ ...classified, detail });
             if (recentToolUses.length > RECENT_TOOL_USE_LIMIT) recentToolUses.shift();
-            if (!silent) broadcast('chat:run:tool-use', { tabId, id: block.id, ...classified });
+            if (!silent) broadcast('chat:run:tool-use', { tabId, id: block.id, ...classified, detail });
           }
         }
       } else if (event.type === 'user') {

package/src/main/config.cjs

@@ -25,6 +25,7 @@ const logs = require('./logs.cjs');
 const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
 const { expandHome } = require('./lib/expandHome.cjs');
 const { listReferencedFiles } = require('./lib/importReferences.cjs');
+const atomicFs = require('./lib/atomicFs.cjs');
 
 /** Map<absPath, {watcher, refCount}> — one chokidar watcher per path. */
 const watchers = new Map();
@@ -38,22 +39,41 @@ function attachWindow(w) {
 
 /**
  * Resolve a path to its realpath, handling non-existent files by resolving
- * the parent directory instead. Prevents symlink traversal attacks.
+ * the nearest existing ancestor directory instead. Prevents symlink
+ * traversal attacks.
+ *
+ * A fresh target can be missing more than one directory level, for example
+ * "<tmpdir>/session-manager-operations/prompt-sessions/x.json" right after
+ * `mkdtemp`, where neither `session-manager-operations` nor
+ * `prompt-sessions` exists yet. Walk up one directory at a time until one
+ * exists, realpath that ancestor, then join every segment below it back on.
+ * Why: stopping after a single parent hop returns the lexical (not
+ * realpath'd) path on macOS, where `os.tmpdir()` sits under `/var`, a
+ * symlink to `/private/var`. The caller's root check then compares that
+ * unresolved `/var/...` path against a sibling root that DID resolve to
+ * `/private/var/...` and always rejects it, even for paths that belong
+ * squarely inside the allowed root.
  */
 function realResolve(abs) {
   const lex = path.resolve(expandHome(abs));
   try {
     return fs.realpathSync(lex);
   } catch (e) {
-    if (e.code === 'ENOENT') {
-      const parent = path.dirname(lex);
-      try {
-        return path.join(fs.realpathSync(parent), path.basename(lex));
-      } catch {
-        return lex;
-      }
+    if (e.code !== 'ENOENT') throw e;
+  }
+  const tail = [path.basename(lex)];
+  let dir = path.dirname(lex);
+  for (;;) {
+    try {
+      const realDir = fs.realpathSync(dir);
+      return path.join(realDir, ...tail.reverse());
+    } catch (e) {
+      if (e.code !== 'ENOENT') throw e;
+      const parentDir = path.dirname(dir);
+      if (parentDir === dir) return lex; // hit the filesystem root; give up safely
+      tail.push(path.basename(dir));
+      dir = parentDir;
     }
-    throw e;
   }
 }
 
@@ -108,11 +128,16 @@ function validatePath(abs) {
   throw new Error(`Path outside allowed boundaries: ${real}`);
 }
 
-// Paths that are allowed as write destinations.
+// Paths that are allowed as write destinations. Built from the REALPATH of
+// home because validateWrite compares against a realpath — on macOS a HOME
+// under os.tmpdir() (/var → /private/var) otherwise never matches.
+const REAL_HOME = (() => {
+  try { return fs.realpathSync(os.homedir()); } catch { return os.homedir(); }
+})();
 const WRITE_PREFIXES = [
-  path.join(os.homedir(), '.claude'),
-  path.join(os.homedir(), '.claude.json'), // global MCP servers config
-  path.join(os.homedir(), '.config', 'claude-code'),
+  path.join(REAL_HOME, '.claude'),
+  path.join(REAL_HOME, '.claude.json'), // global MCP servers config
+  path.join(REAL_HOME, '.config', 'claude-code'),
 ];
 
 /**
@@ -241,21 +266,7 @@ async function writeTextAtomic(abs, text, opts = {}) {
   const real = validatePath(expandHome(abs));
   validateWrite(real);
   assertOpsWrite(real, opts.writer);
-  const dir = path.dirname(real);
-  await fsp.mkdir(dir, { recursive: true });
-  const tmp = `${real}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-  try {
-    await fsp.writeFile(tmp, text, opts.mode ? { encoding: 'utf8', mode: opts.mode } : 'utf8');
-    if (opts.mode) {
-      // chmod explicitly because some platforms ignore the mode arg on
-      // writeFile when the file pre-exists.
-      try { await fsp.chmod(tmp, opts.mode); } catch { /* */ }
-    }
-    await fsp.rename(tmp, real);
-  } catch (e) {
-    try { await fsp.unlink(tmp); } catch { /* tmp never created or already gone */ }
-    throw e;
-  }
+  await atomicFs.writeTextAtomic(real, text, opts);
   const stat = await fsp.stat(real);
   return { ok: true, mtimeMs: stat.mtimeMs };
 }
@@ -296,16 +307,7 @@ function writeJsonSync(abs, data, opts = {}) {
   const real = validatePath(expandHome(abs));
   validateWrite(real);
   assertOpsWrite(real, opts.writer);
-  const dir = path.dirname(real);
-  fs.mkdirSync(dir, { recursive: true });
-  const tmp = `${real}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-  try {
-    fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', 'utf8');
-    fs.renameSync(tmp, real);
-  } catch (e) {
-    try { fs.unlinkSync(tmp); } catch { /* tmp never created or already gone */ }
-    throw e;
-  }
+  atomicFs.writeJsonAtomicSync(real, data, opts);
   const stat = fs.statSync(real);
   return { ok: true, mtimeMs: stat.mtimeMs };
 }
@@ -510,4 +512,5 @@ module.exports = {
   registerPromptSessionsRoot,
   validatePath,
   validateWrite,
+  realResolve,
 };

package/src/main/docEdit.cjs

@@ -18,6 +18,7 @@ const { ipcMain } = require('electron');
 const { spawn } = require('node:child_process');
 const crypto = require('node:crypto');
 const { resolveClaudeBin, claudeSpawnTarget } = require('./lib/claudeBin.cjs');
+const { headlessPermissionArgs, ensureCliCapsProbed } = require('./lib/claudeCliCaps.cjs');
 const { withProcRole } = require('./lib/cleanEnv.cjs');
 const { extractJson } = require('./lib/extractJson.cjs');
 const { assertInsideHome } = require('./lib/insideHome.cjs');
@@ -86,7 +87,8 @@ function parseDocEdit(rawStdout) {
 }
 
 /** Spawn `claude -p`, capture stdout. Resolves {ok, out, err, error} — never throws. */
-function runClaude(prompt, { model = 'sonnet', timeoutMs = 90_000, systemPrompt = null } = {}) {
+async function runClaude(prompt, { model = 'sonnet', timeoutMs = 90_000, systemPrompt = null } = {}) {
+  await ensureCliCapsProbed();
   return new Promise((resolve) => {
     let bin;
     try { bin = resolveClaudeBin(); } catch (e) { resolve({ ok: false, error: `claude not found: ${e?.message}` }); return; }
@@ -94,6 +96,7 @@ function runClaude(prompt, { model = 'sonnet', timeoutMs = 90_000, systemPrompt
       '-p', prompt,
       '--model', model,
       '--dangerously-skip-permissions',
+      ...headlessPermissionArgs(),
       '--output-format', 'text',
     ];
     if (systemPrompt) args.push('--append-system-prompt', systemPrompt);