@sema-agent/client-core 0.94.0 → 0.95.0

package/dist/hitl/parkResolver.js

@@ -1,6 +1,8 @@
 import { putOwnKey, readOwnDataValue } from '../ownKey.js';
-import { DecideTransportRetryExhaustedError, HitlBridge, HitlSafetyError, NO_QUESTION_OVERLAY_REASON, findPendingForTask, isNoDecisionSurfaceReason, readDecideCurrentPending, readWireErrorCode, } from './hitlBridge.js';
-import { ASK_GONE, CHECKPOINT_UNSUPPORTED_VERSION, DECIDE_WORKFLOW_PARK_FORKED, DECIDE_WORKFLOW_PARKS_UNREADABLE, PARKED_RESUME_STARTUP_FAILED, RESUME_POLICY_FOLD_CODE, isDecideParkMovedCode, refusalSaysStillPending } from '../engineErrorCodes.js';
+import { ApprovalStaleError, NotFoundError, ParkedResumeStartupError } from '@sema-agent/sdk';
+import { DecideTransportRetryExhaustedError, GATE_FAILURE_CODES, HitlBridge, NO_QUESTION_OVERLAY_REASON, findPendingForTask, hitlSafetyCodeOf, isNoDecisionSurfaceReason, readDecideCurrentPending, readWireErrorCode, } from './hitlBridge.js';
+import { ASK_GONE, CHECKPOINT_UNSUPPORTED_VERSION, DECIDE_WORKFLOW_PARK_FORKED, DECIDE_WORKFLOW_PARKS_UNREADABLE, PARKED_RESUME_STARTUP_FAILED, RESUME_POLICY_FOLD_CODE, isDecideAlreadyResolvedCode, isDecideParkMovedCode, refusalSaysStillPending } from '../engineErrorCodes.js';
+import { isHitlSafetyErrorLike } from './parkOwnership.js';
 import { publishQuestionFrame, registerLocalQuestionResponder, hasQuestionOverlay, } from '../liveQuestionStore.js';
 import { hostLog } from '../host.js';
 import { surfaceFsApprovalAndDecide } from './toolApprovalWire.js';
@@ -9,7 +11,7 @@ import { flushHeldWithInterruptRewrite, isAskTool } from './frameRouter.js';
 import { approvalCallKey, askGateQuestionId } from './gateIdentity.js';
 import { readDecideReceipt } from '../decideReceipt.js';
 import { decideFailureNote } from '../decideFailureNote.js';
