peaks-loop 3.0.2 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 3.1.0 — 2026-07-03
+
+### Fixed — peaks-solo external-references authority declaration
+
+- `skills/peaks-solo/SKILL.md` External-references paragraph now ends with `Peaks-Loop Solo gates and artifacts remain authoritative.` to satisfy `tests/unit/skill-external-invocation.test.ts:63` (`PEAKS_AUTHORITATIVE_PATTERN`). One-line surgical patch; no behaviour change.
+
+### Added — Peaks-Loop Job
+
+- New `peaks job *` subcommand family: init / status / checkpoint / continue / resume / block / handoff / rotate-now / subagent-cleanup (9 commands).
+- New CLI flag `--main-loop-strategy single|rotating` on `job init`, with rotating-mode hard default for ≥3 slices and `rotateEvery=3` cadence.
+- New `--watch` poll mode + statusline event stub (`emitJobEvent`) for ambient progress visibility. Real statusline wire-up deferred to a follow-up slice.
+- Sub-agent wrapper `SubAgentJobWrapper` enforces `--budget-mb 512` default + cleanup gate before slice checkpoint.
+- New peaks-solo SKILL.md Steps 0.8 / 0.81 / 0.85 / 0.86 / 0.87 wrapping the existing single-rid runbook for multi-slice jobs.
+- 9 hard-red-line rules embedded in the skill prose (cost re-ask ban, slice-coalesce ban, fake-completion ban, detached-mode ban, cleanup-skip ban, rotate-skip ban, etc).
+
+### New services
+
+- `src/services/job/job-types.ts` — Zod schemas + types for SliceState, JobState, ResourceSnapshot, JobStatusSummary, plus CLI input schemas (JobInitInput, JobCheckpointInput, JobBlockInput).
+- `src/services/job/job-state-store.ts` — on-disk state store with per-job lockfile.
+- `src/services/job/job-orchestrator.ts` — state machine with strict / best-effort exit policies.
+- `src/services/job/job-rotation.ts` — main-session rotation cadence (single / rotating mode).
+- `src/services/job/subagent-job-wrapper.ts` — budget + cleanup gate.
+- `src/services/job/job-resource-snapshot.ts` — cpu / mem / disk / context collector.
+- `src/services/job/job-event-emitter.ts` — stderr-stub event emit (real statusline wire-up pending).
+
+### Migration
+
+- Existing single-rid flows are unchanged. The Job is opt-in via peaks-solo Step 0.8 detection; users who do not invoke multi-slice requests see no behavior difference.
+- The `peaks session rotate` and `peaks session cycle-summary` subcommands referenced in the spec are NOT shipped in v1; the rotation path uses constructor-injected stub callbacks. M6.5 follow-up will add the real subcommands.
+
+### Spec / plan
+
+- Design: `docs/superpowers/specs/2026-07-03-peaks-loop-job-design.md` (v3).
+- Plans: `docs/superpowers/plans/2026-07-03-peaks-job/` (M1-M7 + README).
+
+## [3.0.3] — 2026-07-02 — auto-compact zero-pause (ide-native pathway)
+
+**PATCH bump from 3.0.2**. Closes the user-pause gap on long Claude Code sessions: at context ratio ≥ 0.95 the runner now compacts itself via a PreToolUse hook, no human intervention required.
+
+### Added — `ide-native` pathway + `peaks session auto-compact-hook`
+
+The v2.13.0 auto-compact design shipped `shell-exec` as the only pathway, which spawns a NEW claude child process and cannot compact the current runner. Long-task users hit a UX gap: AI CLI still stopped and asked the human to run `/compact` manually.
+
+- **New `ide-native` pathway** — `src/services/context/auto-compact-dispatcher.ts:138-155` routes main-session compacts through `installAutoCompactHook`, which writes a PreToolUse hook into `.claude/settings.local.json` (matcher `Bash|Task`, command `peaks session auto-compact-hook`).
+- **New `peaks session auto-compact-hook` CLI** — `src/cli/commands/session-auto-compact-hook-command.ts`. Reads `CLAUDE_CONTEXT_USAGE_PERCENT`; below 0.95 exits 0 silent; at ratio ≥ 0.95 spawns `claude --compact` in-band against the **current** runner (detached + unref, never blocks the runner's tool call). ENOENT-safe: if `claude` is not on PATH (e.g. user runs Claude Code as an MCP), the hook logs a stderr hint and exits 0 silent rather than crashing the runner.
+- **New `installAutoCompactHook` / `removeAutoCompactHook` service** — `src/services/hooks/auto-compact-hook-install.ts`. Idempotent: re-install returns `already-installed` and does NOT re-write the file; remove preserves other PreToolUse entries (the existing fact-forcing bypass hook on every peaks-loop consumer project survives).
+- **Lazy install** — hook is installed on first `peaks solo auto-compact` invocation, NOT on `peaks workspace init`. User has opted in by running the command; no zero-touch surprise.
+- **Claude Code adapter** — `compactPathway` changed from `shell-exec` to `ide-native` for `target='main'`. Sub-agent shells still get the legacy `shell-exec` pathway.
+
+### Fixed — Solo Step N+2 prose (was 75% / "do NOT auto-execute")
+
+- `skills/peaks-solo/SKILL.md` Step N+2 paragraph rewritten: thresholds now 0.85 pre-compact / 0.95 red-line (matches v2.13.0 auto-compact), explicit Karpathy §4 compact-red-line exception cited, `peaks solo context-now --json` is the canonical probe primitive (replaces `peaks context check --prompt-size <bytes>` hand-pass).
+- `src/services/context/main-session-monitor.ts` — `@deprecated` JSDoc on `evaluateMainSessionThreshold` cross-links to `evaluateCompactTrigger` (0.85/0.95); legacy 4-tier envelope retained for statusline callers (migration to v2.15.0).
+
+### Tests — 4 new suites + 3 modified files
+
+- `tests/unit/services/hooks/auto-compact-hook-install.test.ts` (7 cases) — install / idempotent / remove / preservation of unrelated entries.
+- `tests/unit/services/context/auto-compact-dispatcher-ide-native.test.ts` (9 cases) — `dispatchIdeCompact({ target: 'main' })` routes to `ide-native`; round-trip install / remove.
+- `tests/unit/skills/solo-step-n-plus-2-prose.test.ts` (6 cases) — pins the 0.85 / 0.95 / Karpathy §4 contract; asserts `75%` is NOT in the paragraph.
+- `tests/unit/cli/session-auto-compact-hook-command.test.ts` (3 cases) — dogfood surfacing: below-threshold silent, missing env-var silent, red-line + ENOENT exits 0 with stderr hint.
+- `tests/unit/services/context/main-session-monitor.test.ts` (+2 AC-4 cases), `tests/unit/context/auto-compact-main-target.test.ts` (pathway assertion updated) — coverage.
+
+### Dogfood verified
+
+Validated on `C:/Users/smallMark/Desktop/peaksclaw/ice-cola` (consumer project). End-to-end: install hook alongside existing fact-forcing bypass → idempotent re-run → below-threshold silent → red-line + no-claude-on-PATH exits 0 with hint → remove strips only the auto-compact matcher. No regressions in 5,139 / 5,158 vitest pass.
+
 ## [3.0.2] — 2026-07-02 — change-id shim retirement (v2.19.0) + Understand Anything hybrid context (3.0.2)
 
 **PATCH bump from 3.0.1**. Two independent slices bundled into one release:

package/README-en.md

@@ -137,7 +137,7 @@ peaks project dashboard --project . --json   # one-shot project view
 
 **3 solo wrappers + 7 role skills + 2 standalone audits + 1 orchestrator = 13 skills.** In daily use, 1 skill (`peaks-solo`) covers ≥ 90% of needs.
 
-> **v2.13.0**: zero-human-intervention **auto-compact** (`peaks solo context-now` + `peaks solo auto-compact`) — peaks-loop probes context-fill % autonomously. ≥85% writes a pre-compact checkpoint + convergence plan + dispatches IDE compact. ≥95% forces a synchronous RED-LINE compact. The LLM-runner stays alive with context < 95% without human intervention. **v2.13.4 fix**: auto-compact now targets the **main-session** context (not a sub-agent shell) by writing a `.peaks/_runtime/<sid>/txt/auto-compact-pending.json` intent file that the main-session LLM picks up on its next turn and fires `/compact` in-band.
+> **v2.13.0**: zero-human-intervention **auto-compact** (`peaks solo context-now` + `peaks solo auto-compact`) — peaks-loop probes context-fill % autonomously. ≥85% writes a pre-compact checkpoint + convergence plan + dispatches IDE compact. ≥95% forces a synchronous RED-LINE compact. The LLM-runner stays alive with context < 95% without human intervention. **v2.13.4 fix**: auto-compact now targets the **main-session** context (not a sub-agent shell). **3.0.3 new `ide-native` pathway**: installs a PreToolUse hook into `.claude/settings.local.json` (`Bash|Task` matcher → `peaks session auto-compact-hook`); the runner's next Bash/Task tool call in-band spawns `claude --compact`, no longer relying on the LLM to remember to fire `/compact`. Hook is ENOENT-safe (exits 0 + stderr hint if `claude` is not on PATH; runner is never interrupted).
 
 ## 🚧 Killer feature: un-bypassable gates
 

package/README.md

@@ -175,7 +175,7 @@ peaks project dashboard --project . --json   # 当前项目一眼看完
 
 **3 solo 包装 + 7 角色技能 + 2 独立审计 + 1 编排器 = 13 个。日常 1 个 `peaks-solo` 覆盖 ≥ 90%。**
 
-> **v2.13.0 新增**：zero-human-intervention **auto-compact**（`peaks solo context-now` + `peaks solo auto-compact`）——peaks-loop 自己探测 context %，≥85% 主动收敛（写 checkpoint + 收敛计划 + 触发 IDE compact），≥95% 强制同步压缩红线。LLM-runner 上下文始终 < 95% 自主运行，零介入。**v2.13.4 修复**：`auto-compact` 现在默认压缩**主会话**上下文（不是 sub-agent shell 自己的），通过写 `.peaks/_runtime/<sid>/txt/auto-compact-pending.json` 意图文件让主 LLM 下一轮 in-band 触发 `/compact`。
+> **v2.13.0 新增**：zero-human-intervention **auto-compact**（`peaks solo context-now` + `peaks solo auto-compact`）——peaks-loop 自己探测 context %，≥85% 主动收敛（写 checkpoint + 收敛计划 + 触发 IDE compact），≥95% 强制同步压缩红线。LLM-runner 上下文始终 < 95% 自主运行，零介入。**v2.13.4 修复**：`auto-compact` 现在默认压缩**主会话**上下文（不是 sub-agent shell 自己的）。**3.0.3 新增 `ide-native` 通路**：在 `.claude/settings.local.json` 装 PreToolUse hook（`Bash|Task` matcher → `peaks session auto-compact-hook`），runner 下一次 Bash/Task tool call **in-band** 触发 `claude --compact`，不再依赖 LLM 自己 fire `/compact`。Hook ENOENT-safe（claude CLI 不在 PATH 时退出 0 + stderr 提示，runner 不会被中断）。
 
 ## 🚧 杀手锏：不可绕过的门禁
 

package/dist/src/cli/commands/core/session-command.js

@@ -13,6 +13,7 @@ import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.j
 // saw them — they were effectively hidden.
 import { registerSessionCheckpointCommand } from '../session-checkpoint-command.js';
 import { registerSessionResumeCommand } from '../session-resume-command.js';
+import { registerSessionAutoCompactHookCommand } from '../session-auto-compact-hook-command.js';
 export function registerSessionCommand(program, io) {
     const session = program.command('session').description('Manage Peaks session directories');
     addJsonOption(session
@@ -186,6 +187,11 @@ export function registerSessionCommand(program, io) {
     // `<TAB>`-discovery and the LLM never saw them.
     registerSessionCheckpointCommand(session, io);
     registerSessionResumeCommand(session, io);
+    // Slice 2026-07-02-auto-compact-zero-pause: the Bash command the
+    // PreToolUse hook in `.claude/settings.local.json` fires. Keeping
+    // it eager (same fix as checkpoint + resume) so `peaks session --help`
+    // lists it for LLM `<TAB>`-discovery.
+    registerSessionAutoCompactHookCommand(session);
     addJsonOption(session
         .command('rotate')
         .description('Drop the project-level session binding so the next peaks call auto-generates a fresh session id. The on-disk session directory is left intact — only .peaks/.session.json is removed.')

package/dist/src/cli/commands/job-commands.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerJobCommands(program: Command, io?: ProgramIO): void;

package/dist/src/cli/commands/job-commands.js

@@ -0,0 +1,236 @@
+// src/cli/commands/job-commands.ts
+import { join } from 'node:path';
+import { Command } from 'commander';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { JobStateStore } from '../../services/job/job-state-store.js';
+import { JobOrchestrator } from '../../services/job/job-orchestrator.js';
+import { JobRotation } from '../../services/job/job-rotation.js';
+import { SubAgentJobWrapper } from '../../services/job/subagent-job-wrapper.js';
+import { emitJobEvent } from '../../services/job/job-event-emitter.js';
+import { JobInitInputSchema, JobCheckpointInputSchema, JobBlockInputSchema, } from '../../services/job/job-types.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+function projectRoot(opts) {
+    // Reuse the workspace root resolver from peaks CLI; for now, CWD as a safe placeholder.
+    return opts.project ?? process.cwd();
+}
+/**
+ * Resolves the on-disk root for Job state files.
+ *
+ * Per spec §3.3 + §4.5 (2.7.1 single-scope-axis layout), Job state lives at:
+ *   `<projectRoot>/.peaks/_runtime/<sessionId>/job/<jobId>/state.json`
+ *
+ * The `JobStateStore` itself only knows its `rootDir` + `jobId` and joins them. We
+ * compute the canonical root here (per-call) so the store can stay layout-agnostic.
+ *
+ * Resolution order:
+ * 1. `--session-id` flag (explicit override)
+ * 2. `getCurrentSessionId(project)` — reads `.peaks/_runtime/session.json` per peaks-solo
+ * 3. Error (NO_ACTIVE_SESSION) — must never silently fall back to a random uuid
+ */
+function resolveJobStateRoot(opts) {
+    const project = projectRoot(opts);
+    const sessionId = opts.sessionId ?? getCurrentSessionId(project);
+    if (!sessionId) {
+        throw new Error('NO_ACTIVE_SESSION: peaks job requires --session-id or an active peaks-solo session via peaks workspace init');
+    }
+    const rootDir = join(project, '.peaks', '_runtime', sessionId, 'job');
+    return { rootDir, sessionId, projectRoot: project };
+}
+export function registerJobCommands(program, io = { stdout: (t) => process.stdout.write(t), stderr: (t) => process.stderr.write(t) }) {
+    const job = new Command('job').description('Drive long multi-slice work as one Job (peaks-solo Step 0.8+)');
+    job
+        .command('init')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--slice-list <list>')
+        .option('--parallelism-hint <serial|llm-decides>', 'llm-decides')
+        .option('--exit-policy <strict|best-effort>', 'strict')
+        .option('--main-loop-strategy <single|rotating>', 'rotating')
+        .option('--rotate-every <n>', 'rotate every N slices (rotating mode)', '3')
+        .option('--session-id <sid>', 'session id (default: read from .peaks/_runtime/session.json; required to land in the 2.7.1 single-scope-axis layout)')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const project = projectRoot(opts);
+        // Resolve sessionId: explicit flag > canonical session binding > FAIL.
+        // Per spec §3.3, Job state lives at .peaks/_runtime/<sessionId>/job/<jobId>/state.json —
+        // a random UUID would scatter state across dirs and break resume/auto-compact.
+        let sessionId = opts.sessionId ?? getCurrentSessionId(project);
+        if (!sessionId) {
+            return printResult(io, fail('init', 'NO_ACTIVE_SESSION', 'peaks job init requires --session-id (or an active peaks-solo session via peaks workspace init)', { project }, [
+                'Re-run with --session-id <sid>',
+                'Or run `peaks workspace init` to create a session first'
+            ]), opts);
+        }
+        const parsed = JobInitInputSchema.safeParse({
+            jobId: opts.jobId,
+            sessionId,
+            sliceList: opts.sliceList.split(',').map((s) => s.trim()).filter(Boolean),
+            parallelismHint: opts.parallelismHint,
+            exitPolicy: opts.exitPolicy,
+            mainLoopStrategy: opts.mainLoopStrategy,
+            rotateEvery: Number(opts.rotateEvery),
+            project,
+            json: opts.json,
+        });
+        if (!parsed.success)
+            return printResult(io, fail('init', 'INVALID_INIT', parsed.error.message, {}), opts);
+        const jobRoot = resolveJobStateRoot(opts);
+        const store = new JobStateStore(jobRoot.rootDir);
+        const orch = new JobOrchestrator(store);
+        const state = orch.init({
+            jobId: parsed.data.jobId,
+            sessionId: parsed.data.sessionId,
+            sliceList: parsed.data.sliceList,
+            parallelismHint: parsed.data.parallelismHint,
+            exitPolicy: parsed.data.exitPolicy,
+            mainLoopStrategy: parsed.data.mainLoopStrategy,
+            rotateEvery: parsed.data.rotateEvery,
+        });
+        try {
+            emitJobEvent({ kind: 'job-started', jobId: state.jobId, total: state.slices.length, strategy: state.mainLoopStrategy });
+        }
+        catch (e) {
+            // best-effort: event emission failures must not abort job init
+            void e;
+        }
+        printResult(io, ok('init', { jobId: state.jobId, sliceCount: state.slices.length, statePath: `${jobRoot.rootDir}/${state.jobId}/state.json` }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'init'));
+    job
+        .command('status')
+        .requiredOption('--job-id <jid>')
+        .option('--watch', 'poll every 3s')
+        .option('--show-cost', 'overlay cost from peaks budget')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        const s = orch.status(opts.jobId);
+        if (opts.watch) {
+            const draw = () => {
+                const bar = `[${'='.repeat(s.done)}${' '.repeat(s.total - s.done)}]`;
+                process.stdout.write(`\rjob ${opts.jobId}: ${bar} ${s.done}/${s.total}${s.currentSlice ? ` next=${s.currentSlice}` : ''}    `);
+            };
+            draw();
+            const iv = setInterval(() => { const u = orch.status(opts.jobId); Object.assign(s, u); draw(); if (u.done + u.failed + u.skipped + u.blocked >= u.total)
+                clearInterval(iv); }, 3000);
+            process.on('SIGINT', () => { clearInterval(iv); process.stdout.write('\n'); process.exit(0); });
+            return;
+        }
+        try {
+            emitJobEvent({ kind: 'job-progress', jobId: opts.jobId, done: s.done, total: s.total, ...(s.currentSlice ? { currentSlice: s.currentSlice } : {}) });
+        }
+        catch (e) {
+            // best-effort: event emission failures must not abort job status
+            void e;
+        }
+        printResult(io, ok('status', s), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'status'));
+    // M4.2: wire rotate-now to JobRotation (session-rotate callbacks are stubs pending M6.5 batch-fix).
+    job.command('rotate-now')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const rotation = new JobRotation(store, async (_jid) => { /* delegate to peaks session rotate — implementation wired in M6.5 batch-fix */ return { rotated: true }; }, async (jid) => ({ jobId: jid, cycle: 0 }));
+        const r = await rotation.rotateNow(opts.jobId);
+        printResult(io, ok('rotate-now', r), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'rotate-now'));
+    job.command('subagent-cleanup')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--batch-id <bid>')
+        .option('--force')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const wrapper = new SubAgentJobWrapper(new JobStateStore(resolveJobStateRoot(opts).rootDir), async () => ({ batchId: opts.batchId }));
+        const r = await wrapper.cleanup({ jobId: opts.jobId, batchId: opts.batchId, force: !!opts.force });
+        printResult(io, ok('subagent-cleanup', r), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'subagent-cleanup'));
+    // M3.2: wire the remaining 5 subcommand slots — block, checkpoint, continue, handoff, resume.
+    job
+        .command('checkpoint')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--slice-id <rid>')
+        .requiredOption('--state <done|failed|skipped>')
+        .option('--commit-sha <sha>')
+        .option('--reason <text>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const parsed = JobCheckpointInputSchema.safeParse({
+            jobId: opts.jobId, sliceId: opts.sliceId, state: opts.state,
+            commitSha: opts.commitSha, reason: opts.reason,
+            project: projectRoot(opts), json: opts.json,
+        });
+        if (!parsed.success)
+            return printResult(io, fail('checkpoint', 'INVALID_CHECKPOINT', parsed.error.message, {}), opts);
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        if (parsed.data.state === 'done') {
+            await orch.checkpointDone({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, ...(parsed.data.commitSha ? { commitSha: parsed.data.commitSha } : {}) });
+        }
+        else if (parsed.data.state === 'skipped') {
+            await orch.checkpointSkipped({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, reason: parsed.data.reason });
+        }
+        else {
+            await orch.checkpointFailed({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, reason: parsed.data.reason });
+        }
+        printResult(io, ok('checkpoint', { sliceId: parsed.data.sliceId, status: parsed.data.state }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'checkpoint'));
+    job
+        .command('block')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--slice-id <rid>')
+        .requiredOption('--reason <text>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const parsed = JobBlockInputSchema.safeParse({
+            jobId: opts.jobId, sliceId: opts.sliceId, reason: opts.reason,
+            project: projectRoot(opts), json: opts.json,
+        });
+        if (!parsed.success)
+            return printResult(io, fail('block', 'INVALID_BLOCK', parsed.error.message, {}), opts);
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        await orch.blockSlice(parsed.data);
+        printResult(io, ok('block', { blocked: parsed.data.sliceId, reason: parsed.data.reason }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'block'));
+    job
+        .command('continue')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        const r = orch.continueNow(opts.jobId);
+        printResult(io, ok('continue', r), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'continue'));
+    job
+        .command('resume')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        const s = orch.status(opts.jobId);
+        printResult(io, ok('resume', { resumed: opts.jobId, ...s }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'resume'));
+    job
+        .command('handoff')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        const s = orch.status(opts.jobId);
+        printResult(io, ok('handoff', { handoffFor: opts.jobId, ...s }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'handoff'));
+    program.addCommand(job);
+}

