peaks-loop 4.1.1 → 4.1.3

package/dist/cli/commands/compact-settle-command.js

@@ -0,0 +1,130 @@
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { fail, ok, getErrorMessage } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { readSessionIdFromHookPayload, readTriggerFromHookPayload, settleCompactFromHarnessEvent } from '../../services/code/compact-event-settle.js';
+import { resolveSessionId } from './compact-shared.js';
+const COMPACT_SETTLE_DESCRIPTION = 'PostCompact hook handler: settle the open compact run because the HARNESS reported a ' +
+    'compaction completed, and append an `observed` compact-history row carrying the ' +
+    'harness-reported trigger (manual | auto). Reads the hook JSON on stdin; prints nothing ' +
+    'and exits 0 when run by the hook. Pass --json for the diagnostic envelope.';
+/**
+ * Read the `PostCompact` hook payload from stdin.
+ *
+ * `PEAKS_HOOK_STDIN` is the test seam, verbatim the one `peaks gate enforce`
+ * uses (`gate-commands.ts`) — the CLI side owns `process.stdin`'s lifecycle, so
+ * the reader lives with the command rather than in the service.
+ *
+ * Returns `null` for every shape that is not a JSON object: empty stdin, a TTY
+ * (the `--json` diagnostic path run by a human), malformed JSON. A payload that
+ * cannot be read is not a failure — it is a payload with no `trigger`, which is
+ * an input this path is explicitly designed to accept.
+ */
+async function readHookPayload() {
+    const override = process.env.PEAKS_HOOK_STDIN;
+    let raw;
+    if (override !== undefined) {
+        raw = override;
+    }
+    else if (process.stdin.isTTY) {
+        raw = '';
+    }
+    else {
+        raw = await new Promise((resolveStdin) => {
+            let data = '';
+            process.stdin.setEncoding('utf8');
+            process.stdin.on('data', (chunk) => {
+                data += chunk;
+            });
+            process.stdin.on('end', () => resolveStdin(data));
+            process.stdin.on('error', () => resolveStdin(data));
+        });
+    }
+    if (raw.trim().length === 0)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+function reportCompactSettleSessionFailure(io, error, project) {
+    printResult(io, fail('compact.settle', error.code, error.message, { projectRoot: project }, error.nextActions), true);
+}
+function buildCompactSettleNextActions(result) {
+    return [
+        result.settled
+            ? result.lifecycleWritten
+                ? result.historyWritten
+                    ? `Settled run ${result.runId}; appended a kind:'observed' row with pathway 'post-compact-hook'.`
+                    : `Settled run ${result.runId}, but the kind:'observed' row could NOT be appended — check that .peaks/_runtime/<sid>/ is writable.`
+                : `The harness reported a compaction for run ${result.runId}, but the lifecycle record could NOT be written — that run is still open, so a later probe will settle it from its own measurement and append the row then. Nothing was recorded for this event: a row here would assert a settlement the store never made.`
+            : result.reason === 'different-session'
+                ? `The hook payload names a different harness session, so this project's open compact run was left alone.`
+                : 'No compact run was open, so nothing was settled and no history row was appended.'
+    ];
+}
+function reportCompactSettleFailure(io, error) {
+    printResult(io, fail('compact.settle', 'COMPACT_SETTLE_FAILED', getErrorMessage(error), {}, [
+        'Verify the project path and session binding'
+    ]), true);
+}
+async function runCompactSettle(options, io) {
+    // One parse, two fields: reading stdin twice would let the two readers
+    // disagree about the payload they were handed.
+    const payload = await readHookPayload();
+    const trigger = readTriggerFromHookPayload(payload);
+    const hookSessionId = readSessionIdFromHookPayload(payload);
+    // The hook path returns before any `process.exitCode` assignment below, so
+    // the harness never sees a non-zero exit from this command.
+    try {
+        const project = options.project !== undefined
+            ? resolveCanonicalProjectRoot(options.project)
+            : (findProjectRoot(process.cwd()) ?? process.cwd());
+        const session = resolveSessionId(project, options.sessionId);
+        if (session.error !== null) {
+            if (options.json !== true)
+                return;
+            reportCompactSettleSessionFailure(io, session.error, project);
+            return;
+        }
+        const result = settleCompactFromHarnessEvent({
+            projectRoot: project,
+            sessionId: session.sid,
+            trigger,
+            hookSessionId
+        });
+        if (options.json !== true)
+            return;
+        printResult(io, ok('compact.settle', { projectRoot: project, sessionId: session.sid, trigger: trigger ?? null, ...result }, [], buildCompactSettleNextActions(result)), true);
+    }
+    catch (error) {
+        if (options.json !== true)
+            return;
+        reportCompactSettleFailure(io, error);
+    }
+}
+export function registerCompactSettleCommand(compact, io) {
+    // 8. peaks compact settle [--json]
+    //
+    // The `PostCompact` hook's transport. Before this command, peaks-loop knew a
+    // compaction had landed only because a LATER probe measured a ratio that had
+    // fallen — an inference. This command lets the harness's own event settle the
+    // run, and records what the harness said the compaction WAS (`manual` /
+    // `auto`), which is the one question a ratio can never answer.
+    //
+    // STDOUT IS CONTEXT HERE. `PostCompact`'s output contract is truncated in the
+    // retrievable docs, so the safe assumption is the `SessionStart` one: stdout
+    // is added to the model's context. The hook path therefore prints NOTHING and
+    // exits 0 for every outcome — success, no open run, unresolvable session,
+    // unparseable stdin. An error sentence in the model's context is a false
+    // problem handed to it mid-slice. Same discipline as `session reinject`;
+    // `--json` is the diagnostic surface, and the hook never passes it.
+    addJsonOption(compact
+        .command('settle')
+        .description(COMPACT_SETTLE_DESCRIPTION)
+        .option('--project <path>', 'project root (defaults to git root or cwd)')
+        .option('--session-id <sid>', 'override the active session id (defaults to the canonical binding)')).action((options) => runCompactSettle(options, io));
+}

package/dist/cli/commands/compact-shared.d.ts

@@ -0,0 +1,9 @@
+/** The active session id, or the refusal envelope every caller prints the same way. */
+export declare function resolveSessionId(projectRoot: string, explicit: string | undefined): {
+    sid: string | null;
+    error: {
+        code: string;
+        message: string;
+        nextActions: string[];
+    } | null;
+};

package/dist/cli/commands/compact-shared.js

@@ -0,0 +1,26 @@
+// The session binding every `peaks compact` subcommand resolves through, on its own so
+// the five commands that read it share one fix point.
+import { getSessionIdCanonical } from '../../services/session/session-manager.js';
+/** The active session id, or the refusal envelope every caller prints the same way. */
+export function resolveSessionId(projectRoot, explicit) {
+    if (explicit !== undefined && explicit.length > 0) {
+        return { sid: explicit, error: null };
+    }
+    // Statically-imported `getSessionIdCanonical` (see import block
+    // at the top of this file). It is the single source of truth for
+    // "what session is bound to this project"; we use it instead of
+    // re-implementing the resolution here to keep one fix point when
+    // the binding layout changes.
+    const sid = getSessionIdCanonical(projectRoot) ?? null;
+    if (sid === null) {
+        return {
+            sid: null,
+            error: {
+                code: 'NO_ACTIVE_SESSION',
+                message: 'No active session bound. Run `peaks workspace init --project <repo> --json` to bind one.',
+                nextActions: [`peaks workspace init --project ${projectRoot} --json`]
+            }
+        };
+    }
+    return { sid, error: null };
+}

package/dist/cli/commands/container-commands.d.ts

@@ -1,5 +1,4 @@
 /**
- * `peaks container spawn | release` — slice 2026-07-29-worktree-l2-extended Part 12.
  *
  * L4 container isolation bridge: Part 8 landed the CLI contract
  * (`peaks sub-agent dispatch --isolation container` is accepted

package/dist/cli/commands/container-commands.js

@@ -1,5 +1,4 @@
 /**
- * `peaks container spawn | release` — slice 2026-07-29-worktree-l2-extended Part 12.
  *
  * L4 container isolation bridge: Part 8 landed the CLI contract
  * (`peaks sub-agent dispatch --isolation container` is accepted

package/dist/cli/commands/context-commands.d.ts

@@ -1,7 +1,6 @@
 /**
  * peaks context * CLI (Slice #3 L1c) — context 4-layer loader.
  *
- * Per docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §4 L1c:
  *   - L0: full read (every SKILL.md in full)
  *   - L1: summary (one paragraph per skill + the skill list)
  *   - L2: index (just names + paths)

package/dist/cli/commands/context-commands.js

@@ -1,7 +1,6 @@
 /**
  * peaks context * CLI (Slice #3 L1c) — context 4-layer loader.
  *
- * Per docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §4 L1c:
  *   - L0: full read (every SKILL.md in full)
  *   - L1: summary (one paragraph per skill + the skill list)
  *   - L2: index (just names + paths)

package/dist/cli/commands/core/doctor-command.d.ts

@@ -1,7 +1,6 @@
 import type { Command } from 'commander';
 import { type ProgramIO } from '../../cli-helpers.js';
 /**
- * Slice 2026-09-10-context-audit-and-discipline (Slice B): bounded view of
  * the doctor envelope. The `checks` array (one object per check, each with a
  * full message) and the stale-binding instance list collapse to counts +
  * names-of-first-N; the summary counters and log section are scalars and are

package/dist/cli/commands/core/doctor-command.js

@@ -40,7 +40,6 @@ function statusLineAlreadyInstalledForScope(scope, projectRoot) {
     }
 }
 /**
- * Slice 2026-09-10-context-audit-and-discipline (Slice B): bounded view of
  * the doctor envelope. The `checks` array (one object per check, each with a
  * full message) and the stale-binding instance list collapse to counts +
  * names-of-first-N; the summary counters and log section are scalars and are
@@ -98,11 +97,9 @@ function doctorStatusLineInstalledProbe() {
         return false;
     }
 }
-// Slice v2.16.0 AC-10: stale binding TTL is 5 minutes by default. The
 // threshold is exposed as a CLI flag so users can tune it for
 // long-running sessions.
 const STALE_TTL_MS = 5 * 60 * 1000;
-// Slice v2.16.0 AC-10: identify stale instances (lastHeartbeat > 5min)
 // in the project-level binding. Used by `peaks doctor` and surfaced as
 // a warning in the report. Returns the stale entry descriptors.
 function listStaleInstances(projectRoot, ttlMs = STALE_TTL_MS) {
@@ -119,7 +116,6 @@ function listStaleInstances(projectRoot, ttlMs = STALE_TTL_MS) {
     }
     return stale;
 }
-// Slice 2026-06-16-cli-logging (AC6) — `peaks doctor --log` section.
 //
 // `buildDoctorLogsSection` reads the on-disk log dir and returns the
 // metadata the doctor needs to render the "logs" block. It is
@@ -152,7 +148,6 @@ async function buildDoctorLogsSection() {
         level: process.env.PEAKS_LOG_LEVEL ?? 'info'
     };
 }
-// Slice 2026-06-16-cli-logging (AC6): `peaks doctor --log` adds a
 // "logs" section to the doctor output (logDir, today's file name,
 // size, retention policy, level). Useful for the user when they
 // want to attach a quick log snapshot to a bug report without
@@ -236,7 +231,6 @@ export function registerDoctorCommand(program, io) {
         if (options.log === true) {
             logsSection = await buildDoctorLogsSection();
         }
-        // v2.16.0 AC-10: scan binding for stale instances.
         const ttl = options.staleTtlMs !== undefined ? Number(options.staleTtlMs) : STALE_TTL_MS;
         const staleInstances = listStaleInstances(projectRoot, ttl);
         let droppedStale = [];
@@ -257,7 +251,6 @@ export function registerDoctorCommand(program, io) {
         // Slice B: `--summary` is opt-in and affects the JSON envelope only (the
         // human-readable path below already prints one line per check).
         const data = options.summary === true ? buildDoctorSummary(fullData) : fullData;
-        // Slice 2026-08-05-statusline-sid-only-marker-and-multi-binary-drift-guard
         // repair cycle: `report.summary.ok` already factors in the
         // severity-aware aggregation in `buildReport` (warnings do NOT
         // flip `ok`). Stale-binding is independent and still escalates.
@@ -273,7 +266,6 @@ export function registerDoctorCommand(program, io) {
         }
         else {
             // Human-readable: one line per check, green/red indicators, no JSON.
-            // Slice 2026-08-05-statusline-sid-only-marker-and-multi-binary-drift-guard
             // repair cycle: warn-only findings (severity: 'warning') surface
             // as `! check.ok` with the `! ` (warning) glyph so the operator
             // can tell them apart from real errors without reading JSON.
@@ -320,7 +312,6 @@ export function registerDoctorCommand(program, io) {
                 io.stdout(`\n  ${report.summary.warnings} warning(s) present — exit code 0 (warn-only).`);
             }
         }
-        // Slice 2026-08-05-statusline-sid-only-marker-and-multi-binary-drift-guard
         // repair cycle: `report.summary.ok` already factors in the
         // severity-aware aggregation in `buildReport` (warnings do NOT
         // flip `ok`). The exit-code gate remains `summary.ok &&

package/dist/cli/commands/core/memory-command.js

@@ -201,7 +201,6 @@ export function registerMemoryCommand(program, io) {
  * raised only because a memory TITLE contained a word like `authority`
  * (slice C0). There was no secret anywhere in that memory, so the one thing
  * the hint told the user to do was the one thing that could not help: it sent
- * them looking for a credential that did not exist. A remedy has to answer the
  * check that actually failed.
  *
  * `null` (a failure that is not a safety refusal — a path escape, a missing

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

@@ -5,7 +5,6 @@ import { resolveCanonicalProjectRoot } from '../../../services/config/config-ser
 import { findProjectRoot } from '../../../services/config/config-safety.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
-// Slice 2026-07-01-strategic-compact-cli fix: register the
 // `peaks session checkpoint` and `peaks session resume` subcommands
 // EAGERLY so they appear in `peaks session --help` output. The
 // previous lazy import ran AFTER commander had already produced
@@ -19,7 +18,6 @@ import { registerSessionResumeCommand } from '../session-resume-command.js';
 // `peaks session --help` for LLM `<TAB>`-discovery. See
 // src/services/migrate-skill-name/.
 import { registerSessionMigrateSkillNameCommand } from '../session-migrate-skill-name.js';
-// rid-020a: register `peaks session 24h-mode` eagerly so the
 // state-machine sub-actions (state / transition / attempts / reset)
 // appear in `peaks session --help` for LLM `<TAB>`-discovery.
 import { registerSession24hModeCommand } from '../session-24h-mode.js';
@@ -36,19 +34,16 @@ export function registerSessionCommand(program, io) {
         .description('Show full metadata for a session directory. Pass --active to resolve the canonical binding from .peaks/_runtime/session.json (the "one command a sub-agent runs to find the parent\'s sid" primitive). Slice 021: --active is the SOLE authoritative way to look up the active session id; the on-disk file path is internal and must NOT be `cat`-ed directly.')
         .option('--active', 'resolve the canonical session id from .peaks/_runtime/session.json (ignores [sessionId] when set)')
         .option('--project <path>', 'target project root (defaults to git root or cwd). Slice 021: lets sub-agents skip the cwd heuristic and look up the binding for a specific repo.')
-        // Slice 020 — caller-keyed session binding. The --caller-id flag
         // overrides the per-process PEAKS_CALLER_ID env var and the
         // PLATFORM_FALLBACKS table (D4 priority). The resolved callerId is
         // surfaced in the JSON envelope so callers can confirm what was
         // resolved without re-deriving it.
         .option('--caller-id <id>', 'Override the caller id for this invocation (D4 priority: flag beats env beats platform fallback). When set, the response envelope includes the resolved callerId.')).action(async (sessionId, options) => {
-        // Slice 021: --project wins; otherwise the git-root / cwd fallback
         // (matches the pre-021 behaviour so the existing slice-020 / slice-007
         // sub-agent flow keeps working unchanged).
         const projectRoot = options.project !== undefined
             ? resolveCanonicalProjectRoot(options.project)
             : (findProjectRoot(process.cwd()) ?? process.cwd());
-        // Slice 020 — resolve the callerId up front when the flag was passed.
         // We use `resolveCallerId` for D1/D5 validation; an invalid flag
         // throws CallerIdError (D5 → exit 65). A missing flag and no env
         // and no fallback also throws (D2 → exit 64). The resolved id is
@@ -79,7 +74,6 @@ export function registerSessionCommand(program, io) {
                 const { getCallerBinding } = await import('../../../services/session/caller-binding-service.js');
                 const activeSid = getSessionIdCanonical(projectRoot);
                 const callerBinding = getCallerBinding(projectRoot, callerId);
-                // Slice 021: source is the enum that the unified --active primitive
                 // reports. Callers / migration tooling can detect pre-migration trees
                 // by inspecting `source === 'legacy'`.
                 const bindingSource = existsSync(join(projectRoot, '.peaks', '_runtime', 'session.json'))
@@ -100,9 +94,7 @@ export function registerSessionCommand(program, io) {
             }), options.json);
             return;
         }
-        // Slice 007 + slice 021 — sub-agent session sharing. A sub-agent that
         // does not know the parent's sid reads it from the binding via
-        // `peaks session info --active`. Slice 021 turned this into the
         // SOLE authoritative discovery primitive: it composes on
         // getSessionIdCanonical (canonicalize-on-read; handles the stored
         // "projectRoot: '.'" vs caller-passed absolute realpath mismatch
@@ -138,16 +130,13 @@ export function registerSessionCommand(program, io) {
             }
             // 4. Determine the on-disk source so callers (and future
             //    migration tooling) can detect pre-migration trees. The
-            //    canonical file is preferred when both exist (slice 005
             //    contract).
             const bindingSource = existsSync(join(projectRoot, '.peaks', '_runtime', 'session.json'))
                 ? 'canonical'
                 : 'legacy';
-            // Slice 021: when only the legacy back-compat path is present,
             // surface a warning so callers (and humans tailing the JSON)
             // see "this tree has not been reconciled to the canonical
             // home yet". The warning is informational; the binding is
-            // still valid for one minor release (slice 005 / 006
             // contract). `warnings` is a top-level envelope field, not a
             // data field, so it goes through ok()'s 3rd positional arg.
             const legacyWarnings = bindingSource === 'legacy'
@@ -194,9 +183,7 @@ export function registerSessionCommand(program, io) {
             process.exitCode = 1;
         }
     });
-    // Slice 011: `peaks session checkpoint` and `peaks session resume`.
     // Skill-level primitives — the LLM is the decision-maker; CLI is the muscle.
-    // Slice 2026-07-01-strategic-compact-cli fix: register EAGERLY (not
     // via `void (async () => …)`) so commander walks the subcommand
     // tree synchronously and `peaks session --help` includes both
     // `checkpoint` and `resume`. The previous async-IIFE registered
@@ -211,7 +198,6 @@ export function registerSessionCommand(program, io) {
     // .peaks/_runtime/** for the rename; skipped paths recorded in
     // the response envelope. See src/services/migrate-skill-name/.
     registerSessionMigrateSkillNameCommand(session);
-    // rid-020a: peaks session 24h-mode — state machine backbone.
     registerSession24hModeCommand(session, io);
     registerSpillDemoCommand(session, io);
     addJsonOption(session

package/dist/cli/commands/core/skill-command.d.ts

@@ -1,47 +1,4 @@
 import type { Command } from 'commander';
-import type { AutoCompactMode } from '../../../services/code/auto-compact-modes.js';
-/**
- * Canonicalize a user-supplied `--project <path>` value.
- *
- * Git Bash on Windows hands us forward-slash paths
- * (`C:/Users/.../peaks-loop`) while `peaks workspace init` writes the
- * backslash form, and either side may carry a trailing separator or
- * differing case. Resolving to the real path here means every
- * downstream consumer (`getSessionId`, `setSessionMeta`,
- * `setSkillPresence`) sees one stable form.
- *
- * Returns the input unchanged when it cannot be resolved (path does
- * not exist yet, or is not readable) so a bad `--project` still
- * reaches the existing error handling rather than throwing here.
- */
-/**
- * The loop-hygiene verdict attached to every ACTIVE `skill.presence` read.
- *
- * Why it lives here instead of only in a SKILL.md body: the zero-pause
- * contract ("auto-compact is the skill's own action, never the user's")
- * was already written into `peaks-code/SKILL.md`, including an explicit
- * ban on the exact phrasing "prompt the user to run `/compact`" — and it
- * was still violated. A SKILL.md body is loaded once and is then
- * compacted away, so the rule stops governing at precisely the moment
- * context pressure makes it matter. `skill.presence` is the one call
- * EVERY skill makes on EVERY turn, in EVERY consumer project and EVERY
- * mode, so a value carried here cannot be forgotten, and no skill has to
- * be edited for the obligation to reach the model.
- *
- * READ-ONLY by contract. It probes and reports; it never compacts.
- * Executing `peaks code auto-compact` stays the skill's own action — a
- * side effect here would fire on every single turn.
- *
- * Failure swallows to `null`: the hygiene verdict is advisory and must
- * never be able to break the presence read itself.
- */
-export declare function buildContextVerdict(ratio: number, mode: AutoCompactMode): {
-    context: {
-        ratioPct: string;
-        action: string;
-        mode: string;
-    };
-    nextActions: string[];
-};
 import { type ProgramIO } from '../../cli-helpers.js';
+export { buildContextVerdict } from './skill-context-verdict.js';
 export declare function registerSkillCommand(program: Command, io: ProgramIO): void;