aicodeman 1.44.0 → 1.46.0

package/dist/agent-inspection.js

@@ -0,0 +1,196 @@
+/**
+ * @fileoverview Bounded append-only JSONL evidence reads for agent inspection.
+ * Opaque, expiring server-side cursors contain no public filesystem paths. A cursor
+ * binds the caller, pane generation, attributed conversation and opened file identity.
+ * Complete records only; an oversized row stalls explicitly rather than losing evidence.
+ */
+import { open } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { isUtf8 } from 'node:buffer';
+export const INSPECT_MAX_BYTES = 65536;
+export const INSPECT_SCAN_BYTES = 262144;
+export class InspectionConflict extends Error {
+}
+/** UTF8-safe suffix, also used for explicitly non-incremental pane evidence. */
+export function boundedUtf8Tail(text, maxBytes) {
+    // A UTF8 suffix fits within this many UTF16 units. Include a pair of extra
+    // units so slicing cannot introduce a surrogate replacement inside the result.
+    const bytes = Buffer.from(text.slice(-maxBytes - 2));
+    let start = Math.max(0, bytes.length - maxBytes);
+    while (start < bytes.length && (bytes[start] & 0xc0) === 0x80)
+        start++;
+    return bytes.subarray(start).toString('utf8');
+}
+async function anchor(handle, offset) {
+    const count = Math.min(offset, 4096);
+    const head = Buffer.alloc(count);
+    const tail = Buffer.alloc(count);
+    await handle.read(head, 0, count, 0);
+    await handle.read(tail, 0, count, Math.max(0, offset - count));
+    return createHash('sha256').update(head).update(tail).digest('hex');
+}
+/** Cursors kept per owner and session; older ones are retired first. */
+export const INSPECT_CURSORS_PER_SCOPE = 8;
+export class InspectionReader {
+    now;
+    capacity;
+    ttlMs;
+    perScope;
+    cursors = new Map();
+    constructor(now = Date.now, capacity = 1024, ttlMs = 900000, perScope = INSPECT_CURSORS_PER_SCOPE) {
+        this.now = now;
+        this.capacity = capacity;
+        this.ttlMs = ttlMs;
+        this.perScope = perScope;
+    }
+    async read(path, scope, maxBytes, since) {
+        if (!Number.isInteger(maxBytes) || maxBytes < 1 || maxBytes > INSPECT_MAX_BYTES)
+            throw new Error('Invalid byte budget');
+        const scopeKey = JSON.stringify(scope);
+        const previous = since ? this.cursors.get(since) : undefined;
+        if (since &&
+            (!previous || previous.expiresAt <= this.now() || previous.scope !== scopeKey || previous.path !== path)) {
+            throw new InspectionConflict('Invalid or expired inspection cursor; inspect without since to start again');
+        }
+        const handle = await open(path, 'r');
+        try {
+            const before = await handle.stat();
+            if (!before.isFile())
+                throw new InspectionConflict('Inspection source is not a regular file');
+            const identity = `${before.dev}:${before.ino}:${before.birthtimeMs}`;
+            let offset = previous?.offset ?? Math.max(0, before.size - INSPECT_SCAN_BYTES + 1);
+            if (previous &&
+                (identity !== previous.identity ||
+                    before.size < previous.observedSize ||
+                    (before.size === previous.observedSize &&
+                        (before.mtimeMs !== previous.modifiedAt || before.ctimeMs !== previous.changedAt)) ||
+                    (await anchor(handle, offset)) !== previous.anchor)) {
+                throw new InspectionConflict('Inspection cursor source changed; inspect without since to start again');
+            }
+            let startsAtBoundary = offset === 0;
+            if (!previous && offset > 0) {
+                const preceding = Buffer.alloc(1);
+                await handle.read(preceding, 0, 1, offset - 1);
+                startsAtBoundary = preceding[0] === 10;
+            }
+            const scan = Buffer.alloc(Math.min(INSPECT_SCAN_BYTES - (!previous && offset > 0 ? 1 : 0), Math.max(0, before.size - offset)));
+            const { bytesRead } = await handle.read(scan, 0, scan.length, offset);
+            let selectedStart = 0;
+            let consumed = 0;
+            let blockedReason;
+            let omittedBeforeBytes = 0;
+            if (!previous) {
+                const leading = startsAtBoundary ? 0 : scan.indexOf(10) + 1;
+                const completeEnd = scan.lastIndexOf(10, bytesRead - 1) + 1;
+                if (!startsAtBoundary && leading === 0) {
+                    // The tail lies wholly inside one unfinished oversized record. Its
+                    // beginning is not known: retain the known file boundary rather than
+                    // manufacture a cursor pointing into a JSON/UTF8 fragment.
+                    offset = 0;
+                    blockedReason = 'record-exceeds-scan-limit';
+                }
+                else {
+                    selectedStart = completeEnd;
+                    consumed = completeEnd;
+                    while (selectedStart > leading) {
+                        const recordStart = Math.max(leading, scan.lastIndexOf(10, selectedStart - 2) + 1);
+                        if (completeEnd - recordStart > maxBytes) {
+                            if (selectedStart === completeEnd) {
+                                selectedStart = recordStart;
+                                consumed = recordStart;
+                                blockedReason = 'record-exceeds-output-budget';
+                            }
+                            break;
+                        }
+                        selectedStart = recordStart;
+                    }
+                    if (completeEnd < bytesRead && !blockedReason)
+                        blockedReason = 'partial-record';
+                    // If the only known boundary is the end of a skipped leading row,
+                    // the remainder is a partial record and stays pending there.
+                    if (completeEnd < leading)
+                        selectedStart = consumed = leading;
+                    omittedBeforeBytes = offset + selectedStart;
+                }
+            }
+            else {
+                while (consumed < bytesRead) {
+                    const end = scan.indexOf(10, consumed);
+                    if (end < 0) {
+                        blockedReason = bytesRead === INSPECT_SCAN_BYTES ? 'record-exceeds-scan-limit' : 'partial-record';
+                        break;
+                    }
+                    if (end + 1 > maxBytes) {
+                        if (consumed === 0)
+                            blockedReason = 'record-exceeds-output-budget';
+                        break;
+                    }
+                    consumed = end + 1;
+                }
+            }
+            const evidenceBytes = scan.subarray(selectedStart, consumed);
+            if (!isUtf8(evidenceBytes))
+                throw new InspectionConflict('Inspection source contains invalid UTF8');
+            for (const row of evidenceBytes.toString('utf8').split('\n').slice(0, -1)) {
+                try {
+                    JSON.parse(row);
+                }
+                catch {
+                    throw new InspectionConflict('Inspection source contains invalid JSONL');
+                }
+            }
+            const after = await handle.stat();
+            if (after.size < before.size ||
+                after.ino !== before.ino ||
+                (after.size === before.size && (after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs)))
+                throw new InspectionConflict('Inspection source changed during read');
+            const nextAnchor = await anchor(handle, offset + consumed);
+            const cursor = randomUUID();
+            // No await between capacity enforcement and insertion: concurrent reads
+            // must not all reserve the same remaining slot while hashing anchors.
+            // Each owner and session keeps only its newest cursors, so one agent polling in
+            // a loop retires its own oldest ones instead of pushing every other caller's out
+            // of the shared map. The cursor just used stays among the newest, so a retry of
+            // the last call still works. The global capacity is only a backstop.
+            const holder = JSON.stringify([scope.owner, scope.sessionId]);
+            const mine = [];
+            for (const [key, value] of this.cursors) {
+                if (value.expiresAt <= this.now())
+                    this.cursors.delete(key);
+                else if (value.holder === holder)
+                    mine.push(key);
+            }
+            while (mine.length >= this.perScope)
+                this.cursors.delete(mine.shift());
+            while (this.cursors.size >= this.capacity)
+                this.cursors.delete(this.cursors.keys().next().value);
+            this.cursors.set(cursor, {
+                scope: scopeKey,
+                holder,
+                path,
+                identity,
+                offset: offset + consumed,
+                observedSize: before.size,
+                modifiedAt: before.mtimeMs,
+                changedAt: before.ctimeMs,
+                anchor: nextAnchor,
+                expiresAt: this.now() + this.ttlMs,
+            });
+            return {
+                evidence: evidenceBytes.toString('utf8'),
+                cursor,
+                omittedBeforeBytes,
+                truncated: omittedBeforeBytes > 0 || offset + consumed < before.size,
+                blockedReason,
+                scannedBytes: bytesRead,
+            };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    clear() {
+        this.cursors.clear();
+    }
+}
+//# sourceMappingURL=agent-inspection.js.map

package/dist/agent-inspection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-inspection.js","sourceRoot":"","sources":["../src/agent-inspection.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,IAAI,EAAmB,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AACvC,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAoBzC,MAAM,OAAO,kBAAmB,SAAQ,KAAK;CAAG;AAEhD,gFAAgF;AAChF,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,QAAgB;IAC5D,2EAA2E;IAC3E,+EAA+E;IAC/E,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC;IACrD,IAAI,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC;IACjD,OAAO,KAAK,GAAG,KAAK,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,KAAK,IAAI;QAAE,KAAK,EAAE,CAAC;IACvE,OAAO,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAChD,CAAC;AACD,KAAK,UAAU,MAAM,CAAC,MAAkB,EAAE,MAAc;IACtD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACjC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACjC,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IACrC,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC;IAC/D,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACtE,CAAC;AAED,wEAAwE;AACxE,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAE3C,MAAM,OAAO,gBAAgB;IAGR;IACA;IACA;IACA;IALF,OAAO,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC1D,YACmB,MAAM,IAAI,CAAC,GAAG,EACd,WAAW,IAAI,EACf,QAAQ,MAAM,EACd,WAAW,yBAAyB;QAHpC,QAAG,GAAH,GAAG,CAAW;QACd,aAAQ,GAAR,QAAQ,CAAO;QACf,UAAK,GAAL,KAAK,CAAS;QACd,aAAQ,GAAR,QAAQ,CAA4B;IACpD,CAAC;IAEJ,KAAK,CAAC,IAAI,CAAC,IAAY,EAAE,KAAsB,EAAE,QAAgB,EAAE,KAAc;QAC/E,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,IAAI,QAAQ,GAAG,iBAAiB;YAC7E,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;QACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACvC,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC7D,IACE,KAAK;YACL,CAAC,CAAC,QAAQ,IAAI,QAAQ,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ,CAAC,KAAK,KAAK,QAAQ,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI,CAAC,EACxG,CAAC;YACD,MAAM,IAAI,kBAAkB,CAAC,4EAA4E,CAAC,CAAC;QAC7G,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACrC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YACnC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE;gBAAE,MAAM,IAAI,kBAAkB,CAAC,yCAAyC,CAAC,CAAC;YAC9F,MAAM,QAAQ,GAAG,GAAG,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;YACrE,IAAI,MAAM,GAAG,QAAQ,EAAE,MAAM,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,IAAI,GAAG,kBAAkB,GAAG,CAAC,CAAC,CAAC;YACnF,IACE,QAAQ;gBACR,CAAC,QAAQ,KAAK,QAAQ,CAAC,QAAQ;oBAC7B,MAAM,CAAC,IAAI,GAAG,QAAQ,CAAC,YAAY;oBACnC,CAAC,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,YAAY;wBACpC,CAAC,MAAM,CAAC,OAAO,KAAK,QAAQ,CAAC,UAAU,IAAI,MAAM,CAAC,OAAO,KAAK,QAAQ,CAAC,SAAS,CAAC,CAAC;oBACpF,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAAK,QAAQ,CAAC,MAAM,CAAC,EACrD,CAAC;gBACD,MAAM,IAAI,kBAAkB,CAAC,wEAAwE,CAAC,CAAC;YACzG,CAAC;YACD,IAAI,gBAAgB,GAAG,MAAM,KAAK,CAAC,CAAC;YACpC,IAAI,CAAC,QAAQ,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC5B,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;gBAClC,MAAM,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,CAAC;gBAC/C,gBAAgB,GAAG,SAAS,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;YACzC,CAAC;YACD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CACvB,IAAI,CAAC,GAAG,CAAC,kBAAkB,GAAG,CAAC,CAAC,QAAQ,IAAI,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,IAAI,GAAG,MAAM,CAAC,CAAC,CACpG,CAAC;YACF,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YACtE,IAAI,aAAa,GAAG,CAAC,CAAC;YACtB,IAAI,QAAQ,GAAG,CAAC,CAAC;YACjB,IAAI,aAAiC,CAAC;YACtC,IAAI,kBAAkB,GAAG,CAAC,CAAC;YAC3B,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,MAAM,OAAO,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;gBAC5D,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;gBAC5D,IAAI,CAAC,gBAAgB,IAAI,OAAO,KAAK,CAAC,EAAE,CAAC;oBACvC,mEAAmE;oBACnE,qEAAqE;oBACrE,2DAA2D;oBAC3D,MAAM,GAAG,CAAC,CAAC;oBACX,aAAa,GAAG,2BAA2B,CAAC;gBAC9C,CAAC;qBAAM,CAAC;oBACN,aAAa,GAAG,WAAW,CAAC;oBAC5B,QAAQ,GAAG,WAAW,CAAC;oBACvB,OAAO,aAAa,GAAG,OAAO,EAAE,CAAC;wBAC/B,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,aAAa,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;wBACnF,IAAI,WAAW,GAAG,WAAW,GAAG,QAAQ,EAAE,CAAC;4BACzC,IAAI,aAAa,KAAK,WAAW,EAAE,CAAC;gCAClC,aAAa,GAAG,WAAW,CAAC;gCAC5B,QAAQ,GAAG,WAAW,CAAC;gCACvB,aAAa,GAAG,8BAA8B,CAAC;4BACjD,CAAC;4BACD,MAAM;wBACR,CAAC;wBACD,aAAa,GAAG,WAAW,CAAC;oBAC9B,CAAC;oBACD,IAAI,WAAW,GAAG,SAAS,IAAI,CAAC,aAAa;wBAAE,aAAa,GAAG,gBAAgB,CAAC;oBAChF,kEAAkE;oBAClE,6DAA6D;oBAC7D,IAAI,WAAW,GAAG,OAAO;wBAAE,aAAa,GAAG,QAAQ,GAAG,OAAO,CAAC;oBAC9D,kBAAkB,GAAG,MAAM,GAAG,aAAa,CAAC;gBAC9C,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,OAAO,QAAQ,GAAG,SAAS,EAAE,CAAC;oBAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;oBACvC,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;wBACZ,aAAa,GAAG,SAAS,KAAK,kBAAkB,CAAC,CAAC,CAAC,2BAA2B,CAAC,CAAC,CAAC,gBAAgB,CAAC;wBAClG,MAAM;oBACR,CAAC;oBACD,IAAI,GAAG,GAAG,CAAC,GAAG,QAAQ,EAAE,CAAC;wBACvB,IAAI,QAAQ,KAAK,CAAC;4BAAE,aAAa,GAAG,8BAA8B,CAAC;wBACnE,MAAM;oBACR,CAAC;oBACD,QAAQ,GAAG,GAAG,GAAG,CAAC,CAAC;gBACrB,CAAC;YACH,CAAC;YACD,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;YAC7D,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC;gBAAE,MAAM,IAAI,kBAAkB,CAAC,yCAAyC,CAAC,CAAC;YACpG,KAAK,MAAM,GAAG,IAAI,aAAa,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC1E,IAAI,CAAC;oBACH,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;gBAClB,CAAC;gBAAC,MAAM,CAAC;oBACP,MAAM,IAAI,kBAAkB,CAAC,0CAA0C,CAAC,CAAC;gBAC3E,CAAC;YACH,CAAC;YACD,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAClC,IACE,KAAK,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI;gBACxB,KAAK,CAAC,GAAG,KAAK,MAAM,CAAC,GAAG;gBACxB,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,KAAK,MAAM,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,KAAK,MAAM,CAAC,OAAO,CAAC,CAAC;gBAEtG,MAAM,IAAI,kBAAkB,CAAC,uCAAuC,CAAC,CAAC;YACxE,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC;YAC3D,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;YAC5B,wEAAwE;YACxE,sEAAsE;YACtE,gFAAgF;YAChF,iFAAiF;YACjF,gFAAgF;YAChF,qEAAqE;YACrE,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;YAC9D,MAAM,IAAI,GAAa,EAAE,CAAC;YAC1B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACxC,IAAI,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE;oBAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;qBACvD,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM;oBAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACnD,CAAC;YACD,OAAO,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ;gBAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAG,CAAC,CAAC;YACxE,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ;gBAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAM,CAAC,CAAC;YAClG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE;gBACvB,KAAK,EAAE,QAAQ;gBACf,MAAM;gBACN,IAAI;gBACJ,QAAQ;gBACR,MAAM,EAAE,MAAM,GAAG,QAAQ;gBACzB,YAAY,EAAE,MAAM,CAAC,IAAI;gBACzB,UAAU,EAAE,MAAM,CAAC,OAAO;gBAC1B,SAAS,EAAE,MAAM,CAAC,OAAO;gBACzB,MAAM,EAAE,UAAU;gBAClB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK;aACnC,CAAC,CAAC;YACH,OAAO;gBACL,QAAQ,EAAE,aAAa,CAAC,QAAQ,CAAC,MAAM,CAAC;gBACxC,MAAM;gBACN,kBAAkB;gBAClB,SAAS,EAAE,kBAAkB,GAAG,CAAC,IAAI,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC,IAAI;gBACpE,aAAa;gBACb,YAAY,EAAE,SAAS;aACxB,CAAC;QACJ,CAAC;gBAAS,CAAC;YACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;IACH,CAAC;IACD,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;CACF"}

package/dist/agent-staging.d.ts

@@ -0,0 +1,130 @@
+import type { CliEntry } from './config/cli-registry/types.js';
+/**
+ * The screen chrome a guarded composer read relies on, all from the CLI registry
+ * (`capabilities.workDetect`): the composer glyph, the pattern every row below an
+ * idle composer must match, and what opens a popup or turns Enter into a command.
+ * Nothing here names a CLI; a CLI takes part in guarded input by declaring
+ * `composerFooterLine`.
+ */
+export interface GuardedComposerChrome {
+    promptGlyph: string;
+    footerLine: RegExp;
+    /** A row of a suggestion popup drawn directly above the composer (`composerPopupLine`). */
+    popupLine?: RegExp;
+    /** First characters of a draft that make Enter run a command (`composerCommandPrefixes`). */
+    commandPrefixes?: string;
+    /** First characters of the word at the caret that open a completion popup (`composerCompletionSigils`). */
+    completionSigils?: string;
+}
+/** The chrome a registry entry declares, or null (no guarded input for that CLI). */
+export declare function guardedComposerChrome(entry: CliEntry | undefined): GuardedComposerChrome | null;
+/**
+ * Why a message cannot be staged into this composer, or null. Typing it would change
+ * what Enter does rather than what it sends: a draft starting with a command prefix
+ * (codex: `/` for a slash command, `!` for a shell command) is run, not sent as a
+ * prompt, and a last word starting with a completion sigil (codex: `@` file and
+ * mention search, `$` skills) opens a popup at the caret whose highlighted entry Enter
+ * would accept. Checked before anything is typed. Only the LAST word matters for the
+ * sigils because the caret is at the end of the message and the popup follows the
+ * caret; a sigil word earlier in the message opens nothing.
+ */
+export declare function composerTriggerRefusal(message: string, chrome: GuardedComposerChrome): string | null;
+export declare const STAGE_MAX_BYTES = 8192;
+export declare const promptSha256: (text: string) => string;
+export interface GuardedInputSnapshot {
+    generation: string;
+    revision: number;
+    composerSha: string;
+    /** Actual captured pane width minus the rendered composer prefix (including indentation). */
+    availableColumns: number;
+}
+export interface GuardedInputTarget {
+    id: string;
+    /** The session's composer chrome, read before typing for what a message would trigger. */
+    chrome(): GuardedComposerChrome | null;
+    snapshot(): GuardedInputSnapshot | null;
+    write(text: string): Promise<boolean>;
+    submit(expected: GuardedInputSnapshot): Promise<boolean>;
+}
+export declare class GuardedInputConflict extends Error {
+}
+/**
+ * How long stage keeps reading the pane after typing for a frame that shows the
+ * message, and how often. A capture taken right after the keys land is often a
+ * frame from before them: codex repaints its composer 30 to 60 ms after input
+ * arrives (measured on a live 0.162.0 pane), so the first read can show the old,
+ * empty composer, or nothing provable at all. A second of 50 ms reads covers that
+ * many times over and still answers the caller quickly.
+ */
+export declare const STAGE_SETTLE_TIMEOUT_MS = 1000;
+export declare const STAGE_SETTLE_INTERVAL_MS = 50;
+/**
+ * The least time between the staged keys and the conditional Enter. Stage types its
+ * text as plain keys (`send-keys -l`), which codex's paste-burst detector reads as a
+ * paste, and for 120 ms after such a burst codex turns Enter into a NEWLINE rather
+ * than a submit (`PASTE_ENTER_SUPPRESS_WINDOW`, codex-rs/tui/src/bottom_pane/
+ * paste_burst.rs at rust-v0.162.0). A caller that submits the moment stage answers
+ * would land inside it and be told one Enter was delivered while codex only broke
+ * the line. Submit waits out the rest of this window first; a keystroke in that
+ * time still invalidates the receipt.
+ */
+export declare const SUBMIT_QUIET_MS = 250;
+/** Settle-window overrides for tests: a fake clock comes from the store's `now`. */
+export interface StageSettleOptions {
+    timeoutMs?: number;
+    intervalMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Every refusal after the keys went out says so: stage cannot tell whether the text
+ * landed, so the caller must look before staging again (the recovery steps clear a
+ * stranded draft with Ctrl+U).
+ */
+export declare const MAY_BE_TYPED = "no receipt was issued. The message may already be in the composer: inspect the pane and follow the stranded-draft recovery steps (Ctrl+U) before staging again";
+/**
+ * Conservatively read a composer: exactly one visible, unwrapped row and a known
+ * footer, both as the registry describes them. Never remove internal spaces, infer
+ * an unknown shell prompt, or interpret dialog options as authority. An unsupported
+ * frame yields no proof.
+ */
+export declare function readGuardedComposer(screen: string, chrome: GuardedComposerChrome): string | null;
+/** Require the capture's caret at the exact end of the unwrapped composer. */
+export declare function readGuardedSnapshot(snapshot: string, chrome: GuardedComposerChrome): string | null;
+/** Exact input-row prefix width, shared by proof and preflight wrapping checks. */
+export declare function readGuardedSnapshotDetails(snapshot: string, chrome: GuardedComposerChrome): {
+    composer: string;
+    prefixWidth: number;
+} | null;
+export declare class GuardedStageStore {
+    private readonly now;
+    private readonly capacity;
+    private readonly ttlMs;
+    private readonly receipts;
+    private readonly busy;
+    private readonly settleTimeoutMs;
+    private readonly settleIntervalMs;
+    private readonly sleep;
+    constructor(now?: () => number, capacity?: number, ttlMs?: number, settle?: StageSettleOptions);
+    stage(target: GuardedInputTarget, owner: string, message: string): Promise<{
+        stageId: `${string}-${string}-${string}-${string}-${string}`;
+        sha256: string;
+        expiresAt: number;
+        sessionId: string;
+        submitted: false;
+    }>;
+    /**
+     * The first frame after the write that shows exactly this message, with the input
+     * revision the write itself moved and nothing else changed. A null or stale frame
+     * (the old composer, a half-painted one) is read again until the settle window
+     * ends; a frame showing another writer's keystroke, a new pane lifecycle or a new
+     * geometry is refused at once, since waiting cannot undo that.
+     */
+    private settle;
+    submit(target: GuardedInputTarget, owner: string, stageId: string, confirmSha: string): Promise<{
+        stageId: string;
+        sessionId: string;
+        submitted: true;
+    }>;
+    clear(): void;
+}
+//# sourceMappingURL=agent-staging.d.ts.map

package/dist/agent-staging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-staging.d.ts","sourceRoot":"","sources":["../src/agent-staging.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAE/D;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6FAA6F;IAC7F,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2GAA2G;IAC3G,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AACD,qFAAqF;AACrF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,qBAAqB,GAAG,IAAI,CAiB/F;AACD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,GAAG,MAAM,GAAG,IAAI,CAQpG;AAQD,eAAO,MAAM,eAAe,OAAO,CAAC;AACpC,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,MAAyD,CAAC;AACtG,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,6FAA6F;IAC7F,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AACD,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,0FAA0F;IAC1F,MAAM,IAAI,qBAAqB,GAAG,IAAI,CAAC;IACvC,QAAQ,IAAI,oBAAoB,GAAG,IAAI,CAAC;IACxC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,CAAC,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1D;AASD,qBAAa,oBAAqB,SAAQ,KAAK;CAAG;AAElD;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAC5C,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAC3C;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,oFAAoF;AACpF,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AACD;;;;GAIG;AACH,eAAO,MAAM,YAAY,mKACyI,CAAC;AAEnK;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,GAAG,MAAM,GAAG,IAAI,CAkChG;AAmBD,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,GAAG,MAAM,GAAG,IAAI,CAElG;AACD,mFAAmF;AACnF,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,qBAAqB,GAC5B;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA2BlD;AAED,qBAAa,iBAAiB;IAO1B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IARxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;IACvD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;gBAEnC,GAAG,eAAW,EACd,QAAQ,SAAO,EACf,KAAK,SAAS,EAC/B,MAAM,GAAE,kBAAuB;IAM3B,KAAK,CAAC,MAAM,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;;;;;;;IA6CtE;;;;;;OAMG;YACW,MAAM;IAuBd,MAAM,CAAC,MAAM,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;;;;;IA6B3F,KAAK,IAAI,IAAI;CAId"}

package/dist/agent-staging.js

@@ -0,0 +1,312 @@
+/**
+ * @fileoverview Short-lived, bounded guarded prompt receipts. No prompt content is
+ * retained: only caller/session identity, lifecycle/input revisions and SHA-256.
+ * A receipt is consumed synchronously before verification/delivery, including failures.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { stripAnsi } from './utils/regex-patterns.js';
+import { visibleWidth } from './tui/tui-ansi.js';
+import { compileVersionRegex } from './config/cli-registry/patterns.js';
+/** The chrome a registry entry declares, or null (no guarded input for that CLI). */
+export function guardedComposerChrome(entry) {
+    const detect = entry?.capabilities.workDetect;
+    if (!detect?.promptGlyph || !detect.composerFooterLine)
+        return null;
+    // Config-supplied (~/.codeman/clis.json): compiled through the ReDoS guard, null on refusal.
+    const footerLine = compileVersionRegex(detect.composerFooterLine);
+    if (!footerLine)
+        return null;
+    // A declared popup pattern the guard refuses is no chrome at all: dropping it would
+    // silently read a popup frame as an idle composer.
+    const popupLine = detect.composerPopupLine ? compileVersionRegex(detect.composerPopupLine) : undefined;
+    if (popupLine === null)
+        return null;
+    return {
+        promptGlyph: detect.promptGlyph,
+        footerLine,
+        ...(popupLine ? { popupLine } : {}),
+        ...(detect.composerCommandPrefixes ? { commandPrefixes: detect.composerCommandPrefixes } : {}),
+        ...(detect.composerCompletionSigils ? { completionSigils: detect.composerCompletionSigils } : {}),
+    };
+}
+/**
+ * Why a message cannot be staged into this composer, or null. Typing it would change
+ * what Enter does rather than what it sends: a draft starting with a command prefix
+ * (codex: `/` for a slash command, `!` for a shell command) is run, not sent as a
+ * prompt, and a last word starting with a completion sigil (codex: `@` file and
+ * mention search, `$` skills) opens a popup at the caret whose highlighted entry Enter
+ * would accept. Checked before anything is typed. Only the LAST word matters for the
+ * sigils because the caret is at the end of the message and the popup follows the
+ * caret; a sigil word earlier in the message opens nothing.
+ */
+export function composerTriggerRefusal(message, chrome) {
+    const first = message.trimStart().charAt(0);
+    if (first && chrome.commandPrefixes?.includes(first))
+        return `Stage refuses a message starting with "${first}": the CLI runs it as a command instead of sending it as a prompt. Send commands with \`codeman agent send\` (POST /api/v1/sessions/:id/input) instead`;
+    const last = message.split(/\s/).at(-1)?.charAt(0);
+    if (last && chrome.completionSigils?.includes(last))
+        return `Stage refuses a message whose last word starts with "${last}": it opens a completion popup at the caret and Enter would accept the highlighted entry instead of sending the message. End the message with another word, or use \`codeman agent send\``;
+    return null;
+}
+/** How many rows above the composer a popup check reads: the popup cap (8) plus header and hint rows. */
+const POPUP_WINDOW_ROWS = 12;
+/** Blank rows a popup can leave between itself and the composer row (the composer's own top padding, plus a popup's). */
+const POPUP_GAP_ROWS = 3;
+const escapeRegex = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const composerRow = (chrome) => new RegExp(String.raw `^\s*${escapeRegex(chrome.promptGlyph)}(?:\s|$)`);
+export const STAGE_MAX_BYTES = 8192;
+export const promptSha256 = (text) => createHash('sha256').update(text).digest('hex');
+export class GuardedInputConflict extends Error {
+}
+/**
+ * How long stage keeps reading the pane after typing for a frame that shows the
+ * message, and how often. A capture taken right after the keys land is often a
+ * frame from before them: codex repaints its composer 30 to 60 ms after input
+ * arrives (measured on a live 0.162.0 pane), so the first read can show the old,
+ * empty composer, or nothing provable at all. A second of 50 ms reads covers that
+ * many times over and still answers the caller quickly.
+ */
+export const STAGE_SETTLE_TIMEOUT_MS = 1000;
+export const STAGE_SETTLE_INTERVAL_MS = 50;
+/**
+ * The least time between the staged keys and the conditional Enter. Stage types its
+ * text as plain keys (`send-keys -l`), which codex's paste-burst detector reads as a
+ * paste, and for 120 ms after such a burst codex turns Enter into a NEWLINE rather
+ * than a submit (`PASTE_ENTER_SUPPRESS_WINDOW`, codex-rs/tui/src/bottom_pane/
+ * paste_burst.rs at rust-v0.162.0). A caller that submits the moment stage answers
+ * would land inside it and be told one Enter was delivered while codex only broke
+ * the line. Submit waits out the rest of this window first; a keystroke in that
+ * time still invalidates the receipt.
+ */
+export const SUBMIT_QUIET_MS = 250;
+/**
+ * Every refusal after the keys went out says so: stage cannot tell whether the text
+ * landed, so the caller must look before staging again (the recovery steps clear a
+ * stranded draft with Ctrl+U).
+ */
+export const MAY_BE_TYPED = 'no receipt was issued. The message may already be in the composer: inspect the pane and follow the stranded-draft recovery steps (Ctrl+U) before staging again';
+/**
+ * Conservatively read a composer: exactly one visible, unwrapped row and a known
+ * footer, both as the registry describes them. Never remove internal spaces, infer
+ * an unknown shell prompt, or interpret dialog options as authority. An unsupported
+ * frame yields no proof.
+ */
+export function readGuardedComposer(screen, chrome) {
+    const isComposer = composerRow(chrome);
+    const lines = stripAnsi(screen)
+        .split('\n')
+        .map((line) => line.trimEnd());
+    const rows = lines.map((line, index) => ({ line, index })).filter((row) => isComposer.test(row.line));
+    const last = rows.at(-1);
+    if (!last)
+        return null;
+    const below = lines.slice(last.index + 1).filter((line) => line.trim());
+    if (below.length === 0 || below.length > 3 || below.some((line) => !chrome.footerLine.test(line)))
+        return null;
+    if (chrome.popupLine && popupAbove(lines, last.index, chrome.popupLine))
+        return null;
+    // Preserve exact printable content; only SGR-dim placeholder/suggestion text is excluded.
+    const raw = screen.split('\n')[last.index];
+    let dim = false;
+    let visible = '';
+    // eslint-disable-next-line no-control-regex
+    for (const token of raw.split(/(\x1b\[[0-9;]*m)/)) {
+        // eslint-disable-next-line no-control-regex
+        if (/^\x1b\[/.test(token)) {
+            const codes = token.slice(2, -1).split(';').map(Number);
+            for (let i = 0; i < codes.length; i++) {
+                // Extended color payloads may contain 0, 2 or 22; those are not SGR modes.
+                if (codes[i] === 38 || codes[i] === 48 || codes[i] === 58) {
+                    i += codes[i + 1] === 2 ? 4 : codes[i + 1] === 5 ? 2 : 0;
+                }
+                else if (codes[i] === 0 || codes[i] === 22)
+                    dim = false;
+                else if (codes[i] === 2)
+                    dim = true;
+            }
+        }
+        else if (!dim)
+            visible += token;
+    }
+    // The glyph and the one space after it are the prefix, not input.
+    return stripAnsi(visible)
+        .trimStart()
+        .slice(chrome.promptGlyph.length + 1)
+        .trimEnd();
+}
+/**
+ * Does a suggestion popup sit directly above the composer row? A popup draws over
+ * the rows above the composer and leaves the footer below it alone, so the footer
+ * check alone reads a popup frame as an idle composer. Read the contiguous block of
+ * rows just above (past at most `POPUP_GAP_ROWS` blank rows), never the whole pane:
+ * the transcript further up is the agent's own and may print anything. A transcript
+ * row that happens to match costs a refusal, never a receipt.
+ */
+function popupAbove(lines, composerIndex, popupLine) {
+    let index = composerIndex - 1;
+    for (let gap = 0; gap < POPUP_GAP_ROWS && index >= 0 && !lines[index].trim(); gap++)
+        index--;
+    for (let seen = 0; seen < POPUP_WINDOW_ROWS && index >= 0 && lines[index].trim(); seen++, index--) {
+        if (popupLine.test(lines[index]))
+            return true;
+    }
+    return false;
+}
+/** Require the capture's caret at the exact end of the unwrapped composer. */
+export function readGuardedSnapshot(snapshot, chrome) {
+    return readGuardedSnapshotDetails(snapshot, chrome)?.composer ?? null;
+}
+/** Exact input-row prefix width, shared by proof and preflight wrapping checks. */
+export function readGuardedSnapshotDetails(snapshot, chrome) {
+    // formatPaneSnapshot emits one absolute row address per line, then the caret.
+    // Plain captures lack caret evidence and cannot prove invisible trailing edits.
+    // eslint-disable-next-line no-control-regex
+    const positions = [...snapshot.matchAll(/\x1b\[(\d+);(\d+)H/g)];
+    if (positions.length < 2)
+        return null;
+    const caret = positions.at(-1);
+    if (caret.index + caret[0].length !== snapshot.length)
+        return null;
+    const rows = [];
+    for (let i = 0; i < positions.length - 1; i++) {
+        const position = positions[i];
+        if (Number(position[1]) !== i + 1 || position[2] !== '1')
+            return null;
+        rows.push(snapshot.slice(position.index + position[0].length, positions[i + 1].index));
+    }
+    const composer = readGuardedComposer(rows.join('\n'), chrome);
+    if (composer === null)
+        return null;
+    const isComposer = composerRow(chrome);
+    let row = -1;
+    for (let i = rows.length - 1; i >= 0; i--)
+        if (isComposer.test(stripAnsi(rows[i]))) {
+            row = i;
+            break;
+        }
+    const prefix = stripAnsi(rows[row]).match(new RegExp(String.raw `^(\s*${escapeRegex(chrome.promptGlyph)}[ \u00a0])`));
+    if (!prefix || Number(caret[1]) !== row + 1 || Number(caret[2]) !== visibleWidth(prefix[1] + composer) + 1)
+        return null;
+    return { composer, prefixWidth: visibleWidth(prefix[1]) };
+}
+export class GuardedStageStore {
+    now;
+    capacity;
+    ttlMs;
+    receipts = new Map();
+    busy = new Set();
+    settleTimeoutMs;
+    settleIntervalMs;
+    sleep;
+    constructor(now = Date.now, capacity = 1024, ttlMs = 120000, settle = {}) {
+        this.now = now;
+        this.capacity = capacity;
+        this.ttlMs = ttlMs;
+        this.settleTimeoutMs = settle.timeoutMs ?? STAGE_SETTLE_TIMEOUT_MS;
+        this.settleIntervalMs = settle.intervalMs ?? STAGE_SETTLE_INTERVAL_MS;
+        this.sleep = settle.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    }
+    async stage(target, owner, message) {
+        // eslint-disable-next-line no-control-regex
+        const hasControls = /[\x00-\x1f\x7f-\x9f]/.test(message);
+        if (!message ||
+            message !== message.trimEnd() ||
+            Buffer.byteLength(message) > STAGE_MAX_BYTES ||
+            Buffer.from(message).toString('utf8') !== message ||
+            hasControls)
+            throw new GuardedInputConflict('Stage requires printable single-line input within 8192 UTF8 bytes, without trailing whitespace');
+        const chrome = target.chrome();
+        const refusal = chrome && composerTriggerRefusal(message, chrome);
+        if (refusal)
+            throw new GuardedInputConflict(refusal);
+        const key = target.id;
+        if (this.busy.has(key))
+            throw new GuardedInputConflict('Another guarded input operation is in progress');
+        this.busy.add(key);
+        try {
+            const before = target.snapshot();
+            if (!before || before.composerSha !== promptSha256(''))
+                throw new GuardedInputConflict('An empty, verifiable composer is required');
+            if (!Number.isFinite(before.availableColumns) || visibleWidth(message) >= before.availableColumns)
+                throw new GuardedInputConflict('Message would reach the pane edge or wrap; shorten it or widen the pane');
+            for (const [id, receipt] of this.receipts)
+                if (receipt.expiresAt <= this.now() || receipt.sessionId === target.id)
+                    this.receipts.delete(id);
+            // Refuse capacity before typing. Do not evict a caller's still-live receipt.
+            // Include in-flight stages (this operation already owns one busy slot),
+            // so different sessions cannot type concurrently into the same last slot.
+            if (this.receipts.size + this.busy.size > this.capacity)
+                throw new GuardedInputConflict('Guarded stage receipt capacity reached');
+            if (!(await target.write(message)))
+                throw new GuardedInputConflict(`Staging delivery failed or ambiguous; ${MAY_BE_TYPED}`);
+            const typedAt = this.now();
+            const after = await this.settle(target, before, promptSha256(message));
+            const stageId = randomUUID();
+            const expiresAt = this.now() + this.ttlMs;
+            const sha256 = promptSha256(message);
+            this.receipts.set(stageId, { ...after, owner, sessionId: target.id, expiresAt, sha256, typedAt });
+            return { stageId, sha256, expiresAt, sessionId: target.id, submitted: false };
+        }
+        finally {
+            this.busy.delete(key);
+        }
+    }
+    /**
+     * The first frame after the write that shows exactly this message, with the input
+     * revision the write itself moved and nothing else changed. A null or stale frame
+     * (the old composer, a half-painted one) is read again until the settle window
+     * ends; a frame showing another writer's keystroke, a new pane lifecycle or a new
+     * geometry is refused at once, since waiting cannot undo that.
+     */
+    async settle(target, before, expectedSha) {
+        const deadline = this.now() + this.settleTimeoutMs;
+        for (;;) {
+            const frame = target.snapshot();
+            if (frame &&
+                (frame.generation !== before.generation ||
+                    frame.revision !== before.revision + 1 ||
+                    frame.availableColumns !== before.availableColumns))
+                throw new GuardedInputConflict(`Input or pane changed while staging; ${MAY_BE_TYPED}`);
+            if (frame?.composerSha === expectedSha)
+                return frame;
+            if (this.now() >= deadline)
+                throw new GuardedInputConflict(`The composer did not show the staged message within ${this.settleTimeoutMs} ms; ${MAY_BE_TYPED}`);
+            await this.sleep(this.settleIntervalMs);
+        }
+    }
+    async submit(target, owner, stageId, confirmSha) {
+        const receipt = this.receipts.get(stageId);
+        if (!receipt || receipt.owner !== owner || receipt.sessionId !== target.id)
+            throw new GuardedInputConflict('Unknown, used, or foreign stage receipt');
+        // One shot, even a wrong hash or unprovable composer. No retry of ambiguous Enter.
+        this.receipts.delete(stageId);
+        if (this.busy.has(target.id))
+            throw new GuardedInputConflict('Another guarded input operation is in progress');
+        this.busy.add(target.id);
+        try {
+            if (receipt.expiresAt <= this.now() || receipt.sha256 !== confirmSha)
+                throw new GuardedInputConflict('Expired stage receipt or confirmation hash mismatch');
+            const quiet = receipt.typedAt + SUBMIT_QUIET_MS - this.now();
+            if (quiet > 0)
+                await this.sleep(quiet);
+            const current = target.snapshot();
+            if (!current ||
+                current.generation !== receipt.generation ||
+                current.revision !== receipt.revision ||
+                current.availableColumns !== receipt.availableColumns ||
+                current.composerSha !== receipt.sha256)
+                throw new GuardedInputConflict('Staged composer, input, or pane identity changed; nothing submitted');
+            if (!(await target.submit(current)))
+                throw new GuardedInputConflict('Submission delivery failed or ambiguous; receipt consumed, inspect the pane');
+            return { stageId, sessionId: target.id, submitted: true };
+        }
+        finally {
+            this.busy.delete(target.id);
+        }
+    }
+    clear() {
+        this.receipts.clear();
+        this.busy.clear();
+    }
+}
+//# sourceMappingURL=agent-staging.js.map