peaks-loop 4.0.3 → 4.0.5

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

@@ -2,7 +2,7 @@ import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult, getErrorMessage } from '../cli-helpers.js';
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { buildStatusLineModel, parseStatusLineStdin } from '../../services/skills/skill-statusline-service.js';
-import { renderStatusLine } from '../../services/skills/skill-statusline-renderer.js';
+import { renderStatusLine, resolveStatusLineCapability, } from '../../services/skills/skill-statusline-renderer.js';
 import { applyStatusLineInstall, planStatusLineInstall, removeStatusLineInstall } from '../../services/skills/statusline-settings-service.js';
 import { readHookStatus as readSettingsStatus } from '../../services/skills/hooks-settings-service.js';
 import { detectIdeFromContext } from '../../services/ide/hook-translator.js';
@@ -61,6 +61,12 @@ function resolveIdeForCommand(options, projectRoot) {
  * action (Bug-02 dispatch) and the explicit `render` subcommand. Exported
  * so a unit test can exercise the JSON / text output paths without going
  * through commander.
+ *
+ * Capability resolution is delegated to {@link resolveStatusLineCapability}
+ * with only `env` and `isTTY` — the env-driven path is the single first-
+ * version source of truth. No CLI flag widens the surface. The model
+ * itself is read-only: `buildStatusLineModel` is the sole I/O boundary,
+ * and it now also resolves compact state.
  */
 export async function runDefaultStatuslineRender(options, io) {
     const raw = await readStdin();
@@ -69,7 +75,11 @@ export async function runDefaultStatuslineRender(options, io) {
         ? { ...(stdin ?? {}), workspace: { current_dir: options.project } }
         : stdin;
     const model = buildStatusLineModel(seeded, Date.now());
-    const text = renderStatusLine(model);
+    const capability = resolveStatusLineCapability({
+        env: process.env,
+        isTTY: Boolean(process.stdout.isTTY),
+    });
+    const text = renderStatusLine(model, { capability });
     if (options.json === true) {
         io.stdout(JSON.stringify({ ok: true, command: 'statusline.render', data: { text } }, null, 2));
         return;
@@ -193,19 +203,46 @@ export function registerStatusLineCommands(program, io) {
         }
     });
     // peaks statusline compact (slice 2026-07-30-compact-visibility)
+    //
+    // --session-id contract: this flag is registered on the compact
+    // subcommand but NOT on the default `peaks statusline` render path.
+    // The flag is the internal-supported surface for the QA / LLM layer
+    // (the integration test, the QA criteria, and any future
+    // peaks-loop-internal tool that wants to read a non-canonical session's
+    // compact state). The IDE consumer (Claude Code) does NOT need this
+    // flag — its primary-line path binds to the canonical session via
+    // `getSessionIdCanonical(projectRoot)`. Documenting both paths here
+    // keeps the surface small and consistent: the compact subcommand is
+    // the "I have a specific session id in mind" surface; the default
+    // render is the "use the canonical binding" surface.
     addJsonOption(statusline
         .command('compact')
         .description('Render the single-line auto-compact indicator the LLM embeds ' +
         "in Claude Code's statusline. Default output is plain text; " +
-        'pass --json for the structured envelope.')
+        'pass --json for the structured envelope. ' +
+        'Reads the lifecycle record for the canonical session ' +
+        '(`.peaks/_runtime/<sid>/compact-lifecycle.json`); pass ' +
+        '--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)')
-        .action((options) => {
+        .option('--session-id <sid>', 'override the active session id (defaults to the canonical binding; supported for QA / internal tooling)')
+        .action((options, command) => {
+        // Re-resolve options via `command.optsWithGlobals()` (Commander 12.x
+        // compatibility): when the parent `statusline` command has its own
+        // `--json` registered AND the user types `peaks statusline compact
+        // --json`, commander's parent-vs-child option parser can land
+        // `--json` on the parent scope only. `optsWithGlobals()` merges
+        // parent + child options so the JSON branch fires regardless of
+        // which scope commander assigned the flag to. Verified by the
+        // `compact --json emits the documented envelope` integration test.
+        const merged = {
+            ...options,
+            ...command.optsWithGlobals?.(),
+        };
         try {
-            const projectRoot = options.project !== undefined
-                ? options.project
+            const projectRoot = merged.project !== undefined
+                ? merged.project
                 : (findProjectRoot(process.cwd()) ?? process.cwd());
-            const sid = options.sessionId ?? getSessionIdCanonical(projectRoot) ?? null;
+            const sid = merged.sessionId ?? getSessionIdCanonical(projectRoot) ?? null;
             const state = decideCompactStatusline({
                 projectRoot,
                 sessionId: sid,
@@ -215,8 +252,8 @@ export function registerStatusLineCommands(program, io) {
             // For non-JSON mode we print the LABEL DIRECTLY to stdout
             // (no envelope wrapping) because the consumer is the IDE
             // statusline, not a peaks-Loop caller.
-            if (options.json === true) {
-                printResult(io, ok('statusline.compact', { label, state }), options.json);
+            if (merged.json === true) {
+                printResult(io, ok('statusline.compact', { label, state }), merged.json);
             }
             else {
                 process.stdout.write(`${label}\n`);
@@ -224,7 +261,7 @@ export function registerStatusLineCommands(program, io) {
         }
         catch (error) {
             const message = getErrorMessage(error);
-            printResult(io, fail('statusline.compact', 'STATUSLINE_COMPACT_FAILED', message, {}, [message]), options.json);
+            printResult(io, fail('statusline.compact', 'STATUSLINE_COMPACT_FAILED', message, {}, [message]), merged.json);
             process.exitCode = 1;
         }
     }));

package/dist/cli/commands/sub-agent-shutdown-commands.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `peaks sub-agent shutdown register|unregister|list` CLI verbs.
+ *
+ * Slice 2026-08-01-subagent-merge-and-e2e (Task 6). The sub-agent
+ * dispatches a long-lived local process (vite dev, mock API, docker
+ * proxy, etc.). Before it exits, it MUST register the process with
+ * `peaks sub-agent shutdown register --pid <pid> --name <label>`. The
+ * parent session reads the resulting `service-registrations.json`
+ * before the merge-back step and best-effort-kills each entry via
+ * killRegisteredServices (src/services/dispatch/service-shutdown.ts).
+ *
+ * The CLI is intentionally tiny: it appends / removes entries from a
+ * JSON file at `.peaks/_runtime/<sid>/dispatch/<dispatchId>/service-registrations.json`.
+ * The file is the contract between the sub-agent (writer) and the
+ * merge-back-runner (reader). No locking is needed — the sub-agent
+ * writes at most once before exit, and the parent reads after the
+ * sub-agent's process is gone.
+ *
+ * Skill-first / CLI-auxiliary red line: the user does not invoke
+ * these commands directly. They are invoked by the sub-agent (or its
+ * own scripts) at teardown.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+/** Re-exported shape — kept here so the CLI owns the on-disk contract. */
+export type ServiceRegistration = {
+    readonly pid: number;
+    readonly name: string;
+    readonly url?: string;
+};
+export declare function registerSubAgentShutdownCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/sub-agent-shutdown-commands.js

@@ -0,0 +1,110 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { printResult } from '../cli-helpers.js';
+const REGISTRATIONS_FILE = 'service-registrations.json';
+function registrationsPath(input) {
+    return join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'dispatch', input.dispatchId, REGISTRATIONS_FILE);
+}
+function readAll(file) {
+    if (!existsSync(file))
+        return [];
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return [];
+    }
+}
+function writeAll(file, regs) {
+    mkdirSync(join(file, '..'), { recursive: true });
+    writeFileSync(file, JSON.stringify(regs, null, 2), 'utf8');
+}
+function resolveDispatchId(input) {
+    if (typeof input.dispatchId === 'string' && input.dispatchId.length > 0)
+        return input.dispatchId;
+    return process.env.PEAKS_DISPATCH_ID ?? 'current';
+}
+export function registerSubAgentShutdownCommands(program, io) {
+    // The existing `sub-agent-commands.ts` already creates the `sub-agent`
+    // parent; this file attaches the `shutdown` subcommand to the same
+    // parent via `findCommand` so we do not double-register. Fall back
+    // to a standalone `peaks sub-agent-shutdown` parent if the parent
+    // is not yet registered (e.g. when this file is loaded in isolation).
+    const existing = program.commands.find((c) => c.name() === 'sub-agent');
+    const root = existing ?? program.command('sub-agent-shutdown')
+        .description('Sub-agent shutdown registration (forensic hook)');
+    const shutdown = root
+        .command('shutdown')
+        .description('Register local services for the parent to kill before merge-back');
+    const sessionRoot = process.cwd();
+    shutdown
+        .command('register')
+        .requiredOption('--pid <pid>', 'process id')
+        .requiredOption('--name <label>', 'human-readable label (vite / mock-api / etc.)')
+        .option('--url <url>', 'optional URL the service exposes')
+        .option('--dispatch-id <id>', 'dispatch id; default = PEAKS_DISPATCH_ID env or "current"')
+        .action((options) => {
+        try {
+            const sid = getCurrentSessionId(sessionRoot) ?? 'unknown-sid';
+            const file = registrationsPath({
+                projectRoot: sessionRoot,
+                sessionId: sid,
+                dispatchId: resolveDispatchId(options),
+            });
+            const all = readAll(file);
+            const reg = {
+                pid: Number(options.pid),
+                name: options.name,
+                ...(options.url !== undefined ? { url: options.url } : {}),
+            };
+            writeAll(file, [...all, reg]);
+            printResult(io, ok('sub-agent.shutdown.register', { file, reg }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('sub-agent.shutdown.register', 'REGISTER_FAILED', getErrorMessage(error), {}, [getErrorMessage(error)]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    shutdown
+        .command('unregister')
+        .requiredOption('--pid <pid>', 'process id to remove from the registration list')
+        .option('--dispatch-id <id>', 'dispatch id; default = PEAKS_DISPATCH_ID env or "current"')
+        .action((options) => {
+        try {
+            const sid = getCurrentSessionId(sessionRoot) ?? 'unknown-sid';
+            const file = registrationsPath({
+                projectRoot: sessionRoot,
+                sessionId: sid,
+                dispatchId: resolveDispatchId(options),
+            });
+            const filtered = readAll(file).filter((r) => r.pid !== Number(options.pid));
+            writeAll(file, filtered);
+            printResult(io, ok('sub-agent.shutdown.unregister', { file, removed: options.pid }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('sub-agent.shutdown.unregister', 'UNREGISTER_FAILED', getErrorMessage(error), {}, [getErrorMessage(error)]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    shutdown
+        .command('list')
+        .option('--dispatch-id <id>', 'dispatch id; default = PEAKS_DISPATCH_ID env or "current"')
+        .option('--json', 'emit JSON envelope')
+        .action((options) => {
+        try {
+            const sid = getCurrentSessionId(sessionRoot) ?? 'unknown-sid';
+            const file = registrationsPath({
+                projectRoot: sessionRoot,
+                sessionId: sid,
+                dispatchId: resolveDispatchId(options),
+            });
+            printResult(io, ok('sub-agent.shutdown.list', { file, registrations: readAll(file) }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('sub-agent.shutdown.list', 'LIST_FAILED', getErrorMessage(error), {}, [getErrorMessage(error)]), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/worktree-auth-commands.js

@@ -33,6 +33,7 @@ import { atomicWriteJson } from '../../services/ide/shared/atomic-json.js';
 import { emitLeaseEvent } from '../../services/observability/observability-service.js';
 import { deserializeLease, finalizeLease, generateLeaseId, isLeaseActive, isLeaseGcEligible, leaseFilePath, leaseStoreDir, listLeasesSync, markExpired, markGc, markReleased, renewLease, ttlForRole, worktreePath, } from '../../services/worktree/worktree-lease.js';
 import { execSync } from 'node:child_process';
+import { reconcileHostWorktrees } from '../../services/worktree/host-worktree-reconciler.js';
 import { existsSync, readdirSync, readFileSync as readFileSyncNode, statSync } from 'node:fs';
 const DEFAULT_TTL_MS = 5 * 60 * 1_000;
 const ALLOWED_OPERATIONS = [
@@ -65,6 +66,32 @@ export function registerWorktreeAuthCommand(program, io) {
         'The grant is current-task scoped: the LLM must invoke grant after the user has explicitly ' +
         'asked for the operation. The PreToolUse gate fail-closes on missing or expired grants.');
     const auth_ = auth.command('auth').description('Manage worktree authorization grants (granted by the LLM after explicit user opt-in).');
+    addJsonOption(auth
+        .command('reconcile-host')
+        .description('Read-only reconciliation of host-created .claude/worktrees/agent-* against the canonical Peaks lease store.')
+        .option('--session <sid>', 'override session id')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')
+        .option('--host-root <path>', 'override host worktree root')).action((options) => {
+        const projectRoot = resolveProjectRoot(options);
+        const sessionId = resolveSessionId(options, projectRoot);
+        try {
+            const result = reconcileHostWorktrees({
+                projectRoot,
+                sessionId,
+                ...(options.hostRoot !== undefined ? { hostRoot: options.hostRoot } : {}),
+            });
+            const warnings = result.unmanaged.length > 0
+                ? [`${result.unmanaged.length} host worktree(s) are outside Peaks lease governance.`]
+                : [];
+            printResult(io, ok('worktree.reconcile-host', { ...result, sessionId, projectRoot }, warnings), options.json);
+            if (result.unmanaged.length > 0)
+                process.exitCode = 1;
+        }
+        catch (error) {
+            printResult(io, fail('worktree.reconcile-host', 'HOST_WORKTREE_RECONCILE_FAILED', getErrorMessage(error), { sessionId, projectRoot }, []), options.json);
+            process.exitCode = 1;
+        }
+    });
     addJsonOption(auth_
         .command('grant')
         .description('Append a single grant to the current session\'s worktree authorization file.')

package/dist/services/code/auto-compact-orchestrator.d.ts

@@ -1,6 +1,7 @@
 import { type CompactTrigger, type ConvergencePlan, type InFlightBatchProbe, type AutoCompactResult } from '../context/auto-compact-types.js';
 import type { CompactTarget } from '../context/auto-compact-dispatcher.js';
 import { type AutoCompactMode } from './auto-compact-modes.js';
+import { type CompactLifecycleRecord, type CompactLifecycleStage } from '../compact-statusline/compact-lifecycle-store.js';
 export interface AutoCompactInput {
     /** Project root for context (default cwd). */
     readonly projectRoot: string;
@@ -35,6 +36,37 @@ export interface AutoCompactInput {
      * `--mode <mode>` overrides the 24h-mode auto-detection.
      */
     readonly mode?: AutoCompactMode | undefined;
+    /**
+     * Slice 2026-08-01-compact-lifecycle (Task 5): observer fired on
+     * every lifecycle stage this process actually proved. Telemetry
+     * only — it can neither change the threshold decision nor the
+     * dispatch outcome, and a throwing observer is swallowed.
+     */
+    readonly onLifecycleStage?: ((stage: CompactLifecycleStage, record: CompactLifecycleRecord) => void) | undefined;
+    /**
+     * Test-only injection seams for lifecycle failure paths. NEVER set in
+     * production — these exist so the unit suite can drive the `failed`
+     * transition and the store-outage branch without mocking the SUT.
+     * Each flag toggles a single, well-scoped throw at a documented point:
+     *   - `failPreparing`: throw inside the checkpoint/plan/recovery phase
+     *     (so the record rests at `failedAt: 'preparing'`)
+     *   - `failCompacting`: throw inside the IDE-dispatch phase
+     *     (so the record rests at `failedAt: 'compacting'`)
+     *   - `failLifecycleWrite`: make every lifecycle-store write throw
+     *     (so the compact envelope is proven independent of telemetry)
+     */
+    readonly testHooks?: AutoCompactTestHooks | undefined;
+}
+/**
+ * Test-only injection seams. The `boolean` shape (vs. an injected error)
+ * is deliberate: tests assert the *transition*, not the thrown value —
+ * the value would just be a brittle fingerprint. The real error path
+ * is still exercised by `summarizeLifecycleError`'s tests.
+ */
+export interface AutoCompactTestHooks {
+    readonly failPreparing?: boolean | undefined;
+    readonly failCompacting?: boolean | undefined;
+    readonly failLifecycleWrite?: boolean | undefined;
 }
 /**
  * Map a context ratio to a `CompactTrigger` action. Pure; the side
@@ -68,6 +100,13 @@ export declare function evaluateAutoCompactDecision(input: {
     force?: boolean | undefined;
     bypassRedLine?: boolean | undefined;
     mode?: AutoCompactMode | undefined;
+    /**
+     * Source tag from `readContextPercent.source`. Optional — when absent, the
+     * function behaves exactly as pre-rid (ratio-only). Slice 2026-07-31-rid-
+     * mac-transcript-estimate-trigger uses this to carry forward an explicit
+     * carve-out for the Mac-only `transcript-estimate` signal.
+     */
+    source?: string | undefined;
 }): {
     shouldCompact: boolean;
     reason: 'below-threshold' | 'in-flight-batch' | 'pre-compact' | 'red-line';