package/dist/src/cli/commands/session-auto-compact-hook-command.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `peaks session auto-compact-hook` — slice 2026-07-02-auto-compact-zero-pause.
+ *
+ * The Bash entrypoint the PreToolUse hook fires on every Bash/Task
+ * tool call from the Claude Code runner. Behaviour:
+ *
+ *   1. Read `CLAUDE_CONTEXT_USAGE_PERCENT` (or any adapter-declared
+ *      env-var via the registry — claude-code MVP). If ratio is below
+ *      the red-line threshold (0.95), exit 0 silent — the runner's
+ *      normal flow continues.
+ *   2. If ratio is ≥ 0.95 (red line), write a one-line stderr hint
+ *      so the human sees what happened, then in-band spawn
+ *      `claude --compact` so the **current** runner's context
+ *      window collapses (not a new claude process).
+ *   3. Always exit 0. The hook is a probe, not a gate — the gate is
+ *      `claude --compact` itself returning 0.
+ *
+ * Idempotency: re-running the hook is safe; if `claude --compact`
+ * is already in flight, the new process just exits 0 immediately
+ * (Claude Code's compact is a one-shot operation against the
+ * current runner).
+ *
+ * Why a CLI subcommand instead of an inline JS hook:
+ *   - Keeps the hook payload in `.claude/settings.local.json` small
+ *     (one line: `peaks session auto-compact-hook`).
+ *   - Lets the heavy lifting (ratio parsing, IDE-aware env-var
+ *     resolution, spawning `claude --compact`) live in TypeScript
+ *     where it's unit-testable.
+ *   - Discoverable via `peaks session --help` — future LLM sessions
+ *     see the primitive exists.
+ *
+ * Karpathy §2: 50 lines, no abstractions, no speculative error
+ * handling. The hook command is a single-purpose muscle; if it
+ * grows beyond ~80 lines, that's a signal to split.
+ */
+import type { Command } from 'commander';
+export declare function registerSessionAutoCompactHookCommand(session: Command): void;

