peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/worktree-lease-spawn-command.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `peaks worktree spawn` — write a lease and run `git worktree add`.
+ *
+ * Extracted verbatim from `worktree-lease-commands.ts` (mechanical move of
+ * the `.action()` body plus its two local helpers). The command name,
+ * every option and its help text, the ok/fail envelopes and the
+ * `process.exitCode = 1` on failure are unchanged.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerWorktreeLeaseSpawnCommand(auth: Command, io: ProgramIO): void;

package/dist/cli/commands/worktree-lease-spawn-command.js

@@ -0,0 +1,119 @@
+/**
+ * `peaks worktree spawn` — write a lease and run `git worktree add`.
+ *
+ * Extracted verbatim from `worktree-lease-commands.ts` (mechanical move of
+ * the `.action()` body plus its two local helpers). The command name,
+ * every option and its help text, the ok/fail envelopes and the
+ * `process.exitCode = 1` on failure are unchanged.
+ */
+import { fail, ok } from 'peaks-loop-shared/result';
+import { execSync } from 'node:child_process';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { atomicWriteJson } from '../../services/ide/shared/atomic-json.js';
+import { emitLeaseEvent } from '../../services/observability/observability-service.js';
+import { finalizeLease, generateLeaseId, leaseFilePath, ttlForRole, worktreePath } from '../../services/worktree/worktree-lease.js';
+import { joinPathSession, resolveProjectRoot, resolveSessionId } from './worktree-lease-session.js';
+const SPAWN_DESCRIPTION = `Spawn a worktree under .peaks/_runtime/<sid>/worktrees/<leaseId>/ with a managed lease. ` +
+    `The lease is the source of truth for the L2 hook gate (Part 2 of this slice); ` +
+    `until the hook integration ships, sub-agents may still invoke raw \`git worktree add\` ` +
+    `with a current \`peaks worktree auth grant\` token. Default TTL is role-aware ` +
+    `(rd=30m / qa=15m / ui=1h); pass --ttl <ms> to override.`;
+const SPAWN_TTL_DESCRIPTION = `time-to-live in ms (default role-aware; override with positive number)`;
+// Branch names must be safe for git ref-format; the cap keeps a pathological
+// rid from producing an unusable ref.
+const MAX_BRANCH_NAME_LENGTH = 80;
+function resolveTtlMs(raw, role) {
+    if (typeof raw !== 'string' || raw.length === 0)
+        return ttlForRole(role);
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return ttlForRole(role);
+    return parsed;
+}
+function deriveBranch(rid) {
+    // Branch names must be safe for git ref-format. Strip leading
+    // `rid-` if present and replace any non-safe chars with `-`.
+    return rid.replace(/[^A-Za-z0-9._/-]/g, '-').slice(0, MAX_BRANCH_NAME_LENGTH);
+}
+function printSpawnOk(io, options, ctx) {
+    const { lease, sessionId, projectRoot, ttlMs, wtPath, branch } = ctx;
+    printResult(io, ok('worktree.spawn', {
+        lease,
+        sessionId,
+        projectRoot,
+        ttlMs,
+        nextActions: [
+            `Worktree path: ${wtPath}`,
+            `Branch: ${branch}`,
+            `Lease expires at: ${new Date(lease.expiresAt).toISOString()}`,
+            'Run `peaks worktree release --lease-id <leaseId>` when done',
+            'Hook integration (lease-aware gate) ships in Part 2'
+        ]
+    }, [], []), options.json);
+}
+function printSpawnFailed(io, options, error, sessionId) {
+    printResult(io, fail('worktree.spawn', 'SPAWN_FAILED', getErrorMessage(error), { rid: options.rid, role: options.role, sessionId }, [
+        'Verify `git worktree add` succeeded (output above).',
+        'If the lease file was NOT written, retry; the lease directory is .peaks/_runtime/<sid>/worktree-leases/.',
+        'For an existing branch, pass --branch <name> explicitly (the spawn refuses to overwrite an active branch).'
+    ]), options.json);
+    process.exitCode = 1;
+}
+function runSpawn(options, io) {
+    const projectRoot = resolveProjectRoot(options);
+    const sessionId = resolveSessionId(options, projectRoot);
+    try {
+        const leaseId = generateLeaseId();
+        const now = Date.now();
+        const ttlMs = resolveTtlMs(options.ttl, options.role);
+        const branch = options.branch ?? deriveBranch(options.rid);
+        const wtPath = worktreePath(joinPathSession(projectRoot, sessionId), leaseId);
+        const lease = finalizeLease({
+            leaseId,
+            rid: options.rid,
+            role: options.role,
+            path: wtPath,
+            branch,
+            createdAt: now,
+            expiresAt: now + ttlMs,
+            purpose: options.purpose
+        });
+        // Run `git worktree add` from the project root. The PreToolUse hook
+        // (Part 2 of this slice) will consult the lease file we just wrote
+        // and authorize this very `git worktree add`; for Part 1 we still
+        // require a current `peaks worktree auth grant` token to remain
+        // consistent with the slice-027 hard gate contract.
+        execSync(`git worktree add "${wtPath}" -b "${branch}"`, {
+            cwd: projectRoot,
+            stdio: 'pipe',
+            encoding: 'utf8',
+            windowsHide: true
+        });
+        atomicWriteJson(leaseFilePath(joinPathSession(projectRoot, sessionId), leaseId), lease);
+        // Part 4.A: emit spawn metric (fire-and-forget; never blocks).
+        emitLeaseEvent({
+            sessionId,
+            projectRoot,
+            kind: 'spawn',
+            leaseId,
+            rid: options.rid,
+            role: options.role
+        });
+        printSpawnOk(io, options, { lease, sessionId, projectRoot, ttlMs, wtPath, branch });
+    }
+    catch (error) {
+        printSpawnFailed(io, options, error, sessionId);
+    }
+}
+export function registerWorktreeLeaseSpawnCommand(auth, io) {
+    addJsonOption(auth
+        .command('spawn')
+        .description(SPAWN_DESCRIPTION)
+        .requiredOption('--rid <rid>', 'peaks request id the lease is associated with')
+        .requiredOption('--role <role>', 'sub-agent role (rd | qa | ui | sc | prd | general-purpose)')
+        .requiredOption('--purpose <text>', 'why this worktree was spawned (audit log)')
+        .option('--ttl <ms>', SPAWN_TTL_DESCRIPTION)
+        .option('--branch <name>', 'git branch name (default: derived from rid)')
+        .option('--session <sid>', 'override session id')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => runSpawn(options, io));
+}

