peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/code-context-now-command.js

@@ -0,0 +1,124 @@
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { readJobShapeDecision, JobShapeDecisionError } from '../../services/code/job-shape-decision.js';
+import { resolveOuterSessionId } from '../../services/session/binding-status-service.js';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { readActiveSid } from './code-runtime-session.js';
+import { buildContextNowData, buildContextNowNextActions, buildContextNowWarnings, readContextNowHarness, resolveContextNowDecision } from './code-context-now-envelope.js';
+const CONTEXT_NOW_DESCRIPTION = "v2.13.0 AC-1: read the active IDE adapter's context-fill % " +
+    'without requiring the LLM to pass --prompt-size <bytes> manually. ' +
+    'Adapter-driven (no hard-coded IDE names): Claude Code is the MVP ' +
+    'implementation; trae / codex / cursor / qoder / tongyi-lingma / ' +
+    'hermes / openclaw register their own env-var via IdeAdapter.compact. ' +
+    "v3.1.2 / 2026-09-12: the mode's pre-compact line emits " +
+    'action=auto-compact-now (MANDATORY, single-rid included) and ' +
+    'the red line emits action=red-line (the installed PreToolUse hook re-runs ' +
+    'this command on the next Bash/Task tool call; nothing is blocked). ' +
+    '--enforce-job-mode only changes the reported `jobMode` label; ' +
+    'the thresholds are identical. ' +
+    'Context-window override: set env PEAKS_CONTEXT_WINDOW_TOKENS=<positive int> ' +
+    'or `peaks config set --key context.windowTokens --value <positive int>`; ' +
+    'the JSON envelope reports the winning layer as capacitySource ' +
+    '(env-override | config | model-heuristic | default).';
+/**
+ * The two flags the action derives before any probe: the `--prompt-size`
+ * override (guarded) and the Job-mode label. Pure in `opts` — no ordering
+ * dependency on the call site.
+ */
+function resolveContextNowFlags(opts) {
+    // guard rejects non-finite / negative values; only finite
+    // non-negative numbers reach the reader. Undefined → no override.
+    let promptSizeBytes;
+    if (opts.promptSize !== undefined) {
+        const parsed = Number(opts.promptSize);
+        if (Number.isFinite(parsed) && parsed >= 0) {
+            promptSizeBytes = parsed;
+        }
+    }
+    // v3.1.2: detect Job mode from job-shape.json when --enforce-job-mode
+    // is not explicitly passed. The LLM is the source of truth for
+    // whether the request is Job-shaped; the recorded decision is.
+    let isJobMode = opts.enforceJobMode === true;
+    if (!isJobMode) {
+        try {
+            const sessionIdForDecision = opts.sessionId ?? readActiveSid(opts.project);
+            if (sessionIdForDecision !== null) {
+                const record = readJobShapeDecision(opts.project, sessionIdForDecision);
+                if (record.decision.isJob)
+                    isJobMode = true;
+            }
+        }
+        catch (err) {
+            if (!(err instanceof JobShapeDecisionError))
+                throw err;
+            // missing/malformed decision file is fine — fall back to advisory.
+        }
+    }
+    return { promptSizeBytes, isJobMode };
+}
+/** The catch branch, lifted verbatim out of the action body. */
+function reportContextNowFailure(io, err, json) {
+    printResult(io, fail('code.context-now', 'CONTEXT_NOW_FAILED', getErrorMessage(err), null, [
+        'Verify the project path and try again'
+    ]), json);
+    process.exitCode = 1;
+}
+/** The action body, lifted to a module-level function so both it and the registrar fit in 50 lines. */
+async function runCodeContextNow(opts, io) {
+    try {
+        const { readContextPercent } = await import('../../services/context/auto-compact-reader.js');
+        const flags = resolveContextNowFlags(opts);
+        const sessionId = opts.sessionId ?? readActiveSid(opts.project) ?? 'unknown';
+        const outerSessionId = resolveOuterSessionId(opts.project, sessionId);
+        const probe = readContextPercent({
+            projectRoot: opts.project,
+            sessionId,
+            outerSessionId,
+            env: process.env,
+            promptSizeBytes: flags.promptSizeBytes
+        });
+        // Promote `--project .` (what the PreToolUse hook passes) to the git
+        // root ONCE, for both of the consumers below: the settings path the
+        // harness window is written to, and the session directory the witness
+        // is read from, must not depend on the caller's cwd — and an absolute
+        // path is what the envelope then reports back to the operator. This
+        // resolves through `git rev-parse --show-toplevel`, i.e. a whole
+        // process spawn (measured 2026-09-14: med 111.8 ms per call on this
+        // host), so calling it twice with the same argument charged the witness
+        // read it precedes — 0.027 ms — roughly 4,000x its own cost.
+        const canonicalProjectRoot = resolveCanonicalProjectRoot(opts.project);
+        const harness = readContextNowHarness(canonicalProjectRoot, sessionId, outerSessionId, probe);
+        const decision = resolveContextNowDecision(canonicalProjectRoot, probe.ratio, flags.isJobMode);
+        printResult(io, ok('code.context-now', buildContextNowData({
+            probe,
+            ratioPct: (probe.ratio * 100).toFixed(1),
+            isJobMode: flags.isJobMode,
+            promptSizeBytes: flags.promptSizeBytes,
+            decision,
+            harness
+        }), buildContextNowWarnings(harness), buildContextNowNextActions(decision, harness)), 
+        // `true`, which made the declared `--json` flag a no-op and left the
+        // human with raw JSON and no `next:` lines — so a person running this
+        // command could not see that peaks-loop had just written their
+        // harness settings. The notices above (including the key, the value
+        // and the rollback command) are `nextActions`, which `printResult`
+        // prints as `next: …` lines ONLY in the non-JSON path. Honoring the
+        // flag is what puts them in front of a human. See the consumer audit
+        // in the slice's RD artifact: every in-repo caller (the PreToolUse
+        // hooks, `orchestrator-can-do`, the skill runbooks) passes `--json`
+        // explicitly, so their byte-for-byte output is unchanged.
+        opts.json === true);
+    }
+    catch (err) {
+        reportContextNowFailure(io, err, opts.json);
+    }
+}
+export function registerCodeContextNowCommand(code, io) {
+    addJsonOption(code
+        .command('context-now')
+        .description(CONTEXT_NOW_DESCRIPTION)
+        .requiredOption('--project <path>', 'target project root')
+        .option('--session-id <sid>', 'override session id (default: read from active presence)')
+        .option('--enforce-job-mode', 'v3.1.2: label the run as Job-shaped (jobMode=true). Auto-enabled when job-shape.json says isJob=true. Since 2026-09-12 the ≥0.85 MANDATORY auto-compact applies in single-rid mode too, so this flag no longer changes any action.')
+        .option('--prompt-size <bytes>', 'override the bytes-from-env path; takes priority over env / statusline / transcript. Useful when CLAUDE_CONTEXT_USAGE_PERCENT is absent (e.g. Mac Claude Code).')).action((opts) => runCodeContextNow(opts, io));
+}

