@lmzhen/dsh-evolution-merge 0.29.0 → 0.30.0

package/lib/types/scan-run.js

@@ -0,0 +1,186 @@
+/**
+ * The scan pair loop. Registry/report lifecycle stays in withMergeRun; this module owns
+ * candidate → round1 → pending/fuse → commit transitions and returns the report draft.
+ */
+import { pairKey, } from "./contracts.js";
+import { transition } from "./coordinator.js";
+import { dropRow, loadMergeState, upsertRow } from "./state.js";
+import { recordPair } from "./domain/pair-index-store.js";
+const isAborted = (signal) => signal.aborted;
+function at(now) {
+    return new Date(now()).toISOString();
+}
+function failureOf(stage, error) {
+    return {
+        stage,
+        code: 'merge-failed',
+        message: error instanceof Error ? error.message : String(error),
+        retryable: true,
+        retryFrom: stage === 'decide' ? 'agent1' : 'agent2',
+    };
+}
+function pairOf(row, candidate, outcome, extra = {}) {
+    return {
+        id: row.id,
+        pairKey: row.pairKey,
+        a: row.a,
+        b: row.b,
+        queue: row.queue,
+        candidate,
+        ...(candidate.gate === undefined ? {} : { gate: candidate.gate }),
+        outcome,
+        archived: [],
+        ...extra,
+    };
+}
+export async function runScan(options) {
+    const stage = options.stage ?? (async () => { });
+    const candidates = await options.ports.screening(options.signal);
+    const before = await loadMergeState(options.io, options.home);
+    const queueBefore = { verify: 0, pending: 0, fuse: 0, skipped: 0 };
+    for (const row of before.state.rows)
+        queueBefore[row.queue] += 1;
+    const startedAt = options.startedAt ?? options.now();
+    const timeoutMs = (options.timeoutMinutes ?? 0) > 0 ? options.timeoutMinutes * 60_000 : 0;
+    const pairs = [];
+    const totals = { merged: 0, kept: 0, pending: 0, failed: 0 };
+    const remaining = [];
+    let stopReason = 'completed';
+    for (let index = 0; index < candidates.length; index += 1) {
+        if (isAborted(options.signal)) {
+            stopReason = 'cancelled';
+            remaining.push(...candidates.slice(index).map(candidate => ({ pairKey: pairKey(candidate.a, candidate.b), queue: 'verify' })));
+            break;
+        }
+        if (timeoutMs > 0 && options.now() - startedAt >= timeoutMs) {
+            stopReason = 'timeout';
+            remaining.push(...candidates.slice(index).map(candidate => ({ pairKey: pairKey(candidate.a, candidate.b), queue: 'verify' })));
+            break;
+        }
+        const candidate = candidates[index];
+        await stage('decide', { done: index, total: candidates.length });
+        let row;
+        try {
+            const created = transition(undefined, { type: 'candidate', a: candidate.a, b: candidate.b, at: at(options.now) });
+            if (!created.ok || created.row === null)
+                throw new Error(created.ok ? 'candidate row missing' : created.message);
+            row = created.row;
+            await upsertRow(options.io, options.home, options.now, row);
+        }
+        catch (error) {
+            totals.failed += 1;
+            pairs.push({
+                id: '', pairKey: pairKey(candidate.a, candidate.b), a: candidate.a, b: candidate.b, queue: 'verify',
+                candidate, outcome: 'failed', archived: [], failure: failureOf('screening', error),
+            });
+            continue;
+        }
+        let round1;
+        try {
+            round1 = await options.ports.round1(candidate, options.signal);
+        }
+        catch (error) {
+            round1 = { kind: 'failed', failure: failureOf('decide', error) };
+        }
+        if (isAborted(options.signal)) {
+            stopReason = 'cancelled';
+            remaining.push(...candidates.slice(index).map(candidate => ({ pairKey: pairKey(candidate.a, candidate.b), queue: 'verify' })));
+            break;
+        }
+        if (round1.kind === 'failed') {
+            const next = transition(row, { type: 'round1-fail', failure: round1.failure ?? failureOf('decide', 'round1 failed'), at: at(options.now) });
+            if (next.ok && next.row !== null) {
+                row = next.row;
+                await upsertRow(options.io, options.home, options.now, row);
+            }
+            pairs.push(pairOf(row, candidate, 'failed', { failure: round1.failure ?? failureOf('decide', 'round1 failed') }));
+            totals.failed += 1;
+            continue;
+        }
+        if (round1.kind === 'keep') {
+            const next = transition(row, { type: 'round1-keep', at: at(options.now) });
+            if (next.ok && next.row !== null) {
+                row = next.row;
+                await upsertRow(options.io, options.home, options.now, row);
+                await recordPair(options.io, options.home, { pairKey: row.pairKey, runId: row.runId ?? 'merge', result: 'kept' });
+            }
+            pairs.push(pairOf(row, candidate, 'kept', round1.decision === undefined ? {} : { decision: round1.decision }));
+            totals.kept += 1;
+            continue;
+        }
+        if (round1.decision === undefined) {
+            pairs.push(pairOf(row, candidate, 'failed', { failure: failureOf('decide', 'merge decision missing') }));
+            totals.failed += 1;
+            continue;
+        }
+        if (options.approval) {
+            const next = transition(row, { type: 'round1-merge', approval: 'on', decision: round1.decision, ...(round1.sourceRevision === undefined ? {} : { sourceRevision: round1.sourceRevision }), ...(round1.targetRevision === undefined ? {} : { targetRevision: round1.targetRevision }), at: at(options.now) });
+            if (next.ok && next.row !== null) {
+                row = next.row;
+                await upsertRow(options.io, options.home, options.now, row);
+            }
+            pairs.push(pairOf(row, candidate, 'pending', { decision: round1.decision }));
+            totals.pending += 1;
+            continue;
+        }
+        const fuse = transition(row, { type: 'round1-merge', approval: 'off', decision: round1.decision, ...(round1.stagingRef === undefined ? {} : { stagingRef: round1.stagingRef }), ...(round1.stagingExpiresAt === undefined ? {} : { stagingExpiresAt: round1.stagingExpiresAt }), at: at(options.now) });
+        if (!fuse.ok || fuse.row === null) {
+            pairs.push(pairOf(row, candidate, 'failed', { decision: round1.decision, failure: failureOf('decide', 'cannot enter fuse') }));
+            totals.failed += 1;
+            continue;
+        }
+        row = fuse.row;
+        await upsertRow(options.io, options.home, options.now, row);
+        if (isAborted(options.signal)) {
+            const cancelled = transition(row, { type: 'round2-cancel', at: at(options.now) });
+            if (cancelled.ok && cancelled.row !== null) {
+                row = cancelled.row;
+                await upsertRow(options.io, options.home, options.now, row);
+            }
+            stopReason = 'cancelled';
+            remaining.push(...candidates.slice(index).map(candidate => ({ pairKey: pairKey(candidate.a, candidate.b), queue: 'fuse' })));
+            break;
+        }
+        await stage('author', { done: index, total: candidates.length });
+        let round2;
+        try {
+            round2 = await options.ports.round2(row, round1.decision, options.signal);
+        }
+        catch (error) {
+            round2 = { kind: 'failed', failure: failureOf('author', error) };
+        }
+        if (round2.kind === 'merged') {
+            const success = transition(row, { type: 'round2-success', at: at(options.now) });
+            if (success.ok)
+                await dropRow(options.io, options.home, options.now, row.id);
+            pairs.push(pairOf(row, candidate, 'merged', {
+                decision: round1.decision,
+                ...(round2.unitId === undefined ? {} : { unitId: round2.unitId }),
+                ...(round2.target === undefined ? {} : { target: round2.target }),
+                archived: round2.archived ?? [],
+            }));
+            totals.merged += 1;
+            continue;
+        }
+        const failed = round2.failure ?? failureOf('author', 'round2 failed');
+        const next = transition(row, { type: 'round2-fail', failure: failed, at: at(options.now) });
+        if (next.ok && next.row !== null) {
+            row = next.row;
+            await upsertRow(options.io, options.home, options.now, row);
+        }
+        pairs.push(pairOf(row, candidate, 'failed', { decision: round1.decision, failure: failed }));
+        totals.failed += 1;
+    }
+    return {
+        stopReason,
+        scope: {
+            candidatePairs: candidates.candidatePairs ?? candidates.length,
+            queueBefore,
+        },
+        pairs,
+        totals,
+        notes: [],
+        ...(remaining.length === 0 ? {} : { remaining }),
+    };
+}
+//# sourceMappingURL=scan-run.js.map