package/dist/cli/commands/worktree-lease-status-command.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `peaks worktree lease-status` — show one lease in detail.
+ *
+ * Extracted verbatim from `worktree-lease-commands.ts` (mechanical move of
+ * the `.action()` body). The lease-file failures route through the shared
+ * `loadLeaseOrStop`; the computed `live` flag, the on-disk path
+ * diagnostics and the ok/fail envelopes are unchanged.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerWorktreeLeaseStatusCommand(auth: Command, io: ProgramIO): void;

package/dist/cli/commands/worktree-lease-status-command.js

@@ -0,0 +1,86 @@
+/**
+ * `peaks worktree lease-status` — show one lease in detail.
+ *
+ * Extracted verbatim from `worktree-lease-commands.ts` (mechanical move of
+ * the `.action()` body). The lease-file failures route through the shared
+ * `loadLeaseOrStop`; the computed `live` flag, the on-disk path
+ * diagnostics and the ok/fail envelopes are unchanged.
+ */
+import { fail, ok } from 'peaks-loop-shared/result';
+import { existsSync, statSync } from 'node:fs';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { isLeaseActive, leaseFilePath } from '../../services/worktree/worktree-lease.js';
+import { loadLeaseOrStop } from './worktree-lease-load.js';
+import { joinPathSession, resolveProjectRoot, resolveSessionId } from './worktree-lease-session.js';
+const LEASE_STATUS_DESCRIPTION = 'Show one lease in detail: full lease record + computed `live` flag (active AND not past ' +
+    'expiry) + path/branch/path-exists-on-disk diagnostics. Use this when triaging why a ' +
+    'sub-agent cannot write to a worktree.';
+const STATUS_MISSING_HINTS = ['Run `peaks worktree list` to inspect available leases.'];
+const STATUS_INVALID_HINTS = ['Delete the malformed lease file manually and re-spawn.'];
+/** Whether the lease path is present on disk and is a directory. */
+function inspectLeasePath(leasePath) {
+    const pathExists = existsSync(leasePath);
+    if (!pathExists)
+        return { pathExists, pathIsDirectory: false };
+    try {
+        return { pathExists, pathIsDirectory: statSync(leasePath).isDirectory() };
+    }
+    catch {
+        return { pathExists, pathIsDirectory: false };
+    }
+}
+function printLeaseStatusOk(io, options, ctx) {
+    const { lease, sessionId, projectRoot } = ctx;
+    const now = Date.now();
+    const { pathExists, pathIsDirectory } = inspectLeasePath(lease.path);
+    const live = isLeaseActive(lease, now);
+    printResult(io, ok('worktree.lease-status', {
+        sessionId,
+        projectRoot,
+        file: '.peaks/_runtime/' + sessionId + '/worktree-leases/' + lease.leaseId + '.json',
+        lease,
+        live,
+        diagnostics: {
+            now,
+            remainingMs: lease.expiresAt - now,
+            pathExists,
+            pathIsDirectory
+        }
+    }, [], [
+        `Lease ${lease.leaseId} is ${live ? 'LIVE' : 'NOT LIVE'} ` +
+            `(status=${lease.status}, remaining=${lease.expiresAt - now}ms).`,
+        `Worktree path ${lease.path} ${pathExists ? (pathIsDirectory ? 'exists (dir)' : 'exists (NOT a dir)') : 'MISSING'}.`
+    ]), options.json);
+}
+function printLeaseStatusFailed(io, options, err, sessionId) {
+    printResult(io, fail('worktree.lease-status', 'STATUS_FAILED', getErrorMessage(err), { leaseId: options.leaseId, sessionId }, ['Re-run after fixing the failure (see cause in the error message).']), options.json);
+    process.exitCode = 1;
+}
+function runLeaseStatus(options, io) {
+    const projectRoot = resolveProjectRoot(options);
+    const sessionId = resolveSessionId(options, projectRoot);
+    try {
+        const file = leaseFilePath(joinPathSession(projectRoot, sessionId), options.leaseId);
+        const loaded = loadLeaseOrStop(io, options, {
+            command: 'worktree.lease-status',
+            file,
+            hints: { missing: STATUS_MISSING_HINTS, invalid: STATUS_INVALID_HINTS }
+        });
+        if (loaded.stop) {
+            process.exitCode = 1;
+            return;
+        }
+        printLeaseStatusOk(io, options, { lease: loaded.lease, sessionId, projectRoot });
+    }
+    catch (err) {
+        printLeaseStatusFailed(io, options, err, sessionId);
+    }
+}
+export function registerWorktreeLeaseStatusCommand(auth, io) {
+    addJsonOption(auth
+        .command('lease-status')
+        .description(LEASE_STATUS_DESCRIPTION)
+        .requiredOption('--lease-id <id>', 'lease id to inspect')
+        .option('--session <sid>', 'override session id')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => runLeaseStatus(options, io));
+}