package/dist/cli/commands/code-context-now-envelope.d.ts

@@ -0,0 +1,66 @@
+import type { ContextPercentProbe } from '../../services/context/auto-compact-types.js';
+/**
+ * The harness half of the probe: the window sync, its warning, the witness read
+ * and its notice. Lifted verbatim from the action body — it reads only its
+ * parameters.
+ */
+export declare function readContextNowHarness(canonicalProjectRoot: string, sessionId: string, outerSessionId: string | null | undefined, probe: ContextPercentProbe): {
+    harnessWindow: import("../../services/context/harness-window-config.js").HarnessWindowSyncResult | null;
+    harnessWindowWarning: string | null;
+    harnessWitness: import("../../services/context/harness-context-witness.js").HarnessWitnessComparison;
+    witnessNotice: string | null;
+};
+type ContextNowHarness = ReturnType<typeof readContextNowHarness>;
+/**
+ * Slice H4 (rid=h4-context-now-mode-blind): ONE table, ONE mode
+ * resolver. The hard-coded ladder that used to live in the action read no mode
+ * at all, so on a 24h run (`partial` = 0.65/0.70/0.85) it answered `soft-warn`
+ * + `next: null` across [0.70, 0.85) — the band in which
+ * `peaks code auto-compact` had already decided to compact.
+ */
+export declare function resolveContextNowDecision(canonicalProjectRoot: string, ratio: number, isJobMode: boolean): {
+    action: "ok" | "soft-warn" | "red-line" | "auto-compact-now";
+    next: string | null;
+    verdict: string;
+    bands: {
+        softWarn: string;
+        preCompact: string;
+        redLine: string;
+        preCompactRatio: string;
+        redLineRatio: string;
+    };
+    gateModeNotice: string;
+};
+type ContextNowDecision = ReturnType<typeof resolveContextNowDecision>;
+/** The envelope's `data` record, lifted verbatim out of the action body. */
+export declare function buildContextNowData(args: {
+    probe: ContextPercentProbe;
+    ratioPct: string;
+    isJobMode: boolean;
+    promptSizeBytes: number | undefined;
+    decision: ContextNowDecision;
+    harness: ContextNowHarness;
+}): {
+    ratio: number;
+    ratioPct: string;
+    verdict: string;
+    action: "ok" | "soft-warn" | "red-line" | "auto-compact-now";
+    next: string | null;
+    jobMode: boolean;
+    source: string;
+    ide: string;
+    capacityBytes: number | undefined;
+    rawBytes: number | null;
+    rawTokens: number | null;
+    capacityTokens: number | null;
+    capacitySource: string | null;
+    bytesPrompt: number | null;
+    capturedAt: string;
+    harnessWindow: import("../../services/context/harness-window-config.js").HarnessWindowSyncResult | null;
+    harnessWitness: import("../../services/context/harness-context-witness.js").HarnessWitnessComparison;
+};
+/** The envelope's `warnings` array, lifted verbatim out of the action body. */
+export declare function buildContextNowWarnings(harness: ContextNowHarness): string[];
+/** The envelope's `nextActions` array, lifted verbatim out of the action body. */
+export declare function buildContextNowNextActions(decision: ContextNowDecision, harness: ContextNowHarness): string[];
+export {};

