peaks-loop 4.0.47 → 4.0.48

package/dist/services/prd/handoff-service.d.ts

@@ -3,7 +3,9 @@
  * `v2-11-rm-rd-techdoc-immutable-handoff`).
  *
  * Owns the immutable handoff at
- * `.peaks/_runtime/<sessionId>/prd/handoff.md`:
+ * `.peaks/_runtime/<sessionId>/prd/handoff-<rid>.md` (one capsule per slice;
+ * the pre-rid-scoping `.peaks/_runtime/<sessionId>/prd/handoff.md` stays
+ * readable through `resolveHandoffPath`):
  *
  *   - `initHandoff` — pure; computes sha256 of the body and returns
  *     a Handoff whose frontmatter `handoffHash` matches.
@@ -23,6 +25,43 @@
 import type { Handoff, HandoffProbe } from './handoff-types.js';
 /** Compute the lowercase hex sha256 of a UTF-8 string. */
 export declare function sha256OfBody(body: string): string;
+/**
+ * The canonical capsule path for ONE SLICE, relative to the project root.
+ *
+ * Slice `2026-09-14-prd-capsule-rid-scoping`: the capsule used to be one slot
+ * per SESSION (`prd/handoff.md`), so the second slice's handoff silently
+ * overwrote the first slice's — and `AUDIT_REQUIRES_HANDOFF` stayed green
+ * because it never checked WHOSE rid the file named. Measured on
+ * `2026-09-13-session-21878f`: a four-slice job passed that prerequisite on a
+ * capsule left by a different line of work.
+ *
+ * This is the WRITE target, so it always carries the rid — a consumer-side
+ * fallback here would leave a rid-scoped requirement with a bare-name writer,
+ * which is the defect shape this slice exists to remove. Readers that must
+ * tolerate pre-rid-scoping sessions call `resolveHandoffPath` instead.
+ */
+export declare function handoffRelativePath(sessionId: string, requestId: string): string;
+/**
+ * The capsule a CONSUMER should read for (session, requestId): the rid-scoped
+ * path when it is on disk, else the pre-rid-scoping bare name. Returns null
+ * when neither exists.
+ *
+ * Three sessions on disk still hold only the bare file
+ * (`2026-09-06-session-a87ca4`, `2026-09-12-session-e37ef0`,
+ * `2026-09-13-session-21878f`), so the legacy tier has to keep resolving for
+ * the gate and for every reader below.
+ *
+ * `requestId` is optional because the detect-only audit surface reaches its
+ * service without one. Such a caller can name only the bare path: a session
+ * holding nothing but rid-scoped capsules reports missing rather than picking
+ * among its siblings' capsules, which would re-open the cross-slice mix-up
+ * this scoping exists to close (fail closed, not "some capsule is there").
+ */
+export declare function resolveHandoffPath(opts: {
+    projectRoot: string;
+    sessionId: string;
+    requestId?: string;
+}): string | null;
 /** Pure: produce a Handoff with the frontmatter populated. Hash is
  *  computed here; callers MUST NOT pre-populate `handoffHash`. */
 export declare function initHandoff(opts: {
@@ -33,7 +72,7 @@ export declare function initHandoff(opts: {
     goals: readonly string[];
     acceptanceCriteria: readonly string[];
     preservedBehavior: readonly string[];
-    /** Override path; defaults to `.peaks/_runtime/<sid>/prd/handoff.md`. */
+    /** Override path; defaults to `.peaks/_runtime/<sid>/prd/handoff-<rid>.md`. */
     handoffPath?: string;
 }): Handoff;
 /** Write a Handoff to disk. `projectRoot` is the absolute project

package/dist/services/prd/handoff-service.js

@@ -3,7 +3,9 @@
  * `v2-11-rm-rd-techdoc-immutable-handoff`).
  *
  * Owns the immutable handoff at
- * `.peaks/_runtime/<sessionId>/prd/handoff.md`:
+ * `.peaks/_runtime/<sessionId>/prd/handoff-<rid>.md` (one capsule per slice;
+ * the pre-rid-scoping `.peaks/_runtime/<sessionId>/prd/handoff.md` stays
+ * readable through `resolveHandoffPath`):
  *
  *   - `initHandoff` — pure; computes sha256 of the body and returns
  *     a Handoff whose frontmatter `handoffHash` matches.
@@ -21,20 +23,68 @@
  * markdown source — no normalization, no trailing-newline padding.
  */
 import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { parse as parseYaml } from 'yaml';
+import { serializeHandoffFrontmatter } from './handoff-frontmatter.js';
 /** Required schema version for new handoffs. */
 const HANDOFF_SCHEMA_VERSION = '2';
 /** Compute the lowercase hex sha256 of a UTF-8 string. */
 export function sha256OfBody(body) {
     return createHash('sha256').update(body, 'utf8').digest('hex');
 }
+/**
+ * The canonical capsule path for ONE SLICE, relative to the project root.
+ *
+ * Slice `2026-09-14-prd-capsule-rid-scoping`: the capsule used to be one slot
+ * per SESSION (`prd/handoff.md`), so the second slice's handoff silently
+ * overwrote the first slice's — and `AUDIT_REQUIRES_HANDOFF` stayed green
+ * because it never checked WHOSE rid the file named. Measured on
+ * `2026-09-13-session-21878f`: a four-slice job passed that prerequisite on a
+ * capsule left by a different line of work.
+ *
+ * This is the WRITE target, so it always carries the rid — a consumer-side
+ * fallback here would leave a rid-scoped requirement with a bare-name writer,
+ * which is the defect shape this slice exists to remove. Readers that must
+ * tolerate pre-rid-scoping sessions call `resolveHandoffPath` instead.
+ */
+export function handoffRelativePath(sessionId, requestId) {
+    return join('.peaks', '_runtime', sessionId, 'prd', `handoff-${requestId}.md`);
+}
+/**
+ * The capsule a CONSUMER should read for (session, requestId): the rid-scoped
+ * path when it is on disk, else the pre-rid-scoping bare name. Returns null
+ * when neither exists.
+ *
+ * Three sessions on disk still hold only the bare file
+ * (`2026-09-06-session-a87ca4`, `2026-09-12-session-e37ef0`,
+ * `2026-09-13-session-21878f`), so the legacy tier has to keep resolving for
+ * the gate and for every reader below.
+ *
+ * `requestId` is optional because the detect-only audit surface reaches its
+ * service without one. Such a caller can name only the bare path: a session
+ * holding nothing but rid-scoped capsules reports missing rather than picking
+ * among its siblings' capsules, which would re-open the cross-slice mix-up
+ * this scoping exists to close (fail closed, not "some capsule is there").
+ */
+export function resolveHandoffPath(opts) {
+    const candidates = [
+        ...(opts.requestId !== undefined ? [handoffRelativePath(opts.sessionId, opts.requestId)] : []),
+        join('.peaks', '_runtime', opts.sessionId, 'prd', 'handoff.md')
+    ];
+    for (const relative of candidates) {
+        const absolute = join(opts.projectRoot, relative);
+        if (existsSync(absolute))
+            return absolute;
+    }
+    return null;
+}
 /** Pure: produce a Handoff with the frontmatter populated. Hash is
  *  computed here; callers MUST NOT pre-populate `handoffHash`. */
 export function initHandoff(opts) {
     const handoffPath = opts.handoffPath ??
-        join('.peaks', '_runtime', opts.sessionId, 'prd', 'handoff.md');
+        handoffRelativePath(opts.sessionId, opts.requestId);
     const handoffHash = sha256OfBody(opts.body);
     const frontmatter = {
         requestId: opts.requestId,
@@ -146,8 +196,11 @@ function parseHandoffContent(content) {
     };
 }
 function serializeHandoff(handoff) {
-    const yamlStr = stringifyYaml(handoff.frontmatter).trimEnd();
-    return `---\n${yamlStr}\n---\n${handoff.body}`;
+    // The one canonical frontmatter rendering, shared with
+    // `handoff-auto-regen.ts`. `yaml.stringify` used to render this block and
+    // emitted `schemaVersion: "2"` + a bare `handoffHash:`, which the
+    // `AUDIT_REQUIRES_HANDOFF` gate and both audit loaders all reject.
+    return `${serializeHandoffFrontmatter(handoff.frontmatter)}${handoff.body}`;
 }
 /**
  * N1: accept BOTH shapes of `schemaVersion` — the string `'2'` and the bare
@@ -161,13 +214,33 @@ function serializeHandoff(handoff) {
  * readable handoff was satisfied by a handoff the parser would not read, and
  * `peaks prd handoff verify` exited 1 on a healthy file.
  *
- * Quoting the writer instead is NOT a fix: it would delete the very substring
- * the prereq pins, turning a broken read into a broken gate. The tolerant read
- * is the only change that satisfies both consumers.
+ * Slice `2026-09-14-handoff-writer-gate-divergence` then fixed the other half:
+ * the writer no longer emits the quoted form at all (see
+ * `handoff-frontmatter.ts`). This tolerance stays because handoffs already on
+ * disk were written by the old writer and by hand; the writer fix must not
+ * retroactively make them unreadable.
  */
 function isSchemaVersion2(value) {
     return value === HANDOFF_SCHEMA_VERSION || value === 2;
 }
+/**
+ * The READER's shape check — deliberately looser than `verifyHandoff`:
+ * `handoffHash` must be a string, and nothing about its VALUE is validated here.
+ *
+ * The accepted-but-unverifiable shape, stated rather than left to be
+ * discovered: a capsule carrying `handoffHash: sha256:<hex>` — the form the
+ * pre-fix writer and this session's hand-corrected capsules use — is READ by
+ * `readHandoff` and can NEVER pass `verifyHandoff`. The verifier compares the
+ * value to `sha256OfBody(body)` byte for byte (`:127-135`) and no prefix
+ * normalization exists anywhere in this module, so the leading `sha256:`
+ * guarantees `hash-mismatch`. ONLY the bare-hex form verifies, which is what
+ * every writer now emits (`handoff-frontmatter.ts`).
+ *
+ * So `readHandoff` succeeding is NOT evidence that a capsule is verifiable —
+ * the tolerance above exists so old capsules stay READABLE, not so they become
+ * acceptable. Request §三 bullet 3 asked for exactly this confirmation
+ * (rid `2026-09-14-handoff-writer-gate-divergence`).
+ */
 function isHandoffFrontmatter(value) {
     if (!value || typeof value !== 'object')
         return false;

package/dist/services/prd/handoff-types.d.ts

@@ -14,8 +14,9 @@
  * (D1 in `v2-11-rm-rd-techdoc-immutable-handoff`).
  *
  * Path convention: the file lands at
- * `.peaks/_runtime/<sessionId>/prd/handoff.md` (gitignored session
- * artifact; the binding to `<sessionId>` lives in
+ * `.peaks/_runtime/<sessionId>/prd/handoff-<rid>.md` (one capsule per slice;
+ * `.peaks/_runtime/<sessionId>/prd/handoff.md` is the pre-rid-scoping tier and
+ * stays readable). Gitignored session artifact; the binding to `<sessionId>` lives in
  * `.peaks/_runtime/current-change`). NEVER write under
  * `.peaks/_runtime/<change-id>/...` directly (slice 2.8.3 hard ban).
  */

package/dist/services/prd/handoff-types.js

@@ -14,8 +14,9 @@
  * (D1 in `v2-11-rm-rd-techdoc-immutable-handoff`).
  *
  * Path convention: the file lands at
- * `.peaks/_runtime/<sessionId>/prd/handoff.md` (gitignored session
- * artifact; the binding to `<sessionId>` lives in
+ * `.peaks/_runtime/<sessionId>/prd/handoff-<rid>.md` (one capsule per slice;
+ * `.peaks/_runtime/<sessionId>/prd/handoff.md` is the pre-rid-scoping tier and
+ * stays readable). Gitignored session artifact; the binding to `<sessionId>` lives in
  * `.peaks/_runtime/current-change`). NEVER write under
  * `.peaks/_runtime/<change-id>/...` directly (slice 2.8.3 hard ban).
  */

package/dist/services/qa/qa-business-review-state.js

@@ -16,6 +16,7 @@
  */
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
 /** 6-item business checklist (12 Gaps QA perspective). */
 export const QA_BUSINESS_ITEMS = [
     { id: 'business-flow', question: '这个功能"用起来"对吗?(业务流程顺不顺,操作路径是否反人类,跟现有系统交互有没有断层)' },
@@ -36,6 +37,14 @@ export function buildEmptyQaReview(requestId, sessionId, now = new Date()) {
     };
 }
 export function getQaReviewDir(projectRoot, sessionId) {
+    // Sid axis. Every `peaks qa-business-review|score|accept|reject` subcommand
+    // reaches the runtime tree through this one constructor, so one guard here
+    // covers the whole family — measured: `--session-id ../../../../…/PWNED`
+    // wrote `qa-business-reviews/<rid>.json` outside every project root under an
+    // `ok: true` envelope (RD sweep case A17).
+    if (isUnsafePathInput(sessionId)) {
+        throw new Error(`Invalid session id: ${sessionId} (must be a single path segment)`);
+    }
     return resolve(projectRoot, '.peaks', '_runtime', sessionId, 'qa-business-reviews');
 }
 export function getQaReviewPath(projectRoot, sessionId, requestId) {

package/dist/services/scan/karpathy-service.js

@@ -68,7 +68,7 @@ export async function scanKarpathy(options) {
                 warnings: [
                     `Karpathy review file missing: ${reviewRel}`,
                     'Per karpathy §1 Think Before Coding: state your assumptions. Without a review file, no 5-way fanout evidence is available.',
-                    'Per karpathy §3 Surgical Changes: touch only what the request requires. Create a minimal rd/karpathy-review.md stub before requesting qa-handoff.'
+                    'Per karpathy §3 Surgical Changes: touch only what the request requires. The rd:qa-handoff gate is satisfied by rd/karpathy-review-<rid>.md; this scanner has no rid and reads only the back-compat name rd/karpathy-review.md, so a rid-scoped-only slice still reads as missing here. `peaks request transition --state qa-handoff` is the authoritative gate.'
                 ]
             };
         }
@@ -223,6 +223,6 @@ export function formatKarpathyMarkdown(report, opts = {}) {
     }
     lines.push('### Karpathy-Gate');
     lines.push('');
-    lines.push('Per `andrej-karpathy-skills:karpathy-guidelines` §1 Think Before Coding / §3 Surgical Changes, the hard Karpathy-Gate requires `rd/karpathy-review.md` to be present with all 4 guideline sections before `peaks request transition --state qa-handoff`.');
+    lines.push('Per `andrej-karpathy-skills:karpathy-guidelines` §1 Think Before Coding / §3 Surgical Changes, the hard Karpathy-Gate requires `rd/karpathy-review-<rid>.md` to be present with all 4 guideline sections before `peaks request transition --state qa-handoff`. (`rd/karpathy-review.md` is the accepted back-compat tier, and the only name this scanner probes.)');
     return lines.join('\n');
 }

package/dist/services/session/session-checkpoint-service.js

@@ -12,6 +12,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { join, sep } from 'node:path';
 import { emitObservabilityEvent } from '../observability/observability-service.js';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
 const CHECKPOINTS_DIR = 'checkpoints';
 const CHECKPOINT_FILENAME_EXT = '.json';
 const MAX_CHECKPOINTS = 10;
@@ -76,6 +77,13 @@ function pruneOldest(dir) {
     return removed;
 }
 export function writeCheckpoint(projectRoot, options) {
+    // Sid axis, placed before the first read and the first `mkdir`. Both
+    // `peaks session checkpoint --session-id` and `peaks compact force
+    // --session-id` reach this same function, so one guard closes both measured
+    // surfaces — they were never two joins.
+    if (isUnsafePathInput(options.sessionId)) {
+        throw new Error(`Invalid session id: ${options.sessionId} (must be a single path segment)`);
+    }
     const now = (options.now ?? (() => new Date()))();
     const createdAt = now.toISOString();
     const lastActivity = readSessionLastActivity(projectRoot, options.sessionId) || createdAt;

package/dist/services/skill/resume-detector.js

@@ -32,6 +32,7 @@
  */
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { readArtifactState } from '../artifacts/request-artifact-state-helpers.js';
 const MID_IMPL_RD_STATES = new Set([
     'spec-locked',
     'implemented',
@@ -192,13 +193,21 @@ function classifyTerminalGates(sessionDir, ctx) {
     // RD qa-handoff → deepest gate is C. If the review artifacts are
     // missing the state is inconsistent; fall back to rd-review-fanout.
     if (ctx.primaryRd !== null && ctx.primaryRd.state === 'qa-handoff') {
-        const codeReviewPath = join(sessionDir, 'rd', 'code-review.md');
-        const securityReviewPath = join(sessionDir, 'rd', 'security-review.md');
+        // Slice `2026-09-14-audit-artifact-rid-scoping`: the fan-out evidence
+        // filenames carry the rid. Probe the canonical rid-scoped name first and
+        // the pre-rid names behind it — the same order the transition gate
+        // resolves in, so an inconsistent-looking slice here means the fan-out
+        // never ran, not that it wrote to a name this reader does not know.
+        const rid = ridOf(ctx.primaryRd.filename);
         const missing = [];
-        if (!existsSync(codeReviewPath))
-            missing.push('rd/code-review.md');
-        if (!existsSync(securityReviewPath))
-            missing.push('rd/security-review.md');
+        const codeReviewCandidates = [`rd/code-review-${rid}.md`, 'rd/code-review.md'];
+        const securityCandidates = [`audit/security-${rid}.md`, 'audit/security.md', 'rd/security-review.md'];
+        if (!codeReviewCandidates.some((rel) => existsSync(join(sessionDir, rel)))) {
+            missing.push(codeReviewCandidates[0]);
+        }
+        if (!securityCandidates.some((rel) => existsSync(join(sessionDir, rel)))) {
+            missing.push(securityCandidates[0]);
+        }
         if (missing.length > 0) {
             return {
                 kind: 'resume',
@@ -317,12 +326,21 @@ function readRequestStates(sessionDir, role) {
         };
     });
 }
+/** Empty string (not 'unknown') when the artifact has no state line — `primaryPrd.state.length > 0` below depends on that. */
 function extractState(content) {
-    const match = /^-\s*state:\s*(\S+)|^state:\s*(\S+)/m.exec(content);
-    if (match === null)
-        return '';
-    const captured = match[1] ?? match[2] ?? '';
-    return captured.trim();
+    return readArtifactState(content) ?? '';
+}
+/**
+ * The `<rid>` embedded in a request filename: drop the `.md` suffix and the
+ * zero-padded `NNN-` prefix `request init` writes.
+ *
+ * Uses the same `^0\d{2}-` rule as the request loader
+ * (`request-artifact-service.ts`: "Only strip 3-digit zero-padded prefixes").
+ * A looser `^\d+-` would eat the leading year of every real rid, which is
+ * itself date-shaped (`2026-09-14-<slug>`).
+ */
+function ridOf(filename) {
+    return filename.replace(/^0\d{2}-/, '').replace(/\.md$/, '');
 }
 function hasAbandonedTransitionNote(content) {
     return /user-requested-abandon/.test(content);

package/dist/services/skills/hooks-codegate-superpowers.d.ts

@@ -39,6 +39,12 @@ interface ResolvedHookSpec {
  * cannot help; pinning the hook's `shell` is the only lever the hook schema
  * offers. The platform-neutral default (`undefined` → omit the key) is kept
  * everywhere else.
+ *
+ * Scope note: this is applied to the `Bash`-matcher handlers only. The three
+ * `SessionStart` entries are deliberately NOT pinned, and not because the
+ * mechanism is believed absent there — see the block comment in
+ * `resolveHookEntries` for what is and is not established, and for why adding
+ * the pin in place would break every non-Windows teammate.
  */
 export declare function resolveHookShell(platform?: NodeJS.Platform): string | undefined;
 /**

package/dist/services/skills/hooks-codegate-superpowers.js

@@ -8,7 +8,7 @@
  * type contract re-exported by the caller.
  */
 import { getAdapter } from '../ide/ide-registry.js';
-import { HOOK_OUTER_CACHE_COMMAND, HOOK_OUTER_CACHE_EVENT, HOOK_OUTER_CACHE_SENTINEL, HOOK_POST_COMPACT_REINJECT_COMMAND, HOOK_POST_COMPACT_REINJECT_EVENT, HOOK_POST_COMPACT_REINJECT_MATCHER, HOOK_POST_COMPACT_REINJECT_SENTINEL, HOOK_WORKSPACE_INIT_COMMAND, HOOK_WORKSPACE_INIT_EVENT, HOOK_WORKSPACE_INIT_SENTINEL } from './session-start-hook-constants.js';
+import { HOOK_COMPACT_SETTLE_COMMAND, HOOK_COMPACT_SETTLE_EVENT, HOOK_COMPACT_SETTLE_MATCHER, HOOK_COMPACT_SETTLE_SENTINEL, HOOK_OUTER_CACHE_COMMAND, HOOK_OUTER_CACHE_EVENT, HOOK_OUTER_CACHE_SENTINEL, HOOK_POST_COMPACT_REINJECT_COMMAND, HOOK_POST_COMPACT_REINJECT_EVENT, HOOK_POST_COMPACT_REINJECT_MATCHER, HOOK_POST_COMPACT_REINJECT_SENTINEL, HOOK_WORKSPACE_INIT_COMMAND, HOOK_WORKSPACE_INIT_EVENT, HOOK_WORKSPACE_INIT_SENTINEL } from './session-start-hook-constants.js';
 /** Sentinel substring identifying a Claude-Code gate-enforce hook entry. */
 export const HOOK_ENFORCE_SENTINEL = 'peaks gate enforce';
 /**
@@ -20,6 +20,12 @@ export const HOOK_ENFORCE_SENTINEL = 'peaks gate enforce';
  * cannot help; pinning the hook's `shell` is the only lever the hook schema
  * offers. The platform-neutral default (`undefined` → omit the key) is kept
  * everywhere else.
+ *
+ * Scope note: this is applied to the `Bash`-matcher handlers only. The three
+ * `SessionStart` entries are deliberately NOT pinned, and not because the
+ * mechanism is believed absent there — see the block comment in
+ * `resolveHookEntries` for what is and is not established, and for why adding
+ * the pin in place would break every non-Windows teammate.
  */
 export function resolveHookShell(platform = process.platform) {
     return platform === 'win32' ? 'powershell' : undefined;
@@ -112,6 +118,37 @@ export function resolveHookEntries(ide, _skipProgress = false) {
             ...(spec.hookEnforceShell !== undefined ? { shell: spec.hookEnforceShell } : {})
         }
     ];
+    // ── Why the three SessionStart entries below carry NO `shell` pin ─────────
+    //
+    // The gate-enforce entry above is shell-pinned on Windows (see
+    // `resolveHookShell`) because Claude Code runs a shell-form hook command
+    // through a shell that defaults to bash — Git Bash / MSYS2 on Windows — and
+    // MSYS2 bash force-allocates its own console window. That reason is a
+    // property of the hook RUNNER's shell resolution, not of the `PreToolUse`
+    // event: nothing in it exempts `SessionStart`, so the same command-form
+    // entry on this event goes through the same shell. The pin was applied only
+    // to the `Bash`-matcher handlers because those were the ones the reporter
+    // could see (they run on EVERY Bash tool call); these three run once per
+    // session, so a window here — if there is one — is a single flash rather
+    // than a per-tool-call nuisance. That is a difference in frequency, not
+    // evidence that the window does not appear, and no A/B measurement on this
+    // event exists.
+    //
+    // The pin is nonetheless NOT applied here, and adding it would be a defect
+    // rather than a fix: `shell: "powershell"` resolves to `pwsh`, these entries
+    // are written to the COMMITTED `.claude/settings.json`, and a macOS / Linux
+    // teammate reading that file has no `pwsh` — the exact cross-platform damage
+    // the machine-local split exists to prevent (see the gate-enforce entry's
+    // `machineLocal` flag, and commit 4637baa8's rationale).
+    //
+    // A correct fix therefore has to move these three entries to the
+    // machine-local file as well, which changes where a fresh clone gets its
+    // SessionStart hooks: today they arrive with the repository, after such a
+    // change they would require `peaks hooks install` / `peaks workspace init`.
+    // That is a product-shape decision, not a leftover; it is recorded here so
+    // that whoever makes it starts from the reason the pin is absent instead of
+    // re-deriving it — or, worse, adding the pin in place and breaking every
+    // non-Windows teammate.
     if (ide === 'claude-code') {
         entries.push({
             sentinel: HOOK_OUTER_CACHE_SENTINEL,
@@ -161,6 +198,24 @@ export function resolveHookEntries(ide, _skipProgress = false) {
             command: HOOK_POST_COMPACT_REINJECT_COMMAND,
             event: HOOK_POST_COMPACT_REINJECT_EVENT
         });
+        // rid 2026-09-13-compact-event-settle: the harness's OWN "a compaction
+        // completed" event, which is the only signal that settles a compact as a
+        // FACT rather than as an inference from a ratio that fell.
+        //
+        // No `machineLocal` flag, so this lands in the shared, committed
+        // `.claude/settings.json` — the same file as the three SessionStart entries
+        // above, and NOT the machine-local file the workspace-init materializer
+        // owns. That routing IS the answer to "who owns the `hooks` key for this
+        // entry": the only writer that could delete it is the one that installed
+        // it. See `session-start-hook-constants.ts` for why it also carries no
+        // `shell` pin, and `mergeHooksTree` for the second line of defence if it
+        // ever moves.
+        entries.push({
+            sentinel: HOOK_COMPACT_SETTLE_SENTINEL,
+            matcher: HOOK_COMPACT_SETTLE_MATCHER,
+            command: HOOK_COMPACT_SETTLE_COMMAND,
+            event: HOOK_COMPACT_SETTLE_EVENT
+        });
     }
     return entries;
 }
@@ -191,7 +246,11 @@ export function resolveLegacySentinels(ide) {
         // it) exactly like the other two SessionStart entries. Without this the
         // entry would be unremovable by `peaks hooks uninstall` — the rollback
         // path T2 requires.
-        return [...base, HOOK_OUTER_CACHE_SENTINEL, HOOK_WORKSPACE_INIT_SENTINEL, HOOK_POST_COMPACT_REINJECT_SENTINEL];
+        // rid 2026-09-13-compact-event-settle: the PostCompact settle sentinel joins
+        // too — same rollback argument as the reinject entry above. A hook that
+        // `peaks hooks uninstall` cannot remove is a hook the user cannot get rid
+        // of, and this one fires on every compaction.
+        return [...base, HOOK_OUTER_CACHE_SENTINEL, HOOK_WORKSPACE_INIT_SENTINEL, HOOK_POST_COMPACT_REINJECT_SENTINEL, HOOK_COMPACT_SETTLE_SENTINEL];
     }
     return base;
 }

package/dist/services/skills/hooks-settings-service.js

@@ -322,10 +322,20 @@ function shapeMatchesDesired(settings, entries, allPeaksSentinels) {
                 return false;
             }
         }
-        // (b) every desired entry must be on disk.
-        for (const sentinel of desiredSentinels) {
-            const has = peaksPresent.some((entry) => (entry.hooks ?? []).some((h) => String(h.command ?? '').includes(sentinel)));
-            if (!has)
+        // (b) every desired entry must be on disk AND carry the matcher it declares.
+        //     Presence alone cannot see a WRONG matcher, and a wrong matcher is not
+        //     cosmetic: `''` and `Bash|Task` route the same command to different
+        //     tool sets, so the entry is present while the hook never fires on the
+        //     tools it was installed for. Measured (rid `2026-09-13-compact-event-settle`,
+        //     residual R2): a `PostCompact` entry hand-corrupted to matcher
+        //     `auto|manual` survived `peaks hooks install` unchanged, and the
+        //     installer was structurally unable to repair it.
+        //     An absent matcher reads as `''` — the form Claude Code takes as "every
+        //     source" — so a file written before matchers were explicit converges
+        //     once instead of churning on every install.
+        for (const desired of entries.filter((e) => e.event === eventKey)) {
+            const onDisk = peaksPresent.find((entry) => (entry.hooks ?? []).some((h) => String(h.command ?? '').includes(desired.sentinel)));
+            if (onDisk === undefined || (onDisk.matcher ?? '') !== desired.matcher)
                 return false;
         }
     }

package/dist/services/skills/session-start-hook-constants.d.ts

@@ -83,3 +83,48 @@ export declare const HOOK_WORKSPACE_INIT_SENTINEL = "peaks session primer";
 export declare const HOOK_WORKSPACE_INIT_COMMAND = "peaks session primer --project \"${CLAUDE_PROJECT_DIR}\"";
 /** SessionStart hook event key (same as outer-cache). */
 export declare const HOOK_WORKSPACE_INIT_EVENT = "SessionStart";
+/**
+ * rid `2026-09-13-compact-event-settle` — the `PostCompact` entry that lets the
+ * harness's own event settle a compact, instead of the next `context-now` probe
+ * inferring one from a ratio that fell.
+ *
+ * WHY THIS ENTRY IS NOT A `SessionStart` ONE, despite living in this file: the
+ * three entries above all ride `SessionStart` and differ only by matcher. A
+ * `PostCompact` hook is a different EVENT that carries the one fact no
+ * `SessionStart` payload has — whether the compaction the harness just
+ * completed was `auto` or `manual`. That distinction is the whole question
+ * ("has this machine ever auto-compacted?"), and without it peaks-loop can only
+ * ever see that SOMETHING compacted. See `compact-event-settle.ts` for what the
+ * command does with it.
+ *
+ * WHY THE MATCHER IS THE EMPTY STRING and not the documented `auto|manual`:
+ * both trigger values are wanted, so the matcher must filter nothing. An empty
+ * matcher is the convention the three `SessionStart` entries already rely on to
+ * match every source, and it is the only form that cannot fail SILENTLY — an
+ * alternation string is a match-everything pattern under regex semantics but
+ * matches NEITHER value under exact-equality semantics, and a hook that never
+ * fires looks exactly like a hook with nothing to report.
+ */
+export declare const HOOK_COMPACT_SETTLE_SENTINEL = "peaks compact settle";
+/**
+ * The settle hook command. `--project "${CLAUDE_PROJECT_DIR}"` is byte-for-byte
+ * the shape of the three `SessionStart` entries above — Claude Code's standard
+ * project-root convention, resolved strictly on the CLI side (a hook payload is
+ * env-driven and must not be trusted as a path).
+ *
+ * The command prints NOTHING on the hook path and exits 0 for every outcome.
+ * `PostCompact`'s stdin/stdout contract is truncated in the retrievable docs,
+ * so the safe assumption is the `SessionStart` one — stdout may be added to the
+ * model's context. An error message there would be read as a fact. See
+ * `compact-event-settle.ts`.
+ *
+ * No `shell` pin, deliberately: this entry lands in the shared, committed
+ * `.claude/settings.json`, and a `powershell` pin there would break every
+ * macOS / Linux reader of the file. See `resolveHookEntries`' comment block for
+ * the full reason the three `SessionStart` entries are unpinned too.
+ */
+export declare const HOOK_COMPACT_SETTLE_COMMAND = "peaks compact settle --project \"${CLAUDE_PROJECT_DIR}\"";
+/** The event this entry rides. Claude Code fires it after a compaction completes. */
+export declare const HOOK_COMPACT_SETTLE_EVENT = "PostCompact";
+/** Matcher: empty = every `trigger` (`auto` and `manual`). See the sentinel doc. */
+export declare const HOOK_COMPACT_SETTLE_MATCHER = "";

package/dist/services/skills/session-start-hook-constants.js

@@ -83,3 +83,48 @@ export const HOOK_WORKSPACE_INIT_SENTINEL = 'peaks session primer';
 export const HOOK_WORKSPACE_INIT_COMMAND = `peaks session primer --project "\${CLAUDE_PROJECT_DIR}"`;
 /** SessionStart hook event key (same as outer-cache). */
 export const HOOK_WORKSPACE_INIT_EVENT = 'SessionStart';
+/**
+ * rid `2026-09-13-compact-event-settle` — the `PostCompact` entry that lets the
+ * harness's own event settle a compact, instead of the next `context-now` probe
+ * inferring one from a ratio that fell.
+ *
+ * WHY THIS ENTRY IS NOT A `SessionStart` ONE, despite living in this file: the
+ * three entries above all ride `SessionStart` and differ only by matcher. A
+ * `PostCompact` hook is a different EVENT that carries the one fact no
+ * `SessionStart` payload has — whether the compaction the harness just
+ * completed was `auto` or `manual`. That distinction is the whole question
+ * ("has this machine ever auto-compacted?"), and without it peaks-loop can only
+ * ever see that SOMETHING compacted. See `compact-event-settle.ts` for what the
+ * command does with it.
+ *
+ * WHY THE MATCHER IS THE EMPTY STRING and not the documented `auto|manual`:
+ * both trigger values are wanted, so the matcher must filter nothing. An empty
+ * matcher is the convention the three `SessionStart` entries already rely on to
+ * match every source, and it is the only form that cannot fail SILENTLY — an
+ * alternation string is a match-everything pattern under regex semantics but
+ * matches NEITHER value under exact-equality semantics, and a hook that never
+ * fires looks exactly like a hook with nothing to report.
+ */
+export const HOOK_COMPACT_SETTLE_SENTINEL = 'peaks compact settle';
+/**
+ * The settle hook command. `--project "${CLAUDE_PROJECT_DIR}"` is byte-for-byte
+ * the shape of the three `SessionStart` entries above — Claude Code's standard
+ * project-root convention, resolved strictly on the CLI side (a hook payload is
+ * env-driven and must not be trusted as a path).
+ *
+ * The command prints NOTHING on the hook path and exits 0 for every outcome.
+ * `PostCompact`'s stdin/stdout contract is truncated in the retrievable docs,
+ * so the safe assumption is the `SessionStart` one — stdout may be added to the
+ * model's context. An error message there would be read as a fact. See
+ * `compact-event-settle.ts`.
+ *
+ * No `shell` pin, deliberately: this entry lands in the shared, committed
+ * `.claude/settings.json`, and a `powershell` pin there would break every
+ * macOS / Linux reader of the file. See `resolveHookEntries`' comment block for
+ * the full reason the three `SessionStart` entries are unpinned too.
+ */
+export const HOOK_COMPACT_SETTLE_COMMAND = `peaks compact settle --project "\${CLAUDE_PROJECT_DIR}"`;
+/** The event this entry rides. Claude Code fires it after a compaction completes. */
+export const HOOK_COMPACT_SETTLE_EVENT = 'PostCompact';
+/** Matcher: empty = every `trigger` (`auto` and `manual`). See the sentinel doc. */
+export const HOOK_COMPACT_SETTLE_MATCHER = '';

package/dist/services/skills/skill-statusline-service.d.ts

@@ -7,6 +7,20 @@ export type StatusLineStdin = {
     cwd?: string;
     session_id?: string;
     caller_id?: string;
+    /**
+     * The harness's own context numbers. Declared here because this type IS the
+     * documented shape of the payload the harness pipes in; omitting a documented
+     * field would make the type lie by omission, and a consumer that reached for
+     * it would have to cast. Read (never written) by
+     * `harness-context-witness.ts` — see that module for why
+     * `context_window_size` is NOT a denominator.
+     */
+    context_window?: {
+        context_window_size?: unknown;
+        used_percentage?: unknown;
+        remaining_percentage?: unknown;
+        current_usage?: Record<string, unknown> | undefined;
+    } | undefined;
 };
 export type StatusLineState = 'active' | 'idle' | 'stale' | 'invalid-presence';
 export type StatusLinePresence = {