/** * `cleo doctor twin-collapse`: report and retry the T12535 twin collapses. * * A twin collapse runs inside the tasks and brain domain binds (see * `store/twin-collapse.ts`). When it cannot finish (no space for its snapshot, * an unusable `.cleo/backups/sqlite`, a merge error) the store turns * read-only for users: reads are served from the merged TEMP shadows, and every * mutating command is refused with `E_TWIN_COLLAPSE_FAILED`. This module is how * the user gets out: * * - {@link inspectProjectTwinCollapse} reads the store read-only, WITHOUT * binding a domain: each pair's state, conflicts, * the recorded failure, and a preflight of the snapshot a pending collapse * needs (backup directory usable, space needed vs free). * - {@link retryTwinCollapse} runs the collapse once on the chokepoint handle, * again without binding, and returns the receipts or the same * `E_TWIN_COLLAPSE_FAILED`. * - {@link twinCollapseDoctorCheck} is the `twin_collapse` row of the default * `cleo doctor` report. * * ## Restore path * * A collapse never writes the bare tables, and a failed one changes nothing. * The initial collapse's snapshot is a full `VACUUM INTO` copy of `cleo.db` * from just before the merge, listed by `cleo backup list` as a `migration` * backup (`.cleo/backups/sqlite/cleo.db.`). To return to it: stop * every CLEO process for the project, move `.cleo/cleo.db`, `.cleo/cleo.db-wal` * and `.cleo/cleo.db-shm` aside, and copy the snapshot to `.cleo/cleo.db`. The * next open re-runs the initial collapse. * * @module * @task T12535 */ import { type TwinCollapseReceipt, type TwinCollapseRecoveryPlan, type TwinCollapseRecoveryReceipt, type TwinCollapseRecoveryRollback, type TwinCollapseSnapshotRelease, type TwinCollapseSnapshotReleasePlan, type TwinCollapseSnapshotRepoint, type TwinCollapseStatus } from '../store/twin-collapse.js'; import { type OwnerStoreRewriteOptions } from '../store/worktree-isolation-guard.js'; /** Preflight of the snapshot a pending initial collapse needs. */ export interface TwinCollapsePreflight { /** `.cleo/backups/sqlite/`. */ readonly backupDir: string; /** Why the directory cannot be used, or `null` when it can. */ readonly backupDirProblem: string | null; /** Bytes the snapshot needs (store live pages plus headroom). */ readonly requiredBytes: number; /** Bytes free on that filesystem, or `null` when unknown. */ readonly availableBytes: number | null; /** Whether a snapshot written now would pass the space check and have a directory. */ readonly ok: boolean; } /** Report of `cleo doctor twin-collapse`. */ export interface TwinCollapseReport { /** The project store. */ readonly dbPath: string; /** Whether the store file exists. */ readonly storeExists: boolean; /** One entry per bare/twin pair. */ readonly pairs: readonly TwinCollapseStatus[]; /** Snapshot preflight, when a pending collapse needs a snapshot. */ readonly preflight: TwinCollapsePreflight | null; /** The command that re-runs the collapse. */ readonly retryCommand: 'cleo doctor twin-collapse --retry'; } /** * Report every twin collapse's state, read-only, without binding a domain. * * @param projectRoot - Project directory. * @returns The report. * @task T12535 */ export declare function inspectProjectTwinCollapse(projectRoot: string): TwinCollapseReport; /** * Run the twin collapses once on the chokepoint handle, without binding a * domain. * * @param projectRoot - Project directory. * @returns One receipt per pair. * @throws {CleoError} `E_TWIN_COLLAPSE_FAILED` when it fails again. * @task T12535 */ export declare function retryTwinCollapse(projectRoot: string, options: OwnerStoreRewriteOptions): Promise; /** Result of {@link recoverTwinCollapse}. */ export interface TwinCollapseRecoveryResult { /** The project store. */ readonly dbPath: string; /** `true`: only planned, nothing written. */ readonly dryRun: boolean; /** What the snapshot holds that the live store lacks (for an apply: what was applied). */ readonly plan: TwinCollapseRecoveryPlan; /** The receipt of this apply, or `null` (dry run, or nothing to recover). */ readonly receipt: TwinCollapseRecoveryReceipt | null; /** Markers re-pointed at a moved store's snapshot (T12788), or `null`/absent. */ readonly repointed?: TwinCollapseSnapshotRepoint | null; } /** Options of {@link recoverTwinCollapse} and {@link rollbackTwinCollapse}. */ export interface TwinCollapseRecoveryOptions extends OwnerStoreRewriteOptions { /** Plan only; the live store is opened read-only. */ readonly dryRun?: boolean; /** Pin an unpinned snapshot (its sidecar only) before applying; without it the apply refuses. */ readonly pinSnapshot?: boolean; } /** Audit log of markers re-pointed at a moved store's snapshot (T12788). */ export declare const TWIN_COLLAPSE_REPOINT_AUDIT_FILE = "twin-collapse-repoint.jsonl"; /** * Recover the twin values a 2026.9.21 collapse dropped or replaced (T12727): * `cleo doctor twin-collapse --recover [--dry-run]`. * * Reads the pre-collapse snapshot recorded in the `schema_meta` marker * READ-ONLY (it is never modified) and restores every dropped or replaced twin * value into `twin_collapse_archive:*`, merging the `focus_state` session * notes into the live value once (see `planTwinCollapseRecovery`). A dry run * opens the live store read-only and writes nothing. An apply re-plans under * the write lock, writes in one transaction and records a receipt that * `--rollback` undoes; a second apply finds nothing to do. A store never * collapsed has nothing to recover. An unpinned snapshot is reported by the * plan, and an apply refuses it unless `pinSnapshot` pins it first. A moved * store's snapshot is found by file name in its own backup directory; an * apply re-points the markers and appends a row to * `.cleo/audit/twin-collapse-repoint.jsonl` (T12788). No network. * * @param projectRoot - Project directory. * @param options - `cwd` the command runs from (a worktree needs * `confirmOwnerStore` to write the owner's store), `dryRun`. * @returns The plan and, for an apply, the receipt. * @throws {CleoError} `E_TWIN_COLLAPSE_RECOVER` when the recorded snapshot is * missing, and the owner-store guard's errors; nothing is written. * @task T12727 */ export declare function recoverTwinCollapse(projectRoot: string, options: TwinCollapseRecoveryOptions): Promise; /** * Undo one recovery apply: `cleo doctor twin-collapse --rollback ` * (see `rollbackTwinCollapseRecovery`). The snapshot is not needed. * * @param projectRoot - Project directory. * @param id - The receipt key (`twin_collapse_recovery:`). * @param options - `cwd` and `confirmOwnerStore`, as for {@link recoverTwinCollapse}. * @returns What was undone. * @task T12727 */ export declare function rollbackTwinCollapse(projectRoot: string, id: string, options: OwnerStoreRewriteOptions): Promise; /** Audit log of snapshot releases, under the project's `.cleo/audit/`. */ export declare const TWIN_COLLAPSE_RELEASE_AUDIT_FILE = "twin-collapse-release.jsonl"; /** Result of {@link releaseProjectTwinCollapseSnapshot}. */ export interface TwinCollapseSnapshotReleaseResult { /** The project store. */ readonly dbPath: string; /** `true`: only planned, nothing written. */ readonly dryRun: boolean; /** What a release would do, and why it may or may not. */ readonly plan: TwinCollapseSnapshotReleasePlan; /** The release, or `null` on a dry run. */ readonly release: TwinCollapseSnapshotRelease | null; /** The audit log the release was recorded in, or `null` on a dry run. */ readonly auditFile: string | null; } /** Options of {@link releaseProjectTwinCollapseSnapshot}. */ export interface TwinCollapseSnapshotReleaseOptions extends OwnerStoreRewriteOptions { /** Plan only; the live store is opened read-only. */ readonly dryRun?: boolean; /** * The owner's decision to release, which the calling agent obtained through * its ask tool. The CLI never prompts; without it nothing is written. */ readonly confirm?: boolean; } /** * Release a pre-collapse snapshot (T12767): * `cleo doctor twin-collapse --release-snapshot [--dry-run] --confirm`. * * Allowed only after a verified recovery or a no-recovery-needed check (see * `planSnapshotRelease`): the recovery plan against the snapshot must find * nothing left to recover. A release clears the markers' reference to the * snapshot and its sidecar pin, and appends a row to * `.cleo/audit/twin-collapse-release.jsonl`. The snapshot file is never * touched; it rotates normally afterwards. A dry run reports the bytes * reclaimed once it rotates and writes nothing. * * @param projectRoot - Project directory. * @param id - The snapshot: backup id (`migration-`), file name or path. * @param options - `cwd`, `confirmOwnerStore`, `dryRun`, `confirm`. * @returns The plan and, for a release, what was released. * @throws {CleoError} `E_TWIN_COLLAPSE_RELEASE` (not confirmed, or not * releasable) and the owner-store guard's errors; nothing is written. * @task T12767 */ export declare function releaseProjectTwinCollapseSnapshot(projectRoot: string, id: string, options: TwinCollapseSnapshotReleaseOptions): Promise; /** One row of the default `cleo doctor` report (the `DoctorCheck` shape). */ export interface TwinCollapseDoctorCheck { readonly check: 'twin_collapse'; readonly status: 'ok' | 'warning' | 'error'; readonly message: string; readonly details?: Record; readonly fix?: string; } /** * The `twin_collapse` check of the default `cleo doctor` report: `error` for a * failed collapse or one whose snapshot cannot be written, `warning` for a * pending one or bare rows an older build changed since the last merge. * * @param projectRoot - Project directory. * @returns The check row. * @task T12535 */ export declare function twinCollapseDoctorCheck(projectRoot: string): TwinCollapseDoctorCheck; //# sourceMappingURL=twin-collapse.d.ts.map