@sema-agent/client-core 0.90.0 → 0.92.0

package/dist/hitl/hitlBridge.d.ts

@@ -1,4 +1,5 @@
 import type { AgentEvent, ApprovalDecision, ApprovalStaleError, PendingCheckpoint, CheckpointGate, PlanReviewRequest, AssistantTaskStatus } from '@sema-agent/sdk';
+import type { PermissionResult } from '@sema-agent/agent-types';
 import type { ApprovalsListEnvelope } from './crashConverged.js';
 import { type SuspendedReopenReading } from './suspendedReopen.js';
 export declare const DEFAULT_DENY_REASON = "The user rejected this tool use";
@@ -8,9 +9,9 @@ export interface HitlPermissionDecisionLike {
     message?: string;
     updatedInput?: unknown;
 }
-export type HitlCanUseToolFn<D extends HitlPermissionDecisionLike = HitlPermissionDecisionLike> = (tool: {
+export type HitlCanUseToolFn<D extends HitlPermissionDecisionLike = HitlPermissionDecisionLike, Ctx = never, Msg = never> = (tool: {
     name: string;
-}, input: Record<string, unknown>, toolUseContext: never, assistantMessage: never, toolUseID: string, forceDecision?: D) => Promise<D>;
+}, input: Record<string, unknown>, toolUseContext: Ctx, assistantMessage: Msg, toolUseID: string, forceDecision?: D) => Promise<D>;
 export interface ApprovalsResourceLike {
     list(opts?: {
         signal?: AbortSignal;
@@ -147,8 +148,10 @@ export type GatePrompt<D extends HitlPermissionDecisionLike = HitlPermissionDeci
     toolUseID: string;
     gate: CheckpointGate | null;
 }) => Promise<D>;
-export declare function makeHitlCanUseTool<D extends HitlPermissionDecisionLike = HitlPermissionDecisionLike>(bridge: HitlBridge, prompt: GatePrompt<D>): HitlCanUseToolFn<D>;
-export interface HitlBackendDenyDecision {
+export declare function makeHitlCanUseTool<D extends HitlPermissionDecisionLike = HitlPermissionDecisionLike, Ctx = unknown, Msg = unknown>(bridge: HitlBridge, prompt: GatePrompt<D>): HitlCanUseToolFn<D, Ctx, Msg>;
+export interface HitlBackendDenyDecision extends Extract<PermissionResult, {
+    behavior: 'deny';
+}> {
     behavior: 'deny';
     message: string;
     decisionReason: {

package/dist/hitl/hitlHostSurface.d.ts

@@ -28,6 +28,8 @@ export declare const REMEMBER_NOT_APPLIED_WARN_TEXT = "this session-wide allow w
 export declare const EDIT_NOT_FORWARDED_WARN_TEXT = "your edited tool input was NOT forwarded \u2014 the tool is running with the ORIGINAL input you saw before editing";
 export declare function surfaceRememberNotApplied(): void;
 export declare function surfaceEditNotForwarded(): void;
+export declare const REPLAYED_APPROVAL_LIST_UNREADABLE_WARN_TEXT: string;
+export declare function surfaceReplayedApprovalListUnreadable(): void;
 export declare const EDIT_REFUSED_ON_BLIND_ASK_WARN_TEXT: string;
 export declare function surfaceEditRefusedOnBlindAsk(): void;
 export declare const RULE_NOT_SENT_WARN_TEXT = "your \"don't ask again\" choice was NOT sent to this engine \u2014 support for that rule form could not be confirmed. The approval itself went through, but you will be asked again";

package/dist/hitl/hitlHostSurface.js

@@ -72,6 +72,13 @@ export function surfaceRememberNotApplied() {
 export function surfaceEditNotForwarded() {
     surfaceSelfClearingWarn(EDIT_NOT_FORWARDED_KEY, EDIT_NOT_FORWARDED_WARN_TEXT, EDIT_NOT_FORWARDED_TIMEOUT_MS);
 }
+export const REPLAYED_APPROVAL_LIST_UNREADABLE_WARN_TEXT = "Could not read the pending-approval list, so an approval request read back from this run's event log was not raised as a question, " +
+    'and no decision was sent for it.';
+const REPLAYED_APPROVAL_LIST_UNREADABLE_KEY = 'hitl-replayed-approval-list-unreadable';
+const REPLAYED_APPROVAL_LIST_UNREADABLE_TIMEOUT_MS = 10_000;
+export function surfaceReplayedApprovalListUnreadable() {
+    surfaceSelfClearingWarn(REPLAYED_APPROVAL_LIST_UNREADABLE_KEY, REPLAYED_APPROVAL_LIST_UNREADABLE_WARN_TEXT, REPLAYED_APPROVAL_LIST_UNREADABLE_TIMEOUT_MS);
+}
 export const EDIT_REFUSED_ON_BLIND_ASK_WARN_TEXT = 'That approval was NOT sent: this request does not expose its tool arguments here, so an edited approval cannot be applied. ' +
     'The request is still waiting — approve or deny it as it is.';
 const EDIT_REFUSED_ON_BLIND_ASK_KEY = 'hitl-edit-refused-blind-ask';

package/dist/hitl/livePendingAsk.js

@@ -5,20 +5,39 @@ function nonEmptyString(v) {
 function nonNegativeFinite(v) {
     return typeof v === 'number' && Number.isFinite(v) && v >= 0;
 }
+function snapshotMembers(raw) {
+    const length = raw.length;
+    if (typeof length !== 'number' || !Number.isSafeInteger(length) || length < 0)
+        return undefined;
+    const out = [];
+    for (let i = 0; i < length; i++) {
+        const d = Object.getOwnPropertyDescriptor(raw, i);
+        if (d === undefined || !('value' in d))
+            return undefined;
+        out.push(d.value);
+    }
+    return raw.length === length ? out : undefined;
+}
 export function readLivePendingRows(body) {
     if (body === null || typeof body !== 'object' || Array.isArray(body))
         return { kind: 'malformed' };
-    if (!('livePending' in body))
-        return { kind: 'not_reported' };
-    const raw = body.livePending;
+    const field = Object.getOwnPropertyDescriptor(body, 'livePending');
+    if (field === undefined)
+        return 'livePending' in body ? { kind: 'malformed' } : { kind: 'not_reported' };
+    if (!('value' in field))
+        return { kind: 'malformed' };
+    const raw = field.value;
     if (raw === undefined)
         return { kind: 'not_reported' };
     if (!Array.isArray(raw))
         return { kind: 'malformed' };
+    const members = snapshotMembers(raw);
+    if (members === undefined)
+        return { kind: 'malformed' };
     const rows = [];
     const seen = new Set();
     let dropped = 0;
-    for (const item of raw) {
+    for (const item of members) {
         if (item === null || typeof item !== 'object' || Array.isArray(item)) {
             dropped++;
             continue;
@@ -46,7 +65,7 @@ export function readLivePendingRows(body) {
             ...(isToolApprovalFrame(o.frame) && o.frame.type === 'tool_approval' && o.frame.approvalId === o.approvalId ? { frame: o.frame } : {}),
         });
     }
-    if (raw.length > 0 && rows.length === 0)
+    if (members.length > 0 && rows.length === 0)
         return { kind: 'malformed' };
     return { kind: 'present', rows, dropped };
 }

package/dist/hitl/parkResolver.d.ts

@@ -1,6 +1,7 @@
 import type { AgentEvent } from '@sema-agent/sdk';
 import { type GateCurrentPending, type HitlFailureStage } from './hitlBridge.js';
 import { type QuestionAnswer } from '../liveQuestionStore.js';
+import { type FsApprovalOutcome } from './toolApprovalWire.js';
 import type { AskAnsweredOutput, GateLedger } from './gateLedger.js';
 import { type AskGateWireDeps, type GatePark } from './frameRouter.js';
 import { type DecideReceiptView } from '../decideReceipt.js';
@@ -29,12 +30,16 @@ export type GateOutcome = {
     reason: string;
     code?: GateFailureCode | undefined;
     errorCode?: string | undefined;
+    retriable?: true;
     retryExhausted?: true;
     currentPending?: GateCurrentPending | undefined;
 };
 export declare function isAlreadyResolvedGateReason(reason: unknown): boolean;
-export declare function isGateStandingErrorCode(code: string | null | undefined): boolean;
-export declare function isCodeClassifiedGateFailure(code: string | null | undefined): boolean;
+export declare function isAlreadyResolvedFailure(outcome: Extract<GateOutcome | FsApprovalOutcome, {
+    kind: 'failed';
+}>): boolean;
+export declare function isGateStandingErrorCode(code: string | null | undefined, retriable?: boolean): boolean;
+export declare function isCodeClassifiedGateFailure(code: string | null | undefined, retriable?: boolean): boolean;
 export declare function toAnsweredOutput(questions: unknown[], answer: QuestionAnswer): AskAnsweredOutput;
 export type ParkResolution = {
     kind: 'reattach';

package/dist/hitl/parkResolver.js

@@ -1,6 +1,6 @@
 import { putOwnKey } from '../ownKey.js';
 import { DecideTransportRetryExhaustedError, HitlBridge, HitlSafetyError, NO_QUESTION_OVERLAY_REASON, findPendingForTask, isNoDecisionSurfaceReason, readDecideCurrentPending, readWireErrorCode, } from './hitlBridge.js';
-import { PARKED_RESUME_STARTUP_FAILED, RESUME_POLICY_FOLD_CODE, isDecideParkMovedCode } from '../engineErrorCodes.js';
+import { ASK_GONE, CHECKPOINT_UNSUPPORTED_VERSION, PARKED_RESUME_STARTUP_FAILED, RESUME_POLICY_FOLD_CODE, isDecideParkMovedCode, refusalSaysStillPending } from '../engineErrorCodes.js';
 import { publishQuestionFrame, registerLocalQuestionResponder, hasQuestionOverlay, } from '../liveQuestionStore.js';
 import { hostLog } from '../host.js';
 import { surfaceFsApprovalAndDecide } from './toolApprovalWire.js';
@@ -40,21 +40,33 @@ function alreadyResolvedReasonToken(reason) {
     const r = reason.toLowerCase();
     return ALREADY_RESOLVED_REASON_TOKENS.find((t) => r.includes(t));
 }
-function isAlreadyResolvedFailure(outcome) {
+export function isAlreadyResolvedFailure(outcome) {
+    try {
+        return alreadyResolvedFailureVerdict(outcome);
+    }
+    catch {
+        return false;
+    }
+}
+function alreadyResolvedFailureVerdict(outcome) {
+    if (typeof outcome !== 'object' || outcome === null)
+        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))
+    if ('errorCode' in outcome && isCodeClassifiedGateFailure(outcome.errorCode, Object.hasOwn(outcome, 'retriable') && outcome.retriable === true))
         return false;
     if ('errorCode' in outcome && isDecideParkMovedCode(outcome.errorCode))
         return true;
+    if ('errorCode' in outcome && outcome.errorCode === ASK_GONE)
+        return true;
     return isAlreadyResolvedGateReason(outcome.reason);
 }
-export function isGateStandingErrorCode(code) {
-    return code === RESUME_POLICY_FOLD_CODE || code === 'corrupt';
+export function isGateStandingErrorCode(code, retriable) {
+    return code === RESUME_POLICY_FOLD_CODE || code === 'corrupt' || (code === CHECKPOINT_UNSUPPORTED_VERSION && retriable === true);
 }
-export function isCodeClassifiedGateFailure(code) {
-    return isGateStandingErrorCode(code) || code === PARKED_RESUME_STARTUP_FAILED;
+export function isCodeClassifiedGateFailure(code, retriable) {
+    return isGateStandingErrorCode(code, retriable) || code === PARKED_RESUME_STARTUP_FAILED;
 }
 export function toAnsweredOutput(questions, answer) {
     const answers = {};
@@ -153,6 +165,7 @@ async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal, parkGat
         const code = e instanceof HitlSafetyError && isGateFailureCode(e.code) ? e.code : undefined;
         const currentPending = readDecideCurrentPending(e);
         const wireCode = readWireErrorCode(e);
+        const wireRetriable = typeof e === 'object' && e !== null && refusalSaysStillPending(e);
         return {
             kind: 'failed',
             stage: 'decide',
@@ -162,6 +175,7 @@ async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal, parkGat
             ...(e instanceof DecideTransportRetryExhaustedError ? { retryExhausted: true } : {}),
             ...(currentPending !== undefined ? { currentPending } : {}),
             ...(wireCode !== undefined ? { errorCode: wireCode } : {}),
+            ...(wireRetriable ? { retriable: true } : {}),
         };
     }
 }

package/dist/hitl/persistedRulesWire.d.ts

@@ -50,6 +50,9 @@ export type RulesFailure = {
 } | {
     kind: 'forbidden';
     message: string;
+} | {
+    kind: 'operators-unconfigured';
+    message: string;
 } | {
     kind: 'body-shape';
     message: string;
@@ -100,7 +103,7 @@ export type PersistedRuleWriteBehavior = (typeof PERSISTED_RULE_WRITE_BEHAVIORS)
 export type PersistedRuleWriteRequest = RuleWriteRequest;
 export type PersistedRuleWriteWireResult = RuleWriteResult;
 export type PersistedRuleLiveness = RemovalLiveness;
-export declare const PERSISTED_RULE_WRITE_REFUSAL_CAUSES: readonly ["unwritable_behavior", "unreadable_identity", "unusable_principal", "client_too_old", "field_refused", "body_shape", "operator_only", "store_absent", "lane_too_old", "route_absent", "not_committed"];
+export declare const PERSISTED_RULE_WRITE_REFUSAL_CAUSES: readonly ["unwritable_behavior", "unreadable_identity", "unusable_principal", "client_too_old", "field_refused", "body_shape", "operator_only", "operators_unconfigured", "store_absent", "lane_too_old", "route_absent", "not_committed"];
 export type PersistedRuleWriteRefusalCause = (typeof PERSISTED_RULE_WRITE_REFUSAL_CAUSES)[number];
 export declare const PERSISTED_RULE_WRITE_UNKNOWN_REASONS: readonly ["indeterminate", "malformed_result", "identity_mismatch", "unattributed_method_refusal", "unclassified"];
 export type PersistedRuleWriteUnknownReason = (typeof PERSISTED_RULE_WRITE_UNKNOWN_REASONS)[number];

package/dist/hitl/persistedRulesWire.js

@@ -1,5 +1,7 @@
 import { engineCapTrue } from '../engineCapsCache.js';
+import { CORE_RULE_BEHAVIORS } from '../generated/engineFactTables.js';
 import { wireFailureShapeOf } from '../wireFailureShape.js';
+import { CAPABILITY_OPERATOR_PRINCIPALS_REQUIRED } from '../engineErrorCodes.js';
 import { hostLog } from '../host.js';
 import { observedPermissionRulesWrite, permissionRulesWriteAvailable } from '../permissionRulesWriteCapability.js';
 import { readToolApprovalRespondAck } from './toolApprovalWire.js';
@@ -7,7 +9,7 @@ export function persistedRulesLaneAvailable(baseUrl) {
     return engineCapTrue(baseUrl, 'permissionRules');
 }
 export function persistedRulesGovernanceAvailable(baseUrl) {
-    return engineCapTrue(baseUrl, 'permissionRulesRevoke') && engineCapTrue(baseUrl, 'permissionRules');
+    return engineCapTrue(baseUrl, 'permissionRules');
 }
 export function persistedRulesWriteAvailable(baseUrl) {
     return permissionRulesWriteAvailable(observedPermissionRulesWrite(baseUrl ?? ''));
@@ -66,6 +68,8 @@ export function classifyRulesFailure(e) {
         return { kind: 'too-many-candidates', message };
     if (status === 403 && errorCode === 'auth.operator_only')
         return { kind: 'forbidden', message };
+    if (errorCode === CAPABILITY_OPERATOR_PRINCIPALS_REQUIRED)
+        return { kind: 'operators-unconfigured', message };
     if (status === 405) {
         return errorCode === 'method_not_allowed'
             ? { kind: 'method-unsupported', message }
@@ -73,7 +77,7 @@ export function classifyRulesFailure(e) {
     }
     return { kind: 'error', message };
 }
-export const PERSISTED_RULE_BEHAVIORS = Object.freeze(['deny', 'ask', 'allow']);
+export const PERSISTED_RULE_BEHAVIORS = CORE_RULE_BEHAVIORS;
 const BEHAVIOR_SET = new Set(PERSISTED_RULE_BEHAVIORS);
 function rowStr(row, key) {
     if (typeof row !== 'object' || row === null || Array.isArray(row))
@@ -221,6 +225,7 @@ export const PERSISTED_RULE_WRITE_REFUSAL_CAUSES = Object.freeze([
     'field_refused',
     'body_shape',
     'operator_only',
+    'operators_unconfigured',
     'store_absent',
     'lane_too_old',
     'route_absent',
@@ -242,6 +247,8 @@ function writeOutcomeFromFailure(failure) {
             return { status: 'refused', cause: 'body_shape', message };
         case 'forbidden':
             return { status: 'refused', cause: 'operator_only', message };
+        case 'operators-unconfigured':
+            return { status: 'refused', cause: 'operators_unconfigured', message };
         case 'lane-unavailable':
             return { status: 'refused', cause: 'store_absent', message };
         case 'method-unsupported':

package/dist/hitl/planReviewWire.d.ts

@@ -43,7 +43,7 @@ export interface PlanReviewOutcomeMeta {
     decision: 'approve' | 'reject';
     effect: PlanReviewDecisionEffect;
 }
-export declare function planReviewOutcomeTail(taskId: string, decision: 'approve' | 'reject', effect: PlanReviewDecisionEffect): string;
+export declare function planReviewOutcomeTail(taskId: string, decision: 'approve' | 'reject', effect: PlanReviewDecisionEffect, cause?: 'stored_form_unsupported'): string;
 export type PlanReviewWireClient = {
     assistant: Pick<AgentClient['assistant'], 'planReview'>;
     runs: Pick<AgentClient['runs'], 'get'>;

package/dist/hitl/planReviewWire.js

@@ -6,6 +6,8 @@ import { engineWireTarget } from '../engineWireTarget.js';
 import { enqueuePlanReviewOutcome } from '../notifications.js';
 import { corruptStoredRowContent, corruptStoredRowWhere } from '../wireErrorTriage.js';
 import { decideFailureNote } from '../decideFailureNote.js';
+import { checkpointUnsupportedVersionContent, checkpointUnsupportedVersionFromError } from '../resumeRefusalCopy.js';
+import { REQUEST_FIELD_CONFLICT, isUnavailableFaceCode } from '../engineErrorCodes.js';
 import { denyReasonForWire, isPlanReviewModeAfter } from './hitlBridge.js';
 import { engineCapString } from '../engineCapsCache.js';
 import { planReviewQuestionId, REOPEN_ID_TAIL, taskIdFromPlanReviewQuestionId } from './gateIdentity.js';
@@ -303,7 +305,10 @@ export function armPlanReviewApproval(result, sessionKey, opts) {
         return false;
     }
 }
-export function planReviewOutcomeTail(taskId, decision, effect) {
+export function planReviewOutcomeTail(taskId, decision, effect, cause) {
+    if (effect === 'still_parked' && cause === 'stored_form_unsupported') {
+        return `Do not tell the user the plan was ${decision === 'approve' ? 'approved' : 'rejected'}, and do not ${decision} it again: deciding again will not take effect while it is stored in this form. Tell the user the way forward this outcome gives — cancel this task's run, then submit the work again as a new task.`;
+    }
     switch (effect) {
         case 'took_effect':
             return decision === 'approve'
@@ -500,6 +505,7 @@ function planReviewClientsFor(resolved) {
 async function decidePlanReviewInner(taskId, decision, permissionModeAfter, dispatchNo, releaseLatch, settle, opts, gateBefore) {
     let outcome;
     let effect = 'unconfirmed';
+    let stillParkedCause;
     let stillParkedProven = false;
     let statusSeen;
     const wire = opts?.wire;
@@ -543,7 +549,7 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                 }
                 catch (e1) {
                     const conflict = e1;
-                    if (mode === 'default' && conflict?.status === 400 && conflict?.errorCode === 'request.field_conflict') {
+                    if (mode === 'default' && conflict?.status === 400 && conflict?.errorCode === REQUEST_FIELD_CONFLICT) {
                         hostLog('debug', 'planReviewWire: permissionModeAfter "default" refused as not applicable — re-sending the approval without the key (same meaning)');
                         body = await sendOnce(undefined, () => client.assistant.planReview(taskId, reason !== undefined ? { decision, reason } : { decision }));
                     }
@@ -610,7 +616,7 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                 const status = e?.status;
                 const refusedCode = e?.errorCode;
                 const noAnswer = typeof status === 'number' || typeof e !== 'object' ? null : noAnswerKindOf(e);
-                if (status === 400 && refusedCode === 'request.field_conflict' && permissionModeAfter === 'acceptEdits') {
+                if (status === 400 && refusedCode === REQUEST_FIELD_CONFLICT && permissionModeAfter === 'acceptEdits') {
                     hostLog('debug', 'planReviewWire: approve + acceptEdits refused (request.field_conflict) — NOT re-sent with a different mode');
                     effect = 'still_parked';
                     stillParkedProven = true;
@@ -625,6 +631,14 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                         `This ${decision} was not applied: the engine no longer has a pending plan review for this task — an earlier decision most likely already went through (or the review expired). ` +
                             'This is NOT a rejection of the plan and NOT a failure of the task; the answer just given simply had nothing left to act on.';
                 }
+                else if (checkpointUnsupportedVersionFromError(e) !== null) {
+                    const cu = checkpointUnsupportedVersionFromError(e);
+                    hostLog('debug', `planReviewWire: ${decision} → 409 checkpoint.unsupported_version (the server cannot continue this parked review in its stored form; still pending)`);
+                    effect = 'still_parked';
+                    stillParkedProven = true;
+                    stillParkedCause = 'stored_form_unsupported';
+                    outcome = `This ${decision} was not applied. ${checkpointUnsupportedVersionContent(cu, { parkKind: 'plan_review', runId: taskId })}`;
+                }
                 else if (typeof status === 'number' && corruptStoredRowWhere(e) !== undefined) {
                     const where = corruptStoredRowWhere(e);
                     hostLog('debug', `planReviewWire: ${decision} → ${String(status)} corrupt (stored resume context unreadable)`);
@@ -634,7 +648,7 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                 else if (typeof status === 'number') {
                     const msg = e instanceof Error ? e.message : String(e);
                     hostLog('debug', `planReviewWire: ${decision} → ${status} ${msg.slice(0, 200)}`);
-                    effect = status >= 400 && status < 500 ? 'not_applied' : 'unconfirmed';
+                    effect = (status >= 400 && status < 500) || (typeof refusedCode === 'string' && isUnavailableFaceCode(refusedCode)) ? 'not_applied' : 'unconfirmed';
                     outcome = `${`The plan_review decision failed: HTTP ${status} ${msg}`.trim()}${decideFailureNote(e)}`;
                 }
                 else if (noAnswer === 'time-limit' || noAnswer === 'deadline') {
@@ -651,7 +665,7 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
             }
         }
     }
-    const tail = planReviewOutcomeTail(taskId, decision, effect);
+    const tail = planReviewOutcomeTail(taskId, decision, effect, stillParkedCause);
     const prompt = `<plan-review-outcome>\n${outcome}\n${tail}\n</plan-review-outcome>`;
     const onOutcome = opts?.onOutcome;
     settle(effect === 'not_sent' || (effect === 'still_parked' && stillParkedProven));

package/dist/hitl/replayedApproval.d.ts

@@ -0,0 +1,21 @@
+import { type ApprovalsListEnvelope, type CrashConvergedRow } from './crashConverged.js';
+export type ReplayedApprovalDisposition = {
+    readonly kind: 'live';
+    readonly basis: 'live_leg' | 'preamble' | 'pending_list';
+} | {
+    readonly kind: 'decided';
+    readonly cause?: CrashConvergedRow['cause'];
+} | {
+    readonly kind: 'unknown';
+    readonly why: 'unreadable_frame' | 'no_approval_id' | 'not_read' | 'list_unreadable' | 'list_not_reported' | 'list_incomplete';
+};
+export interface ReplayPendingBasis {
+    readonly preamble?: ReadonlySet<string>;
+    readonly approvals?: {
+        readonly read: 'ok';
+        readonly body: ApprovalsListEnvelope;
+    } | {
+        readonly read: 'failed';
+    };
+}
+export declare function replayedApprovalDisposition(frame: object, basis: ReplayPendingBasis): ReplayedApprovalDisposition;

package/dist/hitl/replayedApproval.js

@@ -0,0 +1,89 @@
+import { hasLedgerPositionKey } from './gateLedger.js';
+import { readLivePendingRows } from './livePendingAsk.js';
+import { projectCrashConverged } from './crashConverged.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' });
+function approvalIdOf(frame) {
+    const v = frame.approvalId;
+    return typeof v === 'string' && v !== '' ? v : undefined;
+}
+function crashConvergedCauseOf(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 undefined;
+}
+export function replayedApprovalDisposition(frame, basis) {
+    let approvalId;
+    try {
+        if (typeof frame !== 'object' || frame === null)
+            return unknown('unreadable_frame');
+        if (!hasLedgerPositionKey(frame))
+            return live('live_leg');
+        approvalId = approvalIdOf(frame);
+    }
+    catch {
+        return unknown('unreadable_frame');
+    }
+    if (approvalId === undefined)
+        return unknown('no_approval_id');
+    let b;
+    let inPreamble = false;
+    try {
+        b = typeof basis === 'object' && basis !== null ? basis : undefined;
+        inPreamble = b?.preamble?.has(approvalId) === true;
+    }
+    catch {
+        inPreamble = false;
+    }
+    if (inPreamble)
+        return live('preamble');
+    let approvals;
+    try {
+        approvals = b?.approvals;
+    }
+    catch {
+        return unknown('not_read');
+    }
+    if (approvals === undefined || approvals === null)
+        return unknown('not_read');
+    let body;
+    try {
+        if (approvals.read !== 'ok')
+            return unknown('list_unreadable');
+        body = approvals.body;
+    }
+    catch {
+        return unknown('list_unreadable');
+    }
+    let reading;
+    try {
+        reading = readLivePendingRows(body);
+    }
+    catch {
+        return unknown('list_unreadable');
+    }
+    if (reading.kind === 'present' && reading.rows.some((r) => r.approvalId === approvalId))
+        return live('pending_list');
+    let cause;
+    try {
+        cause = crashConvergedCauseOf(body, approvalId);
+    }
+    catch {
+        cause = undefined;
+    }
+    if (cause !== undefined)
+        return decided(cause);
+    if (reading.kind === 'not_reported')
+        return unknown('list_not_reported');
+    if (reading.kind === 'malformed')
+        return unknown('list_unreadable');
+    if (reading.dropped > 0)
+        return unknown('list_incomplete');
+    return decided();
+}

package/dist/hitl/sessionPolicyDeliverable.js

@@ -1,5 +1,7 @@
 import { CONFIG_LEGACY_TOOL_NAME, RULES_LEGACY_TOOL_NAME } from '../engineErrorCodes.js';
 import { rosterMountedNames } from './rosterMountedNames.js';
+import { ruleCompileVerdict } from '../ruleCompileVerdict.js';
+import { protocolSegmentOf } from '../protocolSegment.js';
 import { PREFIXES_IN_PROSE, REFUSED_NAME_CLASSES, REFUSED_NAME_FIX, RULES_LEGACY_TOOL_NAME_WRITE_NOTE } from './refusedToolNameProse.js';
 import { CORE_PROTOCOL_PREFIXES, CORE_RETIRED_TOOL_CURRENT_NAMES } from '../generated/toolNameTables.js';
 const COVERING_NAMESPACE_PREFIXES = CORE_PROTOCOL_PREFIXES;
@@ -9,7 +11,7 @@ const WITHHELD_NOTICE = {
     qualified_deny: 'Not written to this session’s rule record: that record holds whole tool names and command names only, and this rule has a part in parentheses it cannot carry — recording just the name could block more than this rule does.',
     peer_wide: 'Not written to this session’s rule record: this rule names a server or agent peer without naming one of its tools, and an engine that matches that record by exact tool name would block none of that peer’s tools.',
     wildcard: 'Not written to this session’s rule record: this rule uses a wildcard (*), and an engine that matches that record by exact tool name would block none of the tools it covers.',
-    not_a_tool_name: 'Not written to this session’s rule record: this entry is not exactly one tool name — it is empty, not text, or has spaces around the name.',
+    not_a_tool_name: 'Not written to this session’s rule record: this entry is not exactly one tool name — it is empty, not text, has spaces around the name, is not a single tool name in rule syntax (for example it contains a backslash or a parenthesis, or is longer than a rule can be), or spells its server or agent peer part in a way the engine never uses when naming tools (for example with a dot or a space), so no tool would ever match it.',
     legacy_tool_name: `Not written to this session’s rule record: unless a tool by exactly this name is available, the engine refuses it — it is a retired tool name, or it contains "__" but does not start with ${PREFIXES_IN_PROSE} — and with it in that record every later run of this session would fail at startup until that entry is removed from the record. ${REFUSED_NAME_FIX}`,
     not_in_roster: 'Not written to this session’s rule record: the tool roster supplied for this check has no tool by exactly this name, as a name or an alias, with letter case counted — it may be misspelled, or name a tool this deployment does not provide — so recorded as it is it would block nothing here.',
 };
@@ -97,7 +99,23 @@ export function sessionPolicyDeliverable(behavior, rules, opts) {
             withheld.push({ rule: '', why: 'not_a_tool_name' });
             continue;
         }
-        const why = withheldWhyOf(r) ?? (mounted !== undefined && !mounted.has(r) ? 'not_in_roster' : undefined);
+        let why = withheldWhyOf(r);
+        if (why === undefined) {
+            const grammar = ruleCompileVerdict(r, 'deny');
+            if (grammar === 'unknown')
+                return unreadable();
+            if (grammar === 'refused')
+                why = 'not_a_tool_name';
+        }
+        if (why === undefined && COVERING_NAMESPACE_PREFIXES.some((p) => r.startsWith(p))) {
+            const segment = protocolSegmentOf(r);
+            if (segment.kind === 'unknown')
+                return unreadable();
+            if (segment.kind === 'unminted')
+                why = 'not_a_tool_name';
+        }
+        if (why === undefined && mounted !== undefined && !mounted.has(r))
+            why = 'not_in_roster';
         if (why === undefined)
             exact.push(r);
         else {

package/dist/hitl/sessionPolicyWire.d.ts

@@ -1,6 +1,8 @@
 import type { SessionPermissionRules, StoredSessionRules } from '@sema-agent/sdk';
 import type { SessionPolicyReading } from '../sessionPolicyCapability.js';
 import type { ToolRosterView } from '../toolRoster.js';
+import { CORE_RULE_TOOL_NAME_VERDICTS } from '../generated/engineFactTables.js';
+export type LegacyToolNameVerdict = Exclude<(typeof CORE_RULE_TOOL_NAME_VERDICTS)[number], 'current'>;
 export interface SessionPolicyFacade {
     getPolicy(sessionId: string, opts?: {
         signal?: AbortSignal;
@@ -43,6 +45,8 @@ export type SessionPolicyFailure = {
     message: string;
     field?: SessionPolicyRemovedEntry['field'];
     name?: string;
+    verdict?: LegacyToolNameVerdict;
+    currentName?: string;
 } | {
     kind: 'unauthorized';
     message: string;
@@ -95,6 +99,8 @@ export type SessionPolicyTightenOutcome = {
     message: string;
     field?: SessionPolicyRemovedEntry['field'];
     name?: string;
+    verdict?: LegacyToolNameVerdict;
+    currentName?: string;
     alreadyInRecord?: boolean;
 } | {
     kind: 'unknown';
@@ -105,6 +111,11 @@ export declare function tightenSessionPolicy(facade: SessionPolicyFacade, req: S
     signal?: AbortSignal;
 }): Promise<SessionPolicyTightenOutcome>;
 export declare function sessionPolicyTightenNotice(outcome: SessionPolicyTightenOutcome): string;
+export declare function sessionPolicyReadNotice(outcome: Exclude<SessionPolicyReadOutcome, {
+    kind: 'present';
+}> | {
+    kind: 'no_target';
+}): string;
 export interface SessionPolicyRemovedEntry {
     readonly field: 'toolDeny' | 'toolAllow';
     readonly rule: string;
@@ -143,6 +154,8 @@ export type SessionPolicyRemovalOutcome = {
     message: string;
     field?: SessionPolicyRemovedEntry['field'];
     name?: string;
+    verdict?: LegacyToolNameVerdict;
+    currentName?: string;
 };
 export type SessionPolicyRosterRequiredWhy = 'absent' | 'unreadable';
 export declare function removeRefusedSessionRules(facade: SessionPolicyFacade, sessionId: string, roster: ToolRosterView | undefined, opts?: {