package/lib/types/skill-card.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=skill-card.js.map

package/lib/types/skipped.js

@@ -0,0 +1,24 @@
+/**
+ * Skipped filtering: a pair the operator marked as not-worth-merging stays out of automatic
+ * screening until mergeSkippedTtlDays expires. Explicit /merge pair ignores this set.
+ */
+import { pairKey } from "./contracts.js";
+export function skippedPairKeys(rows, ttlDays, now) {
+    const keys = new Set();
+    for (const row of rows) {
+        if (row.state !== 'skipped')
+            continue;
+        if (ttlDays <= 0) {
+            keys.add(row.pairKey);
+            continue;
+        }
+        const createdAt = Date.parse(row.createdAt);
+        if (!Number.isFinite(createdAt) || now - createdAt < ttlDays * 86_400_000)
+            keys.add(row.pairKey);
+    }
+    return keys;
+}
+export function isSkippedPair(keys, a, b) {
+    return keys.has(pairKey(a, b));
+}
+//# sourceMappingURL=skipped.js.map

package/lib/types/stage-tool-registry.js

@@ -0,0 +1,32 @@
+export class StageToolRegistry {
+    bindings = new Map();
+    bind(childId, context) {
+        this.bindings.set(childId, context);
+    }
+    unbind(childId) {
+        this.bindings.delete(childId);
+    }
+    clear() {
+        this.bindings.clear();
+    }
+    resolve(exec) {
+        const childId = childIdOf(exec);
+        return childId === undefined ? undefined : this.bindings.get(childId);
+    }
+}
+function childIdOf(exec) {
+    if (typeof exec !== 'object' || exec === null)
+        return undefined;
+    const agent = exec.agent;
+    if (typeof agent !== 'object' || agent === null)
+        return undefined;
+    const session = agent.session;
+    if (typeof session === 'object' && session !== null) {
+        const id = session.id;
+        if (typeof id === 'string')
+            return id;
+    }
+    const sessionId = agent.sessionId;
+    return typeof sessionId === 'string' ? sessionId : undefined;
+}
+//# sourceMappingURL=stage-tool-registry.js.map