package/dist/src/cli/commands/session-auto-compact-hook-command.js

@@ -0,0 +1,127 @@
+/**
+ * `peaks session auto-compact-hook` — slice 2026-07-02-auto-compact-zero-pause.
+ *
+ * The Bash entrypoint the PreToolUse hook fires on every Bash/Task
+ * tool call from the Claude Code runner. Behaviour:
+ *
+ *   1. Read `CLAUDE_CONTEXT_USAGE_PERCENT` (or any adapter-declared
+ *      env-var via the registry — claude-code MVP). If ratio is below
+ *      the red-line threshold (0.95), exit 0 silent — the runner's
+ *      normal flow continues.
+ *   2. If ratio is ≥ 0.95 (red line), write a one-line stderr hint
+ *      so the human sees what happened, then in-band spawn
+ *      `claude --compact` so the **current** runner's context
+ *      window collapses (not a new claude process).
+ *   3. Always exit 0. The hook is a probe, not a gate — the gate is
+ *      `claude --compact` itself returning 0.
+ *
+ * Idempotency: re-running the hook is safe; if `claude --compact`
+ * is already in flight, the new process just exits 0 immediately
+ * (Claude Code's compact is a one-shot operation against the
+ * current runner).
+ *
+ * Why a CLI subcommand instead of an inline JS hook:
+ *   - Keeps the hook payload in `.claude/settings.local.json` small
+ *     (one line: `peaks session auto-compact-hook`).
+ *   - Lets the heavy lifting (ratio parsing, IDE-aware env-var
+ *     resolution, spawning `claude --compact`) live in TypeScript
+ *     where it's unit-testable.
+ *   - Discoverable via `peaks session --help` — future LLM sessions
+ *     see the primitive exists.
+ *
+ * Karpathy §2: 50 lines, no abstractions, no speculative error
+ * handling. The hook command is a single-purpose muscle; if it
+ * grows beyond ~80 lines, that's a signal to split.
+ */
+import { spawn } from 'node:child_process';
+import { detectIdeFromEnv } from '../../services/context/main-session-monitor.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+/**
+ * Red-line ratio threshold. Must match the orchestrator's
+ * AUTO_COMPACT_RED_LINE_RATIO constant (0.95). Kept here as a
+ * literal so the hook command stays self-contained — a future
+ * slice may move this to a shared constant module if the value
+ * starts drifting.
+ */
+const RED_LINE_RATIO = 0.95;
+/**
+ * Parse `CLAUDE_CONTEXT_USAGE_PERCENT` (or the adapter-declared
+ * env-var) into a ratio in [0, 1]. Returns null on missing /
+ * malformed input. Mirrors `readEnvPercent` in
+ * `auto-compact-reader.ts` so the hook command and the
+ * orchestrator agree on parsing semantics.
+ */
+function readRatioFromEnv(env) {
+    const detected = detectIdeFromEnv(env);
+    const ideId = (detected === 'unknown' ? 'claude-code' : detected);
+    const adapter = getAdapter(ideId);
+    if (!adapter.compact)
+        return null;
+    const varName = adapter.compact.envVarForContextPercent;
+    const raw = env[varName];
+    if (typeof raw !== 'string' || raw.length === 0)
+        return null;
+    const parsed = Number.parseFloat(raw);
+    if (!Number.isFinite(parsed))
+        return null;
+    // Allow either "0..1" or "0..100" encoding. Claude Code writes
+    // "0..1" today; statusline tools sometimes write "0..100". Normalize.
+    const ratio = parsed > 1.5 ? parsed / 100 : Math.max(0, Math.min(1, parsed));
+    return { ratio, varName };
+}
+export function registerSessionAutoCompactHookCommand(session) {
+    session
+        .command('auto-compact-hook')
+        .description('PreToolUse hook entrypoint — read CLAUDE_CONTEXT_USAGE_PERCENT and, ' +
+        'at ratio ≥ 0.95, in-band spawn `claude --compact` against the current ' +
+        'runner. Designed for invocation from `.claude/settings.local.json` ' +
+        'PreToolUse hooks; safe to re-run.')
+        .action(() => {
+        const probe = readRatioFromEnv(process.env);
+        if (probe === null) {
+            // No signal → exit 0 silent. The hook must never block the
+            // runner's normal flow on a missing env-var.
+            return;
+        }
+        if (probe.ratio < RED_LINE_RATIO) {
+            // Below red line → exit 0 silent. The orchestrator's
+            // pre-compact zone (0.85–0.95) is handled out-of-band by
+            // the LLM firing `peaks solo auto-compact --execute`; the
+            // hook only fires on the synchronous red-line path.
+            return;
+        }
+        // Red line reached — compact the current runner in-band.
+        // The `detached: true` + `unref()` pair lets the hook return
+        // immediately while Claude Code's own slash-command processor
+        // picks up `claude --compact` against the runner's session.
+        // This is the fix for the shell-exec-spawns-a-child-process
+        // bug documented in `.peaks/memory/2026-06-27-auto-compact-design.md:139-152`.
+        //
+        // Dogfood 2026-07-02 fix: when `claude` is not on PATH (the
+        // user runs Claude Code as an MCP rather than via the CLI
+        // binary), `spawn` raises ENOENT. Catching this MUST NOT crash
+        // the runner's tool call — the hook must exit 0 silently with
+        // a one-line stderr hint so the runner keeps working. The user
+        // can then run `/compact` manually (or `peaks solo auto-compact`
+        // from another terminal).
+        try {
+            const child = spawn('claude', ['--compact'], {
+                stdio: 'ignore',
+                detached: true,
+                env: process.env
+            });
+            child.on('error', () => {
+                // Spawn failed (ENOENT or EPERM). Exit 0 silently with a
+                // stderr hint — the hook contract is "never crash the
+                // runner's tool call".
+                process.stderr.write('[peaks:auto-compact-hook] claude CLI not on PATH; cannot fire in-band. Run `/compact` manually or set up the Claude Code CLI binary.\n');
+            });
+            child.unref();
+            process.stderr.write(`[peaks:auto-compact-hook] ratio=${(probe.ratio * 100).toFixed(1)}% ≥ ${(RED_LINE_RATIO * 100).toFixed(0)}%; firing claude --compact in-band\n`);
+        }
+        catch {
+            // Defensive: `spawn` can throw synchronously on some platforms.
+            process.stderr.write('[peaks:auto-compact-hook] failed to spawn claude --compact; run `/compact` manually.\n');
+        }
+    });
+}