package/dist/cli/commands/code-context-now-envelope.js

@@ -0,0 +1,136 @@
+// The `peaks code context-now` envelope: the harness reading (window sync +
+// witness), the mode-resolved decision, and the `data` / `warnings` /
+// `nextActions` builders. Split out of `code-context-now-command.ts` when
+// compressing its long function pushed that file past the 300-line cap; every
+// body below is the original one, moved verbatim.
+import { resolveAutoCompactProfile } from '../../services/mode/mode-status-service.js';
+import { syncHarnessWindowForProject } from '../../services/context/auto-compact-reader.js';
+import { describeHarnessWindowSync, harnessWindowSyncWarning } from '../../services/context/harness-window-config.js';
+import { describeHarnessWitness, readAndCompareHarnessWitness } from '../../services/context/harness-context-witness.js';
+import { contextNowActionFor, contextNowBandLabels } from './code-context-now-mapping.js';
+/**
+ * The harness half of the probe: the window sync, its warning, the witness read
+ * and its notice. Lifted verbatim from the action body — it reads only its
+ * parameters.
+ */
+export function readContextNowHarness(canonicalProjectRoot, sessionId, outerSessionId, probe) {
+    // the window this probe just divided by into the harness's own settings,
+    // so "85%" here and the harness's own trigger are one point on one
+    // scale. Idempotent (no write when the value is already in force) and a
+    // no-op when the probe carried no token window — peaks-loop never
+    // invents a number it did not measure.
+    const harnessWindow = syncHarnessWindowForProject({
+        projectRoot: canonicalProjectRoot,
+        env: process.env,
+        tokens: probe.capacityTokens ?? null
+    });
+    // The machine half of 要告知. A refused write is not automatically a
+    // non-event: the file may pin a window that disagrees with the one this
+    // probe just divided by, and then the ratio above describes a trigger
+    // the harness is not going to fire. `nextActions` carries the full
+    // sentence; this one line rides `warnings` so a JSON consumer cannot
+    // miss it either.
+    const harnessWindowWarning = harnessWindowSyncWarning(harnessWindow);
+    // own number for the same quantity, captured by the statusline. This is
+    // OBSERVATION ONLY — it never feeds `verdict` / `action` / any threshold
+    // below. A wrong reading here must not be able to fire a compact.
+    const harnessWitness = readAndCompareHarnessWitness({
+        // The same promoted root as the harness-window write above, for the
+        // same reason: the statusline resolves its root from the harness
+        // payload (absolute), so a `--project .` from a hook would otherwise
+        // look for the witness somewhere else and report `absent` forever.
+        projectRoot: canonicalProjectRoot,
+        sessionId,
+        peaksRatio: probe.ratio,
+        peaksTokens: probe.rawTokens ?? null,
+        peaksWindowTokens: probe.capacityTokens ?? null,
+        outerSessionId: outerSessionId ?? null
+    });
+    const witnessNotice = describeHarnessWitness(harnessWitness);
+    return { harnessWindow, harnessWindowWarning, harnessWitness, witnessNotice };
+}
+/**
+ * Slice H4 (rid=h4-context-now-mode-blind): ONE table, ONE mode
+ * resolver. The hard-coded ladder that used to live in the action read no mode
+ * at all, so on a 24h run (`partial` = 0.65/0.70/0.85) it answered `soft-warn`
+ * + `next: null` across [0.70, 0.85) — the band in which
+ * `peaks code auto-compact` had already decided to compact.
+ */
+export function resolveContextNowDecision(canonicalProjectRoot, ratio, isJobMode) {
+    const compactMode = resolveAutoCompactProfile(canonicalProjectRoot);
+    const decided = contextNowActionFor(ratio, compactMode);
+    const action = decided.action;
+    const next = decided.next;
+    const verdict = action === 'red-line' ? 'red-line' : action === 'auto-compact-now' ? 'pre-compact' : action;
+    const bands = contextNowBandLabels(compactMode);
+    // in behaviour ABOVE 0.50 — both auto-fire at ≥0.85 and both red-line at
+    // ≥0.95". That was false: `partial` fires at 0.70, red-lines at 0.85.
+    // The lines now come from the table for the mode in force.
+    const gateModeNotice = isJobMode
+        ? `Job mode (job-shape.json isJob=true): the same ≥${bands.preCompactRatio} / ≥${bands.redLineRatio} thresholds apply, and the decision is recorded in job-shape.json.`
+        : `Single-rid mode: the same ≥${bands.preCompactRatio} / ≥${bands.redLineRatio} thresholds apply — ≥${bands.preCompactRatio} is MANDATORY auto-compact, not advisory.`;
+    return { action, next, verdict, bands, gateModeNotice };
+}
+/** The envelope's `data` record, lifted verbatim out of the action body. */
+export function buildContextNowData(args) {
+    const { probe, decision, harness } = args;
+    return {
+        ratio: probe.ratio,
+        ratioPct: `${args.ratioPct}%`,
+        verdict: decision.verdict,
+        action: decision.action,
+        next: decision.next,
+        jobMode: args.isJobMode,
+        source: probe.source,
+        ide: probe.ide,
+        capacityBytes: probe.capacityBytes,
+        rawBytes: probe.rawBytes ?? null,
+        rawTokens: probe.rawTokens ?? null,
+        capacityTokens: probe.capacityTokens ?? null,
+        // capacityTokens (env-override | config | model-heuristic |
+        // default) — null for byte/percent sources, which have no window.
+        capacitySource: probe.capacitySource ?? null,
+        bytesPrompt: args.promptSizeBytes ?? null,
+        capturedAt: probe.capturedAt,
+        // window sync did on this probe. Reported rather than silent — the
+        // harness tells a user who overrides the window only via
+        // `/autocompact`, so peaks-loop must be the one that says it.
+        harnessWindow: harness.harnessWindow,
+        harnessWitness: harness.harnessWitness
+    };
+}
+/** The envelope's `warnings` array, lifted verbatim out of the action body. */
+export function buildContextNowWarnings(harness) {
+    return [
+        ...(harness.harnessWindowWarning === null ? [] : [harness.harnessWindowWarning]),
+        // AC3: the disagreement rides `warnings` — it is a fact about the
+        // state, not an instruction — and it is one-way. Never an
+        // AskUserQuestion (see .peaks/memory/auto-compact-threshold-policy.md).
+        ...(harness.witnessNotice === null ? [] : [harness.witnessNotice])
+    ];
+}
+/** The envelope's `nextActions` array, lifted verbatim out of the action body. */
+export function buildContextNowNextActions(decision, harness) {
+    const { action, next, bands, gateModeNotice } = decision;
+    return [
+        action === 'red-line'
+            ? `RED LINE: ≥ ${bands.redLine}%. Next: \`${next}\` — peaks-loop asks the harness to compact and KEEPS WORKING (dispatch is not blocked); re-probe to confirm it landed.`
+            : action === 'auto-compact-now'
+                ? `MANDATORY auto-compact (≥${bands.preCompact}%, every mode). Code MUST call \`${next}\` WITHOUT confirmation.`
+                : action === 'soft-warn'
+                    ? `Soft warn (${bands.softWarn}–${bands.preCompact}%). Continue working; the next \`peaks code auto-compact\` will re-check.`
+                    : `Below ${bands.softWarn}%. No action required.`,
+        gateModeNotice,
+        // Single wording, shared with `peaks code auto-compact` — see
+        // `describeHarnessWindowSync`.
+        describeHarnessWindowSync(harness.harnessWindow),
+        // AC3: the one-way hint that accompanies the `warnings` entry. Both
+        // channels carry the SAME fact in the shape each is read for
+        // (machine-readable warning vs human/LLM advice) — see
+        // `harnessWindowSyncWarning` / `describeHarnessWindowSync` above for
+        // the same split, and note this one never asks a question.
+        ...(harness.witnessNotice === null
+            ? []
+            : ['Re-probe with `peaks code context-now` to confirm; this is reported, not blocking.'])
+    ];
+}

