@gajae-code/coding-agent 0.13.2 → 0.14.0

package/src/session-import/types.ts

@@ -0,0 +1,148 @@
+/**
+ * Provider-neutral session-import contract (issue #3709).
+ *
+ * An import accepts ONE explicit user-selected Codex or Claude transcript/export
+ * file, normalizes it into the intermediate representation below, and rebuilds a
+ * bounded, redacted continuation context inside a NEW GJC session. The source
+ * file is only ever read; provider process state is never scraped.
+ */
+
+/** Providers with a first-party observable transcript/export format. */
+export type SessionImportProviderId = "codex" | "claude";
+
+/** Concrete on-disk format variants the adapters understand. */
+export type SessionImportFormatId = "codex-rollout-jsonl" | "claude-code-jsonl" | "claude-export-json";
+
+/** One normalized conversational unit produced by a provider adapter. */
+export interface ImportedMessage {
+	/** Conversational role. Tool evidence is attached to assistant turns. */
+	role: "user" | "assistant";
+	/** Visible text (may be empty when only tool evidence exists). */
+	text: string;
+	/** ISO-8601 source timestamp when the record carried one. */
+	timestamp?: string;
+	/**
+	 * Bounded, already redacted tool/file evidence lines (e.g. `$ ls` → `ok`).
+	 * Rendered inline after the text so completed work stays visible.
+	 */
+	toolEvidence?: string[];
+}
+
+/** Provider-neutral normalized conversation. */
+export interface ImportedConversation {
+	provider: SessionImportProviderId;
+	format: SessionImportFormatId;
+	/** Source-side session/conversation identifier when the format carries one. */
+	sourceSessionId?: string;
+	/** Source title when the format carries one. */
+	title?: string;
+	/** Source workspace cwd when the format carries one. */
+	cwd?: string;
+	messages: ImportedMessage[];
+}
+
+/** Deterministic, actionable import failure codes. */
+export type SessionImportErrorCode =
+	| "invalid_request"
+	| "source_not_found"
+	| "source_unreadable"
+	| "source_changed"
+	| "unsupported_format"
+	| "format_mismatch"
+	| "malformed_input"
+	| "content_too_large"
+	| "destination_conflict"
+	| "io_failed";
+
+/** Import pipeline phase a failure belongs to. */
+export type SessionImportPhase = "request" | "read" | "detect" | "parse" | "normalize" | "persist" | "switch";
+
+export class SessionImportError extends Error {
+	readonly code: SessionImportErrorCode;
+	readonly phase: SessionImportPhase;
+	readonly retryable: boolean;
+	readonly limitBytes?: number;
+	readonly observedBytes?: number;
+
+	constructor(
+		code: SessionImportErrorCode,
+		phase: SessionImportPhase,
+		message: string,
+		options?: { retryable?: boolean; limitBytes?: number; observedBytes?: number },
+	) {
+		super(message);
+		this.name = "SessionImportError";
+		this.code = code;
+		this.phase = phase;
+		this.retryable = options?.retryable ?? false;
+		this.limitBytes = options?.limitBytes;
+		this.observedBytes = options?.observedBytes;
+	}
+}
+
+/** One record the adapter could not map. Never carries raw content. */
+export interface ImportQuarantineRecord {
+	/** 1-based record/line number in the source. */
+	record: number;
+	byteLength: number;
+	sha256: string;
+	reason: "invalid_json" | "unknown_record" | "missing_fields" | "oversized_record";
+}
+
+/** Bounded tallies reported to the user and persisted in provenance. */
+export interface SessionImportCounts {
+	/** Records successfully mapped into the normalized conversation. */
+	mapped: number;
+	/** Records quarantined (never silently dropped). */
+	quarantined: number;
+	/** Secret/credential redactions applied to imported text. */
+	redacted: number;
+	/** Messages omitted from the rendered context by head/tail bounding. */
+	omitted: number;
+}
+
+/** Provenance persisted as a `custom` session entry on the import target. */
+export interface SessionImportProvenance {
+	schemaVersion: 1;
+	customType: "session-import";
+	provider: SessionImportProviderId;
+	format: SessionImportFormatId;
+	/** Basename of the explicit user-selected source file (never a full path). */
+	sourceFileName: string;
+	sourceSessionId?: string;
+	sourceTitle?: string;
+	/** SHA-256 over the exact source bytes that were imported. */
+	sourceSha256: string;
+	sourceBytes: number;
+	/** RFC 4122 UUID of the GJC session that received the import. */
+	targetSessionId: string;
+	importedAt: string;
+	converterVersion: number;
+	sanitizerVersion: number;
+	counts: SessionImportCounts;
+	/** True when head/tail bounding elided part of the conversation. */
+	truncated: boolean;
+	quarantine: { present: boolean; truncated: boolean; records: ImportQuarantineRecord[] };
+}
+
+/** Fully prepared import: parsed, normalized, redacted, bounded. No session state mutated yet. */
+export interface PreparedSessionImport {
+	conversation: ImportedConversation;
+	/** Rendered continuation context for the `custom_message` entry. */
+	contextText: string;
+	provenance: Omit<SessionImportProvenance, "targetSessionId" | "importedAt">;
+	counts: SessionImportCounts;
+	/** Distinct redaction pattern ids that fired (for the user-facing summary). */
+	redactionKinds: string[];
+	sourcePath: string;
+	sourceSha256: string;
+	sourceBytes: number;
+}
+
+/** Result of a completed import into a freshly created session file. */
+export interface SessionImportCompleted {
+	targetSessionId: string;
+	targetPath: string;
+	title: string;
+	prepared: PreparedSessionImport;
+}