package/dist/src/cli/program.js

@@ -74,6 +74,8 @@ import { registerObservabilityCommands } from './commands/observability-commands
 // CLI primitives. See src/services/compact/ and
 // src/cli/commands/compact-command.ts.
 import { registerCompactCommands } from './commands/compact-command.js';
+// Slice 2026-07-01-job-m3.1: `peaks job init|status|...` — Job orchestration CLI surface.
+import { registerJobCommands } from './commands/job-commands.js';
 import { applyRetention } from '../services/log/retention.js';
 import { writeLogEntry, maybeWriteStderr } from '../services/log/logger.js';
 export { printResult } from './cli-helpers.js';
@@ -341,5 +343,9 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     // suggest|recommend|survival|dry-run|force` — strategic-compact CLI
     // primitives. See src/cli/commands/compact-command.ts.
     registerCompactCommands(program, io);
+    // Slice 2026-07-01-job-m3.1: `peaks job init|status|...` — Job
+    // orchestration CLI surface. M3.1 wires init + status + 2 stubs;
+    // the remaining 5 subcommands land in M3.2.
+    registerJobCommands(program, io);
     return program;
 }

package/dist/src/services/context/auto-compact-dispatcher.js

@@ -100,16 +100,36 @@ export async function dispatchIdeCompact(input) {
                 timeoutMs
             });
         case 'ide-native':
