@scotthuang/agent-knock-knock 0.12.11 → 0.12.13

package/dist/src/terminal-watch-store.js

@@ -0,0 +1,861 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { assertRealDirectory, atomicSaveJsonFile, isNodeError, readJsonFileNoFollow } from "./durable-json-file.js";
+import { initialClaudeHumanStartedActiveTaskCheckpoint, validateClaudeHumanStartedActiveTaskCheckpoint, validateClaudeHumanStartedActiveTaskAnchor } from "./claude-local-transcript-provider.js";
+import { validateCodexHumanStartedActiveTaskAnchor } from "./terminal-submission-acceptance.js";
+import { assertStoreReadable, ensureDir, STORE_TERMINAL_WATCHES_DIRECTORY, withStoreWriterLease } from "./store.js";
+import { terminalEndpointIdentityFromEvidence, terminalRouteKeyFromEvidence } from "./terminal-control-ref.js";
+import { isRecord } from "./value-guards.js";
+export const TERMINAL_WATCH_SCHEMA = "agent-knock-knock/terminal-watch";
+export const TERMINAL_WATCH_VERSION = 1;
+export const TERMINAL_WATCHES_DIRECTORY = STORE_TERMINAL_WATCHES_DIRECTORY;
+const PRIVATE_DIRECTORY_MODE = 0o700;
+const PRIVATE_FILE_MODE = 0o600;
+const TERMINAL_WATCH_TERMINAL_STATUSES = [
+    "completed",
+    "failed",
+    "timed_out",
+    "invalidated",
+    "cancelled"
+];
+const TERMINAL_WATCH_STATUSES = [
+    "active",
+    ...TERMINAL_WATCH_TERMINAL_STATUSES
+];
+const TERMINAL_WATCH_NOTIFICATION_KINDS = [
+    "approval",
+    ...TERMINAL_WATCH_TERMINAL_STATUSES
+];
+const TERMINAL_WATCH_NOTIFICATION_STATUSES = [
+    "pending",
+    "delivering",
+    "failed",
+    "delivered",
+    "superseded"
+];
+export function initialTerminalWatchObservationCheckpoint(anchor) {
+    if (anchor.schema ===
+        "agent-knock-knock/claude-human-started-active-task-anchor") {
+        return initialClaudeHumanStartedActiveTaskCheckpoint(anchor);
+    }
+    return {
+        safe_resume_offset_bytes: validateCodexHumanStartedActiveTaskAnchor(anchor)
+            .observed_end_offset_bytes
+    };
+}
+export class TerminalWatchConflictError extends Error {
+    code = "AKK_TERMINAL_WATCH_CONFLICT";
+    watchId;
+    expectedRevision;
+    actualRevision;
+    constructor(watchId, expectedRevision, actualRevision, detail) {
+        super(`terminal Watch ${watchId} changed concurrently` +
+            ` (expected revision ${String(expectedRevision)}, actual ` +
+            `${String(actualRevision)})` +
+            (detail ? `: ${detail}` : ""));
+        this.name = "TerminalWatchConflictError";
+        this.watchId = watchId;
+        this.expectedRevision = expectedRevision;
+        this.actualRevision = actualRevision;
+    }
+}
+export function terminalWatchesDir(storeDir) {
+    return path.join(storeDir, TERMINAL_WATCHES_DIRECTORY);
+}
+export function pathsForTerminalWatch(watchId, storeDir) {
+    assertRecordId(watchId, "terminal Watch id");
+    const root = terminalWatchesDir(storeDir);
+    const statePath = path.join(root, `${watchId}.json`);
+    assertContained(statePath, root, "terminal Watch state");
+    return { root, statePath, lockPath: `${statePath}.lock` };
+}
+/**
+ * Acquire the Store writer lease before the per-Watch state lock. This keeps
+ * the repository compatible with the canonical `writer -> state` lock order.
+ */
+export function withTerminalWatchLock(storeDir, watchId, locks, operation) {
+    const paths = pathsForTerminalWatch(watchId, storeDir);
+    return withStoreWriterLease(storeDir, () => {
+        ensureDir(paths.root);
+        assertOwnerPrivateDirectory(paths.root, "terminal Watch root");
+        const release = locks.acquire(paths.lockPath);
+        try {
+            return operation();
+        }
+        finally {
+            release();
+        }
+    });
+}
+export function createTerminalWatchStore(storeDir, locks) {
+    return Object.freeze({
+        list: () => listTerminalWatches(storeDir),
+        scanForReconciliation: () => scanTerminalWatchesForReconciliation(storeDir),
+        load: (watchId) => loadTerminalWatch(storeDir, watchId),
+        save: (watch, options) => saveTerminalWatch(storeDir, watch, options),
+        withWatchLock: (watchId, operation) => withTerminalWatchLock(storeDir, watchId, locks, operation)
+    });
+}
+export function terminalWatchNotificationId(watchId, kind, evidenceFingerprint) {
+    assertRecordId(watchId, "terminal Watch id");
+    assertNotificationKind(kind);
+    assertSha256(evidenceFingerprint, "notification evidence fingerprint");
+    const digest = createHash("sha256")
+        .update(JSON.stringify({
+        schema: "agent-knock-knock/terminal-watch-notification",
+        version: 1,
+        watch_id: watchId,
+        kind,
+        evidence_fingerprint: evidenceFingerprint
+    }))
+        .digest("hex");
+    return `terminal-watch-notification-${digest}`;
+}
+export function terminalWatchNotificationIdempotencyKey(watchId, notificationId) {
+    assertRecordId(watchId, "terminal Watch id");
+    assertRecordId(notificationId, "terminal Watch notification id");
+    return `agent-knock-knock:terminal-watch:${watchId}:${notificationId}`;
+}
+export function terminalWatchIdentityFingerprint(watch) {
+    const endpoint = terminalEndpointIdentityFromEvidence(watch.terminal.terminal_endpoint);
+    if (!endpoint) {
+        throw new Error("terminal Watch endpoint identity is invalid");
+    }
+    return createHash("sha256")
+        .update(JSON.stringify({
+        version: 1,
+        agent: watch.agent,
+        terminal_id: watch.terminal.terminal_id,
+        endpoint,
+        process_anchor_pid: watch.terminal.terminal_endpoint.process_anchor_pid,
+        workspace: watch.terminal.workspace,
+        binding_token: watch.terminal.binding_token,
+        anchor_fingerprint: watch.anchor.anchor_fingerprint
+    }))
+        .digest("hex");
+}
+export function terminalWatchRevision(watch) {
+    if (!isPositiveSafeInteger(watch.revision)) {
+        throw new Error(`terminal Watch ${watch.watch_id} has no valid revision`);
+    }
+    return watch.revision;
+}
+const IGNORE_VALUE = () => { };
+const POSITIVE_INTEGER = (value, label) => {
+    if (!isPositiveSafeInteger(value)) {
+        throw new Error(`${label} must be a positive safe integer`);
+    }
+};
+const NON_NEGATIVE_INTEGER = (value, label) => {
+    if (!isNonNegativeSafeInteger(value)) {
+        throw new Error(`${label} must be a non-negative safe integer`);
+    }
+};
+const ARRAY_VALUE = (value, label) => {
+    if (!Array.isArray(value))
+        throw new Error(`${label} must be an array`);
+};
+const ABSOLUTE_PATH = (value, label) => {
+    if (typeof value !== "string" || !path.isAbsolute(value)) {
+        throw new Error(`${label} must be absolute`);
+    }
+};
+const NULLABLE_ENDPOINT_STRING = optionalGuard((value, label) => {
+    if (value !== null &&
+        (typeof value !== "string" || value.includes("\0"))) {
+        throw new Error(`${label} is invalid`);
+    }
+});
+const WATCH_FIELDS = {
+    schema: literalGuard(TERMINAL_WATCH_SCHEMA),
+    version: literalGuard(TERMINAL_WATCH_VERSION),
+    watch_id: assertRecordId,
+    revision: optionalGuard(POSITIVE_INTEGER),
+    agent: oneOfGuard(["codex", "claude"]),
+    terminal: assertTerminalIdentity,
+    anchor: IGNORE_VALUE,
+    observation_checkpoint: IGNORE_VALUE,
+    openclaw_session: assertNonEmptyString,
+    openclaw_bin: assertNonEmptyString,
+    created_at: assertTimestamp,
+    deadline_at: assertTimestamp,
+    updated_at: assertTimestamp,
+    status: oneOfGuard(TERMINAL_WATCH_STATUSES),
+    last_activity_at: assertTimestamp,
+    settlement: IGNORE_VALUE,
+    notification_outbox: ARRAY_VALUE
+};
+const TERMINAL_IDENTITY_FIELDS = {
+    terminal_id: assertNonEmptyString,
+    terminal_endpoint: assertTerminalEndpoint,
+    workspace: ABSOLUTE_PATH,
+    binding_token: assertSha256
+};
+const TERMINAL_ENDPOINT_FIELDS = {
+    schema: literalGuard("agent-knock-knock/terminal-endpoint"),
+    version: literalGuard(1),
+    kind: IGNORE_VALUE,
+    endpoint_key: IGNORE_VALUE,
+    resource_key: IGNORE_VALUE,
+    route_key: IGNORE_VALUE,
+    process_anchor_pid: POSITIVE_INTEGER,
+    target: NULLABLE_ENDPOINT_STRING,
+    socket_path: NULLABLE_ENDPOINT_STRING,
+    pane_pid: optionalGuard(nullableGuard(POSITIVE_INTEGER)),
+    server_socket_path: NULLABLE_ENDPOINT_STRING,
+    pane_id: NULLABLE_ENDPOINT_STRING,
+    session_name: NULLABLE_ENDPOINT_STRING,
+    session_dir: NULLABLE_ENDPOINT_STRING,
+    workspace_id: NULLABLE_ENDPOINT_STRING,
+    tab_id: NULLABLE_ENDPOINT_STRING,
+    terminal_id: NULLABLE_ENDPOINT_STRING,
+    current_path: NULLABLE_ENDPOINT_STRING
+};
+const SETTLEMENT_FIELDS = {
+    kind: oneOfGuard(TERMINAL_WATCH_TERMINAL_STATUSES),
+    evidence_fingerprint: assertSha256,
+    observed_at: assertTimestamp,
+    reason_code: optionalGuard(assertReasonCode),
+    completion_text: optionalGuard(assertCompletionText),
+    completion_id: optionalGuard(assertNonEmptyString),
+    completion_timestamp: optionalGuard(assertTimestamp)
+};
+const NOTIFICATION_RECEIPT_FIELDS = {
+    last_attempt_at: optionalGuard(assertTimestamp),
+    attempt_id: optionalGuard(assertNonEmptyString),
+    attempt_lease_expires_at: optionalGuard(assertTimestamp),
+    failed_at: optionalGuard(assertTimestamp),
+    next_attempt_at: optionalGuard(assertTimestamp),
+    last_error_code: optionalGuard(assertReasonCode),
+    delivered_at: optionalGuard(assertTimestamp),
+    superseded_at: optionalGuard(assertTimestamp)
+};
+const NOTIFICATION_FIELDS = {
+    notification_id: assertNonEmptyString,
+    idempotency_key: assertNonEmptyString,
+    kind: oneOfGuard(TERMINAL_WATCH_NOTIFICATION_KINDS),
+    evidence_fingerprint: assertSha256,
+    reason_code: optionalGuard(assertReasonCode),
+    status: oneOfGuard(TERMINAL_WATCH_NOTIFICATION_STATUSES),
+    attempts: NON_NEGATIVE_INTEGER,
+    created_at: assertTimestamp,
+    ...NOTIFICATION_RECEIPT_FIELDS
+};
+const NOTIFICATION_SHAPES = {
+    pending: [0, []],
+    delivering: [1, [
+            "last_attempt_at",
+            "attempt_id",
+            "attempt_lease_expires_at"
+        ]],
+    failed: [1, [
+            "last_attempt_at",
+            "failed_at",
+            "next_attempt_at",
+            "last_error_code"
+        ]],
+    delivered: [1, ["last_attempt_at", "delivered_at"]],
+    superseded: [0, ["superseded_at"]]
+};
+export function assertTerminalWatch(value, expectedWatchId, options = {}) {
+    assertStrictRecord(value, "terminal Watch", WATCH_FIELDS);
+    if (expectedWatchId !== undefined && value.watch_id !== expectedWatchId) {
+        throw new Error(`terminal Watch id ${String(value.watch_id)} does not match ${expectedWatchId}`);
+    }
+    if (value.revision === undefined && !options.allowMissingRevision) {
+        throw new Error("terminal Watch revision must be a positive safe integer");
+    }
+    const watch = value;
+    assertTerminalWatchAnchor(watch.anchor, watch.agent, watch.terminal);
+    assertObservationCheckpoint(watch.observation_checkpoint, watch.anchor);
+    const minimumCheckpointOffset = watch.anchor.schema ===
+        "agent-knock-knock/claude-human-started-active-task-anchor"
+        ? watch.anchor.turn_start_offset_bytes
+        : watch.anchor.observed_end_offset_bytes;
+    if (watch.observation_checkpoint.safe_resume_offset_bytes <
+        minimumCheckpointOffset) {
+        throw new Error("terminal Watch observation checkpoint cannot predate its task anchor");
+    }
+    if (Date.parse(watch.deadline_at) <= Date.parse(watch.created_at) ||
+        Date.parse(watch.updated_at) < Date.parse(watch.created_at) ||
+        Date.parse(watch.last_activity_at) > Date.parse(watch.updated_at)) {
+        throw new Error("terminal Watch timestamps are not monotonic");
+    }
+    const processStartedAt = watch.anchor.schema ===
+        "agent-knock-knock/claude-human-started-active-task-anchor"
+        ? watch.anchor.agent_started_at_ms
+        : undefined;
+    if (Date.parse(watch.anchor.captured_at) > Date.parse(watch.created_at) ||
+        (processStartedAt !== undefined &&
+            processStartedAt > Date.parse(watch.created_at))) {
+        throw new Error("terminal Watch cannot predate its exact observation anchor");
+    }
+    assertSettlement(watch.settlement, watch.status);
+    if (watch.settlement &&
+        (Date.parse(watch.settlement.observed_at) > Date.parse(watch.updated_at) ||
+            (watch.settlement.completion_timestamp !== undefined &&
+                Date.parse(watch.settlement.completion_timestamp) >
+                    Date.parse(watch.updated_at)))) {
+        throw new Error("terminal Watch settlement cannot be newer than its state");
+    }
+    assertNotificationOutbox(watch);
+}
+export function saveTerminalWatch(storeDir, watch, options) {
+    assertTerminalWatch(watch, undefined, { allowMissingRevision: true });
+    assertExpectedRevision(options?.expectedRevision);
+    const paths = pathsForTerminalWatch(watch.watch_id, storeDir);
+    return withStoreWriterLease(storeDir, () => {
+        const current = tryLoadTerminalWatch(storeDir, watch.watch_id);
+        const actualRevision = current?.revision ?? null;
+        if (actualRevision !== options.expectedRevision) {
+            throw new TerminalWatchConflictError(watch.watch_id, options.expectedRevision, actualRevision);
+        }
+        if (watch.revision !== undefined &&
+            watch.revision !== (options.expectedRevision ?? 1)) {
+            throw new TerminalWatchConflictError(watch.watch_id, options.expectedRevision, actualRevision, `candidate carries revision ${watch.revision}`);
+        }
+        if (current) {
+            assertTerminalWatchAdvance(current, watch);
+        }
+        else if (watch.status !== "active" || watch.settlement !== undefined) {
+            throw new Error("a terminal Watch must be created active and unsettled");
+        }
+        const next = {
+            ...watch,
+            revision: (actualRevision ?? 0) + 1
+        };
+        assertTerminalWatch(next, watch.watch_id);
+        atomicSaveTerminalWatch(paths.statePath, next);
+        return next;
+    });
+}
+export function loadTerminalWatch(storeDir, watchId) {
+    assertStoreReadable(storeDir);
+    const paths = pathsForTerminalWatch(watchId, storeDir);
+    assertOwnerPrivateDirectory(paths.root, "terminal Watch root");
+    assertOwnerPrivateFile(paths.statePath, "terminal Watch state");
+    const value = readJsonFileNoFollow(paths.statePath, "terminal Watch state");
+    return decodeTerminalWatch(value, watchId);
+}
+export function tryLoadTerminalWatch(storeDir, watchId) {
+    try {
+        return loadTerminalWatch(storeDir, watchId);
+    }
+    catch (error) {
+        if (isNodeError(error, "ENOENT")) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+export function listTerminalWatches(storeDir) {
+    const scan = scanTerminalWatchDirectory(storeDir, false);
+    return scan.watches;
+}
+/**
+ * Reconciliation isolates only malformed contents of an already-named JSON
+ * record. Directory shape, symlinks, unknown entries, permissions, and I/O
+ * failures remain global fail-closed boundaries.
+ */
+export function scanTerminalWatchesForReconciliation(storeDir) {
+    return scanTerminalWatchDirectory(storeDir, true);
+}
+function scanTerminalWatchDirectory(storeDir, isolateInvalidRecord) {
+    if (!fs.existsSync(storeDir)) {
+        return { watches: [], errors: [] };
+    }
+    assertStoreReadable(storeDir);
+    const root = terminalWatchesDir(storeDir);
+    if (!fs.existsSync(root)) {
+        return { watches: [], errors: [] };
+    }
+    assertOwnerPrivateDirectory(root, "terminal Watch root");
+    const watches = [];
+    const errors = [];
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+        const entryPath = path.join(root, entry.name);
+        if (entry.isSymbolicLink() || !entry.isFile()) {
+            throw new Error(`terminal Watch root contains an invalid entry: ${entryPath}`);
+        }
+        if (isRecognizedWatchLockFile(entry.name) ||
+            isRecognizedWatchTemporaryFile(entry.name)) {
+            assertPrivateTransientEntry(entryPath);
+            continue;
+        }
+        if (!entry.name.endsWith(".json")) {
+            throw new Error(`terminal Watch root contains an unknown file: ${entryPath}`);
+        }
+        const watchId = entry.name.slice(0, -".json".length);
+        assertRecordId(watchId, "terminal Watch id");
+        if (!isolateInvalidRecord) {
+            watches.push(loadTerminalWatch(storeDir, watchId));
+            continue;
+        }
+        // Establish the filesystem/security boundary before isolating JSON syntax
+        // or schema errors. A race, permission failure, or non-regular replacement
+        // must still abort the whole scan.
+        assertOwnerPrivateFile(entryPath, "terminal Watch state");
+        let value;
+        try {
+            value = readJsonFileNoFollow(entryPath, "terminal Watch state");
+        }
+        catch (error) {
+            if (!(error instanceof SyntaxError))
+                throw error;
+            errors.push({
+                watch_id: watchId,
+                error_code: "terminal_watch_record_invalid"
+            });
+            continue;
+        }
+        try {
+            watches.push(decodeTerminalWatch(value, watchId));
+        }
+        catch {
+            errors.push({
+                watch_id: watchId,
+                error_code: "terminal_watch_record_invalid"
+            });
+        }
+    }
+    watches.sort((left, right) => right.updated_at.localeCompare(left.updated_at) ||
+        left.watch_id.localeCompare(right.watch_id));
+    errors.sort((left, right) => left.watch_id.localeCompare(right.watch_id));
+    return { watches, errors };
+}
+function decodeTerminalWatch(value, expectedWatchId) {
+    const normalized = normalizeLegacyTerminalWatch(value);
+    assertTerminalWatch(normalized, expectedWatchId);
+    return normalized;
+}
+function normalizeLegacyTerminalWatch(value) {
+    if (!isRecord(value) ||
+        value.schema !== TERMINAL_WATCH_SCHEMA ||
+        value.version !== TERMINAL_WATCH_VERSION ||
+        value.observation_checkpoint !== undefined ||
+        !isRecord(value.anchor)) {
+        return value;
+    }
+    const anchor = value.anchor;
+    if (anchor.schema ===
+        "agent-knock-knock/claude-human-started-active-task-anchor") {
+        const validated = validateClaudeHumanStartedActiveTaskAnchor(anchor);
+        return {
+            ...value,
+            observation_checkpoint: initialTerminalWatchObservationCheckpoint(validated)
+        };
+    }
+    if (anchor.schema ===
+        "agent-knock-knock/codex-human-started-active-task-anchor") {
+        const validated = validateCodexHumanStartedActiveTaskAnchor(anchor);
+        return {
+            ...value,
+            observation_checkpoint: initialTerminalWatchObservationCheckpoint(validated)
+        };
+    }
+    return value;
+}
+function assertObservationCheckpoint(value, anchor) {
+    if (anchor.schema ===
+        "agent-knock-knock/claude-human-started-active-task-anchor") {
+        validateClaudeHumanStartedActiveTaskCheckpoint(value, anchor);
+        return;
+    }
+    assertStrictRecord(value, "terminal Watch observation checkpoint", {
+        safe_resume_offset_bytes: NON_NEGATIVE_INTEGER
+    });
+}
+function assertTerminalIdentity(value) {
+    assertStrictRecord(value, "terminal Watch terminal identity", TERMINAL_IDENTITY_FIELDS);
+}
+function assertTerminalEndpoint(value) {
+    assertStrictRecord(value, "terminal Watch endpoint", TERMINAL_ENDPOINT_FIELDS);
+    if (!terminalEndpointIdentityFromEvidence(value) ||
+        !terminalRouteKeyFromEvidence(value)) {
+        throw new Error("terminal Watch endpoint evidence is not exact");
+    }
+}
+function assertTerminalWatchAnchor(value, agent, terminal) {
+    if (!isRecord(value)) {
+        throw new Error("terminal Watch anchor must be an object");
+    }
+    if (value.schema ===
+        "agent-knock-knock/codex-human-started-active-task-anchor") {
+        if (agent !== "codex") {
+            throw new Error("Codex Watch anchor cannot belong to another agent");
+        }
+        validateCodexHumanStartedActiveTaskAnchor(value);
+        return;
+    }
+    if (value.schema ===
+        "agent-knock-knock/claude-human-started-active-task-anchor") {
+        if (agent !== "claude") {
+            throw new Error("Claude Watch anchor cannot belong to another agent");
+        }
+        const anchor = validateClaudeHumanStartedActiveTaskAnchor(value);
+        if (anchor.cwd !== terminal.workspace) {
+            throw new Error("Claude Watch workspace does not match its task anchor");
+        }
+        return;
+    }
+    throw new Error("terminal Watch anchor schema is unsupported");
+}
+function assertSettlement(value, status) {
+    if (status === "active") {
+        if (value !== undefined) {
+            throw new Error("an active terminal Watch cannot carry a settlement");
+        }
+        return;
+    }
+    assertStrictRecord(value, "terminal Watch settlement", SETTLEMENT_FIELDS);
+    if (value.kind !== status) {
+        throw new Error("terminal Watch settlement kind must match its status");
+    }
+    if (!["completed", "failed"].includes(status) &&
+        (value.completion_text !== undefined ||
+            value.completion_id !== undefined ||
+            value.completion_timestamp !== undefined)) {
+        throw new Error("only completed or failed terminal Watches may carry completion output");
+    }
+}
+function assertNotificationOutbox(watch) {
+    const seenIds = new Set();
+    const seenEvidence = new Set();
+    let previousCreatedAt = Date.parse(watch.created_at);
+    for (const notification of watch.notification_outbox) {
+        assertNotification(notification, String(watch.watch_id));
+        if (seenIds.has(notification.notification_id)) {
+            throw new Error("terminal Watch notification ids must be unique");
+        }
+        const evidenceKey = `${notification.kind}:${notification.evidence_fingerprint}`;
+        if (seenEvidence.has(evidenceKey)) {
+            throw new Error("terminal Watch notification evidence must be unique");
+        }
+        const createdAt = Date.parse(notification.created_at);
+        if (createdAt < previousCreatedAt ||
+            createdAt > Date.parse(watch.updated_at)) {
+            throw new Error("terminal Watch notification timestamps are not monotonic");
+        }
+        previousCreatedAt = createdAt;
+        seenIds.add(notification.notification_id);
+        seenEvidence.add(evidenceKey);
+    }
+    if (watch.status !== "active") {
+        const settlement = watch.settlement;
+        const terminalNotifications = watch.notification_outbox.filter((notification) => notification.kind !== "approval");
+        if (terminalNotifications.length !== 1 ||
+            terminalNotifications[0].kind !== watch.status ||
+            terminalNotifications[0].evidence_fingerprint !==
+                settlement.evidence_fingerprint) {
+            throw new Error("terminal Watch settlement must have exactly one notification");
+        }
+    }
+    else if (watch.notification_outbox.some((notification) => notification.kind !== "approval")) {
+        throw new Error("an active terminal Watch cannot have an outcome notification");
+    }
+}
+function assertNotification(value, watchId) {
+    assertStrictRecord(value, "terminal Watch notification", NOTIFICATION_FIELDS);
+    const notification = value;
+    const expectedId = terminalWatchNotificationId(watchId, notification.kind, notification.evidence_fingerprint);
+    if (notification.notification_id !== expectedId ||
+        notification.idempotency_key !==
+            terminalWatchNotificationIdempotencyKey(watchId, expectedId)) {
+        throw new Error("terminal Watch notification identity is not deterministic");
+    }
+    const [minimumAttempts, receiptFields] = NOTIFICATION_SHAPES[notification.status];
+    assertNotificationShape(value, minimumAttempts, receiptFields);
+}
+function assertNotificationShape(value, minimumAttempts, required) {
+    if (Number(value.attempts) < minimumAttempts) {
+        throw new Error(`terminal Watch ${String(value.status)} notification has no attempt`);
+    }
+    for (const key of required) {
+        if (value[key] === undefined) {
+            throw new Error(`terminal Watch ${String(value.status)} notification requires ${key}`);
+        }
+    }
+    const allowed = new Set(required);
+    for (const key of Object.keys(NOTIFICATION_RECEIPT_FIELDS)) {
+        if (value[key] !== undefined && !allowed.has(key)) {
+            throw new Error(`terminal Watch ${String(value.status)} notification cannot carry ${key}`);
+        }
+    }
+}
+function assertTerminalWatchAdvance(current, candidate) {
+    for (const [label, before, after] of [
+        ["schema", current.schema, candidate.schema],
+        ["version", current.version, candidate.version],
+        ["watch_id", current.watch_id, candidate.watch_id],
+        ["agent", current.agent, candidate.agent],
+        ["terminal", current.terminal, candidate.terminal],
+        ["anchor", current.anchor, candidate.anchor],
+        ["openclaw_session", current.openclaw_session, candidate.openclaw_session],
+        ["openclaw_bin", current.openclaw_bin, candidate.openclaw_bin],
+        ["created_at", current.created_at, candidate.created_at],
+        ["deadline_at", current.deadline_at, candidate.deadline_at]
+    ]) {
+        if (JSON.stringify(before) !== JSON.stringify(after)) {
+            throw new Error(`terminal Watch cannot change immutable ${label}`);
+        }
+    }
+    if (Date.parse(candidate.updated_at) < Date.parse(current.updated_at) ||
+        Date.parse(candidate.last_activity_at) < Date.parse(current.last_activity_at)) {
+        throw new Error("terminal Watch update cannot move time backwards");
+    }
+    if (candidate.observation_checkpoint.safe_resume_offset_bytes <
+        current.observation_checkpoint.safe_resume_offset_bytes) {
+        throw new Error("terminal Watch observation checkpoint cannot move backwards");
+    }
+    if (current.status !== "active" &&
+        candidate.status !== current.status) {
+        throw new Error("a settled terminal Watch cannot change outcome");
+    }
+    if (current.settlement !== undefined &&
+        JSON.stringify(candidate.settlement) !== JSON.stringify(current.settlement)) {
+        throw new Error("terminal Watch settlement is immutable");
+    }
+    if (current.status !== "active") {
+        if (candidate.last_activity_at !== current.last_activity_at ||
+            JSON.stringify(candidate.observation_checkpoint) !==
+                JSON.stringify(current.observation_checkpoint) ||
+            candidate.notification_outbox.length !== current.notification_outbox.length) {
+            throw new Error("a settled terminal Watch may change only notification delivery receipts");
+        }
+    }
+    else if (candidate.notification_outbox.length >
+        current.notification_outbox.length + 1) {
+        throw new Error("terminal Watch may append at most one notification per update");
+    }
+    assertNotificationAdvance(current.notification_outbox, candidate.notification_outbox);
+}
+function assertNotificationAdvance(current, candidate) {
+    if (candidate.length < current.length) {
+        throw new Error("terminal Watch notification outbox is append-only");
+    }
+    for (let index = 0; index < current.length; index += 1) {
+        const before = current[index];
+        const after = candidate[index];
+        for (const key of [
+            "notification_id",
+            "idempotency_key",
+            "kind",
+            "evidence_fingerprint",
+            "reason_code",
+            "created_at"
+        ]) {
+            if (before[key] !== after[key]) {
+                throw new Error(`terminal Watch notification cannot change immutable ${key}`);
+            }
+        }
+        assertNotificationStatusAdvance(before, after);
+    }
+    for (const added of candidate.slice(current.length)) {
+        if (added.status !== "pending" || added.attempts !== 0) {
+            throw new Error("a terminal Watch notification must be appended pending");
+        }
+    }
+}
+function assertNotificationStatusAdvance(current, candidate) {
+    const allowed = {
+        pending: ["pending", "delivering", "superseded"],
+        delivering: [
+            "delivering", "failed", "delivered", "superseded"
+        ],
+        failed: ["failed", "delivering", "superseded"],
+        delivered: ["delivered"],
+        superseded: ["superseded"]
+    };
+    if (!allowed[current.status].includes(candidate.status)) {
+        throw new Error(`terminal Watch notification cannot advance ${current.status} to ${candidate.status}`);
+    }
+    const reclaimed = current.status === "delivering" &&
+        candidate.status === "delivering" &&
+        candidate.attempt_id !== current.attempt_id;
+    const claimed = ["pending", "failed"].includes(current.status) &&
+        candidate.status === "delivering";
+    const expectedAttempts = claimed || reclaimed
+        ? current.attempts + 1
+        : current.attempts;
+    if (candidate.attempts !== expectedAttempts) {
+        throw new Error("terminal Watch notification attempt count is not monotonic");
+    }
+    if (current.status === candidate.status &&
+        !reclaimed &&
+        JSON.stringify(current) !== JSON.stringify(candidate)) {
+        throw new Error("terminal Watch notification receipt cannot change without a phase advance");
+    }
+}
+function atomicSaveTerminalWatch(filePath, watch) {
+    atomicSaveJsonFile(filePath, watch, {
+        rootLabel: "AKK Store",
+        directoryLabel: "terminal Watch root",
+        fileLabel: "terminal Watch state",
+        ensureDirectory: ensureDir,
+        fsyncNewDirectoryParent: true
+    });
+    assertOwnerPrivateDirectory(path.dirname(filePath), "terminal Watch root");
+    assertOwnerPrivateFile(filePath, "terminal Watch state");
+}
+function isRecognizedWatchLockFile(name) {
+    const suffix = name.endsWith(".json.lock.reclaim")
+        ? ".json.lock.reclaim"
+        : name.endsWith(".json.lock")
+            ? ".json.lock"
+            : undefined;
+    if (!suffix) {
+        return false;
+    }
+    const watchId = name.slice(0, -suffix.length);
+    try {
+        assertRecordId(watchId, "terminal Watch lock id");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isRecognizedWatchTemporaryFile(name) {
+    const match = /^\.(.+)\.json\.([1-9]\d*)\.([0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})\.tmp$/u.exec(name);
+    if (!match)
+        return false;
+    try {
+        assertRecordId(match[1], "terminal Watch temporary id");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function assertPrivateTransientEntry(filePath) {
+    try {
+        assertOwnerPrivateFile(filePath, "terminal Watch transient file");
+    }
+    catch (error) {
+        if (!isNodeError(error, "ENOENT"))
+            throw error;
+    }
+}
+function assertOwnerPrivateDirectory(directory, label) {
+    assertRealDirectory(directory, label);
+    const mode = fs.lstatSync(directory).mode & 0o777;
+    if (mode !== PRIVATE_DIRECTORY_MODE) {
+        throw new Error(`${label} must have owner-private 0700 permissions: ${directory}`);
+    }
+}
+function assertOwnerPrivateFile(filePath, label) {
+    const stat = fs.lstatSync(filePath);
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw new Error(`${label} must be a regular file: ${filePath}`);
+    }
+    if ((stat.mode & 0o777) !== PRIVATE_FILE_MODE) {
+        throw new Error(`${label} must have owner-private 0600 permissions: ${filePath}`);
+    }
+}
+function assertStrictRecord(value, label, shape) {
+    if (!isRecord(value))
+        throw new Error(`${label} must be an object`);
+    const unknown = Object.keys(value).find((key) => !Object.hasOwn(shape, key));
+    if (unknown) {
+        throw new Error(`${label} contains unsupported field ${unknown}`);
+    }
+    for (const [key, guard] of Object.entries(shape)) {
+        guard(value[key], `${label} ${key}`);
+    }
+}
+function literalGuard(expected) {
+    return (value, label) => {
+        if (value !== expected)
+            throw new Error(`${label} is invalid`);
+    };
+}
+function oneOfGuard(allowed) {
+    return (value, label) => {
+        if (!allowed.includes(value))
+            throw new Error(`${label} is invalid`);
+    };
+}
+function optionalGuard(guard) {
+    return (value, label) => {
+        if (value !== undefined)
+            guard(value, label);
+    };
+}
+function nullableGuard(guard) {
+    return (value, label) => {
+        if (value !== null)
+            guard(value, label);
+    };
+}
+function assertExpectedRevision(value) {
+    if (value !== null && !isPositiveSafeInteger(value)) {
+        throw new Error("expectedRevision must be null or a positive safe integer");
+    }
+}
+function assertRecordId(value, label) {
+    if (typeof value !== "string" ||
+        value.trim().length === 0 ||
+        value.includes("\0") ||
+        value === "." ||
+        value === ".." ||
+        path.posix.basename(value) !== value ||
+        path.win32.basename(value) !== value ||
+        path.isAbsolute(value)) {
+        throw new Error(`${label} is not safe for storage: ${String(value)}`);
+    }
+}
+function assertContained(candidate, parent, label) {
+    const resolvedParent = path.resolve(parent);
+    const resolvedCandidate = path.resolve(candidate);
+    if (resolvedCandidate === resolvedParent ||
+        !resolvedCandidate.startsWith(`${resolvedParent}${path.sep}`)) {
+        throw new Error(`${label} escapes its Store root: ${candidate}`);
+    }
+}
+function assertNotificationKind(value) {
+    if (!TERMINAL_WATCH_NOTIFICATION_KINDS.includes(value)) {
+        throw new Error("terminal Watch notification kind is invalid");
+    }
+}
+function isPositiveSafeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function isNonNegativeSafeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function assertNonEmptyString(value, label) {
+    if (typeof value !== "string" ||
+        value.trim().length === 0 ||
+        value.includes("\0")) {
+        throw new Error(`${label} must be a non-empty string without NUL bytes`);
+    }
+}
+function assertSha256(value, label) {
+    if (typeof value !== "string" || !/^[0-9a-f]{64}$/u.test(value)) {
+        throw new Error(`${label} must be a lowercase SHA-256 digest`);
+    }
+}
+function assertTimestamp(value, label) {
+    if (typeof value !== "string" ||
+        !Number.isFinite(Date.parse(value)) ||
+        new Date(value).toISOString() !== value) {
+        throw new Error(`${label} must be a canonical ISO timestamp`);
+    }
+}
+function assertReasonCode(value, label) {
+    if (typeof value !== "string" ||
+        value.length < 1 ||
+        value.length > 128 ||
+        !/^[a-z0-9][a-z0-9_.:-]*$/u.test(value)) {
+        throw new Error(`${label} must be a privacy-safe reason code`);
+    }
+}
+function assertCompletionText(value, label) {
+    if (typeof value !== "string" ||
+        value.length > 4000 ||
+        value.includes("\0")) {
+        throw new Error(`${label} must be redacted and at most 4k`);
+    }
+}
+//# sourceMappingURL=terminal-watch-store.js.map