package/dist/cli/commands/worktree-lease-store.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared lease-store reader for the two sweep-style commands (`list`, `gc`).
+ *
+ * Both enumerate the session's lease directory through the pure
+ * `listLeasesSync` helper with the same real-fs bindings, and both render
+ * the same `Malformed lease: <file> (<error>)` warning line per unreadable
+ * file. Extracted verbatim from `worktree-lease-commands.ts`.
+ */
+import { type LeaseListResult } from '../../services/worktree/worktree-lease.js';
+export interface LeaseStoreSnapshot {
+    storeDir: string;
+    result: LeaseListResult;
+}
+export declare function loadLeaseStore(projectRoot: string, sessionId: string): LeaseStoreSnapshot;
+/** One warning line per malformed lease file skipped by the store reader. */
+export declare function malformedLeaseWarnings(errors: ReadonlyArray<{
+    file: string;
+    error: string;
+}>): string[];

package/dist/cli/commands/worktree-lease-store.js

@@ -0,0 +1,24 @@
+/**
+ * Shared lease-store reader for the two sweep-style commands (`list`, `gc`).
+ *
+ * Both enumerate the session's lease directory through the pure
+ * `listLeasesSync` helper with the same real-fs bindings, and both render
+ * the same `Malformed lease: <file> (<error>)` warning line per unreadable
+ * file. Extracted verbatim from `worktree-lease-commands.ts`.
+ */
+import { existsSync, readdirSync, readFileSync as readFileSyncNode } from 'node:fs';
+import { leaseStoreDir, listLeasesSync } from '../../services/worktree/worktree-lease.js';
+import { joinPathSession } from './worktree-lease-session.js';
+export function loadLeaseStore(projectRoot, sessionId) {
+    const storeDir = leaseStoreDir(joinPathSession(projectRoot, sessionId));
+    const result = listLeasesSync(storeDir, {
+        readdir: (p) => readdirSync(p),
+        readFile: (p) => readFileSyncNode(p, 'utf8'),
+        existsSync: (p) => existsSync(p)
+    });
+    return { storeDir, result };
+}
+/** One warning line per malformed lease file skipped by the store reader. */
+export function malformedLeaseWarnings(errors) {
+    return errors.map((e) => `Malformed lease: ${e.file} (${e.error})`);
+}

