peaks-loop-internal-runtime 0.0.31 → 0.0.33

package/dist/auto-compact-adapter.d.ts

@@ -1,8 +1,18 @@
 import type { AutoCompactEvent } from './status-protocol.js';
+/**
+ * `vendorWindow` is OPTIONAL and, when absent, the attribute is omitted.
+ *
+ * Why it is not defaulted: this used to be filled in by the caller with
+ * `adapter.maxPromptBytes / 40` (204.8 for the claude adapter) — a number that
+ * is not a context window, handed to a child that was then told to measure "85%
+ * of" it. A fabricated denominator is worse than none, because the child cannot
+ * tell that it is fabricated. When the caller genuinely knows the window it is
+ * still carried verbatim (E5, rid 2026-09-13-defects-e).
+ */
 export interface MarkerOpts {
     rid: string;
     sid: string;
-    vendorWindow: number;
+    vendorWindow?: number;
 }
 export interface ScratchPayload {
     seq: number;
@@ -11,6 +21,35 @@ export interface ScratchPayload {
     decisionsKept?: string[];
     discardedOptions?: string[];
 }
+/**
+ * The `<peaks-auto-compact>` marker injected at the head of a detached child's
+ * prompt.
+ *
+ * REWRITTEN IN E5 (rid 2026-09-13-defects-e). The previous text assigned the
+ * child three capabilities it does not have, and the third of them was not even
+ * a registered command:
+ *
+ *   1. "主动 compact 自己的会话" — a model cannot compact its own session. `/compact`
+ *      is not model-invokable, hooks may only observe or veto, there is no
+ *      `--compact` flag, and no external process can reach a running session's
+ *      memory. The HARNESS compacts, on its own window and its own schedule.
+ *   2. "把摘要 + 当前任务状态拼回 prompt 头部" — the child's prompt IS the `-p` argv
+ *      string built at spawn time; `ClaudeAdapter.headlessArgs` prepends this
+ *      very marker to it. Nothing rewrites it afterwards: `dispatchDetached` is
+ *      fire-and-forget and the spawning CLI exits, so there is no re-assembly
+ *      step in this process or any other.
+ *   3. "调用 peaks runtime write-compact-event CLI 记录事件" — no such verb exists.
+ *      `peaks runtime` registers `detect` / `list` / `compact` and nothing else.
+ *
+ * The failure mode was worse than useless: at exactly the moment the child's
+ * context is nearly full, it was told to spend what remained on an instruction
+ * that could not succeed, and to believe it had.
+ *
+ * What survives is the part that IS reachable and useful: the child can write
+ * durable state to disk. That is stated as the action, together with the plain
+ * negative — nothing flows back into its context — so the child neither wastes
+ * effort on the impossible nor mistakes a written file for a restored context.
+ */
 export declare class AutoCompactAdapter {
     marker(opts: MarkerOpts): string;
     parseScratchFile(p: ScratchPayload): Partial<AutoCompactEvent>;

package/dist/auto-compact-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auto-compact-adapter.d.ts","sourceRoot":"","sources":["../src/auto-compact-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,MAAM,WAAW,UAAU;IAAG,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;CAAE;AAC/E,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IACzC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CACvD;AAED,qBAAa,kBAAkB;IAC7B,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM;IAiBhC,gBAAgB,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAG/D"}
+{"version":3,"file":"auto-compact-adapter.d.ts","sourceRoot":"","sources":["../src/auto-compact-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IAAG,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAAE;AAChF,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IACzC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,kBAAkB;IAC7B,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM;IAuBhC,gBAAgB,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAG/D"}

package/dist/auto-compact-adapter.js

@@ -1,17 +1,52 @@
+/**
+ * The `<peaks-auto-compact>` marker injected at the head of a detached child's
+ * prompt.
+ *
+ * REWRITTEN IN E5 (rid 2026-09-13-defects-e). The previous text assigned the
+ * child three capabilities it does not have, and the third of them was not even
+ * a registered command:
+ *
+ *   1. "主动 compact 自己的会话" — a model cannot compact its own session. `/compact`
+ *      is not model-invokable, hooks may only observe or veto, there is no
+ *      `--compact` flag, and no external process can reach a running session's
+ *      memory. The HARNESS compacts, on its own window and its own schedule.
+ *   2. "把摘要 + 当前任务状态拼回 prompt 头部" — the child's prompt IS the `-p` argv
+ *      string built at spawn time; `ClaudeAdapter.headlessArgs` prepends this
+ *      very marker to it. Nothing rewrites it afterwards: `dispatchDetached` is
+ *      fire-and-forget and the spawning CLI exits, so there is no re-assembly
+ *      step in this process or any other.
+ *   3. "调用 peaks runtime write-compact-event CLI 记录事件" — no such verb exists.
+ *      `peaks runtime` registers `detect` / `list` / `compact` and nothing else.
+ *
+ * The failure mode was worse than useless: at exactly the moment the child's
+ * context is nearly full, it was told to spend what remained on an instruction
+ * that could not succeed, and to believe it had.
+ *
+ * What survives is the part that IS reachable and useful: the child can write
+ * durable state to disk. That is stated as the action, together with the plain
+ * negative — nothing flows back into its context — so the child neither wastes
+ * effort on the impossible nor mistakes a written file for a restored context.
+ */
 export class AutoCompactAdapter {
     marker(opts) {
+        const windowAttr = opts.vendorWindow === undefined ? '' : ` vendor-window="${opts.vendorWindow}"`;
         return [
-            `<peaks-auto-compact threshold="0.85|0.95" vendor-window="${opts.vendorWindow}">`,
-            `协议：`,
-            `- 你（子进程 LLM）估算自己已用上下文 ≥ 85% vendor window`,
-            `  → 主动 compact 自己的会话：把对话历史摘要写到`,
-            `    .peaks/_runtime/${opts.sid}/detached/${opts.rid}/compact/<n>.json`,
-            `  → 把摘要 + 当前任务状态拼回 prompt 头部`,
-            `  → 调用 peaks runtime write-compact-event CLI 记录事件`,
-            `- 当 ≥ 95% → 同步 compact + 立刻通知 peaks 主进程`,
-            `  （写 status.json note: 'compact-emergency'）`,
-            `- 不要等 peaks 主进程来催；子进程 LLM 自己监控自己的 context`,
-            `- 不限费用（用户授权）—— compact 本身消耗的 token 随它去`,
+            `<peaks-auto-compact threshold="0.85|0.95"${windowAttr}>`,
+            `上下文续命协议（如实版 —— 只写你确实能做的事）：`,
+            `- 你的会话由 vendor harness（Claude Code 自己）压缩：它按自己的 auto-compact window 触发，`,
+            `  到点直接压，不需要你请求，也无法被你触发。peaks-loop 不能压缩一个正在运行的会话 ——`,
+            `  没有模型可调用的 compact，外部进程也触及不到你的会话内存。`,
+            `  → 所以这里没有让你自己压缩会话的入口，也不要声称做过。`,
+            `- 你能做、也必须做的是「在被压缩之前把不能丢的东西落到磁盘」：`,
+            `  1) 摘要 + 当前任务状态 + 已定决策 + 已弃选项，写到`,
+            `     .peaks/_runtime/${opts.sid}/detached/${opts.rid}/compact/<n>.json`,
+            `     （<n> 从 1 递增；每次新增一个文件，不要改写已有的）`,
+            `  2) 进度 / 心跳照常写 status.json（progress / state / note）`,
+            `- 你的 prompt 在 spawn 时已经固定，没有任何机制能把摘要拼回它。写进文件里的东西`,
+            `  是给 peaks 主进程和人看的进度证据，不会回流到你的上下文。`,
+            `- 这些文件由你自己维护：不要等 peaks 主进程来催，它不会替你写。`,
+            `- token 费用：peaks-loop 不设费用上限、也不因费用中断你（没有费用闸门）。`,
+            `  这不对应任何 flag —— 它是 peaks-loop 没有做的事，不是一条你能引用的授权。`,
             `</peaks-auto-compact>`,
         ].join('\n');
     }

package/dist/dispatch.d.ts

@@ -15,6 +15,13 @@ export interface DispatchResult {
     pid: number;
     dispatchRecordPath: string;
     child?: ChildProcess;
+    /**
+     * Typed launch failure, or `null` when the vendor CLI started. A vendor CLI
+     * that is not installed is an expected environment, not a crash: the ENOENT
+     * used to surface as an unhandled 'error' event (see ProcessSupervisor.spawn)
+     * and escape every awaiting caller's promise chain.
+     */
+    spawnError: NodeJS.ErrnoException | null;
 }
 export declare function dispatchDetached(i: DispatchInput): Promise<DispatchResult>;
 //# sourceMappingURL=dispatch.d.ts.map

package/dist/dispatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAYvD,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,GAAC,IAAI,GAAC,IAAI,GAAC,KAAK,GAAC,iBAAiB,CAAC;IACvE,MAAM,EAAE,QAAQ,GAAC,OAAO,GAAC,SAAS,CAAC;IACnC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAClD,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IACzC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AACD,MAAM,WAAW,cAAc;IAAG,GAAG,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,YAAY,CAAC;CAAE;AAElG,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAsChF"}
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAYvD,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,GAAC,IAAI,GAAC,IAAI,GAAC,KAAK,GAAC,iBAAiB,CAAC;IACvE,MAAM,EAAE,QAAQ,GAAC,OAAO,GAAC,SAAS,CAAC;IACnC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAClD,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IACzC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AACD,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,kBAAkB,EAAE,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC;CAC1C;AAED,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAqDhF"}

package/dist/dispatch.js

@@ -15,7 +15,14 @@ export async function dispatchDetached(i) {
         throw new Error(`vendor adapter not registered: ${i.vendor}`);
     const pb = new PromptBuilder();
     const ac = new AutoCompactAdapter();
-    const marker = ac.marker({ rid: i.rid, sid: i.sid, vendorWindow: adapter.maxPromptBytes / 40 /* rough */ });
+    // E5 (rid 2026-09-13-defects-e): the marker used to carry
+    // `adapter.maxPromptBytes / 40` as its `vendor-window` — 204.8 for the claude
+    // adapter. That is not a context window (it is a prompt BYTE budget divided by
+    // forty), and the child was then told to measure "85% of" it, with no way to
+    // tell the number was fabricated. peaks-loop does not know the child's window
+    // here — the child's own harness owns it — so the attribute is omitted rather
+    // than invented.
+    const marker = ac.marker({ rid: i.rid, sid: i.sid });
     const prompt = pb.assemble({
         rid: i.rid, role: i.role, vendor: i.vendor,
         files: i.files, refs: i.refs, userTask: i.userTask,
@@ -32,13 +39,21 @@ export async function dispatchDetached(i) {
     // no-op (ProcessSupervisor forces detached:false). Pass `false` to
     // reflect the post-F2 contract explicitly.
     const handle = await sup.spawn(adapter.binary, args, { detach: false, rid: i.rid });
+    // `settled` never rejects; it carries the launch outcome as a value. Awaiting
+    // it here is what makes a missing vendor CLI an assertable result rather than
+    // an exception thrown from outside this function's promise chain.
+    const spawnError = (await handle.settled) ?? null;
     lo.register(handle.pid, i.rid, i.sid);
     // Write dispatch record (placeholder — final shape per Task 8 schema)
     const recPath = join(i.subAgentsDir, `dispatch-${i.rid}-${Date.now()}.json`);
     mkdirSync(i.subAgentsDir, { recursive: true });
     writeFileSync(recPath, JSON.stringify({
         rid: i.rid, mode: 'detached', vendor: i.vendor,
-        status: 'running', heartbeats: [], at: Date.now(),
+        // The record must not claim a child is running when the launch failed —
+        // that is the on-disk form of "looks green, checked nothing".
+        status: spawnError ? 'failed' : 'running',
+        ...(spawnError ? { spawnError: { code: spawnError.code, message: spawnError.message } } : {}),
+        heartbeats: [], at: Date.now(),
     }, null, 2));
-    return { pid: handle.pid, dispatchRecordPath: recPath, child: handle.child };
+    return { pid: handle.pid, dispatchRecordPath: recPath, child: handle.child, spawnError };
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const RUNTIME_VERSION = "4.0.46";
+export declare const RUNTIME_VERSION = "4.0.48";
 export declare const RUNTIME_NPM_VERSION = "0.0.21";
 export { ClaudeAdapter } from './vendor/claude-adapter.js';
 export { CodexAdapter } from './vendor/codex-adapter.js';

package/dist/index.js

@@ -1,7 +1,7 @@
 // API contract: RUNTIME_VERSION tracks peaks-loop root version (4.0.x).
 // This is what consumers (sub-agents dispatched by peaks-code) check at
 // runtime to verify protocol compatibility.
-export const RUNTIME_VERSION = '4.0.46';
+export const RUNTIME_VERSION = '4.0.48';
 // npm version: independent 0.0.x SemVer. Runtime is its own package
 // (peaks-loop-internal-runtime@NPM_VERSION) on the registry; bumps
 // per peaks release notes when its public surface actually changes

package/dist/process-supervisor.d.ts

@@ -17,6 +17,15 @@ export interface SpawnHandle {
     pid: number;
     child: ChildProcess;
     kill(signal?: NodeJS.Signals): void;
+    /**
+     * Resolves once the OS confirms the launch (`'spawn'`) or the launch fails
+     * (`'error'`). Never rejects: `null` means the process is running; a launch
+     * failure resolves to the otherwise-unhandled ErrnoException (ENOENT when the
+     * vendor CLI is not installed). The listener that settles this is attached
+     * synchronously in `spawn()` — see the comment there for why no caller can
+     * attach one in time.
+     */
+    settled: Promise<NodeJS.ErrnoException | null>;
 }
 export declare class ProcessSupervisor {
     private readonly cfg;

package/dist/process-supervisor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-supervisor.d.ts","sourceRoot":"","sources":["../src/process-supervisor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,YAAY,EAAqB,MAAM,oBAAoB,CAAC;AAIzF,MAAM,WAAW,SAAS;IACxB;;;;;;;;OAQG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;CAC3B;AACD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;CACrC;AAED,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE;IAElD,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;CA+BnF"}
+{"version":3,"file":"process-supervisor.d.ts","sourceRoot":"","sources":["../src/process-supervisor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,YAAY,EAAqB,MAAM,oBAAoB,CAAC;AAIzF,MAAM,WAAW,SAAS;IACxB;;;;;;;;OAQG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;CAC3B;AACD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IACpC;;;;;;;OAOG;IACH,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;CAChD;AAED,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE;IAElD,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;CAiEnF"}

package/dist/process-supervisor.js

@@ -23,16 +23,48 @@ export class ProcessSupervisor {
             // Suppress the popup console window on Windows without changing
             // process group membership. The child is still part of the
             // parent's process group (no Windows process-group detach flag).
+            // Deliberately NOT set on POSIX — pinned by
+            // `tests/unit/runtime/process-supervisor-in-shell.test.ts` 1a/1b,
+            // which assert this platform split by name. The spawn-hygiene guard
+            // reads this assignment form; see `collectWindowsHideAssignments`.
             spawnOpts.windowsHide = true;
         }
         const child = nodeSpawn(binary, args, spawnOpts);
+        // Attach the 'error' listener in the SAME synchronous turn the child is
+        // created, because no caller can do it in time. A missing binary does not
+        // throw from spawn(): Node emits it asynchronously as an 'error' event, and
+        // an EventEmitter with no 'error' listener re-throws it as a process-level
+        // uncaught exception. That emission runs on the nextTick queue, which
+        // drains BEFORE the awaiting caller resumes — so the documented caller-side
+        // pattern (`await spawn(...); child.on('error', …)`) loses the race by
+        // construction, whatever caller writes it. Capturing it here turns the
+        // failure into a typed value on `settled` and removes the crash.
+        const settled = new Promise((resolve) => {
+            child.on('error', (err) => resolve(err));
+            child.on('spawn', () => resolve(null));
+        });
         const dir = join(this.cfg.runtimeDir, opts.rid);
         mkdirSync(dir, { recursive: true });
-        writeFileSync(join(dir, 'pid'), String(child.pid ?? ''));
+        // `<rid>/pid` exists IFF a real OS process was launched. `child.pid` is
+        // `undefined` until the OS confirms the spawn, so a failed launch used to
+        // write `String(undefined ?? '')` — an EMPTY pid file. That is not a
+        // cosmetic wart: `Number('')` is `0`, so a cleanup path doing
+        // `kill(Number(readFileSync(pid)))` would send its signal to pid 0 (the
+        // whole process group), and an existence check for "is something running
+        // here" reads `true` for a launch that never happened.
+        //
+        // Nothing is lost by omitting it: the launch failure is recorded as a
+        // VALUE on the dispatch record (`status: 'failed'` + `spawnError`), which
+        // is the surface a reader should consult. Absence in the pid file is the
+        // one encoding that cannot be misread as a pid.
+        if (child.pid !== undefined) {
+            writeFileSync(join(dir, 'pid'), String(child.pid));
+        }
         return {
             pid: child.pid ?? -1,
             child,
             kill: (signal = 'SIGTERM') => child.kill(signal),
+            settled,
         };
     }
 }

package/dist/vendor/detect-binary.js

@@ -4,7 +4,7 @@ const DETECT_TIMEOUT_MS = 3000;
 export function detectBinaryInstalled(binary) {
     const locator = process.platform === 'win32' ? 'where.exe' : 'which';
     return new Promise((resolve) => {
-        execFile(locator, [binary], { timeout: DETECT_TIMEOUT_MS }, (error, stdout) => {
+        execFile(locator, [binary], { timeout: DETECT_TIMEOUT_MS, windowsHide: true }, (error, stdout) => {
             resolve(error === null && stdout.trim().length > 0);
         });
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop-internal-runtime",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "description": "Detached sub-agent runtime: ProcessSupervisor + LifecycleOwner + VendorAdapter (claude/codex/copilot) + G8 infinite-context auto-compact. Slice 2026-08-10.",
   "repository": {
     "type": "git",
@@ -16,7 +16,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "peaks-loop-shared": "0.0.80"
+    "peaks-loop-shared": "0.0.82"
   },
   "devDependencies": {
     "typescript": "^5.4.0",

package/src/auto-compact-adapter.ts

@@ -1,25 +1,70 @@
 import type { AutoCompactEvent } from './status-protocol.js';
 
-export interface MarkerOpts { rid: string; sid: string; vendorWindow: number; }
+/**
+ * `vendorWindow` is OPTIONAL and, when absent, the attribute is omitted.
+ *
+ * Why it is not defaulted: this used to be filled in by the caller with
+ * `adapter.maxPromptBytes / 40` (204.8 for the claude adapter) — a number that
+ * is not a context window, handed to a child that was then told to measure "85%
+ * of" it. A fabricated denominator is worse than none, because the child cannot
+ * tell that it is fabricated. When the caller genuinely knows the window it is
+ * still carried verbatim (E5, rid 2026-09-13-defects-e).
+ */
+export interface MarkerOpts { rid: string; sid: string; vendorWindow?: number; }
 export interface ScratchPayload {
   seq: number; at: number; summary: string;
   decisionsKept?: string[]; discardedOptions?: string[];
 }
 
+/**
+ * The `<peaks-auto-compact>` marker injected at the head of a detached child's
+ * prompt.
+ *
+ * REWRITTEN IN E5 (rid 2026-09-13-defects-e). The previous text assigned the
+ * child three capabilities it does not have, and the third of them was not even
+ * a registered command:
+ *
+ *   1. "主动 compact 自己的会话" — a model cannot compact its own session. `/compact`
+ *      is not model-invokable, hooks may only observe or veto, there is no
+ *      `--compact` flag, and no external process can reach a running session's
+ *      memory. The HARNESS compacts, on its own window and its own schedule.
+ *   2. "把摘要 + 当前任务状态拼回 prompt 头部" — the child's prompt IS the `-p` argv
+ *      string built at spawn time; `ClaudeAdapter.headlessArgs` prepends this
+ *      very marker to it. Nothing rewrites it afterwards: `dispatchDetached` is
+ *      fire-and-forget and the spawning CLI exits, so there is no re-assembly
+ *      step in this process or any other.
+ *   3. "调用 peaks runtime write-compact-event CLI 记录事件" — no such verb exists.
+ *      `peaks runtime` registers `detect` / `list` / `compact` and nothing else.
+ *
+ * The failure mode was worse than useless: at exactly the moment the child's
+ * context is nearly full, it was told to spend what remained on an instruction
+ * that could not succeed, and to believe it had.
+ *
+ * What survives is the part that IS reachable and useful: the child can write
+ * durable state to disk. That is stated as the action, together with the plain
+ * negative — nothing flows back into its context — so the child neither wastes
+ * effort on the impossible nor mistakes a written file for a restored context.
+ */
 export class AutoCompactAdapter {
   marker(opts: MarkerOpts): string {
+    const windowAttr = opts.vendorWindow === undefined ? '' : ` vendor-window="${opts.vendorWindow}"`;
     return [
-      `<peaks-auto-compact threshold="0.85|0.95" vendor-window="${opts.vendorWindow}">`,
-      `协议：`,
-      `- 你（子进程 LLM）估算自己已用上下文 ≥ 85% vendor window`,
-      `  → 主动 compact 自己的会话：把对话历史摘要写到`,
-      `    .peaks/_runtime/${opts.sid}/detached/${opts.rid}/compact/<n>.json`,
-      `  → 把摘要 + 当前任务状态拼回 prompt 头部`,
-      `  → 调用 peaks runtime write-compact-event CLI 记录事件`,
-      `- 当 ≥ 95% → 同步 compact + 立刻通知 peaks 主进程`,
-      `  （写 status.json note: 'compact-emergency'）`,
-      `- 不要等 peaks 主进程来催；子进程 LLM 自己监控自己的 context`,
-      `- 不限费用（用户授权）—— compact 本身消耗的 token 随它去`,
+      `<peaks-auto-compact threshold="0.85|0.95"${windowAttr}>`,
+      `上下文续命协议（如实版 —— 只写你确实能做的事）：`,
+      `- 你的会话由 vendor harness（Claude Code 自己）压缩：它按自己的 auto-compact window 触发，`,
+      `  到点直接压，不需要你请求，也无法被你触发。peaks-loop 不能压缩一个正在运行的会话 ——`,
+      `  没有模型可调用的 compact，外部进程也触及不到你的会话内存。`,
+      `  → 所以这里没有让你自己压缩会话的入口，也不要声称做过。`,
+      `- 你能做、也必须做的是「在被压缩之前把不能丢的东西落到磁盘」：`,
+      `  1) 摘要 + 当前任务状态 + 已定决策 + 已弃选项，写到`,
+      `     .peaks/_runtime/${opts.sid}/detached/${opts.rid}/compact/<n>.json`,
+      `     （<n> 从 1 递增；每次新增一个文件，不要改写已有的）`,
+      `  2) 进度 / 心跳照常写 status.json（progress / state / note）`,
+      `- 你的 prompt 在 spawn 时已经固定，没有任何机制能把摘要拼回它。写进文件里的东西`,
+      `  是给 peaks 主进程和人看的进度证据，不会回流到你的上下文。`,
+      `- 这些文件由你自己维护：不要等 peaks 主进程来催，它不会替你写。`,
+      `- token 费用：peaks-loop 不设费用上限、也不因费用中断你（没有费用闸门）。`,
+      `  这不对应任何 flag —— 它是 peaks-loop 没有做的事，不是一条你能引用的授权。`,
       `</peaks-auto-compact>`,
     ].join('\n');
   }
@@ -27,4 +72,4 @@ export class AutoCompactAdapter {
   parseScratchFile(p: ScratchPayload): Partial<AutoCompactEvent> {
     return { at: p.at, threshold: '0.85', tokensBefore: 0, tokensAfter: 0 };
   }
-}
+}

package/src/dispatch.ts

@@ -19,7 +19,18 @@ export interface DispatchInput {
   runtimeDir: string; subAgentsDir: string;
   verbatimBlocks?: string[];
 }
-export interface DispatchResult { pid: number; dispatchRecordPath: string; child?: ChildProcess; }
+export interface DispatchResult {
+  pid: number;
+  dispatchRecordPath: string;
+  child?: ChildProcess;
+  /**
+   * Typed launch failure, or `null` when the vendor CLI started. A vendor CLI
+   * that is not installed is an expected environment, not a crash: the ENOENT
+   * used to surface as an unhandled 'error' event (see ProcessSupervisor.spawn)
+   * and escape every awaiting caller's promise chain.
+   */
+  spawnError: NodeJS.ErrnoException | null;
+}
 
 export async function dispatchDetached(i: DispatchInput): Promise<DispatchResult> {
   const registry = new VendorAdapterRegistry([new ClaudeAdapter(), new CodexAdapter(), new CopilotAdapter()]);
@@ -28,7 +39,14 @@ export async function dispatchDetached(i: DispatchInput): Promise<DispatchResult
 
   const pb = new PromptBuilder();
   const ac = new AutoCompactAdapter();
-  const marker = ac.marker({ rid: i.rid, sid: i.sid, vendorWindow: adapter.maxPromptBytes / 40 /* rough */ });
+  // E5 (rid 2026-09-13-defects-e): the marker used to carry
+  // `adapter.maxPromptBytes / 40` as its `vendor-window` — 204.8 for the claude
+  // adapter. That is not a context window (it is a prompt BYTE budget divided by
+  // forty), and the child was then told to measure "85% of" it, with no way to
+  // tell the number was fabricated. peaks-loop does not know the child's window
+  // here — the child's own harness owns it — so the attribute is omitted rather
+  // than invented.
+  const marker = ac.marker({ rid: i.rid, sid: i.sid });
   const prompt = pb.assemble({
     rid: i.rid, role: i.role, vendor: i.vendor,
     files: i.files, refs: i.refs, userTask: i.userTask,
@@ -48,6 +66,10 @@ export async function dispatchDetached(i: DispatchInput): Promise<DispatchResult
   // no-op (ProcessSupervisor forces detached:false). Pass `false` to
   // reflect the post-F2 contract explicitly.
   const handle = await sup.spawn(adapter.binary, args, { detach: false, rid: i.rid });
+  // `settled` never rejects; it carries the launch outcome as a value. Awaiting
+  // it here is what makes a missing vendor CLI an assertable result rather than
+  // an exception thrown from outside this function's promise chain.
+  const spawnError = (await handle.settled) ?? null;
   lo.register(handle.pid, i.rid, i.sid);
 
   // Write dispatch record (placeholder — final shape per Task 8 schema)
@@ -55,8 +77,12 @@ export async function dispatchDetached(i: DispatchInput): Promise<DispatchResult
   mkdirSync(i.subAgentsDir, { recursive: true });
   writeFileSync(recPath, JSON.stringify({
     rid: i.rid, mode: 'detached', vendor: i.vendor,
-    status: 'running', heartbeats: [], at: Date.now(),
+    // The record must not claim a child is running when the launch failed —
+    // that is the on-disk form of "looks green, checked nothing".
+    status: spawnError ? 'failed' : 'running',
+    ...(spawnError ? { spawnError: { code: spawnError.code, message: spawnError.message } } : {}),
+    heartbeats: [], at: Date.now(),
   }, null, 2));
 
-  return { pid: handle.pid, dispatchRecordPath: recPath, child: handle.child };
+  return { pid: handle.pid, dispatchRecordPath: recPath, child: handle.child, spawnError };
 }

package/src/index.ts

@@ -1,7 +1,7 @@
 // API contract: RUNTIME_VERSION tracks peaks-loop root version (4.0.x).
 // This is what consumers (sub-agents dispatched by peaks-code) check at
 // runtime to verify protocol compatibility.
-export const RUNTIME_VERSION = '4.0.46';
+export const RUNTIME_VERSION = '4.0.48';
 
 // npm version: independent 0.0.x SemVer. Runtime is its own package
 // (peaks-loop-internal-runtime@NPM_VERSION) on the registry; bumps

package/src/process-supervisor.ts

@@ -20,6 +20,15 @@ export interface SpawnHandle {
   pid: number;
   child: ChildProcess;
   kill(signal?: NodeJS.Signals): void;
+  /**
+   * Resolves once the OS confirms the launch (`'spawn'`) or the launch fails
+   * (`'error'`). Never rejects: `null` means the process is running; a launch
+   * failure resolves to the otherwise-unhandled ErrnoException (ENOENT when the
+   * vendor CLI is not installed). The listener that settles this is attached
+   * synchronously in `spawn()` — see the comment there for why no caller can
+   * attach one in time.
+   */
+  settled: Promise<NodeJS.ErrnoException | null>;
 }
 
 export class ProcessSupervisor {
@@ -42,18 +51,52 @@ export class ProcessSupervisor {
       // Suppress the popup console window on Windows without changing
       // process group membership. The child is still part of the
       // parent's process group (no Windows process-group detach flag).
+      // Deliberately NOT set on POSIX — pinned by
+      // `tests/unit/runtime/process-supervisor-in-shell.test.ts` 1a/1b,
+      // which assert this platform split by name. The spawn-hygiene guard
+      // reads this assignment form; see `collectWindowsHideAssignments`.
       spawnOpts.windowsHide = true;
     }
 
     const child = nodeSpawn(binary, args, spawnOpts);
+
+    // Attach the 'error' listener in the SAME synchronous turn the child is
+    // created, because no caller can do it in time. A missing binary does not
+    // throw from spawn(): Node emits it asynchronously as an 'error' event, and
+    // an EventEmitter with no 'error' listener re-throws it as a process-level
+    // uncaught exception. That emission runs on the nextTick queue, which
+    // drains BEFORE the awaiting caller resumes — so the documented caller-side
+    // pattern (`await spawn(...); child.on('error', …)`) loses the race by
+    // construction, whatever caller writes it. Capturing it here turns the
+    // failure into a typed value on `settled` and removes the crash.
+    const settled = new Promise<NodeJS.ErrnoException | null>((resolve) => {
+      child.on('error', (err: Error) => resolve(err as NodeJS.ErrnoException));
+      child.on('spawn', () => resolve(null));
+    });
+
     const dir = join(this.cfg.runtimeDir, opts.rid);
     mkdirSync(dir, { recursive: true });
-    writeFileSync(join(dir, 'pid'), String(child.pid ?? ''));
+    // `<rid>/pid` exists IFF a real OS process was launched. `child.pid` is
+    // `undefined` until the OS confirms the spawn, so a failed launch used to
+    // write `String(undefined ?? '')` — an EMPTY pid file. That is not a
+    // cosmetic wart: `Number('')` is `0`, so a cleanup path doing
+    // `kill(Number(readFileSync(pid)))` would send its signal to pid 0 (the
+    // whole process group), and an existence check for "is something running
+    // here" reads `true` for a launch that never happened.
+    //
+    // Nothing is lost by omitting it: the launch failure is recorded as a
+    // VALUE on the dispatch record (`status: 'failed'` + `spawnError`), which
+    // is the surface a reader should consult. Absence in the pid file is the
+    // one encoding that cannot be misread as a pid.
+    if (child.pid !== undefined) {
+      writeFileSync(join(dir, 'pid'), String(child.pid));
+    }
 
     return {
       pid: child.pid ?? -1,
       child,
       kill: (signal: NodeJS.Signals = 'SIGTERM') => child.kill(signal),
+      settled,
     };
   }
 }

package/src/vendor/detect-binary.ts

@@ -7,7 +7,7 @@ export function detectBinaryInstalled(binary: string): Promise<boolean> {
   const locator = process.platform === 'win32' ? 'where.exe' : 'which';
 
   return new Promise((resolve) => {
-    execFile(locator, [binary], { timeout: DETECT_TIMEOUT_MS }, (error, stdout) => {
+    execFile(locator, [binary], { timeout: DETECT_TIMEOUT_MS, windowsHide: true }, (error, stdout) => {
       resolve(error === null && stdout.trim().length > 0);
     });
   });