package/dist/cli/commands/code-context-now-mapping.d.ts

@@ -0,0 +1,27 @@
+import { type AutoCompactMode } from '../../services/code/auto-compact-modes.js';
+/**
+ * Slice H4 (rid=h4-context-now-mode-blind) — the ONE mapping from the shared
+ * `CompactTrigger` to this command's `action` vocabulary, so the two cannot
+ * drift: the trigger is `evaluateCompactTrigger`, the same function `peaks
+ * code auto-compact` decides with.
+ *
+ * `auto-fire` maps to `soft-warn` in BOTH modes: that tier is `peaks skill
+ * presence`'s — the every-turn probe, which reads this same table and mode
+ * resolver — so `context-now` has no auto-fire tier of its own (SKILL.md
+ * "two probes, two thresholds"). Reporting it as `auto-compact-now` would
+ * change every non-24h session's output, which slice H4 forbids.
+ */
+export declare function contextNowActionFor(ratio: number, mode: AutoCompactMode): {
+    action: 'ok' | 'soft-warn' | 'auto-compact-now' | 'red-line';
+    next: string | null;
+};
+/** Slice H4: the labels `context-now` prints, read out of the table for the mode
+ *  in force — the old hard-coded "≥0.85 / ≥0.95 / 50–85%" told a 24h operator
+ *  the wrong lines. `*Ratio` is the `0.85` form `gateModeNotice` uses. */
+export declare function contextNowBandLabels(mode: AutoCompactMode): {
+    softWarn: string;
+    preCompact: string;
+    redLine: string;
+    preCompactRatio: string;
+    redLineRatio: string;
+};

