@cello-protocol/daemon 0.0.227 → 0.0.229

package/dist/away-inbox-oneshot.js

@@ -0,0 +1,311 @@
+/**
+ * `DOD-INBOX-ONESHOT-1` — an away agent's inbox accepts ONE message, then closes itself.
+ *
+ * ─── What this restores, and why it was missing ────────────────────────────────────────────────
+ *
+ * The away reply tells the caller, in its own words, that this inbox "accepts one message per
+ * visit — please close the session now". Nothing enforced that. A caller who kept talking was
+ * talking into an empty room, and the session stayed open indefinitely with no operator anywhere
+ * near it.
+ *
+ * It was enforced once. `DOD-M15-AWAYSCOPE-1` (2026-09-12) deleted the branch that answered
+ * mid-conversation messages with the away GREETING — correctly: that greeting took a hash-chain
+ * leaf in a live exchange and made the receipt unobtainable. But the one-shot rejection and the
+ * seal it initiated lived in the same branch and went with it, and that half was not the defect.
+ * Its own commit said so: "deleting the wrong one of the two mechanisms is the whole risk here".
+ *
+ * So the termination is back, on its own, in its own file, where it cannot be confused with the
+ * greeting. It NEVER sends the away text. It sends one closing line and seals.
+ *
+ * ─── Why the close is a real message and a real seal ───────────────────────────────────────────
+ *
+ * Because an inbound message is an attack surface, and an away agent's record of it must obey the
+ * same rules as everything else: the rejection is signed, ordered by the relay, and takes its leaf.
+ * A "quiet" close that left no record would be the one conversation in the system with no evidence.
+ *
+ * ⚠️ IT PLACES ITS OWN LEAVES, so this file belongs in the seal call-site enforcer's CALLERS list.
+ *
+ * ─── The rule that stops two machines sealing a conversation nobody had ────────────────────────
+ *
+ * When both agents are away, each side's auto-reply lands on the other as an inbound message. Left
+ * alone, the one-shot fires on BOTH sides, each posts a SEAL ctrl leaf, and two distinct-sender
+ * ctrl leaves is exactly what notarizes a session. Measured from the relay's own log 2026-08-09: a
+ * session sealed THREE SECONDS after opening, its entire content two machines telling each other
+ * nobody was home, while both operators went on believing it was live.
+ *
+ * So a message carrying the auto-reply marker is never answered and never counted. The narrow rule
+ * — suppress a machine answering a machine — is the correct one. The broad rule ("never notarize a
+ * session where we only sent away traffic") was tried and reverted: it also disabled closing the
+ * inbox on a real caller who ignores the instruction, which is the behaviour this file exists for.
+ *
+ * ⚠️ `isOwnAwayAutoReply`, NOT the marker alone. The marker only catches a marker-aware peer; the
+ * recogniser's LEGACY branch also catches this daemon's older default wording, which is what an
+ * un-upgraded CELLO agent still sends. Two away agents on mixed versions sealing a conversation
+ * nobody had is `DOD-AWAY-MUTUAL-SEAL-1`, and it became reachable again the moment this file could
+ * seal. Its documented limit stands: an old peer with a CONFIGURED away message is unmatched.
+ *
+ * ⚠️ THE MARKER IS TEXT, SO IT IS ADVISORY — say it rather than imply a rule. It is a token at the
+ * front of the message body, not a signed frame field, so any caller who types it is never counted
+ * and never closed on. What that buys them is the PRE-FIX behaviour: the session stays open until
+ * the operator returns. It buys them no leaf, no seal, no reply and nothing this side would not
+ * otherwise have given them. Closing that off means carrying the flag in the frame beside the text,
+ * which is a wire change on both sides and is not worth it for an opt-out into waiting longer.
+ */
+import { randomUUID } from "node:crypto";
+import { markAsAutoReply, isOwnAwayAutoReply } from "./away-detection.js";
+import { isLocalCredentialRefusal, LEAF_KIND_MSG } from "./session-relay-client.js";
+import { sentAuthorship } from "./session-content-handlers.js";
+import { escalateToUnilateralSeal as runUnilateralEscalation, UNILATERAL_SEAL_TIMEOUT_MS } from "./seal-escalation.js";
+/** The one line this file ever sends. Marked as machine-generated; [[WRAP]] stays at the END. */
+const ONESHOT_REJECT_TEXT = "This inbox only accepts one message per visit. Closing. [[WRAP]]";
+export function createAwayInboxOneshot(deps) {
+    const { logger, sessionNodeManager, sendClaims, awayAckSent, keyProviders, sealKey, sealInterruptedInProgress, pendingSealWaiters, pendingUnilateralWaiters, sendOver, handleActiveSealFlow, } = deps;
+    /**
+     * Their messages, counted from the DURABLE transcript rather than an arrival buffer.
+     *
+     * The in-memory buffer this used to peek at is deliberately gone (see the note in
+     * session-node-manager.ts): it held the plaintext of every live conversation in daemon memory for
+     * nobody. The transcript is what production serves and what the operator reads, so counting there
+     * also means a restart mid-visit does not reset the caller's allowance.
+     *
+     * Auto-replies are excluded from the count AND cannot be the trigger — see the header.
+     */
+    function readSession(agentName, sessionId) {
+        const { messages } = sessionNodeManager.readTranscript(agentName, sessionId);
+        let theirCount = 0;
+        let latest = null;
+        let weSpoke = false;
+        for (const m of messages) {
+            if (m.direction === "sent") {
+                // ANYTHING of ours that is not the greeting means a human spoke here. See `weSpoke` at the
+                // call site: it is the line between an answering machine and a conversation.
+                if (!isOwnAwayAutoReply(m.text))
+                    weSpoke = true;
+                continue;
+            }
+            if (m.direction !== "received")
+                continue;
+            // `latest` is the last thing they sent WHATEVER it was, because the auto-reply case is a
+            // decision this makes (never answer a machine), not one it can make by never seeing it.
+            latest = m.text;
+            if (isOwnAwayAutoReply(m.text))
+                continue;
+            theirCount += 1;
+        }
+        return { theirCount, latest, weSpoke };
+    }
+    async function closeInboxIfIgnored(agentName, sessionId) {
+        /**
+         * THIS IS THE AWAY CASE AND ONLY THE AWAY CASE — the session was answered by the machine at the
+         * door, because nobody was at the desk OR because this caller's tier says do not engage (a
+         * private agent, which IS attended and still away). The greeting having REACHED the caller is
+         * what says so, and it is why attendance is not consulted here: the tier case would fail an
+         * attendance test while being exactly the case this exists for.
+         *
+         * ⚠️ `:greeted`, NEVER `:request`. The latter is set before the send and stays set when the
+         * outbound screen blocks the greeting — so keying on it would close a visit on a caller who was
+         * never told the rule they are being held to.
+         *
+         * A conversation that was under way when someone dropped is a DIFFERENT case with its own
+         * machinery (recovery and the relay mailbox). Nothing here may reach it — see `weSpoke`.
+         */
+        if (!awayAckSent.has(`${agentName}:${sessionId}:greeted`))
+            return;
+        const rejectedKey = `${agentName}:${sessionId}:rejected`;
+        if (awayAckSent.has(rejectedKey))
+            return;
+        const { theirCount, latest, weSpoke } = readSession(agentName, sessionId);
+        if (latest === null)
+            return;
+        /**
+         * ⚠️ THE LINE PRINCIPLE 4 DRAWS, AND THE WHOLE REASON THIS IS SAFE TO SHIP.
+         *
+         * "A session with nobody live must not be terminal" was ruled on 2026-09-11 after a machine
+         * greeting took a leaf MID-CONVERSATION and cost a completed exchange its receipt. That ruling
+         * is about a conversation. If this side has said anything of its own, a human was here, and the
+         * machine does not get to end it — the party who comes back closes, per principle 8.
+         *
+         * A session whose only outbound line is the greeting is not a conversation. Nobody had it, and
+         * closing it destroys nothing.
+         */
+        if (weSpoke)
+            return;
+        // A send whose transcript row failed is a message this side made that the transcript cannot
+        // show. "Cannot tell" is not "nobody spoke", and only one of those may end a session.
+        if (sendClaims.rowMissing(agentName, sessionId)) {
+            logger.warn("session.away.inbox.oneshot.skipped_unreadable_record", {
+                agentName, sessionId,
+                impact: "this side sent something the transcript does not hold, so whether a human spoke here cannot be decided — the visit is left open",
+            });
+            return;
+        }
+        // AND the same question for a reply that is on the wire but not yet on disk. Without this, the
+        // window between `sendContent` resolving and its transcript row being written reads as silence.
+        if (sendClaims.held(agentName, sessionId)) {
+            logger.info("session.away.inbox.oneshot.skipped_send_in_flight", {
+                agentName, sessionId,
+                impact: "a reply from this side is on the wire, so this is a conversation — the visit is not closed",
+            });
+            return;
+        }
+        // THE ARRIVAL ITSELF IS A MACHINE'S: never answered, never counted, and checked before the
+        // count so two away agents cannot reach the seal below by trading greetings.
+        if (isOwnAwayAutoReply(latest)) {
+            logger.info("session.away.mutual.skipped", {
+                agentName, sessionId,
+                impact: "no one-shot close — two away agents must not notarize a conversation nobody had",
+            });
+            return;
+        }
+        // Their one message has arrived, so the visit is over. Waiting for a SECOND would be a shop that
+        // locks up only when someone tries the handle after closing time.
+        if (theirCount < 1)
+            return;
+        // They are closing of their own accord — let the ordinary seal proceed, and do not spend the
+        // one-shot on it. Matched at the END, because DOD-SIGNAL-TOKEN-1 appends the real token there
+        // and a substring match would read a mere mention of the token as a close.
+        if (latest.trimEnd().endsWith("[[WRAP]]")) {
+            logger.info("session.away.inbox.oneshot.skipped_wrap", { agentName, sessionId });
+            return;
+        }
+        awayAckSent.add(rejectedKey); // guard BEFORE async work — concurrent arrivals must not re-enter
+        const record = sessionNodeManager.getSessionRecord(agentName, sessionId);
+        if (!record || record.status !== "active")
+            return;
+        const rejectText = markAsAutoReply(ONESHOT_REJECT_TEXT);
+        const rejectBytes = new TextEncoder().encode(rejectText);
+        // One decision point for the hash AND its algorithm — see `contentHashForSession`.
+        const reject = await sessionNodeManager.contentHashForSession(agentName, sessionId, rejectBytes);
+        // Best-effort: a send failure still triggers the seal — we are closing regardless.
+        const sendResult = await sessionNodeManager.sendContent(agentName, sessionId, rejectBytes, new Uint8Array(reject.hash), randomUUID(), LEAF_KIND_MSG, reject.alg);
+        if (sendResult.ok || sendResult.durable) {
+            // At the RELAY's position, not the tail, and committed when the send went out OR was durably
+            // queued — either way the relay already witnessed its sequence. This is the sharpest case of
+            // that rule in the codebase: the seal is initiated a few lines below, so a leaf at the wrong
+            // index seals a tree the counterparty can never agree with.
+            const placed = sessionNodeManager.placeOwnLeaf(agentName, sessionId, Buffer.from(reject.hash).toString("hex"), rejectBytes, sendResult.sequenceNumber, randomUUID(), "msg", sentAuthorship(sendResult));
+            if (placed.placed) {
+                sessionNodeManager.recordTranscriptMessage(agentName, sessionId, placed.leafIndex, "sent", rejectBytes, randomUUID(), sentAuthorship(sendResult));
+            }
+            logger.info("session.away.inbox.oneshot.rejected", {
+                agentName, sessionId, sequenceNumber: placed.placed ? placed.leafIndex : placed.heldAt,
+                committed: placed.placed, queued: !sendResult.ok,
+            });
+        }
+        else {
+            // Not queued anywhere — the rejection is gone. We still seal (we are closing regardless), and
+            // the counterparty simply never learns why, so say that plainly.
+            logger.error("session.away.inbox.oneshot.reject_send_failed", {
+                agentName, sessionId, reason: sendResult.reason, cause: sendResult.cause,
+                impact: "the rejection is lost and was NOT queued — the session seals with no explanation to the counterparty",
+            });
+        }
+        /**
+         * The divergence gate has to hold on the path with no operator. `cello_close_session` refuses a
+         * diverged record; this autonomous path must too, and the LOG is its whole surface because
+         * there is no caller awaiting an answer.
+         */
+        /**
+         * ASKED AGAIN, BECAUSE THE SEND ABOVE TOOK A ROUND TRIP. The checks at entry were true when the
+         * caller's message arrived; an operator who started replying during our own send would not have
+         * been visible then. Sealing is the irreversible half, so the last thing before it is the same
+         * question, freshly asked.
+         */
+        if (sendClaims.held(agentName, sessionId) || readSession(agentName, sessionId).weSpoke) {
+            logger.info("session.away.inbox.oneshot.seal_skipped_operator_returned", {
+                agentName, sessionId,
+                impact: "the operator spoke while this was closing, so the session is NOT sealed — it is theirs to close",
+            });
+            return;
+        }
+        const readiness = sessionNodeManager.sealReadiness(agentName, sessionId);
+        if (readiness.diverged) {
+            logger.warn("session.away.inbox.oneshot.seal_skipped_diverged", {
+                agentName, sessionId, treeSize: readiness.treeSize, highWaterSeq: readiness.highWaterSeq,
+                impact: "this side's tree parted from the relay's ordering, so the seal was NOT initiated — the session stays closeable by hand, where the operator can compare counts with the counterparty first",
+            });
+            return;
+        }
+        await initiateSeal(agentName, sessionId, record);
+    }
+    /**
+     * Seal via the RELAY-mediated path, not the signaling one.
+     *
+     * The signaling path compares leaf counts, and this party's tree includes the rejection sent
+     * milliseconds ago while the counterparty's may not have ingested it yet — a race that fails the
+     * seal for a reason that is not real. The relay path posts a SEAL ctrl leaf and waits for the
+     * counterparty to co-seal independently, so no count comparison happens at all.
+     */
+    async function initiateSeal(agentName, sessionId, record) {
+        const correlationId = randomUUID();
+        const sk = sealKey(agentName, sessionId);
+        if (sealInterruptedInProgress.has(sk))
+            return;
+        sealInterruptedInProgress.add(sk);
+        try {
+            let resolveSeal;
+            const sealedP = new Promise((r) => { resolveSeal = r; });
+            pendingSealWaiters.set(sk, resolveSeal);
+            const submit = await sessionNodeManager.submitSealLeaf(agentName, sessionId, correlationId);
+            if (!submit.ok && submit.reason !== "responder_seal_already_submitted") {
+                pendingSealWaiters.delete(sk);
+                if (submit.reason === "relay_unavailable" || isLocalCredentialRefusal(submit.reason)) {
+                    const fallback = await handleActiveSealFlow(sessionId, record, correlationId);
+                    if (fallback.ok)
+                        logger.info("session.away.inbox.oneshot.seal_initiated", { agentName, sessionId, path: "signaling_fallback" });
+                    else
+                        logger.warn("session.away.inbox.oneshot.seal_initiate_failed", { agentName, sessionId, reason: fallback.reason, path: "signaling_fallback" });
+                }
+                else {
+                    logger.warn("session.away.inbox.oneshot.seal_initiate_failed", { agentName, sessionId, reason: submit.reason });
+                }
+                return;
+            }
+            logger.info("session.away.inbox.oneshot.seal_initiated", { agentName, sessionId, path: "relay" });
+            const bilateralTimeoutMs = Number(process.env["CELLO_SEAL_BILATERAL_TIMEOUT_MS"]) || 660_000;
+            let timer;
+            const timeoutP = new Promise((r) => { timer = setTimeout(() => r(null), bilateralTimeoutMs); });
+            const completion = await Promise.race([sealedP, timeoutP]);
+            clearTimeout(timer);
+            pendingSealWaiters.delete(sk);
+            if (completion !== null) {
+                // A REFUSED certificate resolves the waiter rather than being dropped, so the two must be
+                // told apart — logging a refusal as "sealed" is the silent acceptance to avoid.
+                if ("refused" in completion) {
+                    logger.error("session.away.inbox.oneshot.seal_refused", {
+                        agentName, sessionId, reason: completion.reason, detail: completion.detail,
+                        impact: "the away auto-seal was REFUSED: the directory returned a validly signed root that does not describe this conversation. The session is NOT sealed and nothing was signed with this agent's key.",
+                    });
+                    return;
+                }
+                logger.info("session.away.inbox.oneshot.sealed", { agentName, sessionId, sealedRoot: completion.rootHex });
+                return;
+            }
+            const escalation = submit.ok
+                ? { reportedRootHex: submit.reportedRootHex, sequenceNumber: submit.sequenceNumber }
+                : submit.reason === "responder_seal_already_submitted" && typeof submit.reportedRootHex === "string" && typeof submit.sequenceNumber === "number"
+                    ? { reportedRootHex: submit.reportedRootHex, sequenceNumber: submit.sequenceNumber }
+                    : null;
+            if (!escalation) {
+                logger.warn("session.away.inbox.oneshot.seal_pending", { agentName, sessionId });
+                return;
+            }
+            // THE SHARED ESCALATION, not a second copy — a duplicate drifted once and missed every
+            // refusal the shared one gained (empty carry, gappy chain, two of our own ctrl leaves).
+            const uni = await runUnilateralEscalation({ logger, sessionNodeManager, sendOver, pendingUnilateralWaiters, sealKey, getKeyProvider: (a) => keyProviders.get(a), timeoutMs: UNILATERAL_SEAL_TIMEOUT_MS }, agentName, sessionId, escalation, correlationId, { refuseOnUnusableCarry: true });
+            if (uni.ok) {
+                logger.info("session.away.inbox.oneshot.sealed", { agentName, sessionId, sealedRoot: uni.sealed_root, sealType: "unilateral" });
+            }
+            else {
+                // CARRY THE GUIDANCE: it is the sentence telling an operator whether to retry or
+                // force-abandon, and this log is the path's only surface.
+                logger.warn("session.away.inbox.oneshot.seal_unilateral_failed", { agentName, sessionId, reason: uni.reason, guidance: uni.guidance });
+            }
+        }
+        finally {
+            sealInterruptedInProgress.delete(sealKey(agentName, sessionId));
+        }
+    }
+    return { closeInboxIfIgnored };
+}
+//# sourceMappingURL=away-inbox-oneshot.js.map

