peaks-loop 4.1.2 → 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/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;