peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/sediment-pool-commands.js

@@ -0,0 +1,185 @@
+// src/cli/commands/sediment-pool-commands.ts
+//
+// The `peaks skill sediment` verbs that read or write the bee pool itself:
+// `add-segment`, `add-bee`, `list`, `rebuild-index`, `refine-bee`,
+// `clone-bee`, `promote`, `retire`. Split out of `sediment-commands.ts`;
+// every verb's args, envelope and error strings are unchanged.
+import { writeFileSync, mkdirSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { assertNotSystemPath, resolveSegmentsDir, resolveUserBeesDir } from '../../services/sediment/pool-paths.js';
+import { writeBeeManifest } from '../../services/sediment/pool-write.js';
+import { readPool } from '../../services/sediment/pool-read.js';
+import { rebuildIndexFromFs } from '../../services/sediment/pool-rebuild-index.js';
+import { evaluateGate } from '../../services/sediment/promotion-gate.js';
+/** Longest `description` the pool will store; a patch appends under this cap. */
+const DESCRIPTION_MAX_CHARS = 1000;
+export function addSegment(ctx) {
+    const { home, positional, flags } = ctx;
+    const name = positional[1];
+    if (!name)
+        return { ok: false, error: 'MISSING_ARG: name' };
+    const description = flags.maybeString('describe') ?? '';
+    const segDir = join(resolveSegmentsDir({ home }), name);
+    // Soft-protection guard: refuse to write under any `.system` path
+    // segment. Mirrors the same guard in writeBeeManifest.
+    assertNotSystemPath(segDir);
+    mkdirSync(segDir, { recursive: true });
+    writeFileSync(join(segDir, 'SKILL.md'), `---\nname: ${name}\ndescription: ${description}\n---\n`);
+    rebuildIndexFromFs({ home });
+    return { ok: true };
+}
+export function addBee(ctx) {
+    const { home, positional, flags } = ctx;
+    const name = positional[1];
+    if (!name)
+        return { ok: false, error: 'MISSING_ARG: name' };
+    // Collect --segment values; the brief uses repeatable --segment
+    // flags (one token per segment). parseFlags now returns a
+    // 1-element array for a single occurrence and a longer array
+    // for repeated keys, so .list() returns a uniform string[].
+    const segList = flags.list('segment');
+    const description = flags.maybeString('description') ?? '';
+    const m = {
+        schemaVersion: 'peaks.bee/1',
+        name,
+        source: 'user',
+        promotion_status: 'candidate',
+        description,
+        segments: segList.map((s) => ({
+            name: s,
+            inputs: [],
+            outputs: [],
+            sideEffects: []
+        })),
+        entrypoint: { preamble: `## ${name}`, refs: [] },
+        promotion: {
+            minCycles: 1,
+            requiresHumanApproval: true,
+            requiresSmokeTest: true
+        },
+        createdBy: 'llm',
+        lastTouchedAt: new Date().toISOString()
+    };
+    // writeBeeManifest runs zod validation + SYSTEM_PATH_FORBIDDEN
+    // guard internally.
+    writeBeeManifest({ home }, m);
+    rebuildIndexFromFs({ home });
+    return { ok: true };
+}
+export function listPool(ctx) {
+    const idx = readPool({ home: ctx.home });
+    return { ok: true, data: idx.entries };
+}
+export function rebuildIndex(ctx) {
+    const idx = rebuildIndexFromFs({ home: ctx.home });
+    return { ok: true, data: idx };
+}
+/** Read a bee's manifest, or null when it is absent. */
+function readManifest(manifestPath) {
+    if (!existsSync(manifestPath))
+        return null;
+    return JSON.parse(readFileSync(manifestPath, 'utf-8'));
+}
+function beeManifestPath(home, name) {
+    return join(resolveUserBeesDir({ home }), name, 'manifest.json');
+}
+/** Append a `[tag timestamp] text` note to a description under the length cap. */
+function appendNote(description, tag, text, ts) {
+    const note = `[${tag} ${ts}] ${text}`;
+    return (description + (description ? '\n' : '') + note).slice(0, DESCRIPTION_MAX_CHARS);
+}
+export function refineBee(ctx) {
+    const { home, positional, flags } = ctx;
+    const name = positional[1];
+    if (!name)
+        return { ok: false, error: 'MISSING_ARG: refine-bee requires <name>' };
+    const patch = flags.maybeString('patch') ?? '';
+    if (!patch)
+        return { ok: false, error: 'MISSING_ARG: refine-bee requires --patch' };
+    const m = readManifest(beeManifestPath(home, name));
+    if (m === null)
+        return { ok: false, error: 'BEE_NOT_FOUND' };
+    // Append patch note to description, preserving prior content. Cap at
+    // 1000 chars to avoid unbounded growth.
+    const ts = new Date().toISOString();
+    m.description = appendNote(m.description, 'refine', patch, ts);
+    m.lastTouchedAt = ts;
+    // promotion_status is preserved (do not touch it here).
+    writeBeeManifest({ home }, m);
+    rebuildIndexFromFs({ home });
+    return { ok: true };
+}
+export function cloneBee(ctx) {
+    const { home, positional, flags } = ctx;
+    const name = positional[1];
+    if (!name)
+        return { ok: false, error: 'MISSING_ARG: clone-bee requires <name>' };
+    const asName = flags.maybeString('as') ?? '';
+    if (!asName)
+        return { ok: false, error: 'MISSING_ARG: clone-bee requires --as <new-name>' };
+    const src = readManifest(beeManifestPath(home, name));
+    if (src === null)
+        return { ok: false, error: 'BEE_NOT_FOUND' };
+    // Fresh id, reset promotion_status to candidate, rename. The source
+    // manifest is unchanged on disk.
+    const clone = {
+        ...src,
+        name: asName,
+        promotion_status: 'candidate',
+        lastTouchedAt: new Date().toISOString()
+    };
+    writeBeeManifest({ home }, clone);
+    rebuildIndexFromFs({ home });
+    return { ok: true };
+}
+export function promote(ctx) {
+    const { home, positional } = ctx;
+    const name = positional[1];
+    if (!name)
+        return { ok: false, error: 'MISSING_ARG: promote requires <name>' };
+    const m = readManifest(beeManifestPath(home, name));
+    if (m === null)
+        return { ok: false, error: 'BEE_NOT_FOUND' };
+    if (m.source === 'system')
+        return { ok: false, error: 'PROMOTION_SYSTEM_REFUSED' };
+    // Evaluate the PromotionGate (Task 5). The CLI is a thin shim; the
+    // humanApproved / smokeTestPresent inputs default to "true" here
+    // because the LLM-driven peaks-maker workflow has already obtained
+    // those approvals before calling promote.
+    const gate = evaluateGate({ home }, m, {
+        humanApproved: true,
+        smokeTestPresent: m.promotion.requiresSmokeTest
+    });
+    if (!gate.ok) {
+        return {
+            ok: false,
+            error: `PROMOTION_GATE_FAILED: ${gate.failedSubconditions.join(',')}`
+        };
+    }
+    m.promotion_status = 'stable';
+    m.lastTouchedAt = new Date().toISOString();
+    writeBeeManifest({ home }, m);
+    rebuildIndexFromFs({ home });
+    return { ok: true };
+}
+export function retire(ctx) {
+    const { home, positional, flags } = ctx;
+    const name = positional[1];
+    if (!name)
+        return { ok: false, error: 'MISSING_ARG: retire requires <name>' };
+    const reason = flags.maybeString('reason') ?? '';
+    const m = readManifest(beeManifestPath(home, name));
+    if (m === null)
+        return { ok: false, error: 'BEE_NOT_FOUND' };
+    if (m.source === 'system')
+        return { ok: false, error: 'RETIRE_SYSTEM_REFUSED' };
+    m.promotion_status = 'retired';
+    if (reason) {
+        const ts = new Date().toISOString();
+        m.description = appendNote(m.description, 'retire', reason, ts);
+    }
+    m.lastTouchedAt = new Date().toISOString();
+    writeBeeManifest({ home }, m);
+    rebuildIndexFromFs({ home });
+    return { ok: true };
+}

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

@@ -0,0 +1,4 @@
+import type { CliResult, SedimentContext } from './sediment-command-shared.js';
+export declare function search(ctx: SedimentContext): CliResult;
+export declare function recent(ctx: SedimentContext): CliResult;
+export declare function show(ctx: SedimentContext): CliResult;

package/dist/cli/commands/sediment-query-commands.js

@@ -0,0 +1,94 @@
+// src/cli/commands/sediment-query-commands.ts
+//
+// The read-only `peaks skill sediment` verbs: `search`, `recent`, `show`.
+// Split out of `sediment-commands.ts`; every verb's args, envelope and error
+// strings are unchanged.
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveUserBeesDir } from '../../services/sediment/pool-paths.js';
+/** Milliseconds in one day, for `recent --since <N>d`. */
+const MILLISECONDS_PER_DAY = 86_400_000;
+/** `e instanceof Error ? e.message : String(e)` — the pool's error text. */
+function errorText(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/**
+ * Walk `beesDir` and hand every readable bee manifest to `visit`. A manifest
+ * that cannot be parsed is reported as a warning and skipped, exactly as the
+ * per-verb inline loops did.
+ */
+function eachManifest(beesDir, warnings, visit) {
+    if (!existsSync(beesDir))
+        return;
+    for (const name of readdirSync(beesDir)) {
+        const manifestPath = join(beesDir, name, 'manifest.json');
+        if (!existsSync(manifestPath))
+            continue;
+        let manifest;
+        try {
+            manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+        }
+        catch (e) {
+            warnings.push(`skipped ${name}: ${errorText(e)}`);
+            continue;
+        }
+        visit(name, manifest);
+    }
+}
+export function search(ctx) {
+    const { home, positional, flags } = ctx;
+    const query = positional[1] ?? flags.maybeString('q') ?? '';
+    if (!query)
+        return { ok: false, error: 'MISSING_ARG: search requires <query>' };
+    const q = query.toLowerCase();
+    const matches = [];
+    const warnings = [];
+    eachManifest(resolveUserBeesDir({ home }), warnings, (_name, m) => {
+        const haystack = `${m.name ?? ''} ${m.description ?? ''}`.toLowerCase();
+        if (haystack.includes(q)) {
+            matches.push({
+                name: m.name,
+                description: m.description,
+                source: m.source,
+                promotion_status: m.promotion_status
+            });
+        }
+    });
+    return { ok: true, data: { matches, warnings } };
+}
+export function recent(ctx) {
+    const { home, flags } = ctx;
+    const sinceRaw = flags.maybeString('since') ?? '7d';
+    const m = sinceRaw.match(/^(\d+)d$/);
+    if (!m)
+        return { ok: false, error: 'MISSING_ARG: recent requires --since Nd (e.g. 7d)' };
+    const sinceDays = parseInt(m[1], 10);
+    const cutoff = new Date(Date.now() - sinceDays * MILLISECONDS_PER_DAY).toISOString();
+    const matches = [];
+    const warnings = [];
+    eachManifest(resolveUserBeesDir({ home }), warnings, (_name, b) => {
+        if (typeof b.lastTouchedAt === 'string' && b.lastTouchedAt >= cutoff) {
+            matches.push({
+                name: b.name,
+                lastTouchedAt: b.lastTouchedAt,
+                promotion_status: b.promotion_status
+            });
+        }
+    });
+    return { ok: true, data: { matches, warnings } };
+}
+export function show(ctx) {
+    const { home, positional } = ctx;
+    const name = positional[1];
+    if (!name)
+        return { ok: false, error: 'MISSING_ARG: show requires <name>' };
+    const manifestPath = join(resolveUserBeesDir({ home }), name, 'manifest.json');
+    if (!existsSync(manifestPath))
+        return { ok: false, error: 'BEE_NOT_FOUND' };
+    try {
+        return { ok: true, data: JSON.parse(readFileSync(manifestPath, 'utf-8')) };
+    }
+    catch (e) {
+        return { ok: false, error: `MANIFEST_CORRUPT: ${errorText(e)}` };
+    }
+}

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

@@ -0,0 +1,8 @@
+import type { CliResult, SedimentContext } from './sediment-command-shared.js';
+export declare function dispose(ctx: SedimentContext): CliResult;
+export declare function releases(ctx: SedimentContext): CliResult;
+export declare function releaseShow(ctx: SedimentContext): CliResult;
+export declare function releaseDiffVerb(ctx: SedimentContext): CliResult;
+export declare function exportVerb(ctx: SedimentContext): CliResult;
+export declare function importVerb(ctx: SedimentContext): CliResult;
+export declare function gcBlobsVerb(ctx: SedimentContext): CliResult;

package/dist/cli/commands/sediment-release-commands.js

@@ -0,0 +1,232 @@
+// src/cli/commands/sediment-release-commands.ts
+//
+// The `peaks skill sediment` verbs that act on retained releases:
+// `dispose`, `releases`, `release-show`, `release-diff`, `export`, `import`,
+// `gc-blobs`. Split out of `sediment-commands.ts`; every verb's args,
+// envelope, stderr warning and error strings are unchanged.
+import { mkdirSync, existsSync, readFileSync, rmSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { resolveStateDbPath, resolveBlobsDir, resolveUserBeesDir, resolveUserBeeDir } from '../../services/sediment/pool-paths.js';
+import { rebuildIndexFromFs } from '../../services/sediment/pool-rebuild-index.js';
+import { openStateDb } from '../../services/skillhub/sqlite-store.js';
+import { retainRelease } from '../../services/skillhub/release-retain.js';
+import { releaseDiff } from '../../services/skillhub/release-diff.js';
+import { exportRelease } from '../../services/skillhub/release-export.js';
+import { importRelease } from '../../services/skillhub/release-import.js';
+import { gcBlobs } from '../../services/skillhub/release-gc-blobs.js';
+const DEFAULT_RELEASE_VERSION = '0.1.0';
+function beeManifestPath(home, name) {
+    return join(resolveUserBeesDir({ home }), name, 'manifest.json');
+}
+function readManifest(manifestPath) {
+    if (!existsSync(manifestPath))
+        return null;
+    return JSON.parse(readFileSync(manifestPath, 'utf-8'));
+}
+/** `e instanceof Error ? e.message : String(e)` — the pool's error text. */
+function errorText(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/**
+ * User bee destroy: remove the manifest dir from the pool. The scratch
+ * materialization is cleaned up by the dispatch flow (its concern), but the
+ * pool's bees/<name>/manifest.json entry is removed here so the index reflects
+ * reality on next read.
+ */
+function destroyUserBee(home, name) {
+    const beeDir = resolveUserBeeDir({ home }, name);
+    rmSync(beeDir, { recursive: true, force: true });
+    rebuildIndexFromFs({ home });
+    return { ok: true, data: { userDestroyed: true, path: beeDir } };
+}
+/** User bee retain: open state.db, call retainRelease. */
+function retainUserBee(home, manifest, flags) {
+    const version = flags.maybeString('version') ?? DEFAULT_RELEASE_VERSION;
+    const scratchDir = flags.maybeString('scratch') ?? join(home, 'scratch');
+    if (!existsSync(scratchDir))
+        return { ok: false, error: 'SCRATCH_NOT_FOUND' };
+    const stateDbPath = resolveStateDbPath({ home });
+    const blobsDir = resolveBlobsDir({ home });
+    mkdirSync(blobsDir, { recursive: true });
+    const db = openStateDb(stateDbPath);
+    try {
+        retainRelease({ db, blobsDir, scratchDir, manifest, version });
+    }
+    finally {
+        db.close();
+    }
+    return { ok: true, data: { retained: true, version } };
+}
+export function dispose(ctx) {
+    const { home, positional, flags } = ctx;
+    const name = positional[1];
+    if (!name)
+        return { ok: false, error: 'MISSING_ARG: dispose requires <name>' };
+    const decision = flags.maybeString('decision') ?? '';
+    if (decision !== 'destroy' && decision !== 'retain') {
+        return { ok: false, error: 'MISSING_ARG: dispose requires --decision destroy|retain' };
+    }
+    const m = readManifest(beeManifestPath(home, name));
+    if (m === null)
+        return { ok: false, error: 'BEE_NOT_FOUND' };
+    // System bees: silently destroy; refuse retain (Task 9 contract).
+    if (m.source === 'system') {
+        if (decision === 'retain')
+            return { ok: false, error: 'RETAIN_SYSTEM_REFUSED' };
+        return { ok: true, data: { systemDestroyed: true } };
+    }
+    return decision === 'destroy' ? destroyUserBee(home, name) : retainUserBee(home, m, flags);
+}
+const RELEASES_SQL = 'SELECT id, bee_name, version, source, archived_at, archived_by FROM bee_release WHERE bee_name = ? ORDER BY archived_at DESC';
+export function releases(ctx) {
+    const { home, positional } = ctx;
+    const beeName = positional[1];
+    if (!beeName)
+        return { ok: false, error: 'MISSING_ARG: releases requires <bee-name>' };
+    const stateDbPath = resolveStateDbPath({ home });
+    const db = openStateDb(stateDbPath);
+    try {
+        const rows = db.prepare(RELEASES_SQL).all(beeName);
+        return { ok: true, data: rows };
+    }
+    finally {
+        db.close();
+    }
+}
+export function releaseShow(ctx) {
+    const { home, positional, flags } = ctx;
+    const beeName = positional[1];
+    const version = flags.maybeString('version') ?? '';
+    if (!beeName || !version) {
+        return {
+            ok: false,
+            error: 'MISSING_ARG: release-show requires <bee-name> and --version'
+        };
+    }
+    const stateDbPath = resolveStateDbPath({ home });
+    const db = openStateDb(stateDbPath);
+    try {
+        // Cast the row to the typed interface from skillhub/types.ts so
+        // downstream consumers (LLM agents in peaks-maker, CLI JSON
+        // renderers) get a structural shape rather than
+        // Record<string, unknown>. Minor #12 fix.
+        const row = db
+            .prepare('SELECT * FROM bee_release WHERE bee_name = ? AND version = ?')
+            .get(beeName, version);
+        if (!row)
+            return { ok: false, error: 'VERSION_NOT_FOUND' };
+        const id = row.id;
+        const manifest = db.prepare('SELECT * FROM bee_manifest WHERE release_id = ?').get(id);
+        const segments = db
+            .prepare('SELECT * FROM bee_segment_ref WHERE release_id = ?')
+            .all(id);
+        const files = db
+            .prepare('SELECT * FROM bee_file WHERE release_id = ?')
+            .all(id);
+        return { ok: true, data: { release: row, manifest, segments, files } };
+    }
+    finally {
+        db.close();
+    }
+}
+export function releaseDiffVerb(ctx) {
+    const { home, positional, flags } = ctx;
+    const beeName = positional[1];
+    const fromVersion = flags.maybeString('from') ?? '';
+    const toVersion = flags.maybeString('to') ?? '';
+    if (!beeName || !fromVersion || !toVersion) {
+        return {
+            ok: false,
+            error: 'MISSING_ARG: release-diff requires <bee-name> and --from and --to'
+        };
+    }
+    const stateDbPath = resolveStateDbPath({ home });
+    const db = openStateDb(stateDbPath);
+    try {
+        const diff = releaseDiff({ db, beeName, fromVersion, toVersion });
+        return { ok: true, data: diff };
+    }
+    catch (e) {
+        return { ok: false, error: errorText(e) };
+    }
+    finally {
+        db.close();
+    }
+}
+export function exportVerb(ctx) {
+    const { home, positional, flags } = ctx;
+    const beeName = positional[1];
+    const version = flags.maybeString('version') ?? '';
+    const outPath = flags.maybeString('out') ?? '';
+    if (!beeName || !version || !outPath) {
+        return { ok: false, error: 'MISSING_ARG: export requires <bee-name>, --version, --out' };
+    }
+    const stateDbPath = resolveStateDbPath({ home });
+    const blobsDir = resolveBlobsDir({ home });
+    const db = openStateDb(stateDbPath);
+    try {
+        exportRelease({ db, blobsDir, beeName, version, outPath });
+    }
+    catch (e) {
+        return { ok: false, error: errorText(e) };
+    }
+    finally {
+        db.close();
+    }
+    // M7 (spec §7A.2 / §10 RL-9): `peaks skill sediment export` is
+    // an ALIAS of `peaks loop export` for one release cycle. Emit
+    // the deprecation warning to stderr so downstream tooling can
+    // upgrade. Future slice removes the alias.
+    process.stderr.write("warning: 'peaks skill sediment export' is deprecated; use 'peaks loop export' or 'peaks bee export' (peaks.bundle/1, spec §7A.2)\n");
+    return { ok: true, data: { outPath } };
+}
+export function importVerb(ctx) {
+    const { home, positional, flags } = ctx;
+    const bundlePath = positional[1];
+    const asNameRaw = flags.maybeString('as');
+    const asName = asNameRaw && asNameRaw.length > 0 ? asNameRaw : undefined;
+    if (!bundlePath)
+        return { ok: false, error: 'MISSING_ARG: import requires <bundle-path>' };
+    if (!existsSync(bundlePath))
+        return { ok: false, error: 'BUNDLE_NOT_FOUND' };
+    const stateDbPath = resolveStateDbPath({ home });
+    const blobsDir = resolveBlobsDir({ home });
+    mkdirSync(blobsDir, { recursive: true });
+    const db = openStateDb(stateDbPath);
+    try {
+        if (asName !== undefined) {
+            importRelease({ db, blobsDir, inPath: bundlePath, asName });
+        }
+        else {
+            importRelease({ db, blobsDir, inPath: bundlePath });
+        }
+    }
+    catch (e) {
+        return { ok: false, error: errorText(e) };
+    }
+    finally {
+        db.close();
+    }
+    // M7 (spec §7A.2): `peaks skill sediment import` is an ALIAS of
+    // `peaks loop import` for one release cycle. Emit the
+    // deprecation warning so downstream tooling can upgrade.
+    process.stderr.write("warning: 'peaks skill sediment import' is deprecated; use 'peaks loop import' or 'peaks bee import' (peaks.bundle/1, spec §7A.2)\n");
+    return { ok: true, data: { asName: asName ?? basename(bundlePath) } };
+}
+export function gcBlobsVerb(ctx) {
+    const { home, flags } = ctx;
+    const dryRun = flags.bool('dry-run');
+    const stateDbPath = resolveStateDbPath({ home });
+    const blobsDir = resolveBlobsDir({ home });
+    const db = openStateDb(stateDbPath);
+    try {
+        const removed = gcBlobs({ db, blobsDir, dryRun });
+        return { ok: true, data: { removed } };
+    }
+    catch (e) {
+        return { ok: false, error: errorText(e) };
+    }
+    finally {
+        db.close();
+    }
+}

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

@@ -1,82 +1,26 @@
 /**
- * `peaks sub-agent share | shared-read | await` — G8.4 + 2.7.0 await barrier.
+ * `peaks sub-agent share | shared-read | await | finalize` — the registrar layer.
  *
- * to honor the 800-line file cap. These three commands share the G8.4
- * dispatcher-mediated cross-sub-agent signal channel:
+ * These commands share the G8.4 dispatcher-mediated cross-sub-agent signal
+ * channel:
  *   - `share` writes a `<role>.<event>` entry (≤ 1KB soft warn, ≥ 64KB reject).
  *   - `shared-read` returns sibling entries (filtered by `--since` / `--key` glob).
  *   - `await` joins a batch barrier (slice 2.7.0 MVP, claude-code only).
+ *   - `finalize` (D21) signals that a dispatched sub-agent has finished.
  *
  * Not peer-to-peer — pseudo-swarm property 3 preserved.
+ *
+ * The action bodies, error-code hints, record-path scans and the finalize
+ * selection contract live in the sibling `share-*.ts` / `finalize-*.ts` modules;
+ * this file keeps the command shape (names, descriptions, options) and the one
+ * lazily-resolved IDE registry consumer below.
  */
 import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
-/**
- * A `dispatch-*.json` candidate for `finalize --request-id`, as read off disk.
- * The record's own `createdAt` is carried as the recency key — NOT the file's
- * mtime, which any heartbeat or finalize rewrites, so a `done` record can look
- * newer than the `queued` one that superseded it. Keeping the key on the
- * candidate makes the selection rule a pure function of the records and
- * testable without a filesystem.
- */
-export interface FinalizeCandidate {
-    readonly recordPath: string;
-    readonly requestId: string;
-    readonly status: string;
-    readonly createdAt: string;
-}
-/**
- * What `--request-id` actually did, reported in the envelope. N3: the branch
- * used to resolve silently and could not say WHY a record was or was not the
- * one finalized.
- */
-export interface FinalizeSelection {
-    readonly requestId: string;
-    readonly rule: string;
-    readonly matched: number;
-    readonly chosen: string | null;
-    readonly rejected: readonly {
-        readonly recordPath: string;
-        readonly status: string;
-        readonly reason: string;
-    }[];
-}
-/** The one selection rule `--request-id` and `--batch` now share. */
-export declare const FINALIZE_SELECTION_RULE: string;
-/**
- * N3 — pick the record `finalize --request-id` should act on.
- *
- * The branch this replaces `break`ed on the FIRST file whose record carried
- * the requestId and never looked at `status`. With a re-dispatched request
- * always resolved to the OLDEST one — the already-`done` RD record — so
- * finalizing reported success while the newer `queued` QA record stayed
- * queued forever. `--batch` never had that bug: it filters on `queued`.
- *
- * Both branches are now the same rule. Return `null` when nothing is queued:
- * a record that already left `queued` is precisely the one that must NOT be
- * re-finalized, so the caller reports the survivors instead of touching one.
- */
-export declare function selectFinalizeTarget(candidates: readonly FinalizeCandidate[]): FinalizeCandidate | null;
-/** Why a candidate was not the chosen one — reported, never guessed at. */
-export declare function describeFinalizeRejection(candidate: FinalizeCandidate, chosen: FinalizeCandidate | null): string;
+export { FINALIZE_SELECTION_RULE, describeFinalizeRejection, selectFinalizeTarget, type FinalizeCandidate, type FinalizeSelection } from './finalize-selection.js';
+export type { FinalizeOptions } from './finalize-selection.js';
 export declare function registerShareCommand(parent: Command, io: ProgramIO): void;
 export declare function registerSharedReadCommand(parent: Command, io: ProgramIO): void;
 export declare function registerAwaitCommand(parent: Command, io: ProgramIO): void;
-/**
- * signal. Without this, dispatch records stay queued forever.
- *
- * Contract:
- *   - LLM MUST call once per dispatched Task, in post-completion branch.
- *   - --all-stale bulk-marks every queued record for this session (crash recovery).
- */
-export interface FinalizeOptions {
-    batch?: string;
-    requestId?: string;
-    outcome?: string;
-    error?: string;
-    allStale?: boolean;
-    project?: string;
-    sessionId?: string;
-    json?: boolean;
-}
+/** Contract: LLM MUST call once per dispatched Task, in post-completion branch. */
 export declare function registerFinalizeCommand(parent: Command, io: ProgramIO): void;