package/dist/cli/program.js

@@ -8,6 +8,7 @@ import { registerWorkflowCommands } from './commands/workflow-commands.js';
 import { registerCapabilityWorkerConfigAndSCCommands } from './commands/capability-worker-config-sc-commands.js';
 import { registerSubAgentCommands } from './commands/sub-agent-commands.js';
 import { registerLeaseMetricsCommand } from './commands/lease-metrics-commands.js';
+import { registerMcpCommands } from './commands/mcp-commands.js';
 import { registerLeaseStatsCommand } from './commands/lease-stats-commands.js';
 import { registerContainerCommand } from './commands/container-commands.js';
 import { registerVmCommand } from './commands/vm-commands.js';
@@ -197,6 +198,10 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     registerVmCommand(program, io);
     registerCronCommand(program, io);
     registerCronSchedulerCommand(program, io);
+    // The read-only MCP surface's command family. `serve` spawns the server
+    // module by path rather than importing it, so `src/services/mcp/` stays
+    // deletable (see the header of `mcp-commands.ts`).
+    registerMcpCommands(program, io);
     // Auto-route the remaining 60+ commands after the orchestrators so the
     // lazy `skill` parent (used by adapter-commands / sediment-commands)
     // finds the existing `peaks skill` group registered by

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

@@ -0,0 +1,54 @@
+import { type HarnessWindowSyncResult } from '../context/harness-window-config.js';
+import type { ConvergencePlan } from '../context/auto-compact-types.js';
+/**
+ * What the caller is told to do next. The harness-window notice rides along because
+ * the run also rewrites the harness's own settings, so it says so too: the user
+ * accepted that write on the condition 要告知, and a write only one of the two
+ * syncing commands reports is not a notice.
+ */
+export declare function compactNextActions(isRedLine: boolean, harnessWindow: HarnessWindowSyncResult | null): readonly string[];
+/**
+ * Append a one-row convergence decision to the LLM-readable log.
+ * The LLM reads this on the post-compact turn to pick up exactly
+ * where it left off (vs. blindly trusting the IDE's compressed
+ * transcript).
+ */
+export declare function appendAutoDecisionLog(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly plan: ConvergencePlan;
+}): void;
+/**
+ * main-session compact intent so the main-session LLM picks it up on
+ * its next turn and fires `/compact` in-band. Without this file the
+ * orchestrator's "main-session compact" request is invisible to the
+ * main Claude Code window (defeats the whole point of auto-compact
+ * for the main context).
+ *
+ * The file is gitignored under `.peaks/_runtime/<sessionId>/txt/` and
+ * is one-shot: the LLM should `mv` it to `.consumed` after firing
+ * `/compact`. A re-run will overwrite.
+ *
+ * write survives, but nothing consumes the file, and its `nextAction` asks
+ * for a `/compact` the model cannot invoke (the Skill tool exposes only
+ * `/init` and `/security-review`; hooks can observe or veto, never initiate).
+ * Retained deliberately for the sibling A2 slice, which owns harness-side
+ * state re-injection. Not a capability peaks-loop has today.
+ */
+export declare function writeMainSessionCompactIntent(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly ratio: number;
+    readonly redLine: boolean;
+    readonly now: Date;
+}): void;
+/**
+ * Write a pre-compact checkpoint. The shape mirrors `peaks session
+ * checkpoint` so D7's post-compact-detect picks it up unchanged.
+ */
+export declare function writePreCompactCheckpoint(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly now: Date;
+    readonly redLine?: boolean;
+}): string;

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