package/dist/away-inbox-oneshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"away-inbox-oneshot.js","sourceRoot":"","sources":["../src/away-inbox-oneshot.ts"],"names":[],"mappings":"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"}

package/dist/backup-restore-handlers.d.ts

@@ -0,0 +1,10 @@
+import type { IpcHandler } from "./ipc-server.js";
+import type { Logger } from "./types.js";
+export interface BackupRestoreDeps {
+    handlers: Map<string, IpcHandler>;
+    logger: Logger;
+    /** Where the daemon keeps its data — the database this writes out and reads back sits under it. */
+    celloDir: string;
+}
+export declare function registerBackupRestoreHandlers(deps: BackupRestoreDeps): void;
+//# sourceMappingURL=backup-restore-handlers.d.ts.map

package/dist/backup-restore-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-restore-handlers.d.ts","sourceRoot":"","sources":["../src/backup-restore-handlers.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,mGAAmG;IACnG,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAuE3E"}

package/dist/backup-restore-handlers.js

@@ -0,0 +1,82 @@
+/**
+ * Backup and restore: write this machine's agent to a file, and put one back.
+ *
+ * Three dependencies — the handler map, a logger, and where the daemon keeps its data. That is the
+ * whole reason this is its own module rather than sitting with the other admin verbs: it touches
+ * files and nothing else, so it needs none of the signaling, consortium or ceremony machinery they
+ * do, and merging them would push one context over the bound to save one call site.
+ *
+ * The backup file is as sensitive as a private key. `VACUUM INTO` takes a consistent snapshot with
+ * the database still open, which is what makes this safe to run against the daemon serving the call.
+ */
+import { join } from "node:path";
+import { createBackup, inspectBackup } from "./backup-restore.js";
+export function registerBackupRestoreHandlers(deps) {
+    const { handlers, logger, celloDir } = deps;
+    /**
+     * DOD-M15-BACKUP-1 — export the agent, so losing the machine does not lose the identity.
+     *
+     * `VACUUM INTO` takes a consistent snapshot with the database still open, so this is safe to call
+     * on a running daemon — which matters, because the daemon is what serves the tool.
+     */
+    handlers.set("cello_backup", async (params, _connectionId) => {
+        const outPath = typeof params?.["path"] === "string" ? params["path"] : "";
+        if (!outPath) {
+            return {
+                ok: false,
+                reason: "missing_path",
+                guidance: "Give an absolute path to write the backup to, e.g. { path: \"/Users/you/cello-agent.cello-backup\" }. " +
+                    "It is not written to a default location on purpose: the file contains the key to your agent, " +
+                    "so where it lands is a decision you should make deliberately.",
+            };
+        }
+        const res = await createBackup({
+            dbPath: join(celloDir, "sessions.db"),
+            outPath,
+            logger,
+            ...(params?.["overwrite"] === true ? { overwrite: true } : {}),
+        });
+        return res.ok
+            ? { ok: true, path: res.path, bytes: res.bytes, guidance: res.guidance }
+            : { ok: false, reason: res.reason, guidance: res.guidance };
+    });
+    /**
+     * RESTORE IS REFUSED WHILE THIS DAEMON IS RUNNING, and that is not a limitation to apologise for.
+     *
+     * The daemon holds the database open with a write lock. Overwriting the file underneath an open
+     * SQLite handle risks the handle flushing its own pages back over the restored ones — the restore
+     * appears to succeed and the database is a hybrid of two identities, which is worse than either
+     * failing cleanly.
+     *
+     * The capability itself lives in `backup-restore.ts` (a daemon module, per the DoD), and the CLI
+     * calls it with the daemon stopped. So the honest answer here is the exact sequence, not an
+     * attempt.
+     */
+    handlers.set("cello_restore", async (params, _connectionId) => {
+        const archivePath = typeof params?.["path"] === "string" ? params["path"] : "";
+        const inspected = archivePath ? await inspectBackup(archivePath) : null;
+        return {
+            ok: false,
+            reason: "daemon_running",
+            ...(inspected?.ok
+                ? { archive_verified: true, backup_created_at: new Date(inspected.createdAt).toISOString() }
+                : inspected
+                    ? { archive_verified: false, archive_problem: inspected.reason }
+                    : {}),
+            guidance: (inspected?.ok
+                ? `That archive is valid (taken ${new Date(inspected.createdAt).toISOString()}). `
+                : inspected
+                    ? `WARNING: that archive did not validate (${inspected.reason}) — fix that before going further. `
+                    : "") +
+                "Restoring REPLACES this machine's agent database, and it cannot be done while the daemon " +
+                "is holding it open — the running daemon could flush its own pages back over the restored " +
+                "ones and leave a database that is half one identity and half another. Stop the daemon " +
+                "first:\n\n  cello logout\n  cello restore " +
+                (archivePath || "<archive>") +
+                "\n  cello login\n\n" +
+                "Anything that happened on this machine since the backup was taken will be gone — restore " +
+                "replaces, it does not merge.",
+        };
+    });
+}
+//# sourceMappingURL=backup-restore-handlers.js.map

