@sema-agent/client-core 0.104.0 → 0.105.0

package/dist/planReviewCardFacts.js

@@ -0,0 +1,469 @@
+import { displayUntrusted, displayUntrustedMarks, DISPLAY_DECISION_BODY } from './displayUntrusted.js';
+import { readRunTerminal, runTerminalGateKind } from './runTerminal.js';
+import { SDK_PLAN_REVIEW_GATE_KINDS } from './generated/sdkFactTables.js';
+import { CORE_PRESENT_PLAN_TOOL_NAME } from './generated/engineFactTables.js';
+import { DEFAULT_SESSION_KEY } from './sessionSlot.js';
+const PLAN_BODY_MAX_LENGTH = 200_000;
+const PLAN_BODY_UNKNOWN_CAUSES = Object.freeze([
+    'not_observed', 'gate_unidentified', 'gate_moved', 'unreadable', 'ambiguous_call', 'malformed_frame', 'conflicting_claims', 'not_presented', 'not_carried',
+]);
+const TEMPORARY_CAUSES = new Set(['unreadable', 'gate_moved', 'not_observed', 'gate_unidentified']);
+const BODY_JUDGE_READING = Object.freeze({ ...DISPLAY_DECISION_BODY, credentialUrls: false, credentialWords: false });
+export function planReviewBodyOf(text) {
+    try {
+        if (typeof text !== 'string')
+            return Object.freeze({ kind: 'marked', literal: '' });
+        if (text.length > PLAN_BODY_MAX_LENGTH)
+            return Object.freeze({ kind: 'too_large', length: text.length });
+        const laidOut = text.split('\r\n').join('\n');
+        if (displayUntrustedMarks(laidOut, BODY_JUDGE_READING).marks.length > 0) {
+            return Object.freeze({ kind: 'marked', literal: displayUntrusted(laidOut, { ...DISPLAY_DECISION_BODY, escapeBackslashes: true }) });
+        }
+        return Object.freeze({ kind: 'shown', markdown: laidOut });
+    }
+    catch {
+        return Object.freeze({ kind: 'marked', literal: '' });
+    }
+}
+export function mintPlanReviewCardFacts(taskId, checkpointId, body) {
+    const b = checkpointId === undefined ? unknownBody('gate_unidentified') : body;
+    return Object.freeze({ taskId, ...(checkpointId !== undefined ? { checkpointId } : {}), body: Object.isFrozen(b) ? b : Object.freeze({ ...b }) });
+}
+export function unknownBody(cause) {
+    return Object.freeze({ kind: 'unknown', cause });
+}
+function ownData(v, key) {
+    if (typeof v !== 'object' || v === null)
+        return { present: false };
+    const d = Object.getOwnPropertyDescriptor(v, key);
+    if (d === undefined)
+        return { present: false };
+    if (!Object.hasOwn(d, 'value'))
+        return { present: true };
+    return { present: true, value: d.value };
+}
+const nonEmpty = (v) => typeof v === 'string' && v.length > 0;
+export function planReviewCardFactsFrom(v) {
+    try {
+        if (typeof v !== 'object' || v === null || Array.isArray(v))
+            return undefined;
+        const taskId = ownData(v, 'taskId').value;
+        if (!nonEmpty(taskId))
+            return undefined;
+        const ck = ownData(v, 'checkpointId');
+        if (ck.present && !nonEmpty(ck.value))
+            return undefined;
+        const body = readBody(ownData(v, 'body').value);
+        if (body === undefined)
+            return undefined;
+        const checkpointId = ck.present ? ck.value : undefined;
+        if (checkpointId === undefined && !(body.kind === 'unknown' && body.cause === 'gate_unidentified'))
+            return undefined;
+        return mintPlanReviewCardFacts(taskId, checkpointId, body);
+    }
+    catch {
+        return undefined;
+    }
+}
+function readBody(v) {
+    if (typeof v !== 'object' || v === null || Array.isArray(v))
+        return undefined;
+    const kind = ownData(v, 'kind').value;
+    if (kind === 'shown') {
+        const markdown = ownData(v, 'markdown').value;
+        return typeof markdown === 'string' ? Object.freeze({ kind, markdown }) : undefined;
+    }
+    if (kind === 'marked') {
+        const literal = ownData(v, 'literal').value;
+        return typeof literal === 'string' ? Object.freeze({ kind, literal }) : undefined;
+    }
+    if (kind === 'too_large') {
+        const length = ownData(v, 'length').value;
+        return typeof length === 'number' && Number.isInteger(length) && length > PLAN_BODY_MAX_LENGTH ? Object.freeze({ kind, length }) : undefined;
+    }
+    if (kind === 'unknown') {
+        const cause = ownData(v, 'cause').value;
+        return typeof cause === 'string' && PLAN_BODY_UNKNOWN_CAUSES.includes(cause) ? unknownBody(cause) : undefined;
+    }
+    return undefined;
+}
+export function samePlanReviewCardFacts(a, b) {
+    if (a === b)
+        return true;
+    if (a.taskId !== b.taskId || a.checkpointId !== b.checkpointId || a.body.kind !== b.body.kind)
+        return false;
+    const x = a.body;
+    const y = b.body;
+    return x.markdown === y.markdown && x.literal === y.literal && x.length === y.length && x.cause === y.cause;
+}
+function isPlanGateKind(kind) {
+    return typeof kind === 'string' && SDK_PLAN_REVIEW_GATE_KINDS.includes(kind);
+}
+export function isPlanReviewPark(result) {
+    const read = readRunTerminal(result);
+    if (read === null || read.kind !== 'paused')
+        return false;
+    if (!isPlanGateKind(runTerminalGateKind(read)))
+        return false;
+    const taskId = result?.taskId;
+    return typeof taskId === 'string' && taskId.length > 0;
+}
+export function pausedCheckpointIdOf(carrier) {
+    try {
+        const read = readRunTerminal(carrier);
+        if (read === null || read.kind !== 'paused')
+            return undefined;
+        const id = read.checkpointId;
+        return typeof id === 'string' && id.length > 0 ? id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const SETTLED_CALLS_MAX = 10_000;
+const PLAN_REVIEW_RUNS_MAX = 64;
+const planReviewRuns = new Map();
+const runKey = (sessionKey, taskId) => `${sessionKey}\u0000${taskId}`;
+function emptyWindow() {
+    return { presented: [], malformed: false, ambiguous: false, unreadable: false };
+}
+function recordFor(sessionKey, taskId) {
+    const key = runKey(sessionKey, taskId);
+    let rec = planReviewRuns.get(key);
+    if (rec !== undefined) {
+        planReviewRuns.delete(key);
+    }
+    else {
+        rec = { open: new Set(), settled: new Set(), window: emptyWindow(), sawPlanFrame: false, dirty: false, generation: 0, cardIssued: false };
+    }
+    planReviewRuns.set(key, rec);
+    while (planReviewRuns.size > PLAN_REVIEW_RUNS_MAX) {
+        const oldest = planReviewRuns.keys().next();
+        if (oldest.done === true)
+            break;
+        planReviewRuns.delete(oldest.value);
+    }
+    return rec;
+}
+export function _resetPlanReviewRunsForTest() {
+    planReviewRuns.clear();
+}
+export function beginPlanReviewFactsRead(sessionKey, taskId) {
+    const rec = recordFor(sessionKey, taskId);
+    rec.generation += 1;
+    return { sessionKey, taskId, generation: rec.generation };
+}
+export function commitPlanReviewFacts(ticket, facts, claim, highWater) {
+    const rec = planReviewRuns.get(runKey(ticket.sessionKey, ticket.taskId));
+    if (rec === undefined || rec.generation !== ticket.generation)
+        return undefined;
+    const checkpointId = facts.checkpointId;
+    if (checkpointId === undefined)
+        return facts;
+    if (facts.body.kind === 'unknown' && TEMPORARY_CAUSES.has(facts.body.cause))
+        return facts;
+    const prev = rec.gate;
+    let out = facts;
+    if (prev !== undefined && prev.checkpointId === checkpointId && (isConflict(prev.facts) || !samePlanClaim(prev.claim, claim))) {
+        out = mintPlanReviewCardFacts(facts.taskId, checkpointId, unknownBody('conflicting_claims'));
+    }
+    rec.gate = { checkpointId, facts: out, claim, generation: ticket.generation, ...(highWater !== undefined ? { highWater } : {}) };
+    return out;
+}
+function isConflict(facts) {
+    return facts.body.kind === 'unknown' && facts.body.cause === 'conflicting_claims';
+}
+export function samePlanClaim(a, b) {
+    if (a.kind === 'text' && b.kind === 'text')
+        return a.text === b.text;
+    if (a.kind === 'cause' && b.kind === 'cause')
+        return a.cause === b.cause;
+    return false;
+}
+export function registeredPlanReviewCardFacts(sessionKey, taskId, checkpointId) {
+    const gate = currentPlanReviewGateOf(sessionKey, taskId);
+    return gate !== undefined && gate.checkpointId === checkpointId ? gate.facts : undefined;
+}
+export function currentPlanReviewGateOf(sessionKey, taskId) {
+    const rec = planReviewRuns.get(runKey(sessionKey, taskId));
+    const gate = rec?.gate;
+    return rec !== undefined && gate !== undefined && gate.generation === rec.generation
+        ? { checkpointId: gate.checkpointId, facts: gate.facts, generation: gate.generation }
+        : undefined;
+}
+export function planReviewRunGeneration(sessionKey, taskId) {
+    return recordFor(sessionKey, taskId).generation;
+}
+export function notePlanReviewCardIssued(sessionKey, taskId) {
+    const rec = recordFor(sessionKey, taskId);
+    const before = rec.cardIssued;
+    rec.cardIssued = true;
+    return before;
+}
+export function planReviewGateHighWaterOf(sessionKey, taskId, checkpointId) {
+    const gate = planReviewRuns.get(runKey(sessionKey, taskId))?.gate;
+    return gate !== undefined && gate.checkpointId === checkpointId ? gate.highWater : undefined;
+}
+function claimOf(rec) {
+    const w = rec.window;
+    if (w.unreadable)
+        return { kind: 'cause', cause: 'unreadable' };
+    if (w.malformed)
+        return { kind: 'cause', cause: 'malformed_frame' };
+    if (rec.open.size > 0 || w.ambiguous || w.presented.length > 1)
+        return { kind: 'cause', cause: 'ambiguous_call' };
+    const only = w.presented[0];
+    if (only === undefined)
+        return { kind: 'cause', cause: rec.sawPlanFrame ? 'not_presented' : 'not_observed' };
+    return only.plan === undefined ? { kind: 'cause', cause: 'not_carried' } : { kind: 'text', text: only.plan };
+}
+function planMarker(rec, gate) {
+    if (!rec.dirty && rec.claimAtMarker !== undefined && (gate === undefined || rec.claimGate === undefined || rec.claimGate === gate)) {
+        if (gate !== undefined)
+            rec.claimGate = gate;
+        return rec.claimAtMarker;
+    }
+    const claim = claimOf(rec);
+    rec.claimAtMarker = claim;
+    rec.claimGate = gate;
+    rec.dirty = false;
+    rec.window = emptyWindow();
+    return claim;
+}
+function otherMarker(rec) {
+    rec.claimAtMarker = undefined;
+    rec.claimGate = undefined;
+    rec.dirty = false;
+    rec.window = emptyWindow();
+}
+function settle(rec, id) {
+    rec.settled.add(id);
+    while (rec.settled.size > SETTLED_CALLS_MAX) {
+        const oldest = rec.settled.values().next();
+        if (oldest.done === true)
+            break;
+        rec.settled.delete(oldest.value);
+    }
+}
+function classOf(frame) {
+    const type = ownData(frame, 'type').value;
+    if (type === 'tool_start' || type === 'tool_end')
+        return ownData(frame, 'toolName').value === CORE_PRESENT_PLAN_TOOL_NAME ? 'plan_call' : 'other';
+    if (type === 'needs_review' || type === 'suspended')
+        return 'marker';
+    if (type === 'done')
+        return 'done';
+    if (type === 'meta')
+        return 'meta';
+    return 'other';
+}
+function foldPlanCall(rec, frame) {
+    rec.sawPlanFrame = true;
+    const id = ownData(frame, 'toolCallId').value;
+    if (!nonEmpty(id)) {
+        rec.window.malformed = true;
+        rec.dirty = true;
+        return;
+    }
+    if (rec.settled.has(id))
+        return;
+    rec.dirty = true;
+    if (ownData(frame, 'type').value === 'tool_start') {
+        if (ownData(frame, 'recovered').value === true)
+            rec.window.ambiguous = true;
+        rec.open.add(id);
+        return;
+    }
+    const started = rec.open.delete(id);
+    settle(rec, id);
+    if (!started) {
+        rec.window.ambiguous = true;
+        return;
+    }
+    if (ownData(frame, 'isError').value !== false || ownData(frame, 'notExecuted').value === true)
+        return;
+    const s = ownData(frame, 'structured');
+    if (!s.present || s.value === undefined) {
+        rec.window.presented.push({});
+        return;
+    }
+    const sv = s.value;
+    if (typeof sv !== 'object' || sv === null || Array.isArray(sv) || ownData(sv, 'type').value !== 'exit-plan-mode') {
+        rec.window.malformed = true;
+        return;
+    }
+    const plan = ownData(sv, 'plan').value;
+    if (typeof plan !== 'string') {
+        rec.window.malformed = true;
+        return;
+    }
+    rec.window.presented.push({ plan });
+}
+function markerGateOf(frame) {
+    const v = ownData(frame, 'checkpointId').value;
+    return nonEmpty(v) ? v : undefined;
+}
+function foldMarker(rec, frame) {
+    const type = ownData(frame, 'type').value;
+    const gate = ownData(frame, 'gate');
+    if (type === 'needs_review') {
+        if (!gate.present || (gate.value !== null && (typeof gate.value !== 'object' || Array.isArray(gate.value)))) {
+            rec.window.malformed = true;
+            rec.dirty = true;
+            planMarker(rec);
+            return;
+        }
+        if (gate.value === null) {
+            planMarker(rec, markerGateOf(frame));
+            return;
+        }
+        const kind = ownData(gate.value, 'kind').value;
+        if (typeof kind !== 'string') {
+            rec.window.malformed = true;
+            rec.dirty = true;
+            planMarker(rec);
+            return;
+        }
+        if (isPlanGateKind(kind))
+            planMarker(rec, markerGateOf(frame));
+        else
+            otherMarker(rec);
+        return;
+    }
+    const kind = gate.present && typeof gate.value === 'object' && gate.value !== null ? ownData(gate.value, 'kind').value : undefined;
+    if (isPlanGateKind(kind))
+        planMarker(rec, markerGateOf(frame));
+    else
+        otherMarker(rec);
+}
+const LEG_BUFFER_MAX = 256;
+export function openPlanBodyClaimLeg() {
+    return { buffer: [], overflow: false, unreadable: false };
+}
+function bindLeg(leg, taskId) {
+    const rec = recordFor(DEFAULT_SESSION_KEY, taskId);
+    if (leg.taskId === taskId)
+        return rec;
+    const pending = leg.buffer.splice(0);
+    const lost = leg.overflow || leg.unreadable;
+    leg.taskId = taskId;
+    leg.overflow = false;
+    leg.unreadable = false;
+    if (lost) {
+        rec.window.unreadable = true;
+        rec.dirty = true;
+    }
+    for (const p of pending)
+        foldInto(rec, p.frame, p.subFlow);
+    return rec;
+}
+function foldInto(rec, frame, subFlow) {
+    try {
+        const c = classOf(frame);
+        if (c === 'plan_call') {
+            if (!subFlow)
+                foldPlanCall(rec, frame);
+        }
+        else if (c === 'marker') {
+            if (!subFlow)
+                foldMarker(rec, frame);
+        }
+    }
+    catch {
+        rec.window.unreadable = true;
+        rec.dirty = true;
+    }
+}
+export function stepPlanBodyClaim(leg, frame, subFlow) {
+    try {
+        const c = classOf(frame);
+        if (c === 'meta') {
+            const taskId = ownData(frame, 'taskId').value;
+            if (nonEmpty(taskId))
+                bindLeg(leg, taskId);
+            return;
+        }
+        if (c !== 'plan_call' && c !== 'marker')
+            return;
+        if (leg.taskId === undefined) {
+            if (leg.buffer.length >= LEG_BUFFER_MAX)
+                leg.overflow = true;
+            else
+                leg.buffer.push({ frame, subFlow });
+            return;
+        }
+        foldInto(recordFor(DEFAULT_SESSION_KEY, leg.taskId), frame, subFlow);
+    }
+    catch {
+        leg.unreadable = true;
+        if (leg.taskId !== undefined) {
+            const rec = recordFor(DEFAULT_SESSION_KEY, leg.taskId);
+            rec.window.unreadable = true;
+            rec.dirty = true;
+        }
+    }
+}
+export function planReviewParkFacts(leg, result) {
+    let taskId;
+    let checkpointId;
+    try {
+        if (!isPlanReviewPark(result)) {
+            const read = readRunTerminal(result);
+            const tid = ownData(result, 'taskId').value;
+            if (read !== null && read.kind === 'paused' && nonEmpty(tid))
+                otherMarker(legRecord(leg, tid));
+            return undefined;
+        }
+        taskId = result.taskId;
+        checkpointId = pausedCheckpointIdOf(result);
+        const claim = planMarker(legRecord(leg, taskId), checkpointId);
+        const body = claim.kind === 'text' ? planReviewBodyOf(claim.text) : unknownBody(claim.cause);
+        const ticket = beginPlanReviewFactsRead(DEFAULT_SESSION_KEY, taskId);
+        return commitPlanReviewFacts(ticket, mintPlanReviewCardFacts(taskId, checkpointId, body), claim);
+    }
+    catch {
+        return taskId === undefined ? undefined : mintPlanReviewCardFacts(taskId, checkpointId, unknownBody('unreadable'));
+    }
+}
+function legRecord(leg, taskId) {
+    return leg.taskId === undefined || leg.taskId === taskId ? bindLeg(leg, taskId) : recordFor(DEFAULT_SESSION_KEY, taskId);
+}
+export function planReviewFactsCurrent(taken) {
+    const rec = planReviewRuns.get(runKey(taken.sessionKey, taken.taskId));
+    return rec !== undefined && rec.generation === taken.generation;
+}
+export function planGateRowReadOf(row) {
+    try {
+        const result = ownData(row, 'result').value;
+        const read = readRunTerminal(result);
+        const atPlanGate = read !== null && read.kind === 'paused' && isPlanGateKind(runTerminalGateKind(read));
+        const checkpointId = pausedCheckpointIdOf(result);
+        return { ok: true, atPlanGate, ...(checkpointId !== undefined ? { checkpointId } : {}) };
+    }
+    catch {
+        return { ok: false, atPlanGate: false };
+    }
+}
+export function openPlanReviewLedgerFold() {
+    return { open: new Set(), settled: new Set(), window: emptyWindow(), sawPlanFrame: true, dirty: false, generation: 0, cardIssued: false };
+}
+export function stepPlanReviewLedgerFold(fold, frame, subFlow) {
+    if (typeof frame === 'object' && frame !== null)
+        foldInto(fold, frame, subFlow);
+    return fold;
+}
+export function planReviewLedgerClaimOf(fold) {
+    return fold.dirty ? undefined : fold.claimAtMarker;
+}
+export function isPlanReviewClaimFrame(frame) {
+    if (typeof frame !== 'object' || frame === null)
+        return false;
+    let c;
+    try {
+        c = classOf(frame);
+    }
+    catch {
+        c = 'unreadable';
+    }
+    return c === 'plan_call' || c === 'marker' || c === 'unreadable';
+}

package/dist/reattachWindow.d.ts

@@ -1,3 +1,4 @@
+import { type ReattachBreak, type RunNotFollowed } from './runFollow.js';
 export declare const REATTACH_WINDOW_MS = 300000;
 export declare const REATTACH_BACKOFF_START_MS = 1000;
 export declare const REATTACH_BACKOFF_CAP_MS = 30000;
@@ -25,8 +26,10 @@ export interface ReattachWindowState {
     readonly consecutiveNotFound: number;
     readonly notFoundConfirmed: boolean;
     readonly tuning: Readonly<Tuned>;
+    readonly runId?: string;
+    readonly lastBreak?: ReattachBreak;
 }
-export declare function reattachWindowOpen(nowMs: number, tuning?: ReattachWindowTuning): ReattachWindowState;
+export declare function reattachWindowOpen(nowMs: number, tuning?: ReattachWindowTuning, runId?: string): ReattachWindowState;
 export type ReattachProbeResult = 'readable' | 'unreachable' | 'not-found';
 export type ReattachWindowEvent = {
     readonly type: 'attempt';
@@ -40,6 +43,8 @@ export type ReattachWindowEvent = {
 } | {
     readonly type: 'backoff';
     readonly serverRetryAfterMs?: number;
+    readonly break?: ReattachBreak;
+    readonly runId?: string;
 } | {
     readonly type: 'new-segment';
 };
@@ -51,9 +56,11 @@ export type ReattachWindowDecision = {
     readonly afterMs: number;
 } | {
     readonly action: 'window-exhausted';
+    readonly notFollowed: RunNotFollowed<'reattach_exhausted' | 'bad_input'>;
 } | {
     readonly action: 'run-unknown';
     readonly confirmations: number;
+    readonly notFollowed: RunNotFollowed<'run_unknown'>;
 };
 export interface ReattachWindowStep {
     readonly state: ReattachWindowState;

package/dist/reattachWindow.js

@@ -1,5 +1,6 @@
 import { usableClockMs } from './clockReading.js';
 import { readThrownSlot, THROWN_SLOT_UNREADABLE } from './wireFailureShape.js';
+import { isReattachBreak, mintRunNotFollowed } from './runFollow.js';
 export const REATTACH_WINDOW_MS = 300_000;
 export const REATTACH_BACKOFF_START_MS = 1_000;
 export const REATTACH_BACKOFF_CAP_MS = 30_000;
@@ -25,15 +26,37 @@ export function reattachBackoffMs(attempt, tuning) {
     const raw = startMs * 2 ** (attempt - 1);
     return Number.isFinite(raw) ? Math.min(raw, capMs) : capMs;
 }
-export function reattachWindowOpen(nowMs, tuning) {
+const isRunHandle = (v) => typeof v === 'string' && v !== '';
+export function reattachWindowOpen(nowMs, tuning, runId) {
     const t = tuned(tuning);
     const start = usableClockMs(nowMs) ?? Number.NaN;
-    return Object.freeze({ enteredAtMs: start, deadlineMs: start + t.windowMs, attempt: 0, consecutiveNotFound: 0, notFoundConfirmed: false, tuning: Object.freeze(t) });
+    return Object.freeze({
+        enteredAtMs: start,
+        deadlineMs: start + t.windowMs,
+        attempt: 0,
+        consecutiveNotFound: 0,
+        notFoundConfirmed: false,
+        tuning: Object.freeze(t),
+        ...(isRunHandle(runId) ? { runId } : {}),
+    });
 }
 const step = (state, decision) => Object.freeze({ state, decision });
-const exhausted = (state) => step(state, Object.freeze({ action: 'window-exhausted' }));
+const runOf = (state) => {
+    const v = readThrownSlot(state, 'runId', 'data');
+    return isRunHandle(v) ? v : undefined;
+};
+const exhausted = (state) => {
+    const brk = readThrownSlot(state, 'lastBreak', 'data');
+    return step(state, Object.freeze({ action: 'window-exhausted', notFollowed: mintRunNotFollowed('reattach_exhausted', runOf(state), isReattachBreak(brk) ? brk : undefined) }));
+};
+const badInput = (state, runId) => step(state, Object.freeze({ action: 'window-exhausted', notFollowed: mintRunNotFollowed('bad_input', runId) }));
 const cont = (state, notFoundConfirmed = false) => step(state, Object.freeze({ action: 'continue', notFoundConfirmed }));
-const next = (state, patch) => Object.freeze({ ...state, ...patch });
+const next = (state, patch, lastBreak) => {
+    if (lastBreak === undefined)
+        return Object.freeze({ ...state, ...patch });
+    const { lastBreak: _previous, ...rest } = state;
+    return Object.freeze(lastBreak.to === undefined ? { ...rest, ...patch } : { ...rest, ...patch, lastBreak: lastBreak.to });
+};
 const isCount = (v) => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
 function validState(s) {
     if (typeof s !== 'object' || s === null)
@@ -42,18 +65,20 @@ function validState(s) {
     return typeof o.enteredAtMs === 'number' && typeof o.deadlineMs === 'number' && isCount(o.attempt) && isCount(o.consecutiveNotFound) && typeof o.notFoundConfirmed === 'boolean' && typeof o.tuning === 'object' && o.tuning !== null;
 }
 export function reattachWindowStep(state, event, nowMs) {
+    let windowRun;
     try {
+        windowRun = runOf(state);
         if (!validState(state))
-            return exhausted(reattachWindowOpen(Number.NaN));
+            return badInput(reattachWindowOpen(Number.NaN, undefined, windowRun), windowRun);
         if (typeof event !== 'object' || event === null)
             return cont(state);
         const type = event.type;
         const result = event.result;
         const serverRetryAfterMs = event.serverRetryAfterMs;
         if (type === 'new-segment')
-            return cont(reattachWindowOpen(nowMs, state.tuning));
-        if (usableClockMs(nowMs) === null || !Number.isFinite(state.deadlineMs))
-            return exhausted(state);
+            return cont(reattachWindowOpen(nowMs, state.tuning, windowRun));
+        if (usableClockMs(nowMs) === null || usableClockMs(state.enteredAtMs) === null || !Number.isFinite(state.deadlineMs))
+            return badInput(state, windowRun);
         switch (type) {
             case 'attempt':
                 return nowMs < state.deadlineMs ? cont(next(state, { attempt: state.attempt + 1 })) : exhausted(state);
@@ -70,18 +95,25 @@ export function reattachWindowStep(state, event, nowMs) {
             case 'tail-frame':
                 return cont(next(state, { consecutiveNotFound: 0, notFoundConfirmed: false }));
             case 'tail-refused-404':
-                return state.notFoundConfirmed ? step(state, Object.freeze({ action: 'run-unknown', confirmations: state.consecutiveNotFound })) : cont(state);
+                return state.notFoundConfirmed
+                    ? step(state, Object.freeze({ action: 'run-unknown', confirmations: state.consecutiveNotFound, notFollowed: mintRunNotFollowed('run_unknown', windowRun) }))
+                    : cont(state);
             case 'backoff': {
-                const own = reattachBackoffMs(state.attempt, state.tuning);
+                const brkRead = readThrownSlot(event, 'break');
+                const brk = isReattachBreak(brkRead) ? brkRead : undefined;
+                const handoffRead = readThrownSlot(event, 'runId');
+                const handoff = isRunHandle(handoffRead) && handoffRead !== windowRun ? handoffRead : undefined;
+                const moved = next(state, handoff !== undefined ? { runId: handoff, consecutiveNotFound: 0, notFoundConfirmed: false } : {}, { to: brk });
+                const own = reattachBackoffMs(moved.attempt, moved.tuning);
                 const delay = typeof serverRetryAfterMs === 'number' && Number.isFinite(serverRetryAfterMs) && serverRetryAfterMs > 0 ? Math.max(own, serverRetryAfterMs) : own;
-                return nowMs + delay >= state.deadlineMs ? exhausted(state) : step(state, Object.freeze({ action: 'wait', afterMs: delay }));
+                return nowMs + delay >= moved.deadlineMs ? exhausted(moved) : step(moved, Object.freeze({ action: 'wait', afterMs: delay }));
             }
             default:
                 return cont(state);
         }
     }
     catch {
-        return exhausted(reattachWindowOpen(Number.NaN));
+        return badInput(reattachWindowOpen(Number.NaN, undefined, windowRun), windowRun);
     }
 }
 export function poisonFrameInitial() {

package/dist/runFollow.d.ts

@@ -0,0 +1,30 @@
+import type { UiLanguage } from './env/uiLanguage.js';
+import { type MessageRef } from './i18n/translate.js';
+import type { ReattachEvent } from './runReattachPolicy.js';
+export type RunNotFollowedCause = 'reattach_exhausted' | 'no_run_id' | 'bad_input' | 'run_unknown' | 'target_unconfirmed' | 'cursor_unknown';
+export type ReattachBreak = ReattachEvent['cause'];
+export type RunNotFollowed<C extends RunNotFollowedCause = RunNotFollowedCause> = C extends 'reattach_exhausted' ? RunNotFollowedExhausted : RunNotFollowedFact<C>;
+interface RunNotFollowedFact<C extends RunNotFollowedCause> {
+    readonly kind: 'not_followable';
+    readonly cause: C;
+    readonly taskId?: string;
+}
+interface RunNotFollowedExhausted extends RunNotFollowedFact<'reattach_exhausted'> {
+    readonly lastBreak?: ReattachBreak;
+}
+export declare const isReattachBreak: (v: {} | null | undefined) => v is ReattachBreak;
+export declare function mintRunNotFollowed<C extends RunNotFollowedCause>(cause: C, taskId?: string, lastBreak?: ReattachBreak): RunNotFollowed<C>;
+export declare function registerRunNotFollowed(thrown: object, fact: RunNotFollowed): void;
+export declare function runNotFollowedOf(err: {} | null | undefined): RunNotFollowed | undefined;
+interface NoticeParts {
+    readonly reason: MessageRef;
+    readonly ending: MessageRef | '';
+    readonly exit: MessageRef | '';
+}
+export declare function runNotFollowedHeadRef(taskId: string | undefined, parts: NoticeParts): MessageRef;
+export declare function runNotFollowedReasonRef(cause: RunNotFollowedCause, lastBreak?: ReattachBreak): MessageRef;
+export declare function runNotFollowedEndingUnknownRef(): MessageRef;
+export declare function runNotFollowedExitRef(cause: RunNotFollowedCause): MessageRef | '';
+export declare function runNotFollowedNoticeRef(fact: RunNotFollowed): MessageRef;
+export declare function runNotFollowedNotice(fact: RunNotFollowed, lang?: UiLanguage): string;
+export {};