-            // Future slice: write the compact intent to the IDE's hook
-            // file (per `IdeSettingsLocation`). For v2.13.0 MVP the
-            // shell-exec pathway covers Claude Code; this branch stays
-            // reserved.
-            return {
-                ok: false,
-                ide: ideId,
-                pathway: 'ide-native',
-                message: `ide-native compact pathway is reserved for a future slice; adapter '${ideId}' should declare shell-exec or llm-self-compress for now.`
-            };
+            // Slice 2026-07-02-auto-compact-zero-pause: write the auto-compact
+            // PreToolUse hook into `.claude/settings.local.json`. The hook
+            // command (`peaks session auto-compact-hook`) reads
+            // `CLAUDE_CONTEXT_USAGE_PERCENT` on every subsequent Bash/Task
+            // tool call from the runner and, at ratio ≥ 0.95, in-band spawns
+            // `claude --compact` against the CURRENT runner (not a child
+            // process — the bug documented in
+            // `.peaks/memory/2026-06-27-auto-compact-design.md:139-152`).
+            //
+            // `ide-native` is ONLY for the main-session runner. When the
+            // caller is a sub-agent shell (which has its own ephemeral
+            // context window — not the runner's), fall through to
+            // shell-exec so the sub-agent's `compactCommand` spawns a
+            // child claude process and the sub-agent's own runner doesn't
+            // get a PreToolUse hook installed in the wrong place.
+            if (target === 'sub-agent') {
+                return await dispatchShellExec({
+                    ideId,
+                    command: profile.compactCommand,
+                    timeoutMs
+                });
+            }
+            // Lazy install: we only get here when the caller explicitly
+            // invokes `peaks solo auto-compact --execute`, so the user has
+            // already opted in. No zero-touch surprise on workspace init.
+            return await dispatchIdeNativeHook({
+                projectRoot: input.projectRoot,
+                sessionId: input.sessionId,
+                target
+            });
         case 'llm-self-compress':
             return {
                 ok: true,
@@ -188,3 +208,33 @@ function dispatchShellExec(input) {
         });
     });
 }