package/lib/types/stage-tool.js

@@ -0,0 +1,31 @@
+import { copyStagedFile, listStagedFiles, readStagedFile, writeStagedFile, } from "./staging-files.js";
+export async function applyStageTool(io, home, ctx, op) {
+    if (ctx.childId !== ctx.expectedChildId)
+        return { ok: false, code: 'not-merge-child', message: 'merge_stage is only available to the bound merge child' };
+    if (op.op === 'write' || op.op === 'copy') {
+        if (ctx.phase !== 'author')
+            return { ok: false, code: 'phase', message: 'merge_stage write/copy is only allowed in the author phase' };
+    }
+    if (op.op === 'list') {
+        const result = await listStagedFiles(io, home, ctx.runId, op.area, op.path ?? '', op.source);
+        return probeResult(result, 'list');
+    }
+    if (op.op === 'read') {
+        const result = await readStagedFile(io, home, ctx.runId, op.path, op.area, op.source);
+        return probeResult(result, 'read');
+    }
+    if (op.op === 'write') {
+        const result = await writeStagedFile(io, home, ctx.runId, op.path, op.content);
+        return result.ok ? { ok: true, value: { path: result.path } } : { ok: false, code: 'io', message: result.message };
+    }
+    const result = await copyStagedFile(io, home, ctx.runId, op.source, op.from, op.to);
+    return result.ok ? { ok: true, value: { path: result.path } } : { ok: false, code: 'io', message: result.message };
+}
+function probeResult(probe, what) {
+    if (probe.kind === 'present')
+        return { ok: true, value: probe.value };
+    if (probe.kind === 'absent')
+        return { ok: false, code: 'not-found', message: what + ': not found' };
+    return { ok: false, code: 'io', message: what + ': ' + probe.reason };
+}
+//# sourceMappingURL=stage-tool.js.map

package/lib/types/staged-tree.js

