@scotthuang/agent-knock-knock 0.12.5 → 0.12.7

package/dist/src/terminal-submission-acceptance.js

@@ -180,8 +180,174 @@ export function captureCodexRolloutAcceptanceAnchor(options) {
         fs.closeSync(opened.fd);
     }
 }
+export function captureCodexCandidateSetRolloutAcceptanceAnchor({ inventory: inventoryValue, now = new Date() }) {
+    const inventory = validateCodexOpenRootInventoryForAcceptance(inventoryValue);
+    const candidateRollouts = inventory.roots.map((identity) => {
+        const rollout = normalizedRolloutIdentity(identity.rollout);
+        const opened = openExactRollout(rollout);
+        try {
+            const before = opened.stat;
+            assertPrivateRegularFile(before);
+            if (before.size > 0 && !fileEndsWithNewline(opened.fd, before.size)) {
+                throw new Error("Codex candidate rollout did not end at a complete JSONL record before terminal submission");
+            }
+            const after = fs.fstatSync(opened.fd);
+            if (!sameStableFile(before, after)) {
+                throw new Error("Codex candidate rollout changed while its terminal submission anchor was captured");
+            }
+            return {
+                native_thread_id: exactNativeThreadId(identity.sessionId),
+                rollout,
+                offset_bytes: before.size
+            };
+        }
+        finally {
+            fs.closeSync(opened.fd);
+        }
+    });
+    const base = {
+        schema: "agent-knock-knock/codex-rollout-acceptance-anchor",
+        version: 3,
+        process_uuid: inventory.processUuid,
+        process_birth: inventory.processBirth,
+        captured_at: now.toISOString(),
+        mode: "candidate_set",
+        native_thread_binding: "post_submission",
+        file_existed: false,
+        offset_bytes: 0,
+        zero_file_baseline: candidateRollouts.length === 0,
+        inventory_pid: inventory.pid,
+        ...(inventory.cwd ? { inventory_cwd: inventory.cwd } : {}),
+        inventory_fingerprint: inventory.inventoryFingerprint,
+        candidate_rollouts: candidateRollouts
+    };
+    return {
+        ...base,
+        anchor_fingerprint: fingerprint(base)
+    };
+}
+export function detectCodexCandidateSetRolloutAcceptance({ anchor: anchorValue, currentInventory: inventoryValue, requestHash: requestHashValue }) {
+    const anchor = validateCodexRolloutAcceptanceAnchor(anchorValue);
+    if (anchor.version !== 3) {
+        throw new Error("Codex candidate-set acceptance requires a version 3 anchor");
+    }
+    const inventory = validateCodexOpenRootInventoryForAcceptance(inventoryValue);
+    const requestHash = sha256Value(requestHashValue, "terminal request hash");
+    if (inventory.processUuid !== anchor.process_uuid ||
+        inventory.processBirth !== anchor.process_birth ||
+        inventory.pid !== anchor.inventory_pid ||
+        inventory.cwd !== anchor.inventory_cwd) {
+        return {
+            status: "uncertain",
+            code: "candidate_inventory_changed",
+            reason: "Codex process incarnation changed during candidate-set acceptance polling",
+            inspected_candidates: 0,
+            exact_matches: 0
+        };
+    }
+    const anchoredByThread = new Map(anchor.candidate_rollouts.map((candidate) => [
+        candidate.native_thread_id,
+        candidate
+    ]));
+    const currentByThread = new Map(inventory.roots.map((identity) => [identity.sessionId, identity]));
+    for (const identity of inventory.roots) {
+        const anchored = anchoredByThread.get(identity.sessionId);
+        if (anchored &&
+            !sameRolloutIdentity(anchored.rollout, identity.rollout)) {
+            return {
+                status: "uncertain",
+                code: "candidate_inventory_changed",
+                reason: `Codex candidate ${identity.sessionId} changed rollout identity after capture`,
+                inspected_candidates: 0,
+                exact_matches: 0
+            };
+        }
+    }
+    for (const anchored of anchor.candidate_rollouts) {
+        if (!currentByThread.has(anchored.native_thread_id)) {
+            return {
+                status: "uncertain",
+                code: "candidate_inventory_changed",
+                reason: `Codex candidate ${anchored.native_thread_id} is no longer open in the exact process inventory`,
+                inspected_candidates: 0,
+                exact_matches: 0
+            };
+        }
+    }
+    const candidates = inventory.roots.map((identity) => {
+        const anchored = anchoredByThread.get(identity.sessionId);
+        return {
+            identity,
+            offsetBytes: anchored?.offset_bytes ?? 0,
+            requireFreshHeader: anchored === undefined
+        };
+    });
+    const matches = [];
+    let incompleteCandidates = 0;
+    for (const candidate of candidates) {
+        let scan;
+        try {
+            scan = scanCodexRolloutAcceptance({
+                rollout: candidate.identity.rollout,
+                nativeThreadId: candidate.identity.sessionId,
+                processUuid: anchor.process_uuid,
+                processBirth: anchor.process_birth,
+                requestHash,
+                anchorFingerprint: anchor.anchor_fingerprint,
+                offsetBytes: candidate.offsetBytes,
+                requireFreshHeader: candidate.requireFreshHeader,
+                capturedAt: anchor.captured_at
+            });
+        }
+        catch (error) {
+            return {
+                status: "uncertain",
+                code: "candidate_scan_invalid",
+                reason: error instanceof Error ? error.message : String(error),
+                inspected_candidates: candidates.indexOf(candidate) + 1,
+                exact_matches: matches.length
+            };
+        }
+        if (scan.status === "incomplete") {
+            incompleteCandidates += 1;
+        }
+        else if (scan.status === "accepted") {
+            matches.push({
+                identity: candidate.identity,
+                evidence: scan.evidence
+            });
+        }
+    }
+    if (matches.length > 1) {
+        return {
+            status: "uncertain",
+            code: "multiple_exact_request_acceptances",
+            reason: "multiple Codex root rollouts durably accepted the exact terminal request",
+            inspected_candidates: candidates.length,
+            exact_matches: matches.length
+        };
+    }
+    if (matches.length === 0 || incompleteCandidates > 0) {
+        return {
+            status: "pending",
+            inspected_candidates: candidates.length,
+            exact_matches: matches.length,
+            ...(incompleteCandidates > 0
+                ? { incomplete_candidates: incompleteCandidates }
+                : {})
+        };
+    }
+    return {
+        status: "accepted",
+        identity: matches[0].identity,
+        evidence: matches[0].evidence
+    };
+}
 export function detectCodexRolloutAcceptance(options) {
     const anchor = validateCodexRolloutAcceptanceAnchor(options.anchor);
+    if (anchor.version === 3) {
+        throw new Error("Codex candidate-set acceptance requires the inventory-aware detector");
+    }
     const requestHash = sha256Value(options.requestHash, "terminal request hash");
     const current = options.currentIdentity;
     const currentNativeThreadId = exactNativeThreadId(current.sessionId);
@@ -201,66 +367,18 @@ export function detectCodexRolloutAcceptance(options) {
         !sameRolloutIdentity(anchor.rollout, rollout)) {
         throw new Error("Codex rollout identity changed during acceptance polling");
     }
-    const opened = openExactRollout(rollout);
-    try {
-        const before = opened.stat;
-        assertPrivateRegularFile(before);
-        if (before.size < anchor.offset_bytes) {
-            throw new Error("Codex rollout was truncated after terminal submission");
-        }
-        const bytesToRead = before.size - anchor.offset_bytes;
-        if (bytesToRead === 0) {
-            return undefined;
-        }
-        if (bytesToRead > CODEX_ACCEPTANCE_MAX_BYTES) {
-            throw new Error("Codex rollout acceptance suffix exceeded the bounded read limit");
-        }
-        if (!fileEndsWithNewline(opened.fd, before.size)) {
-            return undefined;
-        }
-        const buffer = Buffer.allocUnsafe(bytesToRead);
-        const bytesRead = fs.readSync(opened.fd, buffer, 0, bytesToRead, anchor.offset_bytes);
-        if (bytesRead !== bytesToRead) {
-            return undefined;
-        }
-        const after = fs.fstatSync(opened.fd);
-        if (!sameStableFile(before, after)) {
-            return undefined;
-        }
-        const suffix = buffer.toString("utf8");
-        if (anchor.version === 2) {
-            assertVirginRolloutHeader({
-                text: suffix,
-                nativeThreadId: expectedNativeThreadId,
-                capturedAt: anchor.captured_at
-            });
-        }
-        const accepted = acceptedCodexTurnFromSuffix(suffix, requestHash);
-        if (!accepted) {
-            return undefined;
-        }
-        const evidenceBase = {
-            source: "codex_rollout",
-            kind: "native_user_turn",
-            nativeThreadId: expectedNativeThreadId,
-            requestHash,
-            acceptanceId: accepted.turnId,
-            acceptedAt: accepted.userTimestamp ?? accepted.startedAt,
-            anchorFingerprint: anchor.anchor_fingerprint,
-            metadata: {
-                turn_id: accepted.turnId,
-                anchor_offset_bytes: anchor.offset_bytes,
-                observed_end_offset_bytes: before.size
-            }
-        };
-        return {
-            ...evidenceBase,
-            evidenceFingerprint: fingerprint(evidenceBase)
-        };
-    }
-    finally {
-        fs.closeSync(opened.fd);
-    }
+    const scan = scanCodexRolloutAcceptance({
+        rollout,
+        nativeThreadId: expectedNativeThreadId,
+        processUuid: anchor.process_uuid,
+        processBirth: anchor.process_birth,
+        requestHash,
+        anchorFingerprint: anchor.anchor_fingerprint,
+        offsetBytes: anchor.offset_bytes,
+        requireFreshHeader: anchor.version === 2,
+        capturedAt: anchor.captured_at
+    });
+    return scan.status === "accepted" ? scan.evidence : undefined;
 }
 /**
  * Scans the exact rollout and native turn proven by terminal acceptance.
@@ -300,8 +418,14 @@ export function detectCodexBoundRolloutCompletion(options) {
     catch (error) {
         return codexCompletionFailure("invalid_acceptance_evidence", error, initialDiagnostics);
     }
+    const acceptedCandidate = anchor.version === 3
+        ? anchor.candidate_rollouts.find((candidate) => candidate.native_thread_id === expectedNativeThreadId)
+        : undefined;
+    const scanStartOffset = acceptedCandidate?.offset_bytes ??
+        anchor.offset_bytes;
     const baseDiagnostics = {
         ...initialDiagnostics,
+        scan_start_offset_bytes: scanStartOffset,
         native_thread_id: expectedNativeThreadId
     };
     let acceptanceId;
@@ -339,7 +463,7 @@ export function detectCodexBoundRolloutCompletion(options) {
         return codexCompletionFailure("invalid_acceptance_evidence", error, diagnostics);
     }
     if (evidenceAnchorOffset !== undefined &&
-        evidenceAnchorOffset !== anchor.offset_bytes) {
+        evidenceAnchorOffset !== scanStartOffset) {
         return codexCompletionFailure("acceptance_anchor_mismatch", new Error("Codex acceptance evidence has a different byte offset"), diagnostics);
     }
     const current = options.currentIdentity;
@@ -369,7 +493,10 @@ export function detectCodexBoundRolloutCompletion(options) {
         ...diagnostics,
         rollout_identity_fingerprint: fingerprint(rollout)
     };
-    if (anchor.rollout && !sameRolloutIdentity(anchor.rollout, rollout)) {
+    const anchoredRollout = anchor.version === 3
+        ? acceptedCandidate?.rollout
+        : anchor.rollout;
+    if (anchoredRollout && !sameRolloutIdentity(anchoredRollout, rollout)) {
         return codexCompletionFailure("rollout_identity_mismatch", new Error("Codex rollout identity changed after terminal acceptance"), rolloutDiagnostics);
     }
     let opened;
@@ -397,14 +524,14 @@ export function detectCodexBoundRolloutCompletion(options) {
         catch (error) {
             return codexCompletionFailure("invalid_acceptance_evidence", error, rolloutDiagnostics);
         }
-        if (before.size < anchor.offset_bytes ||
+        if (before.size < scanStartOffset ||
             (evidenceEndOffset !== undefined && before.size < evidenceEndOffset)) {
             return codexCompletionFailure("rollout_truncated", new Error("Codex rollout was truncated after native acceptance"), {
                 ...rolloutDiagnostics,
                 observed_end_offset_bytes: before.size
             });
         }
-        const bytesToRead = before.size - anchor.offset_bytes;
+        const bytesToRead = before.size - scanStartOffset;
         const observedDiagnostics = {
             ...rolloutDiagnostics,
             observed_end_offset_bytes: before.size
@@ -419,7 +546,7 @@ export function detectCodexBoundRolloutCompletion(options) {
             return codexCompletionPending("partial_rollout_record", observedDiagnostics, "the exact Codex rollout ends with a partial JSONL record");
         }
         const buffer = Buffer.allocUnsafe(bytesToRead);
-        const bytesRead = fs.readSync(opened.fd, buffer, 0, bytesToRead, anchor.offset_bytes);
+        const bytesRead = fs.readSync(opened.fd, buffer, 0, bytesToRead, scanStartOffset);
         const after = fs.fstatSync(opened.fd);
         if (bytesRead !== bytesToRead || !sameStableFile(before, after)) {
             return codexCompletionPending("rollout_changed_during_scan", observedDiagnostics, "the exact Codex rollout changed while completion was scanned");
@@ -449,7 +576,7 @@ export function detectCodexBoundRolloutCompletion(options) {
                 native_thread_id: expectedNativeThreadId,
                 anchor_fingerprint: anchor.anchor_fingerprint,
                 rollout_identity_fingerprint: rolloutDiagnostics.rollout_identity_fingerprint,
-                scan_start_offset_bytes: anchor.offset_bytes,
+                scan_start_offset_bytes: scanStartOffset,
                 observed_end_offset_bytes: before.size,
                 scanned_records: scan.scannedRecords,
                 observed_task_complete_records: scan.observedTaskCompleteRecords
@@ -661,6 +788,78 @@ function acceptedCodexTurnFromSuffix(text, requestHash) {
     }
     return matches[0];
 }
+function scanCodexRolloutAcceptance({ rollout: rolloutValue, nativeThreadId: nativeThreadIdValue, processUuid: processUuidValue, processBirth: processBirthValue, requestHash, anchorFingerprint, offsetBytes, requireFreshHeader, capturedAt }) {
+    const rollout = normalizedRolloutIdentity(rolloutValue);
+    const nativeThreadId = exactNativeThreadId(nativeThreadIdValue);
+    requiredString(processUuidValue, "Codex process UUID");
+    requiredString(processBirthValue, "Codex process birth");
+    if (!Number.isSafeInteger(offsetBytes) || offsetBytes < 0) {
+        throw new Error("Codex rollout acceptance byte offset is invalid");
+    }
+    const opened = openExactRollout(rollout);
+    try {
+        const before = opened.stat;
+        assertPrivateRegularFile(before);
+        if (before.size < offsetBytes) {
+            throw new Error("Codex rollout was truncated after terminal submission");
+        }
+        const bytesToRead = before.size - offsetBytes;
+        if (bytesToRead === 0) {
+            return { status: "pending" };
+        }
+        if (bytesToRead > CODEX_ACCEPTANCE_MAX_BYTES) {
+            throw new Error("Codex rollout acceptance suffix exceeded the bounded read limit");
+        }
+        if (!fileEndsWithNewline(opened.fd, before.size)) {
+            return { status: "incomplete" };
+        }
+        const buffer = Buffer.allocUnsafe(bytesToRead);
+        const bytesRead = fs.readSync(opened.fd, buffer, 0, bytesToRead, offsetBytes);
+        if (bytesRead !== bytesToRead) {
+            return { status: "incomplete" };
+        }
+        const after = fs.fstatSync(opened.fd);
+        if (!sameStableFile(before, after)) {
+            return { status: "incomplete" };
+        }
+        const suffix = buffer.toString("utf8");
+        if (requireFreshHeader) {
+            assertVirginRolloutHeader({
+                text: suffix,
+                nativeThreadId,
+                capturedAt
+            });
+        }
+        const accepted = acceptedCodexTurnFromSuffix(suffix, requestHash);
+        if (!accepted) {
+            return { status: "pending" };
+        }
+        const evidenceBase = {
+            source: "codex_rollout",
+            kind: "native_user_turn",
+            nativeThreadId,
+            requestHash,
+            acceptanceId: accepted.turnId,
+            acceptedAt: accepted.userTimestamp ?? accepted.startedAt,
+            anchorFingerprint,
+            metadata: {
+                turn_id: accepted.turnId,
+                anchor_offset_bytes: offsetBytes,
+                observed_end_offset_bytes: before.size
+            }
+        };
+        return {
+            status: "accepted",
+            evidence: {
+                ...evidenceBase,
+                evidenceFingerprint: fingerprint(evidenceBase)
+            }
+        };
+    }
+    finally {
+        fs.closeSync(opened.fd);
+    }
+}
 function exactCodexUserResponseText(content) {
     if (!Array.isArray(content) || content.length !== 1) {
         return undefined;
@@ -699,11 +898,11 @@ function assertVirginRolloutHeader(options) {
         throw new Error("virgin Codex rollout predates its terminal submission anchor");
     }
 }
-function validateCodexRolloutAcceptanceAnchor(value) {
+export function validateCodexRolloutAcceptanceAnchor(value) {
     if (!isRecord(value) ||
         value.schema !== "agent-knock-knock/codex-rollout-acceptance-anchor" ||
-        (value.version !== 1 && value.version !== 2) ||
-        !["existing", "pre_materialization"].includes(String(value.mode)) ||
+        (value.version !== 1 && value.version !== 2 && value.version !== 3) ||
+        !["existing", "pre_materialization", "candidate_set"].includes(String(value.mode)) ||
         !Number.isSafeInteger(value.offset_bytes) ||
         value.offset_bytes < 0 ||
         typeof value.file_existed !== "boolean") {
@@ -715,11 +914,27 @@ function validateCodexRolloutAcceptanceAnchor(value) {
             throw new Error("bound Codex acceptance anchor has deferred binding state");
         }
     }
-    else if (value.mode !== "pre_materialization" ||
+    else if (value.version === 2 && (value.mode !== "pre_materialization" ||
         value.native_thread_binding !== "post_submission" ||
-        "native_thread_id" in value) {
+        "native_thread_id" in value)) {
         throw new Error("virgin Codex acceptance anchor is inconsistent");
     }
+    else if (value.version === 3 && (value.mode !== "candidate_set" ||
+        value.native_thread_binding !== "post_submission" ||
+        "native_thread_id" in value ||
+        value.file_existed !== false ||
+        value.offset_bytes !== 0 ||
+        typeof value.zero_file_baseline !== "boolean" ||
+        !Number.isSafeInteger(value.inventory_pid) ||
+        value.inventory_pid <= 1 ||
+        (value.inventory_cwd !== undefined &&
+            !path.isAbsolute(value.inventory_cwd)) ||
+        !/^[0-9a-f]{64}$/u.test(String(value.inventory_fingerprint)) ||
+        !Array.isArray(value.candidate_rollouts) ||
+        value.candidate_rollouts.length > 128 ||
+        value.zero_file_baseline !== (value.candidate_rollouts.length === 0))) {
+        throw new Error("candidate-set Codex acceptance anchor is inconsistent");
+    }
     requiredString(value.process_uuid, "Codex process UUID");
     requiredString(value.process_birth, "Codex process birth");
     if (!validTimestamp(value.captured_at)) {
@@ -730,6 +945,26 @@ function validateCodexRolloutAcceptanceAnchor(value) {
     if (fingerprint(base) !== value.anchor_fingerprint) {
         throw new Error("Codex rollout acceptance anchor fingerprint does not match");
     }
+    if (value.version === 3) {
+        const seenThreads = new Set();
+        const seenFiles = new Set();
+        for (const candidate of value.candidate_rollouts) {
+            if (!isRecord(candidate)) {
+                throw new Error("Codex candidate-set rollout entry is invalid");
+            }
+            const nativeThreadId = exactNativeThreadId(candidate.native_thread_id);
+            const rollout = normalizedRolloutIdentity(candidate.rollout);
+            if (!Number.isSafeInteger(candidate.offset_bytes) ||
+                candidate.offset_bytes < 0 ||
+                seenThreads.has(nativeThreadId) ||
+                seenFiles.has(`${rollout.device}:${rollout.inode}`)) {
+                throw new Error("Codex candidate-set rollout entries are ambiguous");
+            }
+            seenThreads.add(nativeThreadId);
+            seenFiles.add(`${rollout.device}:${rollout.inode}`);
+        }
+        return value;
+    }
     const rollout = "rollout" in value ? value.rollout : undefined;
     if (value.file_existed !== (value.mode === "existing") ||
         value.file_existed !== Boolean(rollout)) {
@@ -748,6 +983,61 @@ function validateCodexRolloutAcceptanceAnchor(value) {
     }
     return value;
 }
+function validateCodexOpenRootInventoryForAcceptance(value) {
+    if (!isRecord(value) ||
+        value.schema !==
+            "agent-knock-knock/codex-open-root-rollout-inventory" ||
+        value.version !== 1 ||
+        !["verified_absent", "resolved", "unbound"].includes(String(value.status)) ||
+        !Number.isSafeInteger(value.pid) ||
+        value.pid <= 1 ||
+        !Array.isArray(value.roots) ||
+        value.roots.length > 128 ||
+        !/^[0-9a-f]{64}$/u.test(String(value.inventoryFingerprint))) {
+        throw new Error("Codex open-root rollout inventory is invalid");
+    }
+    requiredString(value.processUuid, "Codex process UUID");
+    requiredString(value.processBirth, "Codex process birth");
+    if (value.processUuid !==
+        `codex-pid:${value.pid}:birth:${value.processBirth}`) {
+        throw new Error("Codex open-root rollout inventory process UUID is inconsistent");
+    }
+    if (value.cwd !== undefined && !path.isAbsolute(value.cwd)) {
+        throw new Error("Codex open-root rollout inventory cwd is not absolute");
+    }
+    if ((value.status === "verified_absent" && value.roots.length !== 0) ||
+        (value.status === "resolved" && value.roots.length !== 1) ||
+        (value.status === "unbound" &&
+            (value.roots.length < 2 ||
+                value.reason !== "multiple_open_root_rollouts"))) {
+        throw new Error("Codex open-root rollout inventory status is inconsistent");
+    }
+    const seenThreads = new Set();
+    const seenFiles = new Set();
+    for (const identity of value.roots) {
+        if (!isRecord(identity)) {
+            throw new Error("Codex open-root rollout inventory identity is invalid");
+        }
+        const nativeThreadId = exactNativeThreadId(identity.sessionId);
+        if (identity.processUuid !== value.processUuid ||
+            identity.processBirth !== value.processBirth ||
+            identity.evidence !== "codex_open_root_rollout") {
+            throw new Error("Codex open-root rollout inventory has mixed process authority");
+        }
+        const rollout = normalizedRolloutIdentity(identity.rollout);
+        if (seenThreads.has(nativeThreadId) ||
+            seenFiles.has(`${rollout.device}:${rollout.inode}`)) {
+            throw new Error("Codex open-root rollout inventory is ambiguous");
+        }
+        seenThreads.add(nativeThreadId);
+        seenFiles.add(`${rollout.device}:${rollout.inode}`);
+    }
+    const { status: _status, inventoryFingerprint, reason: _reason, ...authority } = value;
+    if (fingerprint(authority) !== inventoryFingerprint) {
+        throw new Error("Codex open-root rollout inventory fingerprint does not match");
+    }
+    return value;
+}
 function openExactRollout(rollout) {
     if (!path.isAbsolute(rollout.path)) {
         throw new Error("Codex rollout path is not absolute");