+/**
+ * Slice 2026-07-02-auto-compact-zero-pause: implement the
+ * `ide-native` pathway. Writes the auto-compact PreToolUse hook
+ * into `.claude/settings.local.json` (idempotent; the install
+ * service is a no-op if the hook is already present). On the next
+ * Bash/Task tool call from the runner, the hook fires
+ * `peaks session auto-compact-hook` which in-band spawns
+ * `claude --compact` against the CURRENT runner session.
+ *
+ * Returns `ok: true, pathway: 'ide-native'` regardless of install
+ * action (`installed` vs `already-installed`) — both states
+ * achieve the operational goal: the hook is wired and the next
+ * Bash call will trigger it.
+ */
+async function dispatchIdeNativeHook(input) {
+    // Lazy dynamic import — matches the existing pattern in
+    // `runAutoCompact` for `auto-compact-reader.ts` (line 311) and
+    // avoids a static cycle if future slices add cross-imports
+    // between dispatcher and hook-install.
+    const { installAutoCompactHook } = await import('../hooks/auto-compact-hook-install.js');
+    const result = installAutoCompactHook({ projectRoot: input.projectRoot });
+    return {
+        ok: true,
+        ide: 'claude-code',
+        pathway: 'ide-native',
+        message: result.action === 'installed'
+            ? `Auto-compact PreToolUse hook installed at ${result.settingsPath}. Next Bash/Task tool call will read CLAUDE_CONTEXT_USAGE_PERCENT and compact in-band at ratio ≥ 95%.`
+            : `Auto-compact PreToolUse hook already installed at ${result.settingsPath}; next Bash/Task tool call will trigger compact in-band at ratio ≥ 95%.`
+    };
+}