@@ -0,0 +1,75 @@
+/**
+ * Read the merged tree a child wrote into a staging run.
+ *
+ * The tree is the commit source: SKILL.md is the body, every other file is a support file.
+ * A missing SKILL.md is unknown, never an empty merge; the caller then refuses commit.
+ */
+import { join } from 'node:path';
+import { probeList, probeUnknown, } from '@lmzhen/dsh-evolution-core';
+import { readStaging, stagingRoot } from "./staging.js";
+function safeRelative(path) {
+    if (path === '' || path.startsWith('/') || path.startsWith('\\') || path.includes('\0'))
+        return false;
+    return path.replace(/\\/g, '/').split('/').every(part => part !== '' && part !== '.' && part !== '..');
+}
+async function walkFiles(io, root, rel = '') {
+    const abs = rel === '' ? root : join(root, ...rel.split('/'));
+    try {
+        const text = await io.readText(abs);
+        if (text !== null)
+            return [rel];
+    }
+    catch { /* a directory read throws; fall through to list */ }
+    const listed = await probeList(io, abs);
+    if (listed.kind === 'unknown')
+        throw new Error('cannot list ' + abs + ': ' + listed.reason);
+    if (listed.kind === 'absent')
+        return [];
+    const out = [];
+    for (const entry of listed.value) {
+        if (entry === '' || entry === '.' || entry === '..')
+            continue;
+        const child = rel === '' ? entry : rel + '/' + entry;
+        if (!safeRelative(child))
+            continue;
+        out.push(...await walkFiles(io, root, child));
+    }
+    return out;
+}
+export async function readStagedTree(io, home, runId) {
+    const staging = await readStaging(io, home, runId);
+    if (staging.kind === 'absent')
+        return { kind: 'absent' };
+    if (staging.kind === 'unknown')
+        return probeUnknown(staging.reason);
+    const target = staging.value.manifest.target;
+    const root = join(stagingRoot(home, runId), 'merged', target);
+    let paths;
+    try {
+        paths = await walkFiles(io, root);
+    }
+    catch (error) {
+        return probeUnknown('cannot list merged tree: ' + (error instanceof Error ? error.message : String(error)));
+    }
+    if (!paths.includes('SKILL.md'))
+        return probeUnknown('merged tree has no SKILL.md');
+    const files = [];
+    for (const path of paths.sort()) {
+        if (path === 'SKILL.md')
+            continue;
+        try {
+            const content = await io.readText(join(root, ...path.split('/')));
+            if (content === null)
+                return probeUnknown('merged file disappeared: ' + path);
+            files.push({ path, content });
+        }
+        catch (error) {
+            return probeUnknown('cannot read merged file ' + path + ': ' + (error instanceof Error ? error.message : String(error)));
+        }
+    }
+    const body = await io.readText(join(root, 'SKILL.md'));
+    if (body === null)
+        return probeUnknown('merged SKILL.md disappeared');
+    return { kind: 'present', value: { target, body, files } };
+}
+//# sourceMappingURL=staged-tree.js.map

package/lib/types/staging-files.js

@@ -0,0 +1,86 @@
+/**
+ * Staged file operations used by the authoring tool.
+ *
+ * The child never receives a general filesystem write. Every path is resolved under
+ * <run>/sources/<source>/ or <run>/merged/<target>/ and must stay there; the staging
+ * manifest supplies the target name. Reads are three-state, writes are atomic at the
+ * file level, and copy only goes sources -> merged.
+ */
+import { join } from 'node:path';
+import { isPresent, probeUnknown, } from '@lmzhen/dsh-evolution-core';
+import { readStaging, stagingRoot } from "./staging.js";
+function safeRelative(path) {
+    if (path === '' || path.startsWith('/') || path.startsWith('\\') || path.includes('\0'))
+        return false;
+    return path.replace(/\\/g, '/').split('/').every(part => part !== '' && part !== '.' && part !== '..');
+}
+function areaRoot(home, runId, target, area, source) {
+    const root = stagingRoot(home, runId);
+    if (area === 'merged')
+        return join(root, 'merged', target);
+    if (source === undefined || source === '')
+        return null;
+    return join(root, 'sources', source);
+}
+export async function writeStagedFile(io, home, runId, path, content, source) {
+    if (!safeRelative(path))
+        return { ok: false, message: 'unsafe staged path: ' + path };
+    const staging = await readStaging(io, home, runId);
+    if (!isPresent(staging))
+        return { ok: false, message: 'staging is not present for run ' + runId };
+    const root = areaRoot(home, runId, staging.value.manifest.target, 'merged', source);
+    if (root === null)
+        return { ok: false, message: 'staged write requires merged area' };
+    const target = join(root, ...path.split('/'));
+    try {
+        await io.writeText(target, content);
+        return { ok: true, path };
+    }
+    catch (error) {
+        return { ok: false, message: 'staged write failed: ' + (error instanceof Error ? error.message : String(error)) };
+    }
+}
+export async function readStagedFile(io, home, runId, path, area, source) {
+    if (!safeRelative(path))
+        return probeUnknown('unsafe staged path: ' + path);
+    const staging = await readStaging(io, home, runId);
+    if (!isPresent(staging))
+        return staging.kind === 'absent' ? { kind: 'absent' } : probeUnknown(staging.reason);
+    const root = areaRoot(home, runId, staging.value.manifest.target, area, source);
+    if (root === null)
+        return probeUnknown('missing source name for sources area');
+    try {
+        const value = await io.readText(join(root, ...path.split('/')));
+        return value === null ? { kind: 'absent' } : { kind: 'present', value };
+    }
+    catch (error) {
+        return probeUnknown('staged read failed: ' + (error instanceof Error ? error.message : String(error)));
+    }
+}
+export async function listStagedFiles(io, home, runId, area, path = '', source) {
+    if (path !== '' && !safeRelative(path))
+        return probeUnknown('unsafe staged path: ' + path);
+    const staging = await readStaging(io, home, runId);
+    if (!isPresent(staging))
+        return staging.kind === 'absent' ? { kind: 'absent' } : probeUnknown(staging.reason);
+    const root = areaRoot(home, runId, staging.value.manifest.target, area, source);
+    if (root === null)
+        return probeUnknown('missing source name for sources area');
+    try {
+        const entries = await io.list(join(root, ...path.split('/').filter(Boolean)));
+        return { kind: 'present', value: [...entries].sort() };
+    }
+    catch (error) {
+        return probeUnknown('staged list failed: ' + (error instanceof Error ? error.message : String(error)));
+    }
+}
+/** Copy one source file into the merged target; the only cross-area operation allowed. */
+export async function copyStagedFile(io, home, runId, source, from, to) {
+    if (!safeRelative(from) || !safeRelative(to))
+        return { ok: false, message: 'unsafe staged copy path' };
+    const sourceFile = await readStagedFile(io, home, runId, from, 'sources', source);
+    if (!isPresent(sourceFile))
+        return { ok: false, message: 'source file is not readable: ' + from };
+    return await writeStagedFile(io, home, runId, to, sourceFile.value);
+}
+//# sourceMappingURL=staging-files.js.map