@@ -0,0 +1,135 @@
+/**
+ * The files one auto-compact run writes: checkpoint, intent and decision log.
+ *
+ * Split out of `auto-compact-orchestrator.ts` (file-size cap campaign). The
+ * orchestrator re-exports every name declared here, so existing importers keep
+ * using `./auto-compact-orchestrator.js` unchanged.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getSessionDir } from '../session/getSessionDir.js';
+import { describeHarnessWindowSync } from '../context/harness-window-config.js';
+/**
+ * What the caller is told to do next. The harness-window notice rides along because
+ * the run also rewrites the harness's own settings, so it says so too: the user
+ * accepted that write on the condition 要告知, and a write only one of the two
+ * syncing commands reports is not a notice.
+ */
+export function compactNextActions(isRedLine, harnessWindow) {
+    if (isRedLine) {
+        return [
+            'RED-LINE: harness compact requested — sub-agent dispatch is NOT blocked; keep working',
+            'Post-compact resume picks up the convergence plan from auto-decisions.md',
+            'Next `peaks code context-now` probe will confirm the ratio dropped; if it keeps climbing and the harness has not compacted, report that to the user and hand control back',
+            describeHarnessWindowSync(harnessWindow)
+        ];
+    }
+    return [
+        'Pre-compact dispatched — IDE compact in progress (async)',
+        'Post-compact resume picks up the convergence plan from auto-decisions.md',
+        'Next `peaks code auto-compact` probe will confirm ratio dropped below 0.85',
+        describeHarnessWindowSync(harnessWindow)
+    ];
+}
+const PRE_COMPACT_REASON = 'pre-compact-auto';
+/**
+ * Append a one-row convergence decision to the LLM-readable log.
+ * The LLM reads this on the post-compact turn to pick up exactly
+ * where it left off (vs. blindly trusting the IDE's compressed
+ * transcript).
+ */
+export function appendAutoDecisionLog(input) {
+    // Repair R6: same hand-rolled join as `writePreCompactCheckpoint`. All four
+    // session-scoped paths in this file now go through the axis builder; none
+    // composes the join itself, so none can resolve outside the project root.
+    const dir = join(getSessionDir(input.projectRoot, input.sessionId), 'txt');
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const logPath = join(dir, 'auto-decisions.md');
+    const row = [
+        '',
+        `## Auto-compact decision — ${input.plan.createdAt}`,
+        `- ratio: ${(input.plan.ratio * 100).toFixed(1)}%`,
+        `- checkpoint: ${input.plan.checkpointPath}`,
+        `- next-actions: ${input.plan.nextActions.join(' | ')}`,
+        `- resume-hint: ${input.plan.resumeHint}`,
+        ''
+    ].join('\n');
+    if (!existsSync(logPath)) {
+        writeFileSync(logPath, `# peaks-code auto-decisions log\n${row}`, 'utf8');
+        return;
+    }
+    const existing = readFileSync(logPath, 'utf8');
+    writeFileSync(logPath, `${existing}${row}`, 'utf8');
+}
+/**
+ * main-session compact intent so the main-session LLM picks it up on
+ * its next turn and fires `/compact` in-band. Without this file the
+ * orchestrator's "main-session compact" request is invisible to the
+ * main Claude Code window (defeats the whole point of auto-compact
+ * for the main context).
+ *
+ * The file is gitignored under `.peaks/_runtime/<sessionId>/txt/` and
+ * is one-shot: the LLM should `mv` it to `.consumed` after firing
+ * `/compact`. A re-run will overwrite.
+ *
+ * write survives, but nothing consumes the file, and its `nextAction` asks
+ * for a `/compact` the model cannot invoke (the Skill tool exposes only
+ * `/init` and `/security-review`; hooks can observe or veto, never initiate).
+ * Retained deliberately for the sibling A2 slice, which owns harness-side
+ * state re-injection. Not a capability peaks-loop has today.
+ */
+export function writeMainSessionCompactIntent(input) {
+    const dir = join(getSessionDir(input.projectRoot, input.sessionId), 'txt');
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const path = join(dir, 'auto-compact-pending.json');
+    const payload = {
+        schemaVersion: 1,
+        pending: true,
+        target: 'main',
+        requestedAt: input.now.toISOString(),
+        ratio: input.ratio,
+        redLine: input.redLine,
+        nextAction: 'next LLM turn MUST fire `/compact` then `mv .peaks/_runtime/<sid>/txt/auto-compact-pending.json .peaks/_runtime/<sid>/txt/auto-compact-pending.consumed.json`'
+    };
+    writeFileSync(path, JSON.stringify(payload, null, 2), 'utf8');
+}
+/**
+ * Write a pre-compact checkpoint. The shape mirrors `peaks session
+ * checkpoint` so D7's post-compact-detect picks it up unchanged.
+ */
+export function writePreCompactCheckpoint(input) {
+    // Repair R6: this used to hand-roll the session join, which is the one shape
+    // `getSessionDir`'s own header records as NOT covered by the guard — an
+    // unsafe id resolved outside the project root and the checkpoint was written
+    // there. The gate above now refuses an unresolvable id before this point, but
+    // `--force` outranks that gate, so this join has to hold on its own.
+    const dir = join(getSessionDir(input.projectRoot, input.sessionId), 'checkpoints');
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const prefix = input.redLine === true ? 'red-line-' : 'pre-compact-';
+    const filename = `${prefix}${input.now.toISOString().replace(/[:.]/g, '-')}.json`;
+    const path = join(dir, filename);
+    const content = {
+        schemaVersion: 1,
+        reason: input.redLine === true ? 'pre-compact-red-line' : PRE_COMPACT_REASON,
+        sessionId: input.sessionId,
+        createdAt: input.now.toISOString(),
+        // D7 reads `mode`, `currentPlan`, `openQuestions`, `recentDecisions`
+        // out of this JSON. We seed empty arrays; the post-compact LLM
+        // rehydrates from the auto-decisions log + open question list.
+        mode: 'full-auto',
+        currentPlan: input.redLine === true
+            ? 'RED-LINE compact REQUESTED from the harness (not executed by peaks-loop); work continues'
+            : 'auto-compact in progress; resume from auto-decisions.md',
+        openQuestions: [],
+        recentDecisions: [],
+        recentArtifactPaths: [],
+        gitStatus: '',
+        skillsActive: ['peaks-code'],
+        todoState: []
+    };
+    writeFileSync(path, JSON.stringify(content, null, 2), 'utf8');
+    return path;
+}

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