package/src/setup/paseo/check.ts

@@ -0,0 +1,213 @@
+/**
+ * Read-only diagnosis for `gjc setup paseo --check`.
+ *
+ * Two layers, deliberately separated:
+ *
+ * - L1 is everything GJC can observe on the filesystem. Any non-clean L1
+ *   condition is `drift`, checked first and independent of the daemon.
+ * - L2 is a bounded probe of the Paseo daemon. It only runs when L1 is clean,
+ *   and it partitions the remaining three states by its own outcome.
+ *
+ * That ordering is what makes the four states mutually exclusive: `pass`,
+ * `stale`, and `skipped` all require a clean L1 and are then distinguished
+ * solely by whether the daemon answered and whether it listed our entry. A
+ * daemon that is merely down can never produce `drift`.
+ *
+ * This module never writes. `stale` in particular must not restart anything --
+ * Paseo has no reload verb and its own skill forbids restarting without
+ * explicit user approval, which is exactly why `stale` exists as a state.
+ */
+import * as fs from "node:fs/promises";
+import { recoverIntent } from "./install-saga";
+import { PaseoPublishError, readTarget } from "./json-publisher";
+import { createOrchestrationSeed } from "./orchestration-preferences";
+import { readIntent } from "./paseo-ownership";
+import { buildProviderEntry, hasProviderConflict, providerKeyFor, resolveGjcCommand } from "./provider-config";
+import type { DriftReason, SetupCheckResult } from "./result-types";
+import { INSTALL_SKILL_NAMES, type PaseoSetupDependencies } from "./setup-deps";
+import { scanSkillsBridgeDrift } from "./skills-bridge";
+
+const PROBE_TIMEOUT_MS = 5_000;
+
+export const STALE_GUIDANCE =
+	"Paseo has not picked up the new provider entry yet. Paseo does not reload config.json automatically; restart the Paseo daemon yourself when convenient (GJC will not restart it for you).";
+
+export interface CheckOptions {
+	readonly mpreset?: string;
+	readonly force?: boolean;
+}
+
+/** Collect every L1 (filesystem) observation without touching the daemon. */
+async function collectL1(deps: PaseoSetupDependencies, options: CheckOptions): Promise<DriftReason[]> {
+	const reasons: DriftReason[] = [];
+	const providerKey = providerKeyFor(options.mpreset);
+
+	// An interrupted earlier run leaves a durable intent. Report it, never repair
+	// it here -- `--check` is read-only.
+	const intent = await readIntent(deps.paths.intentRecord);
+	if (intent) {
+		// `repair: false` keeps this read-only; the intent is reported, never settled.
+		const recovery = await recoverIntent(deps.paths.intentRecord, { repair: false });
+		if (recovery) {
+			reasons.push({
+				code: "partial-install",
+				subject: deps.paths.intentRecord,
+				detail: recovery.detail,
+			});
+		}
+	}
+
+	const resolution = resolveGjcCommand();
+	if (!resolution.ok) {
+		reasons.push({ code: "missing-executable", subject: "command[0]", detail: resolution.detail });
+	}
+
+	let configParsed: Record<string, unknown> | undefined;
+	try {
+		const config = await readTarget(deps.paths.configJson);
+		configParsed = config.parsed;
+	} catch (error) {
+		if (error instanceof PaseoPublishError && error.refusal.reason !== "cas-conflict") {
+			reasons.push({
+				code: error.refusal.reason === "parse-refusal" ? "parse-refusal" : "format-drift",
+				subject: deps.paths.configJson,
+				detail: error.message,
+			});
+		} else {
+			throw error;
+		}
+	}
+
+	if (configParsed) {
+		const providers = readProviders(configParsed);
+		const existing = providers?.[providerKey];
+		if (existing === undefined) {
+			reasons.push({
+				code: "missing-provider-entry",
+				subject: `agents.providers.${providerKey}`,
+				detail: "GJC is not registered as a Paseo provider",
+			});
+		} else if (resolution.ok) {
+			const desired = buildProviderEntry(resolution.command, options.mpreset);
+			const conflict = hasProviderConflict(configParsed, providerKey, desired);
+			if (conflict.conflict && !options.force) {
+				reasons.push({
+					code: "owned-key-conflict",
+					subject: conflict.subject,
+					detail: `${conflict.detail} Re-run with --force to overwrite it.`,
+				});
+			}
+		}
+	}
+
+	// AC-14 is about what the provider file actually records, not about what we
+	// would write today: a stale entry pointing at a deleted binary is exactly the
+	// case worth reporting, and it must surface even under --force.
+	if (configParsed) {
+		const recorded = readProviders(configParsed)?.[providerKey];
+		const command =
+			recorded && typeof recorded === "object" ? (recorded as { command?: unknown }).command : undefined;
+		const executable = Array.isArray(command) && typeof command[0] === "string" ? command[0] : undefined;
+		if (executable !== undefined && !(await isExecutable(executable))) {
+			reasons.push({
+				code: "missing-executable",
+				subject: executable,
+				detail: "the provider entry records a command that is missing or not executable",
+			});
+		}
+	}
+
+	try {
+		const preferences = await readTarget(deps.paths.orchestrationPreferences);
+		const seed = createOrchestrationSeed(preferences.parsed);
+		if (seed.seededKeys.length > 0) {
+			reasons.push({
+				code: "unseeded-orchestration-role",
+				subject: deps.paths.orchestrationPreferences,
+				detail: `orchestration roles still unset: ${seed.seededKeys.join(", ")}`,
+			});
+		}
+	} catch (error) {
+		if (error instanceof PaseoPublishError && error.refusal.reason !== "cas-conflict") {
+			reasons.push({
+				code: error.refusal.reason === "parse-refusal" ? "parse-refusal" : "format-drift",
+				subject: deps.paths.orchestrationPreferences,
+				detail: error.message,
+			});
+		} else {
+			throw error;
+		}
+	}
+
+	for (const name of INSTALL_SKILL_NAMES) {
+		const link = `${deps.paths.bridgeDir}/${name}`;
+		const linked = await fs
+			.lstat(link)
+			.then(stat => stat.isSymbolicLink())
+			.catch(() => false);
+		if (!linked) {
+			reasons.push({ code: "missing-bridge-link", subject: link, detail: "bridge symlink is missing" });
+		}
+	}
+
+	reasons.push(...(await scanSkillsBridgeDrift(deps)));
+	return reasons;
+}
+
+function readProviders(config: Record<string, unknown>): Record<string, unknown> | undefined {
+	const agents = config.agents;
+	if (!agents || typeof agents !== "object" || Array.isArray(agents)) return undefined;
+	const providers = (agents as Record<string, unknown>).providers;
+	if (!providers || typeof providers !== "object" || Array.isArray(providers)) return undefined;
+	return providers as Record<string, unknown>;
+}
+
+async function isExecutable(candidate: string): Promise<boolean> {
+	try {
+		await fs.access(candidate, fs.constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Diagnose the installation.
+ *
+ * Precedence is total and the predicates are disjoint by construction:
+ * drift absorbs every non-clean L1 condition, and the remaining three states
+ * partition the L2 outcome space (reachable-with-entry / reachable-without-entry
+ * / unreachable).
+ */
+export async function checkPaseoSetup(
+	deps: PaseoSetupDependencies,
+	options: CheckOptions = {},
+): Promise<SetupCheckResult> {
+	const reasons = await collectL1(deps, options);
+	if (reasons.length > 0) return { component: "paseo", status: "drift", reasons };
+
+	const outcome = await deps.runProviderLs(PROBE_TIMEOUT_MS);
+	if (outcome.kind !== "ok") {
+		// The daemon being down, slow, or speaking an unexpected dialect says
+		// nothing about whether our files are correct -- and L1 already proved
+		// they are. Reporting drift here would blame GJC for Paseo being asleep.
+		return { component: "paseo", status: "skipped", reasons: [] };
+	}
+
+	const providerKey = providerKeyFor(options.mpreset);
+	const row = outcome.rows.find(candidate => candidate.id === providerKey);
+	if (!row) return { component: "paseo", status: "stale", reasons: [], guidance: STALE_GUIDANCE };
+
+	// Paseo listing the provider is not the same as Paseo being able to use it.
+	// Reporting `pass` for a row it marks unavailable would claim a working
+	// integration the user does not have.
+	if (row.status !== undefined && row.status !== "available") {
+		return {
+			component: "paseo",
+			status: "stale",
+			reasons: [],
+			guidance: `Paseo knows about the GJC provider but reports it as "${row.status}". ${STALE_GUIDANCE}`,
+		};
+	}
+	return { component: "paseo", status: "pass", reasons: [] };
+}

package/src/setup/paseo/install-saga.ts

@@ -0,0 +1,293 @@
+/**
+ * Four-step install saga with reverse-order compensation.
+ *
+ * GJC writes to four files it does not own, across two applications, with no
+ * distributed lock available. Nothing here can be made atomic across files, so
+ * the design is instead: refuse early, record enough to recover, and undo in
+ * reverse on failure.
+ *
+ * Forward order is fixed:
+ *   1. `~/.paseo/config.json` provider entry + provider-key provenance
+ *   2. `~/.paseo/orchestration-preferences.json` seeded roles + seeded-key provenance
+ *   3. `<agentDir>/paseo-skills/` symlink bridge
+ *   4. `~/.gjc/agent/config.yml` `skills.customDirectories` append
+ *
+ * Steps 1 and 2 each mutate a Paseo file AND the GJC provenance ledger. Those
+ * are separate files, so a durable intent record is written BEFORE either one,
+ * carrying preflight and expected-post identities for BOTH. Recovery classifies
+ * each file independently and refuses whenever the ledger diverged.
+ */
+import type { CasReceipt } from "../../config/atomic-yaml-patch";
+import { currentIdentity, hashBytes, planPublish, publishPlan, readTarget } from "./json-publisher";
+import {
+	classifyIntent,
+	clearIntent,
+	INTENT_VERSION,
+	type IntentRecord,
+	type IntentStep,
+	type ProvenanceLedger,
+	pendingLedgerOf,
+	readIntent,
+	readProvenance,
+	writeIntent,
+	writeProvenance,
+} from "./paseo-ownership";
+import type { PartialInstallEvidence } from "./result-types";
+
+/** One completed forward step, retaining exactly what its inverse needs. */
+export interface CompletedStep {
+	readonly label: string;
+	/** Undo this step. Resolves to `"reverted"`, or `"conflict"` when the resource moved underneath us. */
+	undo(): Promise<StepUndoResult>;
+}
+
+export type StepUndoResult =
+	| { readonly status: "reverted" }
+	| { readonly status: "conflict"; readonly detail: string; readonly retained: readonly string[] };
+
+export class SagaStepError extends Error {
+	readonly label: string;
+	readonly retained: readonly string[];
+
+	constructor(label: string, message: string, retained: readonly string[] = []) {
+		super(message);
+		this.name = "SagaStepError";
+		this.label = label;
+		this.retained = retained;
+	}
+}
+
+export interface CompensationOutcome {
+	readonly compensated: readonly string[];
+	readonly uncompensated: readonly string[];
+	readonly evidence: PartialInstallEvidence;
+}
+
+/**
+ * Undo completed steps newest-first, halting at the first inverse that reports
+ * a conflict.
+ *
+ * Halting is deliberate: once one resource has diverged, continuing to unwind
+ * the others would leave a stranger mix of reverted and live state that no
+ * later run could interpret. Stopping preserves an interpretable prefix.
+ */
+export async function compensate(
+	completed: readonly CompletedStep[],
+	failure: SagaStepError,
+): Promise<CompensationOutcome> {
+	const compensated: string[] = [];
+	const uncompensated: string[] = [];
+	const retained = [...failure.retained];
+	let conflictDetail: string | undefined;
+
+	for (let index = completed.length - 1; index >= 0; index--) {
+		const step = completed[index]!;
+		if (conflictDetail !== undefined) {
+			uncompensated.push(step.label);
+			continue;
+		}
+		const result = await step.undo();
+		if (result.status === "reverted") {
+			compensated.push(step.label);
+			continue;
+		}
+		conflictDetail = result.detail;
+		uncompensated.push(step.label);
+		retained.push(...result.retained);
+	}
+
+	return {
+		compensated,
+		uncompensated,
+		evidence: {
+			failedStep: failure.label,
+			detail: conflictDetail ? `${failure.message}; compensation halted: ${conflictDetail}` : failure.message,
+			retained: [...new Set(retained)],
+		},
+	};
+}
+
+export interface JsonStepInput {
+	readonly label: string;
+	readonly step: IntentStep;
+	readonly targetPath: string;
+	readonly provenancePath: string;
+	readonly intentPath: string;
+	readonly ownedKeys: readonly string[];
+	/** Mutates the parsed target in place. */
+	readonly mutate: (draft: Record<string, unknown>) => void;
+	/** Produces the ledger that must exist once this step commits. */
+	readonly nextLedger: (ledger: ProvenanceLedger) => ProvenanceLedger;
+	/** Reverts the target, removing only what this step added. */
+	readonly revert: (draft: Record<string, unknown>) => void;
+	/** Produces the ledger that must exist once this step is undone. */
+	readonly revertLedger: (ledger: ProvenanceLedger) => ProvenanceLedger;
+	readonly now: Date;
+}
+
+export interface JsonStepOutput {
+	readonly completed: CompletedStep;
+	readonly changed: boolean;
+	readonly backupPath?: string;
+}
+
+/**
+ * Run one JSON step: intent, target publish, ledger commit, intent clear.
+ *
+ * The intent is written first and cleared last. Between those points a crash is
+ * recoverable because the record alone identifies whether the target carries
+ * pre-write bytes, the exact bytes we intended, or something a third party
+ * produced.
+ */
+export async function runJsonStep(input: JsonStepInput): Promise<JsonStepOutput> {
+	const current = await readTarget(input.targetPath);
+	const plan = planPublish(current, input.mutate);
+
+	const ledgerBefore = await readProvenance(input.provenancePath);
+	const ledgerAfter = input.nextLedger(ledgerBefore);
+	const provenancePreflightIdentity = await currentIdentity(input.provenancePath);
+	const provenanceExpectedIdentity = ledgerIdentity(ledgerAfter);
+
+	if (plan.unchanged && provenancePreflightIdentity === provenanceExpectedIdentity) {
+		return { completed: { label: input.label, undo: async () => ({ status: "reverted" }) }, changed: false };
+	}
+
+	const intent: IntentRecord = {
+		version: INTENT_VERSION,
+		step: input.step,
+		targetPath: input.targetPath,
+		ownedKeys: input.ownedKeys,
+		targetPreflightIdentity: current.identity,
+		targetExpectedIdentity: plan.expectedIdentity,
+		provenancePath: input.provenancePath,
+		provenancePreflightIdentity,
+		provenanceExpectedIdentity,
+		provenancePayload: ledgerAfter,
+		startedAt: input.now.toISOString(),
+	};
+	await writeIntent(input.intentPath, intent);
+
+	let backupPath: string | undefined;
+	try {
+		const published = await publishPlan(input.targetPath, plan, {
+			expectedIdentity: current.identity,
+			backup: true,
+			now: input.now,
+		});
+		backupPath = published.backupPath;
+		await writeProvenance(input.provenancePath, ledgerAfter);
+	} catch (error) {
+		throw new SagaStepError(input.label, error instanceof Error ? error.message : String(error), [
+			input.intentPath,
+			...(backupPath ? [backupPath] : []),
+		]);
+	}
+	await clearIntent(input.intentPath);
+
+	const successIdentity = plan.expectedIdentity;
+	return {
+		completed: {
+			label: input.label,
+			undo: async (): Promise<StepUndoResult> => {
+				const observed = await currentIdentity(input.targetPath);
+				if (observed !== successIdentity) {
+					return {
+						status: "conflict",
+						detail: `${input.targetPath} changed after GJC wrote it; GJC will not overwrite the newer contents`,
+						retained: [input.provenancePath, ...(backupPath ? [backupPath] : [])],
+					};
+				}
+				const now = await readTarget(input.targetPath);
+				const revertPlan = planPublish(now, input.revert);
+				await publishPlan(input.targetPath, revertPlan, {
+					expectedIdentity: now.identity,
+					backup: false,
+					now: input.now,
+				});
+				await writeProvenance(input.provenancePath, input.revertLedger(await readProvenance(input.provenancePath)));
+				return { status: "reverted" };
+			},
+		},
+		changed: true,
+		backupPath,
+	};
+}
+
+/** Hash a ledger exactly as it will be serialized, so the expected identity is computable up front. */
+function ledgerIdentity(ledger: ProvenanceLedger): string {
+	return hashBytes(`${JSON.stringify(ledger, null, 2)}\n`);
+}
+
+/** Wrap a `CasReceipt` as a compensable step. */
+export function receiptStep(label: string, receipt: CasReceipt): CompletedStep {
+	return {
+		label,
+		undo: async (): Promise<StepUndoResult> => {
+			const restored = await receipt.restore();
+			if (restored.status === "restored" || restored.status === "discarded") return { status: "reverted" };
+			if (restored.status === "conflict") {
+				return {
+					status: "conflict",
+					detail: `config.yml changed at ${restored.paths.join(", ")} since GJC appended to it`,
+					retained: [],
+				};
+			}
+			return { status: "conflict", detail: "the config.yml change is not restorable", retained: [] };
+		},
+	};
+}
+
+export interface RecoverIntentOptions {
+	/**
+	 * Act on the classification rather than only reporting it.
+	 *
+	 * Install passes `true`. `--check` passes `false` because it must stay
+	 * read-only: it surfaces the lingering intent as drift and leaves the repair
+	 * to the next install.
+	 */
+	readonly repair: boolean;
+}
+
+/**
+ * Classify a lingering intent left by an interrupted run, and optionally act.
+ *
+ * The outcome comes from classifying BOTH the target and the ledger:
+ *
+ * - `discard`   the publish never landed, so nothing was mutated. Safe to clear.
+ * - `complete-ledger` the publish landed but the ledger commit did not. Re-running
+ *   the same install re-derives and commits the identical provenance in step 1,
+ *   so recovery is to PROCEED. The intent is deliberately left in place until
+ *   that step overwrites it, because clearing it first would lose recoverability
+ *   if the retry is interrupted too.
+ * - `refuse`    a third party changed one of the files. Never replay a recorded
+ *   write over someone else's change.
+ */
+export async function recoverIntent(
+	intentPath: string,
+	options: RecoverIntentOptions = { repair: false },
+): Promise<{ recovered: boolean; detail: string } | undefined> {
+	const intent = await readIntent(intentPath);
+	if (!intent) return undefined;
+	const recovery = await classifyIntent(intent);
+	if (recovery.action === "refuse") return { recovered: false, detail: recovery.detail };
+	if (!options.repair) return { recovered: false, detail: recovery.detail };
+	if (recovery.action === "discard") {
+		await clearIntent(intentPath);
+		return { recovered: true, detail: recovery.detail };
+	}
+
+	// complete-ledger: the publish landed, the ledger commit did not. Finish it
+	// from the intent's own payload rather than relying on a retry to re-run the
+	// step -- a seed-if-empty step would be skipped on retry, because its own
+	// publish already filled the roles it was gated on.
+	const pending = pendingLedgerOf(intent);
+	if (!pending) {
+		return {
+			recovered: false,
+			detail: `${recovery.detail}, but the interrupted step recorded no ledger payload to finish`,
+		};
+	}
+	await writeProvenance(intent.provenancePath, pending);
+	await clearIntent(intentPath);
+	return { recovered: true, detail: `${recovery.detail}; provenance recorded` };
+}