package/dist/cli/commands/code-context-now-mapping.js

@@ -0,0 +1,43 @@
+// The one table-to-vocabulary mapping `peaks code context-now` decides with: the
+// shared `CompactTrigger` kind translated to this command's `action`, and the labels
+// it prints, both read out of the mode in force.
+import { thresholdFor } from '../../services/code/auto-compact-modes.js';
+import { AUTO_COMPACT_SOFT_WARN_RATIO } from '../../services/context/auto-compact-types.js';
+import { evaluateCompactTrigger } from '../../services/code/auto-compact-orchestrator.js';
+/** The one dispatch verb the action and red-line tiers name. */
+const COMPACT_CMD = 'peaks code auto-compact';
+/**
+ * Slice H4 (rid=h4-context-now-mode-blind) — the ONE mapping from the shared
+ * `CompactTrigger` to this command's `action` vocabulary, so the two cannot
+ * drift: the trigger is `evaluateCompactTrigger`, the same function `peaks
+ * code auto-compact` decides with.
+ *
+ * `auto-fire` maps to `soft-warn` in BOTH modes: that tier is `peaks skill
+ * presence`'s — the every-turn probe, which reads this same table and mode
+ * resolver — so `context-now` has no auto-fire tier of its own (SKILL.md
+ * "two probes, two thresholds"). Reporting it as `auto-compact-now` would
+ * change every non-24h session's output, which slice H4 forbids.
+ */
+export function contextNowActionFor(ratio, mode) {
+    const kind = evaluateCompactTrigger(ratio, mode).kind;
+    if (kind === 'red-line')
+        return { action: 'red-line', next: COMPACT_CMD };
+    if (kind === 'pre-compact')
+        return { action: 'auto-compact-now', next: COMPACT_CMD };
+    return { action: kind === 'none' ? 'ok' : 'soft-warn', next: null };
+}
+/** Slice H4: the labels `context-now` prints, read out of the table for the mode
+ *  in force — the old hard-coded "≥0.85 / ≥0.95 / 50–85%" told a 24h operator
+ *  the wrong lines. `*Ratio` is the `0.85` form `gateModeNotice` uses. */
+export function contextNowBandLabels(mode) {
+    const pct = (r) => `${(r * 100).toFixed(0)}`;
+    const pre = thresholdFor(mode, 'preCompact');
+    const red = thresholdFor(mode, 'redLine');
+    return {
+        softWarn: pct(AUTO_COMPACT_SOFT_WARN_RATIO),
+        preCompact: pct(pre),
+        redLine: pct(red),
+        preCompactRatio: pre.toFixed(2),
+        redLineRatio: red.toFixed(2)
+    };
+}