package/dist/backup-restore-handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-restore-handlers.js","sourceRoot":"","sources":["../src/backup-restore-handlers.ts"],"names":[],"mappings":"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"}

package/dist/backup-restore.d.ts

@@ -0,0 +1,102 @@
+/**
+ * DOD-M15-BACKUP-1 — export an agent's identity, and put it back on another machine.
+ *
+ * ─── What a backup has to contain, and why the obvious answer is wrong ─────────────────────────
+ *
+ * The DoD line says *"Backup = exporting the SQLCipher database for transport."* Exporting the
+ * database alone produces a file nobody can ever open.
+ *
+ * The database is encrypted and its key is a separate 32-byte file at `<db>.key` — `sqlcipher-db.ts`
+ * calls it "the ONE plaintext key file on disk". A fresh daemon on a new machine mints its own key,
+ * which cannot open a database encrypted under a different one. An operator restoring a
+ * database-only archive would be told it worked, and find out on the day they needed it that the
+ * contents are unreadable forever.
+ *
+ * So the archive carries BOTH, and the round-trip test restores into a directory holding a
+ * different key precisely to prove it.
+ *
+ * ─── The consequence of that, which the tool must say out loud ─────────────────────────────────
+ *
+ * A file containing that key IS the agent. Whoever holds it can sign as them, read every
+ * transcript, and use their identity. Nothing about the word "backup" suggests a file this
+ * dangerous, so the response says it at the moment one is written. `DOD-M15-CLAIM-SCREEN-1`'s rule
+ * applies to affordances as much as claims: silence is not an option.
+ *
+ * ─── Why `VACUUM INTO` rather than copying the file ────────────────────────────────────────────
+ *
+ * The daemon holds the database open with a write lock. Copying the file byte-for-byte while it is
+ * open can capture a torn page or miss a WAL frame, producing an archive that restores into a
+ * corrupt database — the worst outcome available here, because it looks like a successful backup.
+ * `VACUUM INTO` asks SQLite for a consistent snapshot, and on SQLCipher the target inherits the
+ * source's cipher settings, so the snapshot is encrypted under the same key.
+ *
+ * ─── Restore is validated in full BEFORE anything is touched ───────────────────────────────────
+ *
+ * Restore OVERWRITES. A truncated or wrong file that is accepted destroys the working agent the
+ * operator still had — the backup tool becomes the thing that loses the identity. So the container
+ * is parsed, its checksum verified and its payloads decompressed entirely in memory first; only
+ * then does anything reach the disk.
+ *
+ * ─── V1 scope, per the DoD ─────────────────────────────────────────────────────────────────────
+ *
+ * Export plus overwrite-restore. MERGE — restoring onto a device that has its own live state — is
+ * explicitly deferred, and this module does not pretend otherwise: restore replaces, and says so.
+ */
+import type { Logger } from "./types.js";
+export type BackupResult = {
+    ok: true;
+    path: string;
+    bytes: number;
+    guidance: string;
+} | {
+    ok: false;
+    reason: string;
+    guidance: string;
+};
+export type RestoreResult = {
+    ok: true;
+    dbPath: string;
+    guidance: string;
+} | {
+    ok: false;
+    reason: string;
+    guidance: string;
+};
+/**
+ * Take a consistent snapshot of the live database and write a portable archive.
+ *
+ * `dbPath` is the live database. It may be open in this process; `VACUUM INTO` is safe against that
+ * and is why the snapshot goes through SQLite rather than a file copy.
+ */
+export declare function createBackup(opts: {
+    dbPath: string;
+    outPath: string;
+    logger: Logger;
+    keyPath?: string;
+    /** A backup is not a scratch file: replacing one is deliberate, never incidental. */
+    overwrite?: boolean;
+}): Promise<BackupResult>;
+/** Read an archive's metadata without restoring it. */
+export declare function inspectBackup(archivePath: string): Promise<{
+    ok: true;
+    createdAt: number;
+    hasKey: boolean;
+    dbBytes: number;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/**
+ * Replace this machine's database and key with the archive's.
+ *
+ * OVERWRITE, not merge — merge is explicitly deferred, and pretending otherwise would silently pick
+ * a winner between two divergent histories. The caller is responsible for the daemon not holding
+ * the database open; the handler enforces that.
+ */
+export declare function restoreBackup(opts: {
+    archivePath: string;
+    dbPath: string;
+    logger: Logger;
+    keyPath?: string;
+}): Promise<RestoreResult>;
+//# sourceMappingURL=backup-restore.d.ts.map

package/dist/backup-restore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-restore.d.ts","sourceRoot":"","sources":["../src/backup-restore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAQH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAqCzC,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAYpD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,GAAG,OAAO,CAAC,YAAY,CAAC,CA0FxB;AAED,uDAAuD;AACvD,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAS5G;AA0DD;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,aAAa,CAAC,CA6FzB"}