package/dist/src/services/context/main-session-monitor.d.ts

@@ -56,6 +56,18 @@ export declare function detectIdeFromEnv(env?: NodeJS.ProcessEnv): IdeKind;
  * Threshold check. Pure function (no IO). `capacityBytes` is injectable
  * for tests and future per-IDE capacity overrides. Defaults to the
  * G9 256K proxy (matches G9 for cognitive continuity).
+ *
+ * @deprecated Slice 2026-07-02-auto-compact-zero-pause: the
+ * 50/75/90 tier thresholds pre-date the v2.13.0 auto-compact
+ * design. The authoritative tier table for triggering compaction
+ * now lives in `evaluateCompactTrigger` (auto-compact-orchestrator.ts)
+ * with the 0.85 pre-compact / 0.95 red-line thresholds. New
+ * callers should call `evaluateCompactTrigger(ratio)` directly.
+ * This function is retained because legacy `peaks context check
+ * --prompt-size` still emits its 4-tier envelope for callers that
+ * need the soft signal (e.g. statusline display). Migration is
+ * scheduled for v2.15.0; the @deprecated tag flips callers'
+ * eslint warnings so the migration is mechanical.
  */
 export declare function evaluateMainSessionThreshold(promptSize: number, capacityBytes?: number): MainSessionEvaluation;
 export interface InFlightBatchProbe {