-import { wireFailureTextsOf } from '../wireFailureShape.js';
+import { thrownIsInstanceOf, wireFailureTextsOf } from '../wireFailureShape.js';
 export const MAX_GATE_HOPS = 2;
 export function nextHopBudget(prev, round) {
     const total = (prev?.total ?? 0) + 1;
@@ -18,16 +20,6 @@ export function nextHopBudget(prev, round) {
 const MAX_TRANSPORT_REATTACHES = 2;
 export const MAX_TOTAL_PARKS = 64;
 const MAX_ALREADY_RESOLVED_REATTACHES = 1;
-export const GATE_FAILURE_CODES = [
-    'no_pending',
-    'binding_mismatch',
-    'wrong_gate',
-    'bad_plan_edit',
-    'bad_plan_mode',
-    'empty_answer',
-];
-const _gateFailureCodePins = [true, true];
-void _gateFailureCodePins;
 function isGateFailureCode(v) {
     return typeof v === 'string' && GATE_FAILURE_CODES.includes(v);
 }
@@ -41,27 +33,59 @@ function alreadyResolvedReasonToken(reason) {
     const r = reason.toLowerCase();
     return ALREADY_RESOLVED_REASON_TOKENS.find((t) => r.includes(t));
 }
-export function isAlreadyResolvedFailure(outcome) {
+export function isAlreadyResolvedFailure(failure) {
     try {
-        return alreadyResolvedFailureVerdict(outcome);
+        return alreadyResolvedFailureVerdict(failure);
     }
     catch {
         return false;
     }
 }
-function alreadyResolvedFailureVerdict(outcome) {
-    if (typeof outcome !== 'object' || outcome === null)
+const ALREADY_RESOLVED_TYPED_ERROR_NAMES = Object.freeze([ApprovalStaleError.name, NotFoundError.name]);
+const PARKED_RESUME_STARTUP_TYPED_ERROR_NAME = ParkedResumeStartupError.name;
+function decideFailureFactsOf(failure) {
+    if (typeof failure !== 'object' || failure === null)
+        return undefined;
+    const o = failure;
+    const ec = o.errorCode;
+    const errorCode = typeof ec === 'string' && ec.length > 0 ? ec : undefined;
+    const retriable = refusalSaysStillPending(failure);
+    if (Object.hasOwn(failure, 'kind') && o.kind === 'failed') {
+        const safety = isGateFailureCode(o.safetyCode) ? o.safetyCode : undefined;
+        const code = isGateFailureCode(o.code) ? o.code : safety;
+        return { code, safetySignal: safety !== undefined, errorCode, retriable, typedErrorName: undefined, reason: o.reason };
+    }
+    const name = o.name;
+    return {
+        code: isGateFailureCode(o.code) ? o.code : undefined,
+        safetySignal: isHitlSafetyErrorLike(failure),
+        errorCode,
+        retriable,
+        typedErrorName: typeof name === 'string' ? name : undefined,
+        reason: String(failure),
+    };
+}
+function alreadyResolvedFailureVerdict(failure) {
+    const f = decideFailureFactsOf(failure);
+    if (f === undefined)
         return false;
-    const code = 'code' in outcome && isGateFailureCode(outcome.code) ? outcome.code : undefined;
-    if (code !== undefined)
-        return code === 'no_pending';
-    if ('errorCode' in outcome && isCodeClassifiedGateFailure(outcome.errorCode, Object.hasOwn(outcome, 'retriable') && outcome.retriable === true))
+    if (f.code !== undefined)
+        return f.code === 'no_pending';
+    if (f.safetySignal)
+        return false;
+    if (isDecideAlreadyResolvedCode(f.errorCode))
+        return true;
+    if (f.typedErrorName !== undefined && ALREADY_RESOLVED_TYPED_ERROR_NAMES.includes(f.typedErrorName))
+        return true;
+    if (f.typedErrorName === PARKED_RESUME_STARTUP_TYPED_ERROR_NAME && !isDecideParkMovedCode(f.errorCode))
+        return false;
+    if (isCodeClassifiedGateFailure(f.errorCode, f.retriable))
         return false;
-    if ('errorCode' in outcome && isDecideParkMovedCode(outcome.errorCode))
+    if (isDecideParkMovedCode(f.errorCode))
         return true;
-    if ('errorCode' in outcome && outcome.errorCode === ASK_GONE)
+    if (f.errorCode === ASK_GONE)
         return true;
-    return isAlreadyResolvedGateReason(outcome.reason);
+    return isAlreadyResolvedGateReason(f.reason);
 }
 export function isGateStandingErrorCode(code, retriable) {
     return (code === RESUME_POLICY_FOLD_CODE ||
@@ -167,7 +191,7 @@ async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal, parkGat
         return { kind: 'decided', gatedCallId, ...(declinedReceipt !== undefined ? { receipt: declinedReceipt } : {}) };
     }
     catch (e) {
-        const code = e instanceof HitlSafetyError && isGateFailureCode(e.code) ? e.code : undefined;
+        const code = hitlSafetyCodeOf(e);
         const currentPending = readDecideCurrentPending(e);
         const wireCode = readWireErrorCode(e);
         const wireRetriable = typeof e === 'object' && e !== null && refusalSaysStillPending(e);
@@ -179,7 +203,7 @@ async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal, parkGat
             gatedCallId,
             reason: `decide failed: ${failureTexts.reason}${decideFailureNote(e, attemptedDecision)}`,
             ...(code !== undefined ? { code } : {}),
-            ...(e instanceof DecideTransportRetryExhaustedError ? { retryExhausted: true } : {}),
+            ...(thrownIsInstanceOf(e, DecideTransportRetryExhaustedError) ? { retryExhausted: true } : {}),
             ...(currentPending !== undefined ? { currentPending } : {}),
             ...(wireCode !== undefined ? { errorCode: wireCode } : {}),
             ...(wireRetriable ? { retriable: true } : {}),

package/dist/hitl/persistedRulesWire.js

@@ -66,7 +66,11 @@ export function classifyRulesFailure(e, context) {
         catch {
             cursorSent = undefined;
         }
-        return cursorSent === false ? { kind: 'query-refused', message } : { kind: 'cursor-stale', message };
+        if (cursorSent === true)
+            return { kind: 'cursor-stale', message };
+        if (cursorSent === false)
+            return { kind: 'query-refused', message };
+        return { kind: 'error', message };
     }
     if (status === 400 && errorCode === 'request.field_invalid')
         return { kind: 'field-refused', message };

package/dist/hitl/planReviewWire.d.ts

@@ -12,6 +12,7 @@ export type PlanReviewChoice = {
     permissionModeAfter?: PlanReviewModeAfter;
 } | {
     decision: 'reject';
+    reason?: string;
 };
 export declare function planReviewChoiceFromAnswer(answer: QuestionAnswer | null | undefined, shownLabels?: readonly string[]): PlanReviewChoice | 'dismissed';
 export declare function planReviewCardOptions(offerModeAfter: boolean): Array<{
@@ -76,14 +77,13 @@ export declare function __resetPlanReviewDecisionLatchForTests(): void;
 export declare function decidePlanReview(taskId: string, decision: 'approve' | 'reject', permissionModeAfter?: string, opts?: DecidePlanReviewOptions): Promise<void>;
 export interface ReopenPlanReviewOpts {
     mintFreshQuestionId?: boolean;
-    deliverDecision?: (taskId: string, decision: 'approve' | 'reject') => void | Promise<void>;
+    deliverDecision?: (taskId: string, decision: 'approve' | 'reject', reason?: string) => void | Promise<void>;
     sessionKey?: string;
     wire?: PlanReviewWire;
     onOutcome?: PlanReviewDeliveryOptions['onOutcome'];
     presentationReceiptMs?: number;
     trigger?: PlanReviewReopenTrigger;
     readGateInstanceKeys?: PlanReviewGateInstanceReader;
-    decisionHandedOver?: (taskId: string) => boolean;
     pendingReadStartedAt?: number;
 }
 export declare function _resetActiveReopenRespondersForTest(): void;

package/dist/hitl/planReviewWire.js

@@ -29,31 +29,59 @@ const ALL_KNOWN_LABELS = Object.freeze([
     PLAN_REVIEW_APPROVE_LABEL,
     PLAN_REVIEW_REJECT_LABEL,
 ]);
-export function planReviewDecisionFromAnswer(answer, shownLabels) {
-    const choice = planReviewChoiceFromAnswer(answer, shownLabels);
+export function planReviewDecisionFromAnswer(answer, shownLabels = LEGACY_TWO_CHOICE_LABELS) {
+    const { choice } = readPlanReviewAnswer(answer, shownLabels);
     if (choice === 'dismissed')
         return 'dismissed';
     return choice.decision;
 }
-export function planReviewChoiceFromAnswer(answer, shownLabels = LEGACY_TWO_CHOICE_LABELS) {
+function readDismissed() {
+    return { choice: 'dismissed', noteIgnoredOnApprove: false };
+}
+function freeTextNoteOf(entry) {
+    try {
+        const note = entry?.note;
+        return typeof note === 'string' && note.trim() !== '' ? note : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readPlanReviewAnswer(answer, shownLabels) {
     const answers = answer?.answers;
     if (!Array.isArray(answers) || answers.length !== 1)
-        return 'dismissed';
-    const picked = answers[0]?.selected;
-    if (!Array.isArray(picked) || picked.length !== 1)
-        return 'dismissed';
+        return readDismissed();
+    const entry = answers[0];
+    const picked = entry?.selected;
+    if (!Array.isArray(picked))
+        return readDismissed();
+    const note = freeTextNoteOf(entry);
+    if (picked.length === 0) {
+        if (note === undefined || !shownLabels.includes(REJECT_LABEL))
+            return readDismissed();
+        return { choice: { decision: 'reject', reason: note }, noteIgnoredOnApprove: false };
+    }
+    if (picked.length !== 1)
+        return readDismissed();
     const selected = picked[0];
     if (typeof selected !== 'string' || !shownLabels.includes(selected))
-        return 'dismissed';
+        return readDismissed();
+    const ignored = note !== undefined;
     if (selected === PLAN_REVIEW_APPROVE_AUTO_LABEL)
-        return { decision: 'approve', permissionModeAfter: 'acceptEdits' };
+        return { choice: { decision: 'approve', permissionModeAfter: 'acceptEdits' }, noteIgnoredOnApprove: ignored };
     if (selected === PLAN_REVIEW_APPROVE_MANUAL_LABEL)
-        return { decision: 'approve', permissionModeAfter: 'default' };
+        return { choice: { decision: 'approve', permissionModeAfter: 'default' }, noteIgnoredOnApprove: ignored };
     if (selected === APPROVE_LABEL)
-        return { decision: 'approve' };
+        return { choice: { decision: 'approve' }, noteIgnoredOnApprove: ignored };
     if (selected === REJECT_LABEL)
-        return { decision: 'reject' };
-    return 'dismissed';
+        return { choice: note === undefined ? { decision: 'reject' } : { decision: 'reject', reason: note }, noteIgnoredOnApprove: false };
+    return readDismissed();
+}
+export function planReviewChoiceFromAnswer(answer, shownLabels = LEGACY_TWO_CHOICE_LABELS) {
+    const { choice, noteIgnoredOnApprove } = readPlanReviewAnswer(answer, shownLabels);
+    if (noteIgnoredOnApprove)
+        hostLog('debug', 'planReviewWire: note ignored on approve — an approval carries no feedback text; the note was not sent');
+    return choice;
 }
 export function planReviewCardOptions(offerModeAfter) {
     const reject = { label: REJECT_LABEL, description: 'Discard this plan and stay in plan mode to refine it' };
@@ -270,10 +298,12 @@ export function armPlanReviewApproval(result, sessionKey, opts) {
             const decided = choice.decision;
             notePlanReviewDecisiveAnswerFor(DEFAULT_SESSION_KEY, taskId);
             const modeAfter = choice.decision === 'approve' ? choice.permissionModeAfter : undefined;
+            const cardReason = choice.decision === 'reject' ? choice.reason : undefined;
+            const cardDelivery = cardReason !== undefined ? { ...delivery, reason: cardReason } : delivery;
             offerModeAfterByTask.delete(taskId);
             notePlanReviewAnswered(questionId);
             hostLog('debug', `planReviewWire: arm responder delivering ${decided} for task ${taskId} (path=arm)`);
-            void decidePlanReviewFor(taskId, decided, modeAfter, delivery, gateBefore);
+            void decidePlanReviewFor(taskId, decided, modeAfter, cardDelivery, gateBefore);
             return { ok: true };
         });
         publishPlanReviewCard(taskId);
@@ -821,9 +851,10 @@ function mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs) {
         ? { ...(opts.wire !== undefined ? { wire: opts.wire } : {}), ...(opts.onOutcome !== undefined ? { onOutcome: opts.onOutcome } : {}) }
         : undefined;
     const deliver = opts?.deliverDecision ??
-        ((tid, decision) => {
+        ((tid, decision, reason) => {
             hostLog('debug', `planReviewWire: reopen responder delivering ${decision} for task ${tid} (path=reopen-default)`);
-            void (delivery === undefined ? decidePlanReview(tid, decision) : decidePlanReview(tid, decision, undefined, delivery));
+            const withReason = reason === undefined ? delivery : { ...delivery, reason };
+            void (withReason === undefined ? decidePlanReview(tid, decision) : decidePlanReview(tid, decision, undefined, withReason));
         });
     const activeKey = `${sessionKey}\u0000${canonicalId}`;
     const unregister = registerLocalQuestionResponder(questionId, async (_id, answer) => {
@@ -831,15 +862,20 @@ function mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs) {
         if (activeReopenResponders.get(activeKey)?.questionId === questionId) {
             activeReopenResponders.delete(activeKey);
         }
-        const decided = planReviewDecisionFromAnswer(answer, LEGACY_TWO_CHOICE_LABELS);
-        if (decided === 'dismissed') {
+        const choice = planReviewChoiceFromAnswer(answer, LEGACY_TWO_CHOICE_LABELS);
+        if (choice === 'dismissed') {
             notePlanReviewUserDismissalFor(sessionKey, taskId, opts?.readGateInstanceKeys, questionId);
             return { ok: true };
         }
+        const decided = choice.decision;
+        const cardReason = choice.decision === 'reject' ? choice.reason : undefined;
         notePlanReviewDecisiveAnswerFor(sessionKey, taskId);
         notePlanReviewAnsweredFor(sessionKey, questionId);
         try {
-            await deliver(taskId, decided);
+            if (cardReason === undefined)
+                await deliver(taskId, decided);
+            else
+                await deliver(taskId, decided, cardReason);
         }
         catch (e) {
             hostLog('error', `planReviewWire: reopen decision delivery threw for task ${taskId}: ${String(e)}`);
@@ -887,18 +923,8 @@ async function reopenAfterDismissalCheck(taskId, opts, sessionKey, receiptMs, ma
                 }
             }
         }
-        let handedOver = false;
         const ledgerSaysInFlight = planReviewDecisionInFlight(taskId, recheckReadStart);
-        if (!ledgerSaysInFlight) {
-            try {
-                handedOver = opts.decisionHandedOver?.(taskId) === true;
-            }
-            catch (err) {
-                hostLog('debug', `planReviewWire: reopen for task ${taskId} refused — the host's decision hand-over check threw: ${String(err)}`);
-                return { reopened: false };
-            }
-        }
-        if (ledgerSaysInFlight || handedOver) {
+        if (ledgerSaysInFlight) {
             hostLog('debug', `planReviewWire: reopen for task ${taskId} refused after the dismissal check — a decision for this task went out while the check was reading`);
             return { reopened: false, _sema_decisionInFlight: true };
         }

package/dist/hitl/replayedApproval.d.ts

@@ -1,3 +1,4 @@
+import { type ApprovalSettledHow } from './gateLedger.js';
 import { type ApprovalsListEnvelope, type CrashConvergedRow } from './crashConverged.js';
 export type ReplayedApprovalDisposition = {
     readonly kind: 'live';
@@ -5,6 +6,8 @@ export type ReplayedApprovalDisposition = {
 } | {
     readonly kind: 'decided';
     readonly cause?: CrashConvergedRow['cause'];
+    readonly needsHumanReason?: NonNullable<CrashConvergedRow['needsHumanReason']>;
+    readonly settled?: ApprovalSettledHow;
 } | {
     readonly kind: 'unknown';
     readonly why: 'unreadable_frame' | 'no_approval_id' | 'not_read' | 'list_unreadable' | 'list_not_reported' | 'list_incomplete';
@@ -17,5 +20,10 @@ export interface ReplayPendingBasis {
     } | {
         readonly read: 'failed';
     };
+    readonly settled?: ReadonlyMap<string, ApprovalSettledHow>;
 }
+export declare function settledApprovalDisposition(frame: object, settled: ReplayPendingBasis['settled']): ReplayedApprovalDisposition | undefined;
 export declare function replayedApprovalDisposition(frame: object, basis: ReplayPendingBasis): ReplayedApprovalDisposition;
+export declare function replayedApprovalSentence(disposition: ReplayedApprovalDisposition | undefined, opts?: {
+    readonly toolName?: string;
+}): string | undefined;

package/dist/hitl/replayedApproval.js

@@ -1,29 +1,64 @@
-import { hasLedgerPositionKey } from './gateLedger.js';
+import { APPROVAL_SETTLED_HOWS, hasLedgerPositionKey } from './gateLedger.js';
 import { readLivePendingRows } from './livePendingAsk.js';
 import { projectCrashConverged } from './crashConverged.js';
+import { quoteUntrustedForSentence } from '../displayUntrusted.js';
 const live = (basis) => Object.freeze({ kind: 'live', basis });
 const unknown = (why) => Object.freeze({ kind: 'unknown', why });
-const decided = (cause) => Object.freeze(cause !== undefined ? { kind: 'decided', cause } : { kind: 'decided' });
+const decided = (row) => Object.freeze(row === undefined
+    ? { kind: 'decided' }
+    : { kind: 'decided', cause: row.cause, ...(row.needsHumanReason !== undefined ? { needsHumanReason: row.needsHumanReason } : {}) });
+const decidedSettled = (how) => Object.freeze({ kind: 'decided', settled: how });
 function approvalIdOf(frame) {
     const v = frame.approvalId;
     return typeof v === 'string' && v !== '' ? v : undefined;
 }
-function crashConvergedCauseOf(body, approvalId) {
+function crashConvergedFactsOf(body, approvalId) {
     const projection = projectCrashConverged(body);
     if (projection === undefined)
         return undefined;
     for (const row of [...projection.resumeSafe, ...projection.needsHuman]) {
         if (row.approvalId === approvalId)
-            return row.cause;
+            return { cause: row.cause, ...(row.needsHumanReason !== undefined ? { needsHumanReason: row.needsHumanReason } : {}) };
     }
     return undefined;
 }
+export function settledApprovalDisposition(frame, settled) {
+    try {
+        if (typeof settled !== 'object' || settled === null || typeof settled.get !== 'function')
+            return undefined;
+        const id = approvalIdOf(frame);
+        if (id === undefined)
+            return undefined;
+        const how = settled.get(id);
+        return typeof how === 'string' && APPROVAL_SETTLED_HOWS.includes(how) ? decidedSettled(how) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function replayedApprovalDisposition(frame, basis) {
     let approvalId;
+    let positioned;
     try {
         if (typeof frame !== 'object' || frame === null)
             return unknown('unreadable_frame');
-        if (!hasLedgerPositionKey(frame))
+        positioned = hasLedgerPositionKey(frame);
+    }
+    catch {
+        return unknown('unreadable_frame');
+    }
+    let settledBasis;
+    try {
+        settledBasis = typeof basis === 'object' && basis !== null ? basis.settled : undefined;
+    }
+    catch {
+        settledBasis = undefined;
+    }
+    const early = settledApprovalDisposition(frame, settledBasis);
+    if (early !== undefined)
+        return early;
+    try {
+        if (!positioned)
             return live('live_leg');
         approvalId = approvalIdOf(frame);
     }
@@ -70,15 +105,15 @@ export function replayedApprovalDisposition(frame, basis) {
     }
     if (reading.kind === 'present' && reading.rows.some((r) => r.approvalId === approvalId))
         return live('pending_list');
-    let cause;
+    let facts;
     try {
-        cause = crashConvergedCauseOf(body, approvalId);
+        facts = crashConvergedFactsOf(body, approvalId);
     }
     catch {
-        cause = undefined;
+        facts = undefined;
     }
-    if (cause !== undefined)
-        return decided(cause);
+    if (facts !== undefined)
+        return decided(facts);
     if (reading.kind === 'not_reported')
         return unknown('list_not_reported');
     if (reading.kind === 'malformed')
@@ -87,3 +122,83 @@ export function replayedApprovalDisposition(frame, basis) {
         return unknown('list_incomplete');
     return decided();
 }
+const TOOL_NAME_MAX = 80;
+const THIS_REQUEST = 'this approval request';
+const sentenceInitial = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+const TOOL_STATE_NOT_SHOWN = 'Whether the tool had started is not shown here.';
+const STOPPED_BY_CAUSE = Object.freeze({
+    crashed_before_park: 'the engine stopped unexpectedly',
+    shutdown_before_park: 'the engine was shut down in an orderly way',
+});
+const STATE_BY_REASON = Object.freeze({
+    pending_unsafe: 'waiting',
+    approved_then_interrupted: 'approved',
+    contradictory: 'unclear',
+    unstable_row: 'unclear',
+});
+const CRASH_CONVERGED_SENTENCE = Object.freeze({
+    waiting: (what, stopped) => `${sentenceInitial(what)} was still waiting when ${stopped}, so the engine denied it automatically; no decision was sent for it from here. ${TOOL_STATE_NOT_SHOWN}`,
+    approved: (what, stopped) => `${sentenceInitial(what)} had already been approved and may have been running when ${stopped}, so a side effect may have partly landed; the engine then marked it denied, and no decision was sent for it from here.`,
+    unclear: (what, stopped) => `${sentenceInitial(what)} was denied automatically when ${stopped}, but its record does not show reliably whether it had been approved or whether the tool had started; no decision was sent for it from here.`,
+});
+function crashConvergedStateOf(disposition) {
+    let reason;
+    try {
+        if (typeof disposition !== 'object' || disposition === null || !('needsHumanReason' in disposition))
+            return 'waiting';
+        reason = disposition.needsHumanReason;
+    }
+    catch {
+        return 'unclear';
+    }
+    if (reason === undefined)
+        return 'waiting';
+    return typeof reason === 'string' && Object.hasOwn(STATE_BY_REASON, reason) ? STATE_BY_REASON[reason] : 'unclear';
+}
+const SETTLED_PHRASE = Object.freeze({
+    answered: 'answered',
+    interrupted: 'dismissed',
+    closed_by_engine: 'closed by the engine',
+});
+const settledRepeat = (what, how) => `${sentenceInitial(what)} was ${SETTLED_PHRASE[how]} earlier, so this repeated copy of it was not raised as a new question and no decision was sent for it.`;
+const decidedPlain = (what) => `${sentenceInitial(what)} is no longer listed by the engine as waiting for a decision, so no decision was sent for it.`;
+const unconfirmed = (what) => `Whether ${what} is still waiting for a decision could not be confirmed, so no decision was sent for it.`;
+function guardedGet(o, key) {
+    try {
+        if (typeof o !== 'object' || o === null)
+            return undefined;
+        return o[key];
+    }
+    catch {
+        return undefined;
+    }
+}
+function subjectOf(opts) {
+    const raw = guardedGet(opts, 'toolName');
+    if (typeof raw !== 'string')
+        return THIS_REQUEST;
+    let quoted;
+    try {
+        quoted = quoteUntrustedForSentence(raw, TOOL_NAME_MAX);
+    }
+    catch {
+        return THIS_REQUEST;
+    }
+    return quoted === undefined ? THIS_REQUEST : `the approval request for ${quoted}`;
+}
+export function replayedApprovalSentence(disposition, opts) {
+    const kind = guardedGet(disposition, 'kind');
+    if (kind === 'unknown')
+        return unconfirmed(subjectOf(opts));
+    if (kind !== 'decided')
+        return undefined;
+    const what = subjectOf(opts);
+    const cause = guardedGet(disposition, 'cause');
+    if (typeof cause === 'string' && Object.hasOwn(STOPPED_BY_CAUSE, cause)) {
+        return CRASH_CONVERGED_SENTENCE[crashConvergedStateOf(disposition)](what, STOPPED_BY_CAUSE[cause]);
+    }
+    const settled = guardedGet(disposition, 'settled');
+    if (typeof settled === 'string' && Object.hasOwn(SETTLED_PHRASE, settled))
+        return settledRepeat(what, settled);
+    return decidedPlain(what);
+}

package/dist/hitl/resumeRunningCard.d.ts

@@ -17,6 +17,7 @@ export interface ResumeRunningCardOption {
 }
 export declare function resumeRunningLivenessRow(msSinceLastActivity: number | null | undefined): string | null;
 export declare function resumeRunningQuestionText(i: ResumeRunningCardInput): string;
+export declare function runningAttachOffered(canAttach: boolean | undefined): boolean;
 export declare function resumeRunningOptions(i: ResumeRunningCardInput): ResumeRunningCardOption[];
 export declare function resumeChoiceFromLabels(selected: readonly string[] | null | undefined): ResumeRunningChoice;
 export declare const RESUME_RUNNING_NO_UI_EXIT_CODE = 75;
@@ -26,4 +27,5 @@ export declare function resumeRunningNoUiGuidance(i: {
     sessionId?: string | null;
 }): string;
 export declare function resumeAttachReplayDisclosure(taskId: string): string;
+export declare function resumeRunningCancelConfirmedRow(taskId: string): string;
 export declare function resumeRunningCancelUnconfirmedRow(taskId: string): string;

package/dist/hitl/resumeRunningCard.js

@@ -14,6 +14,9 @@ export function resumeRunningQuestionText(i) {
     const liveness = resumeRunningLivenessRow(i.msSinceLastActivity);
     return liveness === null ? head : `${head}\n${liveness}`;
 }
+export function runningAttachOffered(canAttach) {
+    return canAttach === true;
+}
 export function resumeRunningOptions(i) {
     const options = [
         {
@@ -21,7 +24,7 @@ export function resumeRunningOptions(i) {
             description: 'Leaves the run alone. It keeps executing on the engine, but this screen will not show it and it will not be listed here — your next message runs into it again, and sema asks you then.',
         },
     ];
-    if (i.canAttach) {
+    if (runningAttachOffered(i.canAttach)) {
         options.push({
             label: RESUME_CHOICE_ATTACH_LABEL,
             description: 'Follows that run from here: sema replays it from the engine ledger and keeps streaming it into this conversation. ' +
@@ -65,8 +68,16 @@ export function resumeAttachReplayDisclosure(taskId) {
         `The replayed turns are not billed into this session's cost again either — the engine's own record ` +
         `(GET /v1/runs/${taskId}) is the authority on what that run really spent.`);
 }
+function cancelRow(taskId, confirmed) {
+    return confirmed
+        ? `The engine accepted the cancel for run ${taskId} on your request. A cancel finishes on the engine's side, so that run may need a moment to stop.`
+        : `sema: the cancel for run ${taskId} did not come back confirmed, so that run may still be executing. ` +
+            `This screen does not list it — read its real state on the engine (GET /v1/runs/${taskId}) before ` +
+            `assuming this session is free.`;
+}
+export function resumeRunningCancelConfirmedRow(taskId) {
+    return cancelRow(taskId, true);
+}
 export function resumeRunningCancelUnconfirmedRow(taskId) {
-    return (`sema: the cancel for run ${taskId} did not come back confirmed, so that run may still be executing. ` +
-        `This screen does not list it — read its real state on the engine (GET /v1/runs/${taskId}) before ` +
-        `assuming this session is free.`);
+    return cancelRow(taskId, false);
 }

package/dist/hitl/toolApprovalWire.d.ts

@@ -6,7 +6,7 @@ import { type DenyAttributionRefusalDetail } from '../wireRefusalCopy.js';
 import { type ApprovalDecidedByReading } from '../approvalDecidedByCapability.js';
 import { type DecideReceiptView } from '../decideReceipt.js';
 import { RULE_OFFER_MATCHES, RULE_OFFER_BATCH_MEMBER_KINDS, RULE_OFFER_UNCOVERED_REASONS, RULE_OFFERS_ABSENCE_REASONS } from '@sema-agent/sdk';
-import type { ApprovalDecidedBy, ToolApprovalRespondAck, PersistedRuleAnchor as SdkPersistedRuleAnchor, RuleOfferMatch as SdkRuleOfferMatch, RuleOfferBatchMember as SdkRuleOfferBatchMember, RuleOfferUncoveredDetail as SdkRuleOfferUncoveredDetail, RuleOfferUncoveredReason as SdkRuleOfferUncoveredReason, AskOrigin as SdkAskOrigin, RuleOffersAbsence as SdkRuleOffersAbsence, DenialLimitKind as SdkDenialLimitKind, DenialLimitFallback as SdkDenialLimitFallback } from '@sema-agent/sdk';
+import type { ApprovalDecidedBy, ApprovalSettleCause, ToolApprovalRespondAck, PersistedRuleAnchor as SdkPersistedRuleAnchor, RuleOfferMatch as SdkRuleOfferMatch, RuleOfferBatchMember as SdkRuleOfferBatchMember, RuleOfferUncoveredDetail as SdkRuleOfferUncoveredDetail, RuleOfferUncoveredReason as SdkRuleOfferUncoveredReason, AskOrigin as SdkAskOrigin, RuleOffersAbsence as SdkRuleOffersAbsence, DenialLimitKind as SdkDenialLimitKind, DenialLimitFallback as SdkDenialLimitFallback } from '@sema-agent/sdk';
 export declare function isFsApprovalGate(gate: {
     kind?: unknown;
     toolName?: unknown;
@@ -137,7 +137,6 @@ export interface ApprovalCardRequest {
     ruleOffersReadOnly?: RuleOffer[];
     inputHasBidi?: true;
     hasBidiControls?: true;
-    persistedRuleShadowed?: string;
     allowRuleShadow?: ApprovalAllowRuleShadow;
     probeCause?: unknown;
     probeReason?: string;
@@ -177,6 +176,9 @@ export declare function hasApprovalCardPortFor(sessionKey: string): boolean;
 export declare function approvalCardPortFor(sessionKey: string): ApprovalCardPort | null;
 export declare function _resetApprovalCardPortForTest(): void;
 export declare function surfaceApprovalCard(req: ApprovalCardRequest): Promise<ApprovalCardDecision>;
+declare const REMEMBER_REFUSAL_CODES: readonly ["remember_not_in_proof", "remember_requires_binding", "capability.store_required", "decide.workflow_remember_unsupported", "decide.parked_remember_unsupported"];
+export type RememberRefusalCode = (typeof REMEMBER_REFUSAL_CODES)[number];
+export declare function rememberRefusalOf(error: unknown): RememberRefusalCode | undefined;
 export declare function surfaceFsApprovalAndDecide(deps: FsApprovalWireDeps, taskId: string, argsByCall: Map<string, unknown>, signal?: AbortSignal, parkGatedCallId?: string): Promise<FsApprovalOutcome>;
 export interface BoundSkillGrantsWire {
     readonly skill: string | null;
@@ -192,6 +194,7 @@ export interface ToolApprovalFrame {
     args?: unknown;
     argsOmitted?: boolean;
     outcome?: 'allowed' | 'denied' | 'expired';
+    cause?: ApprovalSettleCause;
     sourceTaskId?: string;
     fromSubagent?: true;
     sourceAgentName?: string;
@@ -232,7 +235,7 @@ export interface ToolApprovalDelegation {
     depth: number;
     agentName?: string;
 }
-export declare const TOOL_APPROVAL_FRAME_KEYS_MIRROR: readonly ["type", "approvalId", "toolCallId", "toolName", "sourceTaskId", "fromSubagent", "sourceAgentName", "message", "args", "argsOmitted", "governanceForced", "ruleOffers", "ruleOffersAbsence", "denialLimitFallback", "readRootCandidate", "mandated", "mandate", "origin", "askClass", "classes", "inputHasBidi", "parked", "persistedRuleShadowed", "allowRuleShadowed", "probeCause", "probeReason", "rememberRefused", "boundGrantDigest", "boundGrants", "classifierNoRuling", "ruleEvidence", "requiresRealApproval", "expiresInMs", "expiresAtMs", "serverNowMs", "delegation", "outcome"];
+export declare const TOOL_APPROVAL_FRAME_KEYS_MIRROR: readonly ["type", "approvalId", "toolCallId", "toolName", "sourceTaskId", "fromSubagent", "sourceAgentName", "message", "args", "argsOmitted", "governanceForced", "ruleOffers", "ruleOffersAbsence", "denialLimitFallback", "readRootCandidate", "mandated", "mandate", "origin", "askClass", "classes", "inputHasBidi", "parked", "persistedRuleShadowed", "allowRuleShadowed", "probeCause", "probeReason", "rememberRefused", "boundGrantDigest", "boundGrants", "classifierNoRuling", "ruleEvidence", "requiresRealApproval", "expiresInMs", "expiresAtMs", "serverNowMs", "delegation", "outcome", "cause"];
 export interface ApprovalMandatedFacts {
     readonly mandated?: true;
     readonly ruleOffersAbsence?: string;
@@ -307,6 +310,7 @@ export type ToolApprovalRespondRefusal = (ToolApprovalRespondRefusalFields & {
 export declare function readToolApprovalRespondRefusal(err: unknown): ToolApprovalRespondRefusal | undefined;
 export declare function isToolApprovalFrame(ev: unknown): ev is ToolApprovalFrame;
 export declare function askProbeReasonDetail(card: Pick<ApprovalCardRequest, 'probeReason' | 'probeCause'> | null | undefined): string | undefined;
+export declare function readApprovalRememberRefused(v: unknown): boolean;
 export declare function readApprovalBoundGrants(v: unknown): BoundSkillGrantsWire | undefined;
 export declare function readApprovalClassifierNoRuling(v: unknown): string | undefined;
 export declare function classifierNoRulingDetail(word: string | undefined): string;
@@ -323,4 +327,20 @@ export interface ToolApprovalFrameLaneOpts {
     windowIsCurrent?: boolean;
     argsUnavailable?: true;
 }
-export declare function surfaceToolApprovalFrameAndRespond(frame: ToolApprovalFrame, respond: RespondToolApprovalFn, streamArgs: unknown | undefined, signal?: AbortSignal, lane?: ToolApprovalFrameLaneOpts): Promise<ToolApprovalFrameOutcome>;
+export declare function surfaceToolApprovalFrameAndRespond(frame: ToolApprovalFrame, respond: RespondToolApprovalFn, streamArgs: unknown | undefined, signal?: AbortSignal, lane?: ToolApprovalFrameLaneOpts, run?: {
+    readonly taskId?: string;
+    readonly sessionId?: string;
+}): Promise<ToolApprovalFrameOutcome>;
+export interface ApprovalHolderIdentity {
+    readonly approvalId?: string;
+    readonly taskId?: string;
+    readonly toolCallId?: string;
+    readonly sessionId?: string;
+}
+export type ApprovalHolderJoin = {
+    readonly kind: 'joined';
+    readonly outcome: ToolApprovalFrameOutcome;
+} | {
+    readonly kind: 'free';
+};
+export declare function joinApprovalHolder(identity: ApprovalHolderIdentity, signal?: AbortSignal): Promise<ApprovalHolderJoin>;