@@ -0,0 +1,46 @@
+/**
+ * The two side-effecting phases of a run: prepare the artifacts, then dispatch.
+ *
+ * Split out of `auto-compact-orchestrator.ts` (file-size cap campaign). The
+ * orchestrator re-exports every name declared here, so existing importers keep
+ * using `./auto-compact-orchestrator.js` unchanged.
+ */
+import { type AutoCompactResult, type CompactDispatchResult, type ConvergencePlan } from '../context/auto-compact-types.js';
+import type { CompactTarget } from '../context/auto-compact-dispatcher.js';
+import { CompactLifecyclePublisher } from './auto-compact-lifecycle.js';
+import type { CompactRun } from './auto-compact-run-types.js';
+export type PrepareOutcome = {
+    readonly ok: true;
+    readonly lifecycle: CompactLifecyclePublisher;
+    readonly checkpointPath: string;
+    readonly plan: ConvergencePlan;
+} | {
+    readonly ok: false;
+    readonly envelope: AutoCompactResult;
+};
+/**
+ * One runId per attempt, committed to compacting: the publisher is created at
+ * `queued` and every later transition carries the same id forward. `preparing`
+ * covers the checkpoint, the convergence plan and the decision-log write; a throw
+ * in any of them rests the record at `failedAt: 'preparing'`.
+ */
+export declare function prepareCompactAttempt(ctx: CompactRun): PrepareOutcome;
+export type DispatchOutcome = {
+    readonly ok: true;
+    readonly target: CompactTarget;
+    readonly dispatch: CompactDispatchResult;
+} | {
+    readonly ok: false;
+    readonly envelope: AutoCompactResult;
+};
+/**
+ * The IDE-dispatch phase. The intent record is written only for `main`: without it
+ * the main-session LLM has no signal that the orchestrator asked for compact, and
+ * the dispatcher alone would have been a no-op against the main Claude Code window.
+ */
+export declare function dispatchAttempt(args: {
+    readonly ctx: CompactRun;
+    readonly lifecycle: CompactLifecyclePublisher;
+    readonly checkpointPath: string;
+    readonly plan: ConvergencePlan;
+}): Promise<DispatchOutcome>;

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

