peaks-loop 4.0.16 → 4.0.18

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

@@ -43,7 +43,16 @@ function listExpectedEntriesForIde(ide, _skipProgress = false) {
     if (ide === 'trae') {
         return [{ matcher: adapter.toolMatcher, sentinel: 'peaks hook handle' }];
     }
-    return [{ matcher: adapter.toolMatcher, sentinel: 'peaks gate enforce' }];
+    // Slice 2026-08-06-codegate-vendor-neutral: Claude Code install
+    // also emits the Edit|Write|MultiEdit code-gate entry. The summary
+    // mirrors the install shape, NOT a hardcoded expected list. The
+    // hook source of truth is `src/services/hooks/pre-tool-code-gate.sh`
+    // (vendor-neutral); the runtime adapter is `peaks code-gate --json`
+    // registered as a PreToolUse entry.
+    return [
+        { matcher: adapter.toolMatcher, sentinel: 'peaks gate enforce' },
+        { matcher: 'Edit|Write|MultiEdit', sentinel: 'peaks code-gate' }
+    ];
 }
 /**
  * Slice 2026-07-24-peaks-code-bridge-002-rootcause (G6b / G10): copy the
@@ -98,6 +107,26 @@ function copyBridgeHookIfPresent(userHome) {
     copyFileSync(source, target);
     return { copied: true, source, target };
 }
+/**
+ * Slice 2026-08-06-codegate-vendor-neutral: copy the code-gate hook
+ * source (`src/services/hooks/pre-tool-code-gate.sh`) into the user-
+ * global peaks-code hooks dir, mirroring the bridge-hook copy. The
+ * hook itself is vendor-neutral (no `claude` / `anthropic` strings in
+ * the script) — this installer is the vendor adapter that decides
+ * where the file lands. The CLI command `peaks code-gate` is the
+ * runtime entry; the shell script is the canonical artifact distributed
+ * alongside the bridge hook.
+ */
+function copyCodeGateHookIfPresent(userHome) {
+    const source = resolve(__dirname, '..', '..', 'services', 'hooks', 'pre-tool-code-gate.sh');
+    const target = resolve(userHome, '.claude', 'skills', 'peaks-code', 'hooks', 'pre-tool-code-gate.sh');
+    if (!existsSync(source)) {
+        return { copied: false, source, target };
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    copyFileSync(source, target);
+    return { copied: true, source, target };
+}
 export function registerHooksCommands(program, io) {
     const hooks = program
         .command('hooks')
@@ -121,6 +150,14 @@ export function registerHooksCommands(program, io) {
                 const bridgeCopy = scope === 'global'
                     ? copyBridgeHookIfPresent(process.env.USERPROFILE ?? process.env.HOME ?? '')
                     : { copied: false, source: '', target: '' };
+                // Slice 2026-08-06-codegate-vendor-neutral: also copy the
+                // code-gate hook script. The runtime gate lives at
+                // `peaks code-gate --json` (registered as a PreToolUse entry
+                // in the install output); the script is the build artifact
+                // distributed alongside the bridge hook.
+                const codeGateCopy = scope === 'global'
+                    ? copyCodeGateHookIfPresent(process.env.USERPROFILE ?? process.env.HOME ?? '')
+                    : { copied: false, source: '', target: '' };
                 printResult(io, ok('hooks.install', {
                     ...plan,
                     ide,
@@ -129,6 +166,7 @@ export function registerHooksCommands(program, io) {
                     skipProgress,
                     entries: dryRunEntries,
                     bridgeHookCopy: bridgeCopy,
+                    codeGateHookCopy: codeGateCopy,
                     // Slice 2026-07-29-worktree-layer3-deny: surface the
                     // Layer 3 deny entries the install WOULD write. The
                     // dry-run branch never actually invokes
@@ -141,7 +179,10 @@ export function registerHooksCommands(program, io) {
                     `would write ${listSuperpowersDenyEntries().length} permissions.deny entries (Layer 3 worktree governance)`,
                     bridgeCopy.copied
                         ? `would copy bridge hook from ${bridgeCopy.source} to ${bridgeCopy.target}`
-                        : 'would not copy bridge hook (source missing or non-global scope)'
+                        : 'would not copy bridge hook (source missing or non-global scope)',
+                    codeGateCopy.copied
+                        ? `would copy code-gate hook from ${codeGateCopy.source} to ${codeGateCopy.target}`
+                        : 'would not copy code-gate hook (source missing or non-global scope)'
                 ]), options.json);
                 return;
             }
@@ -161,6 +202,14 @@ export function registerHooksCommands(program, io) {
             const bridgeCopy = scope === 'global'
                 ? copyBridgeHookIfPresent(process.env.USERPROFILE ?? process.env.HOME ?? '')
                 : { copied: false, source: '', target: '' };
+            // Slice 2026-08-06-codegate-vendor-neutral: also copy the
+            // code-gate hook script. The runtime gate lives at
+            // `peaks code-gate --json` (registered as a PreToolUse entry
+            // in the install output); the script is the build artifact
+            // distributed alongside the bridge hook.
+            const codeGateCopy = scope === 'global'
+                ? copyCodeGateHookIfPresent(process.env.USERPROFILE ?? process.env.HOME ?? '')
+                : { copied: false, source: '', target: '' };
             const nextActions = result.applied
                 ? [
                     'Restart the IDE (or reload the workspace) so the hook entries take effect',
@@ -170,7 +219,10 @@ export function registerHooksCommands(program, io) {
                     `Layer 3 deny: wrote ${listSuperpowersDenyEntries().length} permissions.deny entries (worktree governance)`,
                     bridgeCopy.copied
                         ? `Copied bridge hook: ${bridgeCopy.target}`
-                        : 'Bridge hook not copied (source missing or non-global scope)'
+                        : 'Bridge hook not copied (source missing or non-global scope)',
+                    codeGateCopy.copied
+                        ? `Copied code-gate hook: ${codeGateCopy.target}`
+                        : 'Code-gate hook not copied (source missing or non-global scope)'
                 ]
                 : (bridgeCopy.copied
                     ? [`Bridge hook copied: ${bridgeCopy.target}`]
@@ -189,6 +241,7 @@ export function registerHooksCommands(program, io) {
                 skipProgress,
                 entries: installedEntries.map((e) => ({ matcher: e.matcher, sentinel: e.sentinel })),
                 bridgeHookCopy: bridgeCopy,
+                codeGateHookCopy: codeGateCopy,
                 permissionsDenyApplied: result.applied,
                 permissionsDenyEntries: denyEntries
             }, [], nextActions), options.json);

package/dist/cli/commands/primer-command.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Slice rid-statusline-stale-ux AC-2: `peaks session primer --project <path>`.
+ *
+ * Lightweight SessionStart primer that fires rotation + presence
+ * cleanup BEFORE the first statusline render of a fresh session.
+ * Independent subcommand (NOT a flag on `peaks workspace init` per
+ * task regulation: "don't add a flag to workspace init"). Cleaner
+ * permission boundary — primer cannot be mistaken for init by users.
+ *
+ * Performs only 3 things:
+ *   1. ensureSessionWithRotation(projectRoot) — the real rotation
+ *      entry point (verified at
+ *      src/services/session/session-binding-bridge.ts:461-527).
+ *   2. If outer-mismatch rotation occurred: call
+ *      clearStalePresenceOnRotation with the verified single-options-
+ *      object signature (mirrors init-command.ts:324-329 pattern with
+ *      all 3 fields populated). Note: on 4.0.11-A sid-scoped leases
+ *      this is a legacy-compat no-op; the real cleanup mechanism is
+ *      rotation itself (rebinding changes the bound sid so the
+ *      reader looks in the new sid's empty lease dir).
+ *   3. gcStalePresenceLeases({ projectRoot, trigger: 'manual' }) —
+ *      sync; documented as legacy-compat no-op on 4.0.11-A sid-scoped
+ *      data.
+ *
+ * SKIPS (per RD §4.2.1):
+ *   - bootstrapProjectScan
+ *   - materializeClaudeSettingsLocal
+ *   - resolveFirstTimeHooksInstall
+ *   - applyHookInstall (prevents accidental first-launch hook install)
+ *
+ * Mounted as a CHILD of the existing `session` commander group at
+ * `src/cli/commands/core/session-command.ts:32` (verified pattern:
+ * `session.command('list')...`). NOT `program.command('session primer')`.
+ *
+ * The action handler is exported as `runPrimerAction` so the
+ * integration test suite can drive it directly without going through
+ * Commander's argv-parsing wrapper (which would mangle empty /
+ * whitespace / NUL-byte inputs before reaching the action body).
+ */
+import type { Command } from 'commander';
+import type { ProgramIO } from '../cli-helpers.js';
+export type PrimerOptions = {
+    project: string;
+    json?: boolean;
+};
+/**
+ * Pure action body for `peaks session primer`. Exported so
+ * integration tests can drive it directly with crafted inputs (empty
+ * string, whitespace, NUL byte) that would otherwise be rejected by
+ * Commander's argv parser.
+ *
+ * Returns `{ exitCode: 0 | 1 }` so callers (CLI path or test path)
+ * can apply the exit code uniformly. NEVER calls `process.exit` —
+ * exits are the responsibility of the CLI wrapper.
+ */
+export declare function runPrimerAction(opts: PrimerOptions, io: ProgramIO): Promise<{
+    exitCode: 0 | 1;
+}>;
+export declare function registerPrimerCommand(program: Command, io: ProgramIO): void;

package/dist/cli/commands/primer-command.js

@@ -0,0 +1,160 @@
+/**
+ * Slice rid-statusline-stale-ux AC-2: `peaks session primer --project <path>`.
+ *
+ * Lightweight SessionStart primer that fires rotation + presence
+ * cleanup BEFORE the first statusline render of a fresh session.
+ * Independent subcommand (NOT a flag on `peaks workspace init` per
+ * task regulation: "don't add a flag to workspace init"). Cleaner
+ * permission boundary — primer cannot be mistaken for init by users.
+ *
+ * Performs only 3 things:
+ *   1. ensureSessionWithRotation(projectRoot) — the real rotation
+ *      entry point (verified at
+ *      src/services/session/session-binding-bridge.ts:461-527).
+ *   2. If outer-mismatch rotation occurred: call
+ *      clearStalePresenceOnRotation with the verified single-options-
+ *      object signature (mirrors init-command.ts:324-329 pattern with
+ *      all 3 fields populated). Note: on 4.0.11-A sid-scoped leases
+ *      this is a legacy-compat no-op; the real cleanup mechanism is
+ *      rotation itself (rebinding changes the bound sid so the
+ *      reader looks in the new sid's empty lease dir).
+ *   3. gcStalePresenceLeases({ projectRoot, trigger: 'manual' }) —
+ *      sync; documented as legacy-compat no-op on 4.0.11-A sid-scoped
+ *      data.
+ *
+ * SKIPS (per RD §4.2.1):
+ *   - bootstrapProjectScan
+ *   - materializeClaudeSettingsLocal
+ *   - resolveFirstTimeHooksInstall
+ *   - applyHookInstall (prevents accidental first-launch hook install)
+ *
+ * Mounted as a CHILD of the existing `session` commander group at
+ * `src/cli/commands/core/session-command.ts:32` (verified pattern:
+ * `session.command('list')...`). NOT `program.command('session primer')`.
+ *
+ * The action handler is exported as `runPrimerAction` so the
+ * integration test suite can drive it directly without going through
+ * Commander's argv-parsing wrapper (which would mangle empty /
+ * whitespace / NUL-byte inputs before reaching the action body).
+ */
+import { printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { resolveCanonicalProjectRootStrict, InvalidProjectRootError } from '../../services/config/config-safety.js';
+import { ensureSessionWithRotation } from '../../services/session/session-manager.js';
+import { clearStalePresenceOnRotation } from '../../services/skills/skill-presence-service.js';
+import { gcStalePresenceLeases } from '../../services/skills/presence-lease-service.js';
+/**
+ * Pure action body for `peaks session primer`. Exported so
+ * integration tests can drive it directly with crafted inputs (empty
+ * string, whitespace, NUL byte) that would otherwise be rejected by
+ * Commander's argv parser.
+ *
+ * Returns `{ exitCode: 0 | 1 }` so callers (CLI path or test path)
+ * can apply the exit code uniformly. NEVER calls `process.exit` —
+ * exits are the responsibility of the CLI wrapper.
+ */
+export async function runPrimerAction(opts, io) {
+    // Explicit empty / whitespace-only guard BEFORE the strict
+    // resolver. Commander's requiredOption checks presence, not
+    // emptiness; node's `resolve('')` returns cwd (silent
+    // fall-through), so we must short-circuit explicitly.
+    if (!opts.project || opts.project.trim() === '') {
+        printResult(io, fail('session.primer', 'PRIMER_EMPTY_PROJECT', '--project <path> required and must be non-empty', { project: opts.project }, ['Pass a non-empty absolute path to --project']), opts.json);
+        return { exitCode: 1 };
+    }
+    // P1 H1 option A: use NEW strict helper. Throws on NUL /
+    // non-canonical / non-existent path. The fail-open
+    // `resolveCanonicalProjectRoot` is not safe here because primer
+    // is invoked from a SessionStart hook on a path pulled from
+    // `${CLAUDE_PROJECT_DIR}` — the env var is user-controlled and
+    // may contain path traversal payloads.
+    let projectRoot;
+    try {
+        projectRoot = resolveCanonicalProjectRootStrict(opts.project);
+    }
+    catch (error) {
+        if (error instanceof InvalidProjectRootError) {
+            printResult(io, fail('session.primer', `PRIMER_INVALID_PROJECT_ROOT_${error.reason.replace(/-/g, '_').toUpperCase()}`, error.message, { project: opts.project, reason: error.reason }, ['Pass a non-empty absolute canonical path to --project']), opts.json);
+            return { exitCode: 1 };
+        }
+        throw error;
+    }
+    // Real rotation entry point (verified
+    // src/services/session/session-binding-bridge.ts:461-527).
+    // NOT the invented `runRotationCheck` from cycle-2 RD.
+    const rotation = await ensureSessionWithRotation(projectRoot);
+    const rotationOccurred = rotation.previousSessionId !== null
+        && rotation.rotationReason === 'outer-session-mismatch';
+    let clearOutcome = null;
+    if (rotationOccurred) {
+        // VERIFIED single-options-object signature (see
+        // skill-presence-service.ts:584-588). Mirror the real caller
+        // pattern at init-command.ts:324-329 with all 3 fields
+        // populated. NOTE: on 4.0.11-A sid-scoped leases this is a
+        // legacy-compat no-op (clearSkillPresence only unlinks legacy
+        // single-slot files; the real cleanup mechanism is rotation
+        // itself).
+        clearOutcome = clearStalePresenceOnRotation({
+            projectRootOverride: projectRoot,
+            currentOuterSessionId: process.env.PEAKS_OUTER_SESSION_ID
+                ?? process.env.CLAUDE_CODE_SESSION_ID,
+            rotatedOutSessionId: rotation.previousSessionId
+        });
+    }
+    // Sync call (verified presence-lease-service.ts:383-414) —
+    // documented as legacy-compat no-op on 4.0.11-A sid-scoped
+    // data; iterates `input.leases ?? []` and gets `[]` on the
+    // real init-command.ts:463-466 caller.
+    const gcOutcome = gcStalePresenceLeases({
+        projectRoot,
+        trigger: 'manual'
+    });
+    printResult(io, ok('session.primer', {
+        projectRoot,
+        sessionId: rotation.sessionId,
+        rotationOccurred,
+        ...(rotation.previousSessionId !== null
+            ? { previousSessionId: rotation.previousSessionId }
+            : {}),
+        clearOutcome,
+        gcOutcome: {
+            removed: gcOutcome.removed,
+            retained: gcOutcome.retained
+        }
+    }), opts.json);
+    return { exitCode: 0 };
+}
+export function registerPrimerCommand(program, io) {
+    // Reuse the existing `session` commander group registered earlier
+    // in `createProgram` (via autoRegisterAllCommands → session-command.ts:32).
+    // Creating a new `program.command('session')` here throws
+    // `cannot add command 'session' as already have command 'session'`
+    // because commander disallows duplicate top-level command names.
+    // This regression was caught in publish.yml gate-changeset step
+    // (run #134, exit 1) on the first 4.0.18 release attempt.
+    const session = program.commands.find((c) => c.name() === 'session');
+    if (!session) {
+        throw new Error('registerPrimerCommand: session group not registered; ' +
+            'autoRegisterAllCommands must run before registerPrimerCommand');
+    }
+    session
+        .command('primer')
+        .description('Lightweight SessionStart primer: rotation + presence cleanup. ' +
+        'Does NOT bootstrap project scan / materialize settings / install hooks. ' +
+        'Idempotent; safe to run on every SessionStart.')
+        .requiredOption('--project <path>', 'Project root (must be non-empty canonical path)')
+        .option('--json', 'emit a JSON envelope { ok, data } to stdout')
+        .action(async (opts) => {
+        try {
+            const { exitCode } = await runPrimerAction(opts, io);
+            if (exitCode !== 0) {
+                process.exitCode = exitCode;
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            printResult(io, fail('session.primer', 'PRIMER_FAILED', message, { project: opts.project }, ['Verify the project path exists, is writable, and is canonical']), opts.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -25,8 +25,7 @@
  * with reason `--no-browser`. This is a slice-level opt-out for
  * backend-only or already-covered-by-unit-tests work.
  */
-import { join } from 'node:path';
-import { resolve } from 'node:path';
+import { join, resolve } from 'node:path';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { archiveScreenshots } from '../../services/qa/screenshot-archive-service.js';

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

@@ -1,5 +1,5 @@
 import type { Command } from "commander";
-import type { ProgramIO } from "../cli-helpers.js";
+import { type ProgramIO } from "../cli-helpers.js";
 export interface CliResult {
     ok: boolean;
     error?: string;

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

@@ -9,6 +9,17 @@ import { decompose as multiPassDecompose } from '../../services/slice/multi-pass
 import { readResult as readDecompositionResult, writeResult as writeSchemaResult } from '../../services/slice/schema-router.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+/**
+ * PRD-002b slice 2 — extract CLI listing-pagination + table-format
+ * constants. Values are bytewise-identical to the original literals.
+ */
+const SLICE_LIST_DEFAULT_LIMIT = 50;
+const SLICE_LIST_MAX_LIMIT = 500;
+const SLICE_LIST_RID_COL_WIDTH = 34;
+const SLICE_LIST_MTIME_COL_WIDTH = 22;
+const SLICE_LIST_SIZE_COL_WIDTH = 8;
+const SLICE_LIST_PICKED_COL_WIDTH = 6;
+const SLICE_LIST_SEPARATOR_WIDTH = 76;
 export function registerSliceCommands(program, io) {
     const slice = program.command('slice').description('Slice lifecycle: check (boundary), decompose (PRD -> 6-stage algorithm), ' +
         'pick (fzf multi-select), plan (apply via peaks request init). ' +
@@ -67,12 +78,12 @@ export function registerSliceCommands(program, io) {
         '(mtime > 30d). Use --stale-only to filter, --rid <substring> to narrow, ' +
         '--limit <n> to cap. To remove stale entries, use `peaks slice cleanup` (separate slice).')
         .option('--project <path>', 'target project root', '.')
-        .option('--limit <n>', 'cap result count (default 50, max 500)', (v) => parseInt(v, 10), 50)
+        .option('--limit <n>', 'cap result count (default 50, max 500)', (v) => parseInt(v, 10), SLICE_LIST_DEFAULT_LIMIT)
         .option('--stale-only', 'only include rids older than the stale threshold', false)
         .option('--rid <substring>', 'case-insensitive substring filter on rid', '')).action((options) => {
         try {
             const projectRoot = resolveCanonicalProjectRoot(options.project);
-            const limit = Math.max(1, Math.min(500, options.limit ?? 50));
+            const limit = Math.max(1, Math.min(SLICE_LIST_MAX_LIMIT, options.limit ?? SLICE_LIST_DEFAULT_LIMIT));
             const all = listDecompositions(projectRoot);
             let filtered = all;
             const ridSub = (options.rid ?? '').toLowerCase();
@@ -97,13 +108,13 @@ export function registerSliceCommands(program, io) {
             }
             // Plaintext mode: header + table
             const lines = [];
-            lines.push('RID'.padEnd(34) + 'MTIME'.padEnd(22) + 'SIZE'.padEnd(8) + 'PICKED'.padEnd(6) + 'STALE');
-            lines.push('-'.repeat(76));
+            lines.push('RID'.padEnd(SLICE_LIST_RID_COL_WIDTH) + 'MTIME'.padEnd(SLICE_LIST_MTIME_COL_WIDTH) + 'SIZE'.padEnd(SLICE_LIST_SIZE_COL_WIDTH) + 'PICKED'.padEnd(SLICE_LIST_PICKED_COL_WIDTH) + 'STALE');
+            lines.push('-'.repeat(SLICE_LIST_SEPARATOR_WIDTH));
             for (const r of page) {
-                lines.push(r.rid.padEnd(34) +
-                    r.mtime.padEnd(22) +
-                    String(r.sizeBytes).padEnd(8) +
-                    (r.pickedPath ? 'yes' : 'no').padEnd(6) +
+                lines.push(r.rid.padEnd(SLICE_LIST_RID_COL_WIDTH) +
+                    r.mtime.padEnd(SLICE_LIST_MTIME_COL_WIDTH) +
+                    String(r.sizeBytes).padEnd(SLICE_LIST_SIZE_COL_WIDTH) +
+                    (r.pickedPath ? 'yes' : 'no').padEnd(SLICE_LIST_PICKED_COL_WIDTH) +
                     (r.isStale ? 'yes' : 'no'));
             }
             if (truncated) {
@@ -365,6 +376,7 @@ function writeDecompositionFile(rid, result, projectRoot) {
  * recorded in .peaks/memory/ for follow-up). If that slice ships with a
  * different default, both must update here.
  */
+// eslint-disable-next-line no-magic-numbers -- canonical 30-day-in-ms math
 const STALE_THRESHOLD_MS = 30 * 24 * 60 * 60 * 1000;
 /**
  * Enumerate every slice decomposition artifact under

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

@@ -3,6 +3,7 @@ import { type ProgramIO } from '../cli-helpers.js';
 type RenderOptions = {
     project?: string;
     json?: boolean;
+    now?: number | string;
 };
 /**
  * Default-statusline render body. Reused by both the top-level default

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

@@ -74,7 +74,14 @@ export async function runDefaultStatuslineRender(options, io) {
     const seeded = options.project
         ? { ...(stdin ?? {}), workspace: { current_dir: options.project } }
         : stdin;
-    const model = buildStatusLineModel(seeded, Date.now());
+    // Slice 2026-08-07-statusline-flake: accept `--now <epoch-ms>` to pin
+    // `Date.now()` for deterministic lifecycle-window checks under full-
+    // suite concurrency. The integration test passes a test-time `now`
+    // pinned at the moment `seedLifecycle` was called so the completed-
+    // expiry window stays in-range regardless of how long the spawned
+    // subprocess sat descheduled. Production callers omit the flag.
+    const now = options.now !== undefined ? Number(options.now) : Date.now();
+    const model = buildStatusLineModel(seeded, now);
     const capability = resolveStatusLineCapability({
         env: process.env,
         isTTY: Boolean(process.stdout.isTTY),
@@ -98,7 +105,8 @@ export function registerStatusLineCommands(program, io) {
     const statusline = addJsonOption(program
         .command('statusline')
         .description('Render the Peaks skill status line for the current session, or manage the adapter-driven statusLine entry. Run with no subcommand to render; with a subcommand (install | uninstall | status) to manage.')
-        .option('--project <path>', 'project root path (used to label the status line when stdin is absent; applies to the default render path)'));
+        .option('--project <path>', 'project root path (used to label the status line when stdin is absent; applies to the default render path)')
+        .option('--now <ms>', 'override current time (epoch ms) — for testing / deterministic rendering of the lifecycle expiry window'));
     // Default behavior: when the user types `peaks statusline` with no
     // subcommand, render the status line. Without this default action,
     // commander falls back to printing usage (Bug-02, ice-cola surface check
@@ -225,6 +233,7 @@ export function registerStatusLineCommands(program, io) {
         '--session-id to target a non-canonical session explicitly.')
         .option('--project <path>', 'project root (auto-detected from cwd when omitted)')
         .option('--session-id <sid>', 'override the active session id (defaults to the canonical binding; supported for QA / internal tooling)')
+        .option('--now <ms>', 'override current time (epoch ms) — for testing / deterministic rendering of the lifecycle expiry window')
         .action((options, command) => {
         // Re-resolve options via `command.optsWithGlobals()` (Commander 12.x
         // compatibility): when the parent `statusline` command has its own
@@ -243,10 +252,15 @@ export function registerStatusLineCommands(program, io) {
                 ? merged.project
                 : (findProjectRoot(process.cwd()) ?? process.cwd());
             const sid = merged.sessionId ?? getSessionIdCanonical(projectRoot) ?? null;
+            // Slice 2026-08-07-statusline-flake: honor `--now` (epoch ms)
+            // when present so deterministic lifecycle-window checks stay
+            // in-range under full-suite concurrency. See `--now` doc on
+            // the parent `statusline` command.
+            const now = merged.now !== undefined ? Number(merged.now) : Date.now();
             const state = decideCompactStatusline({
                 projectRoot,
                 sessionId: sid,
-                now: Date.now(),
+                now,
             });
             const label = renderCompactStatusline(state);
             // For non-JSON mode we print the LABEL DIRECTLY to stdout

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

@@ -18,7 +18,7 @@
  *     (B2 contract preservation rule from the rid-009 closure record).
  */
 import type { Command } from 'commander';
-import type { ProgramIO } from '../cli-helpers.js';
+import { type ProgramIO } from '../cli-helpers.js';
 import type { WorkspaceConfig } from '../../services/config/config-types.js';
 import { type TechChangeStatus, type WorkspaceConfig as _WorkspaceConfig } from '../../services/tech/tech-change-id-service.js';
 export type { WorkspaceConfig };

package/dist/cli/program.js

@@ -16,6 +16,7 @@ import { registerCronSchedulerCommand } from './commands/cron-scheduler-commands
 import { registerWorkspaceCommands } from './commands/workspace-commands.js';
 import { registerSopCommands } from './commands/sop-commands.js';
 import { registerSkillVisibilityCommand } from './commands/skill-visibility.js';
+import { registerPrimerCommand } from './commands/primer-command.js';
 import { applyRetention, cleanupEccCache } from '../services/log/retention.js';
 import { writeLogEntry, maybeWriteStderr } from '../services/log/logger.js';
 import { printSuperCommandCatalog } from './cli-helpers.js';
@@ -209,5 +210,12 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     // registerCoreAndArtifactCommands instead of being created twice.
     autoRegisterAllCommands(program, io);
     registerSkillVisibilityCommand(program, repoRoot);
+    // Slice rid-statusline-stale-ux AC-2: register `peaks session primer`
+    // so it appears in `peaks session --help` for LLM `<TAB>`-discovery.
+    // Mounted as a CHILD of the existing `session` commander group
+    // (verified at src/cli/commands/core/session-command.ts:32). NOT
+    // `program.command('session primer')` (that registers a single
+    // literal command name, not a child of the session group).
+    registerPrimerCommand(program, io);
     return program;
 }

package/dist/services/artifacts/request-artifact-service.d.ts

@@ -1,6 +1,6 @@
 import { DEFAULT_REQUEST_TYPE, isRequestType, VALID_REQUEST_TYPES, type PrerequisiteCheckResult, type RequestType } from './artifact-prerequisites.js';
 export { VALID_REQUEST_TYPES, DEFAULT_REQUEST_TYPE, isRequestType, type RequestType };
-import type { RequestArtifactRole } from './artifact-templates.js';
+import { type RequestArtifactRole } from './artifact-templates.js';
 export type { RequestArtifactRole } from './artifact-templates.js';
 export { formatHandoffPath, formatCommitBoundaryPath, formatSkillUsageLessonsPath } from './artifact-templates.js';
 export type CreateRequestArtifactOptions = {
@@ -110,7 +110,7 @@ export type TransitionRequestArtifactResult = RequestArtifactSummary & {
     content: string;
     bypassedPrerequisites?: PrerequisiteCheckResult;
 };
-import type { RequestArtifactState } from './request-artifact-state-helpers.js';
+import { type RequestArtifactState } from './request-artifact-state-helpers.js';
 export { allowedStatesForRole, FileSizeViolationError, LintGateError, PrerequisitesNotSatisfiedError, TypeSanityViolationError, updateStatusBlock } from './request-artifact-state-helpers.js';
 export type { RequestArtifactState } from './request-artifact-state-helpers.js';
 export declare function transitionRequestArtifact(options: TransitionRequestArtifactOptions): Promise<TransitionRequestArtifactResult | null>;

package/dist/services/artifacts/request-artifact-service.js

@@ -16,6 +16,15 @@ import { requireUserConfirmation } from '../mode/mode-enforcement.js';
 import { scanFileSize } from '../scan/file-size-scan.js';
 import { emitObservabilityEvent } from '../observability/observability-service.js';
 export { VALID_REQUEST_TYPES, DEFAULT_REQUEST_TYPE, isRequestType };
+// Re-export the pure-function template surface so external callers (CLI,
+// tests) keep importing from this module unchanged. The render templates,
+// handoff-path helpers, and `RequestArtifactRole` type all live in the
+// sibling `artifact-templates.ts` module — see slice
+// 2026-06-24-handoff-path-canonicalization for the rationale.
+//
+// `import type` is required so the type is in scope as a bare identifier
+// within this file (the value re-export alone does not bring types into
+// the local namespace under `isolatedModules`).
 import { renderTemplate } from './artifact-templates.js';
 export { formatHandoffPath, formatCommitBoundaryPath, formatSkillUsageLessonsPath } from './artifact-templates.js';
 const REQUEST_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
@@ -324,7 +333,7 @@ async function readRequestArtifact(projectRoot, scope, role, found) {
 // the sibling `request-artifact-state-helpers.ts` module — see
 // v2.18.3 file-split for the rationale. Function signatures and
 // behaviour are unchanged (verbatim move).
-import { ALLOWED_STATES_PER_ROLE, FileSizeViolationError, LintGateError, PrerequisitesNotSatisfiedError, TypeSanityViolationError, updateStatusBlock } from './request-artifact-state-helpers.js';
+import { ALLOWED_STATES_PER_ROLE, FileSizeViolationError, LintGateError, PrerequisitesNotSatisfiedError, TypeSanityViolationError, updateStatusBlock, } from './request-artifact-state-helpers.js';
 export { allowedStatesForRole, FileSizeViolationError, LintGateError, PrerequisitesNotSatisfiedError, TypeSanityViolationError, updateStatusBlock } from './request-artifact-state-helpers.js';
 export async function transitionRequestArtifact(options) {
     if (!VALID_ROLES.has(options.role)) {

package/dist/services/audit/enforcers/lint-reference-shape.js

@@ -35,6 +35,20 @@ const ABSOLUTE_PATH_WINDOWS = /[A-Z]:\\[\w\\]/;
 const ABSOLUTE_PATH_UNIX = /\/usr\/(?:local|bin|opt)\b/;
 const MAGIC_NUMBER = /\b(\d{3,})\b/;
 const LOAD_STRATEGY_PATTERN = /loadStrategy:\s*(always|on-demand)/i;
+/**
+ * PRD-002b slice 2 — extract cross-cutting thresholds used by
+ * multiple enforcers (file-size cap, magic-number digit floor).
+ * Per-rule spec literals (≤800 lines, ≤12 H2 headings, ≤10 magic
+ * digits, top-N aggregation cap) are kept inline because they ARE
+ * the rule spec; extracting them would change the rule semantics to
+ * depend on a constant with no semantic gain. Names here describe
+ * the role only.
+ */
+const KB_PER_FILE = 1024;
+const LOAD_STRATEGY_FILE_SIZE_KB = 5;
+const OVERVIEW_TOP_SEARCH_LINES = 30;
+const OVERVIEW_MIN_LINE_COUNT = 200;
+const LOAD_STRATEGY_PROBE_LINES = 20;
 function findLine(lines, pattern) {
     for (let i = 0; i < lines.length; i += 1) {
         if (pattern.test(lines[i] ?? ''))
@@ -129,9 +143,9 @@ export function lintH2CountLe12(ref) {
     return [hit('rl-ref-h2-count-le-12-001', 'at most 12 `## <heading>` per reference', ref.path, 1, `(h2 count ${matches.length} > 12)`)];
 }
 export function lintOverviewNearTop(ref) {
-    if (ref.lines.length <= 200)
+    if (ref.lines.length <= OVERVIEW_MIN_LINE_COUNT)
         return [];
-    if (findLine(ref.lines.slice(0, 30), OVERVIEW_HEADING) !== -1)
+    if (findLine(ref.lines.slice(0, OVERVIEW_TOP_SEARCH_LINES), OVERVIEW_HEADING) !== -1)
         return [];
     return [hit('rl-ref-overview-section-near-top-001', 'long references (>200 lines) must have `## Overview` within the first 30 lines', ref.path, 1, '(missing `## Overview` near top of long reference)')];
 }
@@ -149,7 +163,7 @@ export function lintLoadStrategyAlwaysCacheable(ref) {
     // Heuristic: a loadStrategy: always reference must not have a
     // top-level shell command. This is a soft check — we look at
     // the first 10 non-frontmatter lines for I/O patterns.
-    const lines = ref.lines.slice(0, 20);
+    const lines = ref.lines.slice(0, LOAD_STRATEGY_PROBE_LINES);
     for (const line of lines) {
         if (/^\s*(npm|pnpm|yarn|npx|git|curl|wget|docker)\s+/.test(line)) {
             return [hit('rl-ref-loadstrategy-always-cacheable-001', 'loadStrategy: always references must not run I/O at top of file', ref.path, 1, `(I/O pattern at top of file: ${line.trim()})`)];
@@ -249,7 +263,7 @@ export function lintSkillCitesEveryReference(ref, skill) {
 }
 export function lintLoadStrategyMatchesSize(ref) {
     const sizeBytes = Buffer.byteLength(ref.body, 'utf8');
-    if (sizeBytes <= 5 * 1024)
+    if (sizeBytes <= LOAD_STRATEGY_FILE_SIZE_KB * KB_PER_FILE)
         return [];
     // >5KB file should declare loadStrategy: on-demand (always
     // is a context-budget bug).

package/dist/services/code/auto-compact-orchestrator.js

@@ -36,6 +36,14 @@ import { describeMode, thresholdFor } from './auto-compact-modes.js';
 import { read24hState } from '../24h-mode/store.js';
 import { readCompactLifecycle, writeCompactLifecycle } from '../compact-statusline/compact-lifecycle-store.js';
 const PRE_COMPACT_REASON = 'pre-compact-auto';
+/**
+ * PRD-002b slice 2 — extract the few cross-cutting magic numbers
+ * that actually appear at runtime call sites in this orchestrator.
+ * Threshold ratios (0.85 / 0.95) live in `auto-compact-types.ts`
+ * and are NOT extracted here because they ARE the contract; comment
+ * + spec prose references must keep the literal value visible.
+ */
+const COLLAPSED_ERROR_MAX_CHARS = 160;
 /**
  * Map a context ratio to a `CompactTrigger` action. Pure; the side
  * effects (checkpoint + IDE dispatch) live in `runAutoCompact`. Two
@@ -409,7 +417,7 @@ function summarizeLifecycleError(error) {
         raw = 'unknown error';
     const firstLine = raw.split('\n')[0] ?? '';
     const collapsed = firstLine.replace(/\s+/g, ' ').trim();
-    return collapsed.length === 0 ? 'unknown error' : (collapsed.length > 160 ? collapsed.slice(0, 160) : collapsed);
+    return collapsed.length === 0 ? 'unknown error' : (collapsed.length > COLLAPSED_ERROR_MAX_CHARS ? collapsed.slice(0, COLLAPSED_ERROR_MAX_CHARS) : collapsed);
 }
 /**
  * Slice 2026-08-01-compact-lifecycle (Task 5, Step 4): close out an