@sema-agent/client-core 0.98.0 → 0.100.0

package/dist/hitl/hitlBridge.js

@@ -7,8 +7,9 @@ import { ownDataField, readOwnDataValue } from '../ownKey.js';
 import { PROTOCOL_ERROR_NAME, THROWN_SLOT_UNREADABLE, protocolErrorNameReading, readBlockedBy, readThrownSlot, thrownIsInstanceOf, wireFailureTextsOf } from '../wireFailureShape.js';
 import { APPROVAL_BINDING_MISMATCH, CHECKPOINT_INVALID_OUTCOME, RESUME_POLICY_FOLD_CODE } from '../engineErrorCodes.js';
 import { suspendedReopenOf } from './suspendedReopen.js';
+import { closeDecisionOp, decisionLedgerKeysOf, openDecisionOp } from './decisionLedger.js';
 export const DEFAULT_DENY_REASON = 'The user rejected this tool use';
-const MAX_DENY_REASON_CHARS = 4096;
+export const MAX_DENY_REASON_CHARS = 4096;
 export function denyReasonForWire(reason, tag) {
     if (typeof reason !== 'string')
         return undefined;
@@ -146,13 +147,13 @@ function isTransientDecideTransportFailure(e, depth = 0) {
         return false;
     if (thrownIsInstanceOf(e, HitlSafetyError))
         return false;
-    const status = readThrownSlot(e, 'status');
+    const status = readThrownSlot(e, 'status', 'data');
     if (status === THROWN_SLOT_UNREADABLE || typeof status === 'number')
         return false;
     const name = readThrownSlot(e, 'name');
     if (name === 'TimeoutError' || name === 'AbortError')
         return true;
-    const code = readThrownSlot(e, 'code');
+    const code = readThrownSlot(e, 'code', 'data');
     if (typeof code === 'string' && TRANSIENT_NETWORK_CODES.has(code))
         return true;
     const message = readThrownSlot(e, 'message');
@@ -172,6 +173,7 @@ class DecideSpan {
     owner;
     observer;
     identity;
+    ledgerOp;
     attempts = 0;
     ok = false;
     retryExhausted = false;
@@ -189,9 +191,11 @@ class DecideSpan {
         return mine === undefined || (mine.sessionId === identity.sessionId && mine.boundCallId === identity.boundCallId);
     }
     async run(identity, send) {
-        if (this.observer !== undefined && this.identity === undefined) {
+        if (this.identity === undefined) {
             this.identity = identity;
-            notifyDecideObserver(this.observer, Object.freeze({ ...this.identity, phase: 'start' }));
+            this.ledgerOp = openDecideLedgerOp(identity);
+            if (this.observer !== undefined)
+                notifyDecideObserver(this.observer, Object.freeze({ ...this.identity, phase: 'start' }));
         }
         this.inFlight++;
         const tally = { attempts: 0 };
@@ -224,11 +228,16 @@ class DecideSpan {
         if (this.ended)
             return;
         this.ended = true;
+        if (this.ledgerOp !== undefined)
+            closeDecisionOp(this.ledgerOp, 'package');
         if (this.observer === undefined || this.identity === undefined)
             return;
         notifyDecideObserver(this.observer, Object.freeze({ ...this.identity, phase: 'end', ok: this.ok, attempts: this.attempts, retryExhausted: this.retryExhausted }));
     }
 }
+function openDecideLedgerOp(identity) {
+    return openDecisionOp('tool_approval', decisionLedgerKeysOf({ taskId: identity.taskId, callId: identity.boundCallId }), 'posting', true);
+}
 function wireOptsOf(opts) {
     if (opts === undefined || opts.operation === undefined)
         return opts;
@@ -408,10 +417,10 @@ export class HitlBridge {
         }
         const observer = this.decideObserver;
         const tally = { attempts: 0 };
-        if (observer === undefined)
-            return this.decideRawAttempts(sessionId, decision, opts, tally);
         const identity = this.decideIdentityOf(sessionId, decision);
-        notifyDecideObserver(observer, Object.freeze({ ...identity, phase: 'start' }));
+        const ledgerOp = openDecideLedgerOp(identity);
+        if (observer !== undefined)
+            notifyDecideObserver(observer, Object.freeze({ ...identity, phase: 'start' }));
         let ok = false;
         let retryExhausted = false;
         try {
@@ -424,7 +433,10 @@ export class HitlBridge {
             throw e;
         }
         finally {
-            notifyDecideObserver(observer, Object.freeze({ ...identity, phase: 'end', ok, attempts: tally.attempts, retryExhausted }));
+            closeDecisionOp(ledgerOp, 'package');
+            if (observer !== undefined) {
+                notifyDecideObserver(observer, Object.freeze({ ...identity, phase: 'end', ok, attempts: tally.attempts, retryExhausted }));
+            }
         }
     }
     decideIdentityOf(sessionId, decision) {

package/dist/hitl/persistedRulesWire.d.ts

@@ -1,4 +1,5 @@
 import type { CcImportLayer, CcImportPrepareResult, CcImportRedeemResult, PersistedRule, RuleBehavior, RuleListParams, RuleListResult, RuleRevokeRequest, RemovalLiveness, RuleRevokeResult, RuleWriteRequest, RuleWriteResult } from '@sema-agent/sdk';
+import type { UiLanguage } from '../env/uiLanguage.js';
 export interface RulesFacade {
     list(params?: RuleListParams, opts?: {
         signal?: AbortSignal;
@@ -93,9 +94,9 @@ export interface PersistedRuleOriginsRow {
         readonly origin?: string | undefined;
     }[] | undefined;
 }
-export declare function persistedRuleAddOriginLabel(origin: string | undefined): string;
-export declare function persistedRuleOriginsLabel(rule: PersistedRuleOriginsRow): string;
-export declare function persistedRuleScopeLabel(scope: string | undefined): string;
+export declare function persistedRuleAddOriginLabel(origin: string | undefined, lang?: UiLanguage): string;
+export declare function persistedRuleOriginsLabel(rule: PersistedRuleOriginsRow, lang?: UiLanguage): string;
+export declare function persistedRuleScopeLabel(scope: string | undefined, lang?: UiLanguage): string;
 export type PersistedRuleRevokeOutcomeWord = 'removed' | 'nothing-written' | 'unknown-status';
 export interface PersistedRuleRevokeResultBody {
     readonly status?: string | undefined;
@@ -107,11 +108,11 @@ export interface PersistedRuleRevokeOutcome {
     readonly notice: string;
     readonly change: string;
 }
-export declare function persistedRuleRevokeOutcome(ruleText: string | undefined, result: PersistedRuleRevokeResultBody | undefined): PersistedRuleRevokeOutcome;
+export declare function persistedRuleRevokeOutcome(ruleText: string | undefined, result: PersistedRuleRevokeResultBody | undefined, lang?: UiLanguage): PersistedRuleRevokeOutcome;
 export interface PersistedRuleMatchRow {
     readonly match?: string | undefined;
 }
-export declare function persistedRuleMatchLabel(ruleOrMatch: string | PersistedRuleMatchRow | undefined): string;
+export declare function persistedRuleMatchLabel(ruleOrMatch: string | PersistedRuleMatchRow | undefined, lang?: UiLanguage): string;
 export declare function revokeTargetFromPersistedRule(rule: unknown, opts?: {
     principal?: string;
 }): RuleRevokeRequest | undefined;

package/dist/hitl/persistedRulesWire.js

@@ -4,6 +4,7 @@ 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 { msg, renderMessage } from '../i18n/translate.js';
 import { guardedRead, readOwnDataValue } from '../ownKey.js';
 import { observedPermissionRulesWrite, permissionRulesWriteAvailable } from '../permissionRulesWriteCapability.js';
 import { isToolApprovalRespondReplayed, readToolApprovalRespondAck } from './toolApprovalWire.js';
@@ -114,123 +115,104 @@ export const PERSISTED_RULE_BEHAVIOR_UNKNOWN = '(unknown)';
 export function persistedRuleBehaviorLabel(rule) {
     return rowStr(rule, 'behavior') ?? PERSISTED_RULE_BEHAVIOR_UNKNOWN;
 }
-const PERSISTED_RULE_ORIGIN_PHRASES = Object.freeze({
-    user: 'added by you',
-    'imported-cc': 'imported',
-    starter: 'preset',
+const PERSISTED_RULE_ORIGIN_KEYS = Object.freeze({
+    user: 'rules.origin.user',
+    'imported-cc': 'rules.origin.importedCc',
+    starter: 'rules.origin.starter',
 });
-const UNKNOWN_ORIGIN_PHRASE = 'an origin this build does not know';
-const NO_ORIGIN_PHRASE = 'unknown origin';
+const UNKNOWN_ORIGIN_KEY = 'rules.origin.unknownWord';
+const NO_ORIGIN_KEY = 'rules.origin.none';
+function originKeyOf(origin) {
+    return typeof origin === 'string' && Object.hasOwn(PERSISTED_RULE_ORIGIN_KEYS, origin) ? PERSISTED_RULE_ORIGIN_KEYS[origin] : UNKNOWN_ORIGIN_KEY;
+}
 function ownSlot(o, key) {
     if (typeof o !== 'object' || o === null)
         return undefined;
     return guardedRead(() => readOwnDataValue(o, key));
 }
 const ORIGINS_READ_MAX = 256;
-export function persistedRuleAddOriginLabel(origin) {
-    return typeof origin === 'string' && Object.hasOwn(PERSISTED_RULE_ORIGIN_PHRASES, origin)
-        ? PERSISTED_RULE_ORIGIN_PHRASES[origin]
-        : UNKNOWN_ORIGIN_PHRASE;
+export function persistedRuleAddOriginLabel(origin, lang) {
+    return renderMessage(msg(originKeyOf(origin)), lang);
 }
-export function persistedRuleOriginsLabel(rule) {
+export function persistedRuleOriginsLabel(rule, lang) {
     const adds = ownSlot(rule, 'adds');
     const isArr = guardedRead(() => (Array.isArray(adds) ? true : undefined));
     if (isArr !== true)
-        return NO_ORIGIN_PHRASE;
+        return renderMessage(msg(NO_ORIGIN_KEY), lang);
     const lenRaw = ownSlot(adds, 'length');
     const len = typeof lenRaw === 'number' && Number.isSafeInteger(lenRaw) && lenRaw > 0 ? Math.min(lenRaw, ORIGINS_READ_MAX) : 0;
     const seen = [];
     for (let i = 0; i < len; i++) {
         const origin = ownSlot(ownSlot(adds, String(i)), 'origin');
-        const phrase = persistedRuleAddOriginLabel(typeof origin === 'string' ? origin : undefined);
-        if (!seen.includes(phrase))
-            seen.push(phrase);
+        const key = originKeyOf(typeof origin === 'string' ? origin : undefined);
+        if (!seen.includes(key))
+            seen.push(key);
     }
-    return seen.length === 0 ? NO_ORIGIN_PHRASE : seen.join(' + ');
+    return seen.length === 0 ? renderMessage(msg(NO_ORIGIN_KEY), lang) : seen.map((k) => renderMessage(msg(k), lang)).join(renderMessage(msg('rules.origin.join'), lang));
 }
-const UNKNOWN_SCOPE_PHRASE = 'a scope this build does not know';
-export function persistedRuleScopeLabel(scope) {
+const UNKNOWN_SCOPE_KEY = 'rules.scope.unknown';
+export function persistedRuleScopeLabel(scope, lang) {
     if (scope === 'global')
-        return 'all projects';
+        return renderMessage(msg('rules.scope.all'), lang);
     if (typeof scope === 'string' && scope.startsWith('project:') && scope.length > 'project:'.length) {
         const shown = displayUntrusted(scope.slice('project:'.length), { max: 400, blanks: true });
-        return shown === '' ? UNKNOWN_SCOPE_PHRASE : shown;
+        return shown === '' ? renderMessage(msg(UNKNOWN_SCOPE_KEY), lang) : shown;
     }
-    return UNKNOWN_SCOPE_PHRASE;
+    return renderMessage(msg(UNKNOWN_SCOPE_KEY), lang);
 }
-const PERSISTED_RULE_REVOKE_LINES = Object.freeze({
+const PERSISTED_RULE_REVOKE_KEYS = Object.freeze({
     removed: {
-        yes: {
-            notice: '{rule}: a tombstone was written, but the rule is still live — it was approved again during the call.',
-            change: 'Revoked saved rule {rule} (still live — approved again meanwhile)',
-        },
-        unknown: {
-            notice: '{rule}: a tombstone was written, but whether the rule is still live could not be confirmed — treat it as still in effect and check the list.',
-            change: 'Revoked saved rule {rule} (liveness could not be confirmed — treated as still in effect)',
-        },
-        no: { notice: 'Removed {rule}.', change: 'Revoked saved rule {rule}' },
+        yes: { notice: 'rules.revoke.removed.yes.notice', change: 'rules.revoke.removed.yes.change' },
+        unknown: { notice: 'rules.revoke.removed.unknown.notice', change: 'rules.revoke.removed.unknown.change' },
+        no: { notice: 'rules.revoke.removed.no.notice', change: 'rules.revoke.removed.no.change' },
     },
     'nothing-written': {
-        yes: {
-            notice: '{rule}: nothing was written, and the rule is still live — it was not removed; check the list.',
-            change: 'Removing saved rule {rule} wrote nothing — the rule is still live',
-        },
-        unknown: {
-            notice: '{rule}: nothing was written, and whether the rule is still live could not be confirmed — treat it as still in effect and check the list.',
-            change: 'Removing saved rule {rule} wrote nothing — liveness could not be confirmed',
-        },
-        no: { notice: '{rule}: nothing to remove.', change: 'Removing saved rule {rule} wrote nothing (nothing to remove)' },
+        yes: { notice: 'rules.revoke.nothingWritten.yes.notice', change: 'rules.revoke.nothingWritten.yes.change' },
+        unknown: { notice: 'rules.revoke.nothingWritten.unknown.notice', change: 'rules.revoke.nothingWritten.unknown.change' },
+        no: { notice: 'rules.revoke.nothingWritten.no.notice', change: 'rules.revoke.nothingWritten.no.change' },
     },
 });
-const REVOKE_UNKNOWN_STATUS = Object.freeze({
-    absent: {
-        notice: '{rule}: the engine did not say what this removal did, so whether anything was removed is unclear — check the list.',
-        change: 'Removing saved rule {rule} came back without saying what it did',
-    },
-    unrecognised: {
-        notice: '{rule}: the engine answered with a status this build does not know, so whether anything was removed is unclear — check the list.',
-        change: 'Removing saved rule {rule} returned a status this build does not know',
-    },
-    liveness: { yes: ' It also reports the rule is still live.', unknown: ' Whether the rule is still live could not be confirmed either.', no: '' },
+const REVOKE_UNKNOWN_STATUS_KEYS = Object.freeze({
+    absent: { notice: 'rules.revoke.absent.notice', change: 'rules.revoke.absent.change' },
+    unrecognised: { notice: 'rules.revoke.unrecognised.notice', change: 'rules.revoke.unrecognised.change' },
+    liveness: { yes: 'rules.revoke.liveness.yes', unknown: 'rules.revoke.liveness.unknown', no: undefined },
 });
-const fillRule = (template, rule) => template.split('{rule}').join(rule);
-export function persistedRuleRevokeOutcome(ruleText, result) {
+export function persistedRuleRevokeOutcome(ruleText, result, lang) {
     const quoted = typeof ruleText === 'string' ? quoteUntrustedForSentence(ruleText, 120) : undefined;
-    const rule = quoted ?? 'this rule';
+    const rule = quoted ?? msg('rules.revoke.thisRule');
     const status = ownSlot(result, 'status');
     const rawLive = ownSlot(result, 'stillLive');
     const liveness = rawLive === 'yes' || rawLive === 'no' || rawLive === 'unknown' ? rawLive : 'unknown';
     if (status === 'removed' || status === 'no-op') {
         const outcome = status === 'removed' ? 'removed' : 'nothing-written';
-        const line = PERSISTED_RULE_REVOKE_LINES[outcome][liveness];
-        return Object.freeze({ outcome, liveness, notice: fillRule(line.notice, rule), change: fillRule(line.change, rule) });
+        const line = PERSISTED_RULE_REVOKE_KEYS[outcome][liveness];
+        return Object.freeze({ outcome, liveness, notice: renderMessage(msg(line.notice, { rule }), lang), change: renderMessage(msg(line.change, { rule }), lang) });
     }
-    const head = typeof status === 'string' && status !== '' ? REVOKE_UNKNOWN_STATUS.unrecognised : REVOKE_UNKNOWN_STATUS.absent;
+    const head = typeof status === 'string' && status !== '' ? REVOKE_UNKNOWN_STATUS_KEYS.unrecognised : REVOKE_UNKNOWN_STATUS_KEYS.absent;
+    const tailKey = REVOKE_UNKNOWN_STATUS_KEYS.liveness[liveness];
     return Object.freeze({
         outcome: 'unknown-status',
         liveness,
-        notice: `${fillRule(head.notice, rule)}${REVOKE_UNKNOWN_STATUS.liveness[liveness]}`,
-        change: fillRule(head.change, rule),
+        notice: `${renderMessage(msg(head.notice, { rule }), lang)}${tailKey === undefined ? '' : renderMessage(msg(tailKey), lang)}`,
+        change: renderMessage(msg(head.change, { rule }), lang),
     });
 }
-const PERSISTED_RULE_MATCH_LABELS = Object.freeze({
-    exact: 'exact match',
-    prefix: 'prefix match',
-    wildcard: 'wildcard match',
-    subpath: 'subpath match',
-    path: 'path match',
-    name: 'skill name match',
-    name_prefix: 'skill name prefix match',
-    host: 'web domain match (one host)',
-    subdomain: 'web domain match (every host under the domain)',
+const PERSISTED_RULE_MATCH_KEYS = Object.freeze({
+    exact: 'rules.match.exact',
+    prefix: 'rules.match.prefix',
+    wildcard: 'rules.match.wildcard',
+    subpath: 'rules.match.subpath',
+    path: 'rules.match.path',
+    name: 'rules.match.name',
+    name_prefix: 'rules.match.namePrefix',
+    host: 'rules.match.host',
+    subdomain: 'rules.match.subdomain',
 });
-export function persistedRuleMatchLabel(ruleOrMatch) {
+export function persistedRuleMatchLabel(ruleOrMatch, lang) {
     const word = typeof ruleOrMatch === 'string' ? ruleOrMatch : ownSlot(ruleOrMatch, 'match');
     if (typeof word !== 'string' || word === '')
-        return 'an unreported match form';
-    return Object.hasOwn(PERSISTED_RULE_MATCH_LABELS, word)
-        ? PERSISTED_RULE_MATCH_LABELS[word]
-        : 'a match form this build does not know';
+        return renderMessage(msg('rules.match.unreported'), lang);
+    return renderMessage(msg(Object.hasOwn(PERSISTED_RULE_MATCH_KEYS, word) ? PERSISTED_RULE_MATCH_KEYS[word] : 'rules.match.unknown'), lang);
 }
 export function revokeTargetFromPersistedRule(rule, opts) {
     const behavior = persistedRuleBehaviorOf(rule);

package/dist/hitl/planReviewWire.d.ts

@@ -37,6 +37,11 @@ export interface PlanReviewCardLike {
         }>;
     }>;
 }
+export interface PlanReviewQuestionIdReading {
+    readonly taskId: string;
+    readonly reopened: boolean;
+}
+export declare function planReviewTaskIdFromQuestionId(questionId: {} | null | undefined): PlanReviewQuestionIdReading | undefined;
 export declare function planReviewOfferedModeOf(card: string | PlanReviewCardLike): PlanReviewOfferedMode;
 export interface ArmPlanReviewOptions {
     submittedInPlanMode?: boolean;

package/dist/hitl/planReviewWire.js

@@ -11,6 +11,7 @@ import { readOwnDataNonEmptyString, readOwnDataValue } from '../ownKey.js';
 import { checkpointUnsupportedVersionContent, checkpointUnsupportedVersionFromError, resumeContextUnavailableContent, resumeContextUnavailableFromError } from '../resumeRefusalCopy.js';
 import { REQUEST_FIELD_CONFLICT } from '../engineErrorCodes.js';
 import { refusalDeliveryOf } from './decisionRefusal.js';
+import { __resetDecisionLedgerForTests, decisionInFlightOf, decisionKeyInFlight, decisionLedgerKeysOf, decisionOpsWithKey, decisionReadMark, dropDecisionOp, latestDecisionHandedMark, markLatestDecisionNotApplied, openDecisionOp, planDecisionKey, readMarkOf, settleDecisionOp, settleDecisionOpsOnGateLeft, } from './decisionLedger.js';
 import { denyReasonForWire, isPlanReviewModeAfter } from './hitlBridge.js';
 import { planReviewQuestionId, REOPEN_ID_TAIL, taskIdFromPlanReviewQuestionId } from './gateIdentity.js';
 import { notePlanReviewAnswered, notePlanReviewAnsweredFor, planReviewArmedKeyFor, waitForGateArmedFor, wasGateArmedFor, } from './armedGateRegistry.js';
@@ -300,6 +301,14 @@ function offeredModeFromLabels(card) {
         return 'two_choice';
     return undefined;
 }
+export function planReviewTaskIdFromQuestionId(questionId) {
+    if (typeof questionId !== 'string')
+        return undefined;
+    const taskId = taskIdFromPlanReviewQuestionId(questionId);
+    if (taskId === undefined)
+        return undefined;
+    return Object.freeze({ taskId, reopened: questionId.includes(REOPEN_ID_TAIL) });
+}
 function offeredModeFromQuestionId(questionId) {
     if (taskIdFromPlanReviewQuestionId(questionId) === undefined)
         return 'unknown';
@@ -449,42 +458,21 @@ function usablePlanReviewWireClient(client) {
     return clientHasVerbs(client, [['assistant', 'planReview'], ['runs', 'get']]);
 }
 const PLAN_REVIEW_INJECTED_REPULL_TIMEOUT_MS = 15_000;
-const planReviewDecisionOps = [];
-const MAX_PLAN_REVIEW_DECISION_OPS = 32;
-let planReviewLedgerClock = 0;
-let decideDispatchSeq = 0;
-function planReviewOpsOf(taskId) {
-    return planReviewDecisionOps.filter((op) => op.taskId === taskId);
-}
-function settlePlanReviewDecisionOp(op, by) {
-    if (op.settledAt !== null)
-        return;
-    op.settledAt = ++planReviewLedgerClock;
-    op.settler = by;
-}
-function pushPlanReviewDecisionOp(op) {
-    planReviewDecisionOps.push(op);
-    while (planReviewDecisionOps.length > MAX_PLAN_REVIEW_DECISION_OPS) {
-        let victim = planReviewDecisionOps.findIndex((o) => o.settledAt !== null && !o.ownCallOpen);
-        if (victim < 0)
-            victim = planReviewDecisionOps.findIndex((o) => o !== op && o.phase === 'handed');
-        if (victim < 0)
-            break;
-        planReviewDecisionOps.splice(victim, 1);
-    }
+function planReviewLedgerKeys(taskId) {
+    return taskId === '' ? [planDecisionKey('')] : decisionLedgerKeysOf({ taskId, planTaskId: taskId });
 }
-function dropPlanReviewDecisionOp(op) {
-    const i = planReviewDecisionOps.indexOf(op);
-    if (i >= 0)
-        planReviewDecisionOps.splice(i, 1);
+function planReviewOpsOf(taskId) {
+    return decisionOpsWithKey('plan_review', planDecisionKey(taskId));
 }
+let decideDispatchSeq = 0;
 function claimablePlanReviewDecisionOp(taskId) {
-    const open = planReviewDecisionOps.find((o) => o.taskId === taskId && o.phase === 'handed' && o.settledAt === null);
+    const ops = planReviewOpsOf(taskId);
+    const open = ops.find((o) => o.phase === 'handed' && o.settledAt === null);
     if (open !== undefined)
         return open;
     let leftBehind;
-    for (const o of planReviewDecisionOps) {
-        if (o.taskId !== taskId || o.phase !== 'handed' || o.settler !== 'gate_left')
+    for (const o of ops) {
+        if (o.phase !== 'handed' || o.settler !== 'gate_left')
             continue;
         if (leftBehind === undefined || o.handedAt > leftBehind.handedAt)
             leftBehind = o;
@@ -494,62 +482,47 @@ function claimablePlanReviewDecisionOp(taskId) {
 export function notePlanReviewDecisionHandedOver(taskId) {
     if (typeof taskId !== 'string' || taskId === '')
         return null;
-    if (planReviewDecisionOps.some((op) => op.taskId === taskId && op.settledAt === null))
+    if (planReviewOpsOf(taskId).some((op) => op.settledAt === null))
         return null;
-    const op = { taskId, handedAt: ++planReviewLedgerClock, settledAt: null, settler: null, phase: 'handed', notApplied: false, ownCallOpen: false };
-    pushPlanReviewDecisionOp(op);
+    const op = openDecisionOp('plan_review', planReviewLedgerKeys(taskId), 'handed', false);
     return {
         settle: () => {
             if (op.phase !== 'handed')
                 return;
-            settlePlanReviewDecisionOp(op, 'host');
+            settleDecisionOp(op, 'host');
         },
         revoke: () => {
             if (op.phase !== 'handed' || op.settledAt !== null)
                 return;
-            dropPlanReviewDecisionOp(op);
+            dropDecisionOp(op);
         },
     };
 }
 export function planReviewPendingReadMark() {
-    return ++planReviewLedgerClock;
+    return decisionReadMark();
 }
 export function planReviewDecisionInFlight(taskId, pendingReadStartedAt) {
     if (typeof taskId !== 'string' || taskId === '')
         return false;
-    const mark = typeof pendingReadStartedAt === 'number' && Number.isFinite(pendingReadStartedAt) ? pendingReadStartedAt : undefined;
-    return planReviewDecisionOps.some((op) => op.taskId === taskId && (op.settledAt === null || (mark !== undefined && op.settledAt > mark && !op.notApplied)));
+    return decisionKeyInFlight(planDecisionKey(taskId), readMarkOf(pendingReadStartedAt));
 }
 export function notePlanReviewDecisionNotApplied(taskId) {
     if (typeof taskId !== 'string' || taskId === '')
         return;
-    const ops = planReviewOpsOf(taskId);
-    if (ops.some((op) => op.settledAt === null))
-        return;
-    let latest;
-    for (const op of ops)
-        if (latest === undefined || op.handedAt > latest.handedAt)
-            latest = op;
-    if (latest !== undefined)
-        latest.notApplied = true;
+    markLatestDecisionNotApplied('plan_review', planDecisionKey(taskId));
 }
 export function notePlanReviewGateLeft(taskId) {
     if (typeof taskId !== 'string' || taskId === '')
         return;
-    for (const op of planReviewOpsOf(taskId))
-        settlePlanReviewDecisionOp(op, 'gate_left');
+    settleDecisionOpsOnGateLeft('plan_review', planDecisionKey(taskId));
 }
 export function latestPlanReviewDecisionMark(taskId) {
     if (typeof taskId !== 'string' || taskId === '')
         return null;
-    let mark = null;
-    for (const op of planReviewOpsOf(taskId))
-        if (mark === null || op.handedAt > mark)
-            mark = op.handedAt;
-    return mark;
+    return latestDecisionHandedMark('plan_review', planDecisionKey(taskId));
 }
 export function __resetPlanReviewDecisionLatchForTests() {
-    planReviewDecisionOps.length = 0;
+    __resetDecisionLedgerForTests('plan_review');
 }
 export async function decidePlanReview(taskId, decision, permissionModeAfter, opts) {
     return decidePlanReviewFor(taskId, decision, permissionModeAfter, opts, parkedGateIdentityOf(opts));
@@ -601,14 +574,13 @@ function bodySaysReparked(body) {
     }
 }
 async function decidePlanReviewFor(taskId, decision, permissionModeAfter, opts, gateBefore) {
-    if (typeof taskId === 'string' && planReviewDecisionOps.some((op) => op.taskId === taskId && op.phase === 'posting')) {
+    if (typeof taskId === 'string' && planReviewOpsOf(taskId).some((op) => op.phase === 'posting')) {
         hostLog('error', `planReviewWire: decidePlanReview(${decision}) for task ${taskId} REFUSED — a decision for this task is already in flight (duplicate delivery latched)`);
         return;
     }
-    let op = claimablePlanReviewDecisionOp(taskId);
+    let op = typeof taskId === 'string' ? claimablePlanReviewDecisionOp(taskId) : undefined;
     if (op === undefined) {
-        op = { taskId: typeof taskId === 'string' ? taskId : String(taskId), handedAt: ++planReviewLedgerClock, settledAt: null, settler: null, phase: 'posting', notApplied: false, ownCallOpen: true };
-        pushPlanReviewDecisionOp(op);
+        op = openDecisionOp('plan_review', planReviewLedgerKeys(typeof taskId === 'string' ? taskId : String(taskId)), 'posting', true);
     }
     else {
         if (op.settler === 'gate_left') {
@@ -627,7 +599,7 @@ async function decidePlanReviewFor(taskId, decision, permissionModeAfter, opts,
     const settle = (notApplied) => {
         if (notApplied)
             mine.notApplied = true;
-        settlePlanReviewDecisionOp(mine, 'package');
+        settleDecisionOp(mine, 'package');
     };
     const dispatchNo = ++decideDispatchSeq;
     hostLog('debug', `planReviewWire: decidePlanReview dispatch #${dispatchNo} task=${taskId} decision=${decision} mode=${permissionModeAfter ?? '-'}`);
@@ -636,7 +608,7 @@ async function decidePlanReviewFor(taskId, decision, permissionModeAfter, opts,
     }
     finally {
         releaseLatch();
-        settlePlanReviewDecisionOp(mine, 'package');
+        settleDecisionOp(mine, 'package');
         mine.ownCallOpen = false;
     }
 }
@@ -904,10 +876,10 @@ function joinReopenFlight(flight, taskId, receiptMs) {
         abortableSleep(Math.max(0, receiptMs), ac.signal).then(() => false),
     ]).then((presented) => {
         ac.abort();
-        return presented ? { reopened: true, firstSight: false } : { reopened: false };
+        return presented ? { reopened: true, firstSight: false } : refusedReopen('not_presented');
     }, () => {
         ac.abort();
-        return { reopened: false };
+        return refusedReopen('not_presented');
     });
 }
 function mintPlanReviewReopen(taskId, opts, sessionKey, receiptMs) {
@@ -947,10 +919,10 @@ function mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs) {
     const markBefore = dismissalEntryFor(sessionKey, taskId);
     const settleOnReceipt = (receipt, firstSight) => receipt.then((presented) => {
         if (!presented)
-            return { reopened: false };
+            return refusedReopen('not_presented');
         revokePlanReviewUserDismissal(sessionKey, taskId, markBefore);
         return { reopened: true, firstSight };
-    }, () => ({ reopened: false }));
+    }, () => refusedReopen('not_presented'));
     const canonicalId = planReviewQuestionId(taskId);
     const armedKey = planReviewArmedKeyFor(sessionKey, taskId);
     const firstSight = !wasGateArmedFor(sessionKey, armedKey);
@@ -1009,6 +981,9 @@ function mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs) {
     publishQuestionFrameFor(sessionKey, planReviewQuestionFrame(questionId, REOPEN_QUESTION, false, true));
     return settleOnReceipt(receipt, firstSight);
 }
+function refusedReopen(cause) {
+    return { reopened: false, _sema_reopenRefusal: cause };
+}
 function noPresentationSurfaceVerdict(taskId, sessionKey) {
     const verdict = { reopened: false, _sema_noPresentationSurface: true };
     hostLog('debug', `planReviewWire: reopen for task ${taskId} refused — nothing is subscribed to question frames for session ` +
@@ -1031,7 +1006,7 @@ async function reopenAfterDismissalCheck(taskId, opts, sessionKey, receiptMs, ma
                 }
             }
         }
-        const ledgerSaysInFlight = planReviewDecisionInFlight(taskId, recheckReadStart);
+        const ledgerSaysInFlight = decisionInFlightOf({ gate: 'plan_review', taskId }, recheckReadStart);
         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 };
@@ -1080,24 +1055,26 @@ async function staleDismissalVerdict(current, sessionKey, taskId, receiptMs) {
     const windowEnd = abortableSleep(Math.max(0, receiptMs), ac.signal).then(() => false);
     try {
         let entry = current;
+        let lastWaitPresented;
         for (let round = 0; round < 8; round++) {
             if (entry?.kind === 'decided')
                 return { reopened: false, _sema_decisionInFlight: true };
             if (entry?.kind === 'dismissed')
                 return { reopened: false, dismissedByUser: true };
             if (entry?.kind !== 'reopened' || entry.onScreen === undefined)
-                return { reopened: false };
+                return refusedReopen(entry === undefined && lastWaitPresented === false ? 'not_presented' : 'gate_record_gone');
             const onScreen = await Promise.race([
                 entry.onScreen.then((v) => v === true, () => false),
                 windowEnd,
             ]);
             const now = dismissalEntryFor(sessionKey, taskId);
             if (now === entry) {
-                return onScreen ? { reopened: true, firstSight: !wasGateArmedFor(sessionKey, planReviewArmedKeyFor(sessionKey, taskId)) } : { reopened: false };
+                return onScreen ? { reopened: true, firstSight: !wasGateArmedFor(sessionKey, planReviewArmedKeyFor(sessionKey, taskId)) } : refusedReopen('not_presented');
             }
+            lastWaitPresented = onScreen;
             entry = now;
         }
-        return { reopened: false };
+        return refusedReopen('gate_record_gone');
     }
     finally {
         ac.abort();
@@ -1107,25 +1084,25 @@ export function reopenPlanReviewCard(taskId, opts) {
     const receiptMs = opts?.presentationReceiptMs;
     if (typeof receiptMs !== 'number' || Number.isNaN(receiptMs)) {
         hostLog('debug', `planReviewWire: reopen for task ${String(taskId)} refused — presentationReceiptMs is required (a number of milliseconds); the synchronous form was retired in 0.98.0`);
-        return Promise.resolve({ reopened: false });
+        return Promise.resolve(refusedReopen('invalid_call'));
     }
     try {
         if (typeof taskId !== 'string' || taskId.length === 0) {
-            return Promise.resolve({ reopened: false });
+            return Promise.resolve(refusedReopen('invalid_call'));
         }
         const injected = opts;
         if (opts?.mintFreshQuestionId === false && (injected?.deliverDecision !== undefined || injected?.wire !== undefined || injected?.onOutcome !== undefined)) {
             hostLog('error', `planReviewWire: plan_review reopen for task ${taskId} refused — mintFreshQuestionId:false reuses the armed card's responder and its delivery, ` +
                 'so deliverDecision / wire / onOutcome cannot be given with it; drop mintFreshQuestionId:false to deliver through the injected path');
-            return Promise.resolve({ reopened: false });
+            return Promise.resolve(refusedReopen('invalid_call'));
         }
         const readStart = typeof opts.pendingReadStartedAt === 'number' && Number.isFinite(opts.pendingReadStartedAt) ? opts.pendingReadStartedAt : undefined;
-        if (planReviewDecisionInFlight(taskId, readStart)) {
+        if (decisionInFlightOf({ gate: 'plan_review', taskId }, readStart)) {
             hostLog('debug', `planReviewWire: reopen for task ${taskId} refused — a decision for this task is in flight (its answer is still being delivered)`);
             const refused = { reopened: false, _sema_decisionInFlight: true };
             return Promise.resolve(refused);
         }
-        const guardStartedAt = planReviewPendingReadMark();
+        const guardStartedAt = decisionReadMark();
         const recheckReadStart = readStart === undefined ? guardStartedAt : Math.min(readStart, guardStartedAt);
         const sessionKey = opts.sessionKey ?? DEFAULT_SESSION_KEY;
         if (!hasQuestionOverlayFor(sessionKey)) {
@@ -1136,7 +1113,7 @@ export function reopenPlanReviewCard(taskId, opts) {
                 '而缺省决断投递口(decidePlanReview)今天固定打默认槽的 baseUrl/token/principal。' +
                 '整条链转 keyed 之前,非默认槽要重开请自带 deliverDecision(按本槽投递);' +
                 '此处拒绝而不是照发 —— 照发会把这条会话的决断发到另一个槽上。');
-            return Promise.resolve({ reopened: false });
+            return Promise.resolve(refusedReopen('no_delivery_path'));
         }
         const trigger = opts.trigger === undefined ? undefined : opts.trigger === 'user' ? 'user' : 'automatic';
         if (trigger === 'automatic') {
@@ -1147,6 +1124,6 @@ export function reopenPlanReviewCard(taskId, opts) {
         return mintPlanReviewReopen(taskId, opts, sessionKey, receiptMs);
     }
     catch {
-        return Promise.resolve({ reopened: false });
+        return Promise.resolve(refusedReopen('internal_error'));
     }
 }

package/dist/hitl/sessionPolicyDeliverable.d.ts

@@ -1,11 +1,13 @@
 import type { SessionPermissionRules } from '@sema-agent/sdk';
 import type { ToolRosterView } from '../toolRoster.js';
+import type { SessionRuleInertReason } from './sessionPolicyWire.js';
 export type SessionPolicyWithheldWhy = 'ask_no_bucket' | 'qualified_deny' | 'peer_wide' | 'wildcard' | 'not_a_tool_name' | 'legacy_tool_name' | 'not_in_roster';
 export declare const SESSION_POLICY_WITHHELD_WHY: readonly SessionPolicyWithheldWhy[];
 export interface SessionPolicyWithheldRule {
     readonly rule: string;
     readonly why: SessionPolicyWithheldWhy;
     readonly currentName?: string;
+    readonly inertReason?: SessionRuleInertReason;
 }
 export interface SessionPolicyDeliverability {
     readonly deliverable: SessionPermissionRules;