package/lib/types/staging.d.ts

@@ -46,4 +46,11 @@ export declare function readStaging(io: EvolutionIoLike, home: string, runId: st
 export declare function ensureStaging(io: EvolutionIoLike, home: string, input: CreateStagingInput): Promise<CreateStagingResult>;
 export declare function setStagingTarget(io: EvolutionIoLike, home: string, stageKey: string, target: string, mode?: 'merge-into-existing' | 'create-umbrella' | 'keep'): Promise<boolean>;
 export declare function dropStaging(io: EvolutionIoLike, home: string, stageKey: string): Promise<void>;
+export interface StagingCleanupResult {
+    readonly removed: readonly string[];
+    readonly kept: readonly string[];
+    readonly unknown: readonly string[];
+}
+/** Remove expired run-level staging trees; `keep` names runs a live row still points at. */
+export declare function cleanupExpiredStaging(io: EvolutionIoLike, home: string, now: number, keep?: ReadonlySet<string>): Promise<StagingCleanupResult>;
 //# sourceMappingURL=staging.d.ts.map

package/lib/types/staging.js

@@ -0,0 +1,149 @@
+/**
+ * Staging is a run ARTIFACT, not a queue: <home>/merge/runs/<runId>/.
+ *
+ * createStaging writes a sibling .partial tree first and renames it into place; the .stage
+ * marker is the last write inside the partial. A directory without that marker is a
+ * half-created artifact and reads as unknown, never as "empty".
+ */
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { isPresent, probeAbsent, probePresent, probeText, probeUnknown, } from '@lmzhen/dsh-evolution-core';
+export const STAGING_SCHEMA_VERSION = 1;
+export function stageKeyOf(runId, pairKey) {
+    return runId + '/pairs/' + createHash('sha256').update(pairKey).digest('hex').slice(0, 16);
+}
+export function stagingRoot(home, runId) {
+    return join(home, 'merge', 'runs', runId);
+}
+/** Relative support paths only; the staging tree must never escape its run directory. */
+function safeRelative(path) {
+    if (path === '' || path.startsWith('/') || path.startsWith('\\') || path.includes('\0'))
+        return false;
+    return path.replace(/\\/g, '/').split('/').every(part => part !== '' && part !== '.' && part !== '..');
+}
+function manifestText(manifest) {
+    return JSON.stringify(manifest, null, 2) + '\n';
+}
+export async function createStaging(io, home, input) {
+    const final = stagingRoot(home, input.runId);
+    if (await io.exists(final))
+        return { ok: false, message: 'staging already exists for run ' + input.runId };
+    const names = new Set();
+    for (const source of input.sources) {
+        if (names.has(source.name))
+            return { ok: false, message: 'duplicate source ' + source.name };
+        names.add(source.name);
+        for (const file of source.files) {
+            if (!safeRelative(file.path))
+                return { ok: false, message: 'unsafe support path: ' + file.path };
+        }
+    }
+    const partial = final + '.partial';
+    try {
+        await io.remove(partial);
+        for (const source of input.sources) {
+            const dir = join(partial, 'sources', source.name);
+            await io.writeText(join(dir, 'SKILL.md'), source.body);
+            for (const file of source.files) {
+                await io.writeText(join(dir, ...file.path.split('/')), file.content);
+            }
+        }
+        const at = input.now();
+        const manifest = {
+            schemaVersion: STAGING_SCHEMA_VERSION,
+            runId: input.runId,
+            target: input.target,
+            ...(input.mode === undefined ? {} : { mode: input.mode }),
+            sources: input.sources.map(source => source.name),
+            promptVersion: input.promptVersion,
+            createdAt: at,
+            expiresAt: at + Math.max(0, input.ttlDays) * 86_400_000,
+        };
+        await io.writeText(join(partial, 'manifest.json'), manifestText(manifest));
+        // Marker last: its absence is the half-created signal readStaging reports as unknown.
+        await io.writeText(join(partial, '.stage'), '');
+        await io.rename(partial, final);
+        return { ok: true, path: final, manifest };
+    }
+    catch (error) {
+        try {
+            await io.remove(partial);
+        }
+        catch { /* best effort */ }
+        return { ok: false, message: 'staging create failed: ' + (error instanceof Error ? error.message : String(error)) };
+    }
+}
+export async function readStaging(io, home, runId) {
+    const path = stagingRoot(home, runId);
+    if (!await io.exists(path))
+        return probeAbsent();
+    if (!await io.exists(join(path, '.stage')))
+        return probeUnknown('staging ' + runId + ' has no .stage marker (half-created)');
+    const probe = await probeText(io, join(path, 'manifest.json'));
+    if (!isPresent(probe))
+        return probe;
+    try {
+        const parsed = JSON.parse(probe.value);
+        if (parsed.schemaVersion !== STAGING_SCHEMA_VERSION || parsed.runId !== runId || typeof parsed.target !== 'string' || !Array.isArray(parsed.sources)) {
+            return probeUnknown('staging manifest has an unexpected shape');
+        }
+        return probePresent({ path, manifest: parsed });
+    }
+    catch (error) {
+        return probeUnknown('staging manifest is not JSON: ' + (error instanceof Error ? error.message : String(error)));
+    }
+}
+export async function ensureStaging(io, home, input) {
+    const existing = await readStaging(io, home, input.runId);
+    if (existing.kind === 'present')
+        return { ok: true, path: stagingRoot(home, input.runId), manifest: existing.value.manifest };
+    return createStaging(io, home, input);
+}
+export async function setStagingTarget(io, home, stageKey, target, mode) {
+    const view = await readStaging(io, home, stageKey);
+    if (view.kind !== 'present')
+        return false;
+    const manifest = Object.assign({}, view.value.manifest, { target }, mode === undefined ? {} : { mode });
+    await io.writeText(join(stagingRoot(home, stageKey), 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
+    return true;
+}
+export async function dropStaging(io, home, stageKey) {
+    await io.remove(stagingRoot(home, stageKey));
+}
+/** Remove expired run-level staging trees; `keep` names runs a live row still points at. */
+export async function cleanupExpiredStaging(io, home, now, keep = new Set()) {
+    let runs;
+    try {
+        runs = await io.list(join(home, 'merge', 'runs'));
+    }
+    catch {
+        return { removed: [], kept: [], unknown: [] };
+    }
+    const removed = [];
+    const kept = [];
+    const unknown = [];
+    for (const runId of runs.sort()) {
+        if (keep.has(runId)) {
+            kept.push(runId);
+            continue;
+        }
+        const view = await readStaging(io, home, runId);
+        if (view.kind === 'unknown') {
+            unknown.push(runId);
+            continue;
+        }
+        if (view.kind !== 'present' || view.value.manifest.expiresAt > now) {
+            kept.push(runId);
+            continue;
+        }
+        try {
+            await io.remove(stagingRoot(home, runId));
+            removed.push(runId);
+        }
+        catch {
+            unknown.push(runId);
+        }
+    }
+    return { removed, kept, unknown };
+}
+//# sourceMappingURL=staging.js.map