package/dist/cli/commands/code-emit-handoff-command.d.ts

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

package/dist/cli/commands/code-emit-handoff-command.js

@@ -0,0 +1,136 @@
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { evaluateEmitHandoff, JOB_COMPLETED_NO_SEDIMENT, JOB_NOT_INITIALIZED, JOB_REMAINING_BLOCKED } from '../../services/code/emit-handoff.js';
+import { readActiveSid } from './code-runtime-session.js';
+export function registerCodeEmitHandoffCommand(code, io) {
+    // v3.1.2 Step 11 / final handoff — Size-fear ban.
+    // Refuses to emit a final handoff while a Job has remaining slices.
+    addJsonOption(code
+        .command('emit-handoff')
+        .description('v3.1.2 Step 11 size-fear ban: under Job mode, refuse to emit a final ' +
+        'handoff while remaining > 0. Exit 0 = allow, exit 1 = block. Pass ' +
+        '--force-under-job to override (requires explicit user approval).')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--session-id <sid>', 'override session id (default: read from active presence)')
+        .option('--job-id <jid>', 'override job id (default: read from job-shape.json decision.suggestedJobId)')
+        .option('--force-under-job', 'override the remaining>0 block (explicit user approval required)')
+        .option('--force-no-sediment <reason>', 'override the no-sediment block on a COMPLETED Job: supply the reason the ' +
+        'user approved a no-sediment outcome. A blank reason does not override.')).action((opts) => runEmitHandoff(opts, io));
+}
+function runEmitHandoff(opts, io) {
+    try {
+        const sessionId = opts.sessionId ?? readActiveSid(opts.project);
+        if (sessionId === null) {
+            printEmitHandoffNoSession(io, opts.json);
+            return;
+        }
+        const evalInput = {
+            projectRoot: opts.project,
+            sessionId
+        };
+        if (opts.jobId !== undefined)
+            evalInput.jobId = opts.jobId;
+        if (opts.forceUnderJob === true)
+            evalInput.forceUnderJob = true;
+        if (opts.forceNoSediment !== undefined)
+            evalInput.forceNoSedimentReason = opts.forceNoSediment;
+        const verdict = evaluateEmitHandoff(evalInput);
+        reportEmitHandoffVerdict(verdict, io, opts.json);
+    }
+    catch (err) {
+        reportEmitHandoffFailure(io, err, opts.json);
+    }
+}
+function reportEmitHandoffVerdict(verdict, io, json) {
+    if (verdict.kind === 'allow-not-job') {
+        printEmitHandoffAllowNotJob(io, json);
+        return;
+    }
+    if (verdict.kind === 'allow-done') {
+        printEmitHandoffAllowDone(verdict, io, json);
+        return;
+    }
+    if (verdict.kind === 'allow-force-override') {
+        printEmitHandoffAllowForceOverride(verdict, io, json);
+        return;
+    }
+    if (verdict.kind === 'block-not-initialized') {
+        printEmitHandoffBlockNotInitialized(verdict, io, json);
+        return;
+    }
+    if (verdict.kind === 'block-remaining') {
+        printEmitHandoffBlockRemaining(verdict, io, json);
+        return;
+    }
+    if (verdict.kind === 'allow-forced-no-sediment') {
+        printEmitHandoffAllowForcedNoSediment(verdict, io, json);
+        return;
+    }
+    printEmitHandoffBlockNoSediment(verdict, io, json);
+}
+function printEmitHandoffNoSession(io, json) {
+    const envelope = ok('code.emit-handoff', { allow: true, mode: 'no-session' }, [], ['No active session id; gate passes through (single-rid mode).']);
+    printResult(io, envelope, json);
+}
+function printEmitHandoffAllowNotJob(io, json) {
+    const envelope = ok('code.emit-handoff', { allow: true, mode: 'single' }, [], ['job-shape.json says isJob=false (or absent); normal handoff allowed.']);
+    printResult(io, envelope, json);
+}
+function printEmitHandoffAllowDone(verdict, io, json) {
+    const envelope = ok('code.emit-handoff', { allow: true, mode: 'job-done', remaining: verdict.remaining }, [], [`Job is complete (remaining=0); handoff allowed.`]);
+    printResult(io, envelope, json);
+}
+function printEmitHandoffAllowForceOverride(verdict, io, json) {
+    const envelope = ok('code.emit-handoff', { allow: true, mode: 'job-force-override', remaining: verdict.remaining }, [], [
+        `Job has ${verdict.remaining} remaining slices; --force-under-job override applied. Handoff allowed (explicit user approval).`
+    ]);
+    printResult(io, envelope, json);
+}
+function printEmitHandoffBlockNotInitialized(verdict, io, json) {
+    const envelope = fail('code.emit-handoff', JOB_NOT_INITIALIZED, `Job ${verdict.jobId} has no state.json; peaks job init was skipped.`, { jobId: verdict.jobId }, [`Run \`peaks job init --job-id ${verdict.jobId} --slice-list <...>\` before emitting handoff.`]);
+    printResult(io, envelope, json);
+    process.exitCode = 1;
+}
+function printEmitHandoffBlockRemaining(verdict, io, json) {
+    // block-remaining
+    const blockMessage = `BLOCKED: Job ${verdict.jobId} has ${verdict.remaining} remaining slices. Run \`peaks job status\`. Use --force-under-job only with explicit user approval.`;
+    const envelope = fail('code.emit-handoff', JOB_REMAINING_BLOCKED, blockMessage, { jobId: verdict.jobId, remaining: verdict.remaining }, [
+        `Run \`peaks job status --job-id ${verdict.jobId}\` to see remaining slices.`,
+        'Resume Step 0.81 (per-slice checkpoint loop) and continue until remaining === 0.',
+        'Use --force-under-job only with explicit user approval (size-fear ban override).'
+    ]);
+    io.stderr(`${blockMessage}\n`);
+    printResult(io, envelope, json);
+    process.exitCode = 1;
+}
+function printEmitHandoffAllowForcedNoSediment(verdict, io, json) {
+    const envelope = ok('code.emit-handoff', {
+        allow: true,
+        mode: 'job-forced-no-sediment',
+        remaining: verdict.remaining,
+        sedimentState: verdict.sedimentState,
+        approvedNoSedimentReason: verdict.reason
+    }, [], [
+        `Job is complete (remaining=0) and the session sedimented no memory (${verdict.sedimentState}); the user explicitly approved a no-sediment outcome — "${verdict.reason}". Handoff allowed.`
+    ]);
+    printResult(io, envelope, json);
+}
+function printEmitHandoffBlockNoSediment(verdict, io, json) {
+    const why = verdict.sedimentState === 'none'
+        ? 'the session sedimented no memory'
+        : 'the memory index could not be read, so it cannot be shown that the session sedimented any memory';
+    const blockMessage = `BLOCKED: Job ${verdict.jobId} is complete (remaining=0) but ${why}. Step 11 requires at least one memory in the project memory store, or an explicit user-approved no-sediment outcome. Run \`peaks memory extract --apply\` (or record a non-handoff memory with the user's help), then re-run.`;
+    const envelope = fail('code.emit-handoff', JOB_COMPLETED_NO_SEDIMENT, blockMessage, { jobId: verdict.jobId, sedimentState: verdict.sedimentState }, [
+        'Sediment the session: run `peaks memory extract --project <root> --artifact .peaks/_runtime/<sessionId>/txt/handoff.md --apply --json`, then `peaks memory reindex --project <root> --apply --json`.',
+        'Ask the user whether a no-sediment outcome is acceptable; only then re-run with `--force-no-sediment "<the reason the user gave>"`.'
+    ]);
+    io.stderr(`${blockMessage}\n`);
+    printResult(io, envelope, json);
+    process.exitCode = 1;
+}
+function reportEmitHandoffFailure(io, err, json) {
+    printResult(io, fail('code.emit-handoff', 'EMIT_HANDOFF_FAILED', getErrorMessage(err), null, [
+        'Verify the project path and try again'
+    ]), json);
+    process.exitCode = 1;
+}

package/dist/cli/commands/code-gate-step-08-command.d.ts

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