@@ -0,0 +1,88 @@
+import { CompactLifecyclePublisher, newCompactRunId } from './auto-compact-lifecycle.js';
+import { appendAutoDecisionLog, compactNextActions, writeMainSessionCompactIntent, writePreCompactCheckpoint } from './auto-compact-artifacts.js';
+import { buildConvergencePlan } from './auto-compact-decision.js';
+import { dispatchFailureResult, prepareFailureResult } from './auto-compact-envelopes.js';
+/**
+ * One runId per attempt, committed to compacting: the publisher is created at
+ * `queued` and every later transition carries the same id forward. `preparing`
+ * covers the checkpoint, the convergence plan and the decision-log write; a throw
+ * in any of them rests the record at `failedAt: 'preparing'`.
+ */
+export function prepareCompactAttempt(ctx) {
+    const { input, sessionId, probe, harnessWindow, isRedLine, now } = ctx;
+    const lifecycle = new CompactLifecyclePublisher({
+        projectRoot: input.projectRoot,
+        sessionId,
+        runId: newCompactRunId(now),
+        triggerRatio: probe.ratio,
+        redLine: isRedLine,
+        onLifecycleStage: input.onLifecycleStage,
+        failLifecycleWrite: input.testHooks?.failLifecycleWrite
+    });
+    lifecycle.advance('queued');
+    try {
+        lifecycle.advance('preparing');
+        if (input.testHooks?.failPreparing)
+            throw new Error('disk full while writing checkpoint');
+        const checkpointPath = writePreCompactCheckpoint({
+            projectRoot: input.projectRoot,
+            sessionId,
+            now,
+            redLine: isRedLine
+        });
+        const plan = buildConvergencePlan({
+            sessionId,
+            projectRoot: input.projectRoot,
+            ratio: probe.ratio,
+            checkpointPath,
+            nextActions: compactNextActions(isRedLine, harnessWindow),
+            redLine: isRedLine
+        });
+        appendAutoDecisionLog({ projectRoot: input.projectRoot, sessionId, plan });
+        return { ok: true, lifecycle, checkpointPath, plan };
+    }
+    catch (error) {
+        lifecycle.fail(error);
+        return { ok: false, envelope: prepareFailureResult(ctx, error) };
+    }
+}
+/**
+ * The IDE-dispatch phase. The intent record is written only for `main`: without it
+ * the main-session LLM has no signal that the orchestrator asked for compact, and
+ * the dispatcher alone would have been a no-op against the main Claude Code window.
+ */
+export async function dispatchAttempt(args) {
+    const { ctx, lifecycle, checkpointPath, plan } = args;
+    const { input, sessionId, probe, isRedLine, now } = ctx;
+    const { dispatchIdeCompact } = await import('../context/auto-compact-dispatcher.js');
+    const target = input.target ?? 'main';
+    try {
+        if (input.testHooks?.failCompacting)
+            throw new Error('IDE dispatch exploded');
+        if (target === 'main') {
+            writeMainSessionCompactIntent({
+                projectRoot: input.projectRoot,
+                sessionId,
+                ratio: probe.ratio,
+                redLine: isRedLine,
+                now
+            });
+        }
+        const dispatch = await dispatchIdeCompact({
+            projectRoot: input.projectRoot,
+            sessionId,
+            env: input.env,
+            target
+        });
+        return { ok: true, target, dispatch };
+    }
+    catch (error) {
+        // `compacting` is the phase this failure died in — a phase label,
+        // not a claim that a compaction was in flight.
+        lifecycle.fail(error, 'compacting');
+        return {
+            ok: false,
+            envelope: dispatchFailureResult(ctx, { checkpointPath, plan, target }, error)
+        };
+    }
+}