@sema-agent/server 7.135.0 → 7.136.0

package/dist/tool-approval.js

@@ -13,7 +13,7 @@ import { recordFailOpen } from "./observability/fail-open.js";
 import { ownerOfCheckpointScope } from "./security.js";
 import { deriveAskId, deriveAskScopedBatchId, deriveBatchId, MAX_DECISION_NOTE_CHARS, noteLandedOnRow, noteRecordedReceipt } from "./approval-ask-machine.js";
 import { currentParkArm, MAX_RULE_OFFERS, buildApprovalCard, buildApprovalCardEnvelope, buildApprovalRequestFrame, buildReplayFrame, buildRevokeFrame, readDenialLimitFallback, readProbeCause, readProbeReason, readReadRootCandidate, readStoredCardEnvelope, readRuleEvidence, readAllowRuleShadowed, readRuleOffersAbsence, readRuleOffersAbsenceSeat, readParkRowTrueSeat, readAskClassPair, readClosedWordSeat, buildApprovalCompleteFrame, readRuleOfferList, } from "./approval-card.js";
-import { askRowCarriesOwner, POLICY_REFUSAL_DECISION, projectAskTerminalClaimTruth } from "./plugins/approval-ask-store-sql.js";
+import { askOwnerAdmits, askRowCarriesOwner, POLICY_REFUSAL_DECISION, projectAskTerminalClaimTruth } from "./plugins/approval-ask-store-sql.js";
 import { APPROVAL_ENDING_CAUSES, SETTLE_OUTCOME, causeOfAskRow } from "./approval-deny-reasons.js";
 import { settleByPolicy } from "./approval-policy-settlement.js";
 import { governanceAskMarksFor, runWithGovernanceAskScope } from "./governance-ask-marks.js";
@@ -195,8 +195,11 @@ function mandatedFromSeat(seat) {
             return false;
     }
 }
+function rowOrUnknown(read) {
+    return read.kind === "row" ? read.row : null;
+}
 function askRowVisibleTo(row, principal) {
-    return row !== null && (row.owner === null || row.owner === principal);
+    return row !== null && askOwnerAdmits(row.owner, principal);
 }
 function waitingLegsReached(entry, othersReached) {
     return (entry.adopted === true ? 0 : 1) + othersReached;
@@ -206,7 +209,7 @@ function withConsumerDisclosure(result, waitingLegs) {
 }
 function livePendingRowOf(e) {
     const listFrame = e.adopted === true ? e.cardFrame : (e.cardFrame ?? e.frame);
-    const approvalCard = e.adopted === true ? e.cardFrame.approvalCard : e.frame.approvalCard;
+    const approvalCard = e.adopted === true ? e.cardFrame.card.approvalCard : e.frame.approvalCard;
     return {
         approvalId: e.approvalId,
         toolName: e.toolName,
@@ -2049,17 +2052,21 @@ export class ToolApprovalCoordinator {
         }
         const entry = this.liveEntryFor(id);
         if (entry?.adopted === true)
-            return this.respondAdopted(entry, id, principal, parsed, httpReq);
-        if (!entry || (entry.owner !== null && entry.owner !== principal)) {
-            return this.respondLate(id, principal, parsed, httpReq);
-        }
-        return this.answerRegistration(entry, entry.owner, id, principal, parsed, httpReq);
+            return this.respondByRow(entry, id, principal, parsed, httpReq);
+        if (entry !== undefined && askOwnerAdmits(entry.owner, principal))
+            return this.answerRegistration(entry, entry.owner, id, principal, parsed, httpReq);
+        if (entry !== undefined && this.registrationHasRow(entry))
+            return this.respondByRow(entry, id, principal, parsed, httpReq);
+        return this.respondLate(id, principal, parsed, httpReq);
     }
-    async respondAdopted(entry, id, principal, parsed, httpReq) {
+    registrationHasRow(entry) {
+        return this.askStore !== undefined && entry.askId !== undefined;
+    }
+    async respondByRow(entry, id, principal, parsed, httpReq) {
         const store = this.askStore;
         if (!store)
             return this.notPending();
-        const row = await this.askRowFor(store, id, "getAsk(respond-adopted)");
+        const row = rowOrUnknown(await this.askRowFor(store, id, "getAsk(respond-by-row)"));
         if (!askRowVisibleTo(row, principal))
             return this.notPending(NOT_PENDING_UNKNOWN_CAUSE);
         if (row.state !== "STREAM_PENDING")
@@ -2067,7 +2074,7 @@ export class ToolApprovalCoordinator {
         return this.answerRegistration(entry, row.owner, id, principal, parsed, httpReq);
     }
     answerRegistration(entry, judgedOwner, id, principal, parsed, httpReq) {
-        const preRule = this.precheckEditedRuleBeforeDecision(entry, parsed);
+        const preRule = this.precheckEditedRuleBeforeDecision(entry, judgedOwner, parsed);
         if (preRule !== undefined)
             return preRule;
         if (parsed.value !== "deny" && policyCannotAnswer(heldAskOf(entry.requiresRealApproval === true), parsed.decidedBy)) {
@@ -2076,17 +2083,17 @@ export class ToolApprovalCoordinator {
         const ruleEligibility = { eligible: true };
         const store = this.askStore;
         if (store && entry.askId !== undefined && entry.batchId !== undefined) {
-            return this.respondWithCas(store, entry.askId, entry.batchId, judgedOwner, entry, parsed, ruleEligibility).then((cas) => cas.lost ? this.dispatchRowTruth(cas.row, id, parsed, httpReq, principal) : this.afterLiveDecision(cas.result, entry, parsed, principal, ruleEligibility));
+            return this.respondWithCas(store, entry.askId, entry.batchId, judgedOwner, entry, parsed, ruleEligibility).then((cas) => cas.lost ? this.dispatchRowTruth(cas.row, id, parsed, httpReq, principal) : this.afterLiveDecision(cas.result, entry, judgedOwner, parsed, principal, ruleEligibility));
         }
-        return this.afterLiveDecision(this.finishRespond(entry, parsed), entry, parsed, principal, ruleEligibility);
+        return this.afterLiveDecision(this.finishRespond(entry, judgedOwner, parsed), entry, judgedOwner, parsed, principal, ruleEligibility);
     }
-    afterLiveDecision(decided, entry, parsed, principal, ruleEligibility) {
-        const settled = this.recordDeploymentListAnswer(decided, entry, parsed, principal, ruleEligibility);
+    afterLiveDecision(decided, entry, judgedOwner, parsed, principal, ruleEligibility) {
+        const settled = this.recordDeploymentListAnswer(decided, entry, judgedOwner, parsed, principal, ruleEligibility);
         if (parsed.persistRule === undefined)
             return settled;
-        return this.persistRuleAfterDecision(settled, entry, parsed.persistRule, parsed.updatedInput !== undefined, ruleEligibility);
+        return this.persistRuleAfterDecision(settled, entry, judgedOwner, parsed.persistRule, parsed.updatedInput !== undefined, ruleEligibility);
     }
-    recordDeploymentListAnswer(decided, entry, parsed, principal, eligibility) {
+    recordDeploymentListAnswer(decided, entry, judgedOwner, parsed, principal, eligibility) {
         const store = this.sessionGrants;
         const sessionId = entry.sessionId;
         if (parsed.value !== "allow_session" || !sessionId || store === undefined)
@@ -2101,9 +2108,9 @@ export class ToolApprovalCoordinator {
                 return { ...result, body: { ...result.body, rememberApplied: false } };
             let rememberApplied = false;
             try {
-                await this.withStoreDeadline(store.grant(sessionId, entry.toolName, principal ?? entry.owner), "sessionGrants.grant(deployment-list)", DURABLE_CALL_TIMEOUT_MS);
+                await this.withStoreDeadline(store.grant(sessionId, entry.toolName, principal ?? judgedOwner), "sessionGrants.grant(deployment-list)", DURABLE_CALL_TIMEOUT_MS);
                 rememberApplied = true;
-                defaultLogger.info("approval_exemption_granted", { sessionId, toolName: entry.toolName, grantedBy: principal ?? entry.owner });
+                defaultLogger.info("approval_exemption_granted", { sessionId, toolName: entry.toolName, grantedBy: principal ?? judgedOwner });
             }
             catch (err) {
                 defaultLogger.warn("approval_exemption_grant_failed", { sessionId, toolName: entry.toolName, error: String(err).slice(0, 200) });
@@ -2111,7 +2118,7 @@ export class ToolApprovalCoordinator {
             return { ...result, body: { ...result.body, rememberApplied } };
         })();
     }
-    precheckEditedRuleBeforeDecision(entry, parsed) {
+    precheckEditedRuleBeforeDecision(entry, judgedOwner, parsed) {
         const persistRule = parsed.persistRule;
         if (persistRule === undefined || persistRule.kind !== "text" || !persistRule.edited)
             return undefined;
@@ -2120,7 +2127,7 @@ export class ToolApprovalCoordinator {
         if (entry.governanceForced === true)
             return undefined;
         const command = entry.ruleLane?.command;
-        if (this.ruleConsent === undefined || command === undefined || entry.owner === null)
+        if (this.ruleConsent === undefined || command === undefined || judgedOwner === null)
             return undefined;
         const verdict = precheckCardRuleText(persistRule.rule, command);
         if (verdict === undefined || verdict.ok)
@@ -2155,9 +2162,9 @@ export class ToolApprovalCoordinator {
     }
     readApproval(id, principal) {
         const entry = this.liveEntryFor(id);
-        if (entry?.adopted === true)
-            return this.readAdopted(entry, id, principal);
-        if (entry !== undefined && (entry.owner === null || entry.owner === principal)) {
+        if (entry !== undefined && this.registrationHasRow(entry))
+            return this.readByRow(entry, id, principal);
+        if (entry !== undefined && askOwnerAdmits(entry.owner, principal)) {
             const body = { state: "pending", ...livePendingRowOf(entry) };
             return { status: 200, body };
         }
@@ -2166,11 +2173,18 @@ export class ToolApprovalCoordinator {
             return this.notPending();
         return this.readAskRowState(store, id, principal);
     }
-    async readAdopted(entry, id, principal) {
+    async readByRow(entry, id, principal) {
         const store = this.askStore;
         if (!store)
             return this.notPending();
-        const row = await this.askRowFor(store, id, "getAsk(read-adopted)");
+        const read = await this.askRowFor(store, id, "getAsk(read-by-row)");
+        if (read.kind === "unreadable") {
+            if (entry.adopted === true || !askOwnerAdmits(entry.owner, principal))
+                return this.notPending(NOT_PENDING_UNKNOWN_CAUSE);
+            const body = { state: "pending", ...livePendingRowOf(entry) };
+            return { status: 200, body };
+        }
+        const row = rowOrUnknown(read);
         if (askRowVisibleTo(row, principal) && row.state === "STREAM_PENDING") {
             const body = { state: "pending", ...livePendingRowOf(entry) };
             return { status: 200, body };
@@ -2178,7 +2192,7 @@ export class ToolApprovalCoordinator {
         return this.readStateOfRow(row, principal);
     }
     async readAskRowState(store, id, principal) {
-        return this.readStateOfRow(await this.askRowFor(store, id, "getAsk(read)"), principal);
+        return this.readStateOfRow(rowOrUnknown(await this.askRowFor(store, id, "getAsk(read)")), principal);
     }
     async readParkedGate(row) {
         const gate = this.parkedGate;
@@ -2310,15 +2324,16 @@ export class ToolApprovalCoordinator {
         return undefined;
     }
     async dispatchLateByRow(store, id, parsed, httpReq, principal) {
-        return this.dispatchRowTruth(await this.askRowFor(store, id, "getAsk(respond-late)"), id, parsed, httpReq, principal);
+        return this.dispatchRowTruth(rowOrUnknown(await this.askRowFor(store, id, "getAsk(respond-late)")), id, parsed, httpReq, principal);
     }
     async askRowFor(store, id, label) {
         try {
-            return await this.withStoreDeadline(store.getAsk(id), label, DURABLE_CONVERGE_READ_TIMEOUT_MS);
+            const row = await this.withStoreDeadline(store.getAsk(id), label, DURABLE_CONVERGE_READ_TIMEOUT_MS);
+            return row === null ? { kind: "absent" } : { kind: "row", row };
         }
         catch (err) {
             this.noteStoreError(err, label);
-            return null;
+            return { kind: "unreadable" };
         }
     }
     async dispatchRowTruth(row, id, parsed, httpReq, principal) {
@@ -2580,13 +2595,13 @@ export class ToolApprovalCoordinator {
             },
         };
     }
-    async persistRuleAfterDecision(settled, entry, persistRule, inputWasEdited, ruleEligibility) {
+    async persistRuleAfterDecision(settled, entry, judgedOwner, persistRule, inputWasEdited, ruleEligibility) {
         const result = await settled;
         if (result.status !== 200)
             return result;
         const lane = this.ruleConsent;
         const material = entry.ruleLane;
-        const owner = entry.owner;
+        const owner = judgedOwner;
         const withFlag = (rulePersisted, ruleRefusal, echo) => ({
             status: result.status,
             body: { ...result.body, rulePersisted, ...(ruleRefusal !== undefined ? { ruleRefusal } : {}), ...(echo ?? {}) },
@@ -2708,11 +2723,11 @@ export class ToolApprovalCoordinator {
             if (!converged) {
                 return { lost: false, result: this.notPending() };
             }
-            return { lost: false, result: withConsumerDisclosure(this.finishRespond(entry, parsed, { updatedInputDelivered: false, noteRecorded: noteLanded }), waitingLegsReached(entry, othersReached)) };
+            return { lost: false, result: withConsumerDisclosure(this.finishRespond(entry, owner, parsed, { updatedInputDelivered: false, noteRecorded: noteLanded }), waitingLegsReached(entry, othersReached)) };
         }
         const payloadIsMine = ambiguousConfirmedRow === undefined ||
             approvalPayloadFingerprint({ updatedInput: ambiguousConfirmedRow.updatedInput }) === approvalPayloadFingerprint({ updatedInput: parsed.updatedInput });
-        const result = this.finishRespond(entry, parsed, {
+        const result = this.finishRespond(entry, owner, parsed, {
             noteRecorded: noteLanded,
             ...(winnerRow !== undefined ? { settleOutcome: outcomeOfDecidedRow(winnerRow), settleOutcomeIsThisRequest: ambiguousConfirmedRow === undefined } : {}),
             ...(entry.adopted === true ? { updatedInputDelivered: false } : ambiguousConfirmedRow !== undefined ? { updatedInputDelivered: payloadIsMine } : {}),
@@ -2720,7 +2735,7 @@ export class ToolApprovalCoordinator {
         const othersReached = winnerRow !== undefined ? this.notifyExternalDecision(askId, outcomeOfDecidedRow(winnerRow)).settled : 0;
         return { lost: false, result: withConsumerDisclosure(result, waitingLegsReached(entry, othersReached)) };
     }
-    finishRespond(entry, parsed, opts) {
+    finishRespond(entry, judgedOwner, parsed, opts) {
         let rememberApplied;
         const home = standingAnswerHome(pendingEntryStandingAnswerFacts(entry));
         let grantable;
@@ -2745,7 +2760,7 @@ export class ToolApprovalCoordinator {
                 if (oldest !== undefined)
                     this.allowAllSessions.delete(oldest);
             }
-            this.allowAllSessions.add(sessionAllowKey(entry.owner, entry.sessionId, sessionAllowCategory(entry.toolName), entry.grantBinding));
+            this.allowAllSessions.add(sessionAllowKey(judgedOwner, entry.sessionId, sessionAllowCategory(entry.toolName), entry.grantBinding));
         }
         const allowed = parsed.value !== "deny";
         const settleArgs = opts?.settleOutcome !== undefined ? settleArgsOfDecided(opts.settleOutcome) : { allowed, updatedInput: parsed.updatedInput, settledBy: liveSettledBy(parsed.decidedBy) };

package/dist/trace/core-keyset-guard.d.ts

@@ -218,8 +218,8 @@ type _GuardInboxSummaryReverse = AssertAllKeysHandled<Exclude<SummaryProjected |
 type ParkArmKeys = keyof Extract<PendingAction, {
     kind: "tool_approval";
 }>;
-type ParkArmQueueProjected = "toolName" | "toolCallId" | "boundInputHash" | "ruleOffers" | "hasBidiControls" | keyof import("../approval-card.js").ParkRowFacts;
-type ParkArmQueueExcluded = "kind" | "args" | "batchToolCallIds" | "completedCallIds" | "capabilityId" | "contractId" | "shapeDigest" | "implementationRevision" | "family" | "pathTarget" | "hostTarget" | "targets" | "names" | "preview" | "previewWithheld" | "execCwd" | "denialLimitFallback" | "authoredBy" | "boundGrantDigest" | "boundGrants" | "classifierNoRuling";
+type ParkArmQueueProjected = "toolName" | "toolCallId" | "boundInputHash" | "ruleOffers" | "hasBidiControls" | keyof import("../approval-card.js").ParkRowFacts | keyof import("../approval-card.js").SkillCardFacts;
+type ParkArmQueueExcluded = "kind" | "args" | "batchToolCallIds" | "completedCallIds" | "capabilityId" | "contractId" | "shapeDigest" | "implementationRevision" | "family" | "pathTarget" | "hostTarget" | "targets" | "names" | "preview" | "previewWithheld" | "execCwd" | "denialLimitFallback" | "authoredBy";
 type _GuardParkArmQueue = AssertAllKeysHandled<Exclude<ParkArmKeys, ParkArmQueueProjected | ParkArmQueueExcluded>>;
 type _GuardParkArmQueueReverse = AssertAllKeysHandled<Exclude<ParkArmQueueProjected | ParkArmQueueExcluded, ParkArmKeys>>;
 type _NoDoubleBookParkArmQueue = AssertAllKeysHandled<Extract<ParkArmQueueProjected, ParkArmQueueExcluded>>;

package/dist/trace/exit-seat.js

@@ -3,7 +3,7 @@ import { CALLER_TEXT_CUT_MARK } from "../caller-text-echo.js";
 import { errorKindOf } from "../observability/err-text.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { OVERSIZED_REDACTION_PLACEHOLDER } from "../observability/run-terminal.js";
-import { proposeRedactionSpans, REDACTION_TOKEN_RE_SRC } from "./redact.js";
+import { proposeRedactionSpans, readingHeadEnd, REDACTION_TOKEN_RE_SRC } from "./redact.js";
 const EXIT_SEATS = {
     "trace-frame-text": { scope: "free-text" },
     "trace-frame-line": { scope: "free-text", maxChars: 300 },
@@ -38,8 +38,7 @@ function mergeSpans(spans) {
     return out;
 }
 const TOKEN_AT = new RegExp(REDACTION_TOKEN_RE_SRC, "y");
-function cutPlain(gap, room) {
-    let cut = room;
+function safeCutPoint(gap, cut) {
     const hi = gap.charCodeAt(cut - 1);
     if (cut > 0 && hi >= 0xd800 && hi <= 0xdbff && (gap.charCodeAt(cut) & 0xfc00) === 0xdc00)
         cut -= 1;
@@ -50,16 +49,19 @@ function cutPlain(gap, room) {
         if (m !== null && open + m[0].length > cut)
             cut = open;
     }
-    return gap.slice(0, cut);
+    return cut;
 }
-function renderOnce(text, groups) {
+const cutPlain = (gap, room) => gap.slice(0, safeCutPoint(gap, room));
+function renderOnce(text, groups, until = Number.POSITIVE_INFINITY) {
     const parts = [];
     let at = 0;
     for (const g of groups) {
+        if (g.start >= until)
+            break;
         parts.push(text.slice(at, g.start), g.repl);
         at = g.end;
     }
-    parts.push(text.slice(at));
+    parts.push(text.slice(at, until));
     return parts.join("");
 }
 function emitAs(form, text) {
@@ -79,12 +81,18 @@ function emitAs(form, text) {
     }
 }
 const layoutOf = (row) => (row.emit === undefined ? "multi-line" : "single-line");
-function boundRow(out, row) {
-    if (row.maxChars === undefined || out.length <= row.maxChars)
+const SCAN_WINDOW_FLOOR = 4096;
+const SCAN_WINDOW_PER_BOUND = 8;
+const scanWindowOf = (maxChars) => Math.max(SCAN_WINDOW_FLOOR, maxChars * SCAN_WINDOW_PER_BOUND);
+function boundRow(out, row, cutUpstream) {
+    if (row.maxChars === undefined)
         return out;
     if (row.emit === undefined)
-        return cutPlain(out, row.maxChars);
-    return cutPlain(out, row.maxChars - CALLER_TEXT_CUT_MARK.length) + CALLER_TEXT_CUT_MARK;
+        return out.length <= row.maxChars ? out : cutPlain(out, row.maxChars);
+    if (out.length <= row.maxChars && !cutUpstream)
+        return out;
+    const room = row.maxChars - CALLER_TEXT_CUT_MARK.length;
+    return (out.length <= room ? out : cutPlain(out, room)) + CALLER_TEXT_CUT_MARK;
 }
 export function seatText(seat, text) {
     const row = SEAT_ROWS.get(seat);
@@ -92,11 +100,27 @@ export function seatText(seat, text) {
         throw new Error(`exit seat: ${JSON.stringify(seat)} is not a row of the seat table`);
     let out;
     try {
-        if (row.emit !== undefined && emitAs(row.emit, text) === "")
+        const layout = layoutOf(row);
+        const scanWindow = row.maxChars === undefined ? undefined : scanWindowOf(row.maxChars);
+        let windowEnd;
+        let regionEnd;
+        if (scanWindow !== undefined && text.length > scanWindow) {
+            const half = scanWindow >>> 1;
+            const region = safeCutPoint(text, readingHeadEnd(text, layout, half));
+            const end = safeCutPoint(text, readingHeadEnd(text, layout, scanWindow - half, region));
+            if (end < text.length) {
+                windowEnd = end;
+                regionEnd = region;
+            }
+        }
+        const head = windowEnd === undefined ? text : text.slice(0, windowEnd);
+        if (row.emit !== undefined && emitAs(row.emit, head) === "")
             out = "";
         else {
-            const rendered = renderOnce(text, mergeSpans(proposeRedactionSpans(text, row.scope, layoutOf(row))));
-            out = boundRow(row.emit === undefined ? rendered : emitAs(row.emit, rendered), row);
+            const emitUntil = regionEnd;
+            const extent = windowEnd === undefined ? "whole" : "head";
+            const rendered = renderOnce(head, mergeSpans(proposeRedactionSpans(head, row.scope, layout, extent)), emitUntil);
+            out = boundRow(row.emit === undefined ? rendered : emitAs(row.emit, rendered), row, windowEnd !== undefined);
         }
     }
     catch (err) {

package/dist/trace/redact.d.ts

@@ -65,16 +65,6 @@ declare const DISPLAY_SAFE_URL_TOKEN = "\u00ABredacted:url\u00BB";
 /** [ref]:出网代理 URL 的回显尺(`outbound-dispatcher.ts` `displayProxyUrl`)形不干净时整只用**同一枚**占位 —— 单独一行导出,
  *  上面那行字面量保持 `const NAME = "…";` 形(`test/api-notice-text-freeze.test.ts` §6 的冻结扫描按这一形认替换 token)。 */
 export { DISPLAY_SAFE_URL_TOKEN };
-/**
- * 名表的**只读导出**([ref]:第四处消费 —— 受理口的 URL 凭据判官 `url-credential.ts`;文档同步钉按它对表)。
- * 表的属主仍是本模块的 {@link CREDENTIAL_NAME_ANCHORS};加一个名字只改那一处,本数组与下面的谓词随之现算。
- */
-export declare const CREDENTIAL_PARAM_NAMES: readonly string[];
-/**
- * 「这个**已解码**的参数名是不是凭据名」([ref] 第四处消费)。入参是收方读到的那一形(`URLSearchParams` 解过一次码的名字),
- * 判法与本模块 URL 参数臂同读 —— 同一只判定 {@link credentialNameAnchor}:整名在表里(ASCII 大小写不敏感,不做 Unicode 折叠)。
- */
-export declare function isCredentialParamName(decodedName: string): boolean;
 /**
  * 🔴 **取证相的重扫模式(测试座,[ref])** —— 生产恒 `"incremental"`;`"full"` 是**参照语义** = 「没有可复用的上一次执行」:
  * 每级五条取证臂整段重跑、URL 臂每段重扫,既不读足迹也不回放(池把每一级的脏区间当作「未知」交下去,与级 0 同一个读法)。
@@ -135,6 +125,32 @@ export declare function setRedactionObserver(fn: ((patternLabel: string, count:
  *  · `single-line`:出口在读者看见之前把文本压成一行(出口座的日志字段行 / 标题行:空白控制字符被删或折成空格)⇒ ①②③④。
  */
 export type RedactionLayout = "multi-line" | "single-line";
+/**
+ * 一段文本相对「它所在的那一整段」的**范围**(闭集两词;调用方对自己交来的文本的陈述,不是旋钮):
+ *  · `whole`:这就是全部。所有「见收尾才认」的结构臂走到末尾仍没见收尾 ⇒ 这一起点不成 —— 判据 = 声明正则(`test/trace-redact.test.ts` 的真值表钉着扫描器与声明正则逐跨度等价);
+ *  · `head`:这只是更长文本的头一段(出口座对有界行只扫一段头,见 `trace/exit-seat.ts` 的扫描窗)。**一条律:结构的判定走到这一段末尾还没走完 ⇒ 判定在更远处(未决)⇒ 从结构起点遮到这一段的末尾**
+ *    (fail-closed:起点在、判定要看窗外,明文不许出门)。未决只有两种,同读一条臂:
+ *    ① **收尾没见到** —— JSON 串值(要收尾引号)· URL authority(要 `@`;authority 一路走到末尾没有 `/` / 空白,里面有没有 `@` 都读成还在 userinfo 里)·
+ *    SSH2 / PEM 栅栏(要收尾栅栏)· 带引号的强锚值(要收尾引号)· PuTTY 容器(终止符之后到末尾没见下一个版本头);
+ *    ② **起头没读完**(起头本身不设长度上界,起点可以离末尾很远)—— PEM 起始栅栏行(标签之后到末尾一枚 `-----` 都没有,已读到的部分也还可能是合法栅栏行的前缀)· PuTTY 版本头(`<数字串>: ` 没写完)·
+ *    无头 .ppk 字段(`Private-Lines: <数字串>` 之后下一个体行的判定没走完)。
+ *    PuTTY 容器臂的「无合格终止 ⇒ 吃到输入末尾」本来就是这一律在整段文本上的形,两种范围都吃到末尾;区别只在留痕 —— 整段读法上它是兜底(记 `server.redact.ppk-eat-to-end`),
+ *    head 读法上终止可能在更远处,是未决(不记)。**未决一律不记 fail-open**:它是这一律的正常读数,不是回退;
+ *    由裸形 / 关键字 / 查询参数 / 环境变量赋值等**不靠收尾**的臂认出的凭据(值到字符类的自然右界)两种范围读法逐字相同。
+ */
+export type RedactionExtent = "whole" | "head";
+/**
+ * 🔴 **出口座扫描窗的单位 = 读法单元,不是原始码元**(修复验证腿 high ①):从 `from`(缺省 0)起数 `units` 个**读法单元**(各读法里最少的那一读 —— 删得最多的 —— 剩下的码元),
+ * 返回原文里的终点(含 `≥ units` 个读法单元的前缀,至多是最短那一个的两倍;文本不够长 ⇒ `text.length`)。格式字符 / 控制字符 / 转义写法的不可见字符不计数:它们在读法格里被删,
+ * 整段读法认得出的凭据(`sk-` + 18 位 + 五千个零宽空格 + 余下 12 位)靠它们之后的字节凑够最短长度 —— 窗若按原始码元计,填充一撑就把证据推到窗外,窗读法只见前缀而漏。
+ * `from`:出门区与余量**各自从自己的起点数**(窗 = 出门区〔从头数半窗〕+ 余量〔从出门区终点起再数半窗〕),不是各自从头数「第一个 ≥ units 的终点」—— 后者遇到不可见填充会按翻倍
+ * 跳到同一个终点,余量塌成 0,被窗尾切开的凭据在出门区里露出半截(修复验证 r3 high)。
+ * 取舍:不可见填充很大的文本,窗随之延伸(最坏延伸到整段 = 整段读法的代价),换来「窗里的读法单元数恒 ≥ `units`」这一个不变量 —— 窗里每一读的视图都不短于 `units`。
+ * 终点不落在转义写法中间:前缀末尾还没写完的转义写法({@link trailingPartialEscapeStart},在读法后文本上判,{@link shortestReading})不计数、窗延伸到它写完 —— 出门区终点与窗尾都因此落在转义的边上,余量从干净的边起数。
+ * 复杂度:**第一趟**若可见占比 ≥ 一半(少量换行 / 色码)按占比补足缺口,均匀的文本一两趟落在终点附近;补不足(或占比低)的趟一律至少翻倍 —— 总趟数 O(log 终点)、总功 O(终点),
+ * 不存在逐趟只前进几个码元的爬行(4095 个可见 + 4000 个控制字符曾因此平方,K=4000 约 0.2–0.3 s)。判据与读法格同源(同一批切除点收集器,零第二份「什么算不可见」)。
+ */
+export declare function readingHeadEnd(text: string, layout: RedactionLayout, units: number, from?: number): number;
 export declare function redactSecrets(text: string, opts?: {
     observe?: boolean;
     json?: boolean;
@@ -195,7 +211,7 @@ export type RedactionSpan = {
     readonly repl: string;
 };
 export type { RedactionScope };
-export declare function proposeRedactionSpans(text: string, scope: RedactionScope, layout: RedactionLayout): readonly RedactionSpan[];
+export declare function proposeRedactionSpans(text: string, scope: RedactionScope, layout: RedactionLayout, extent: RedactionExtent): readonly RedactionSpan[];
 /**
  * 🔴 环 + 深度预算(2026-07-25 补)。原实现是纯递归、**既不记已访问节点也不限深度**,而它的调用位置是
  * **最不可信的边界**:`toolStart`/`toolEnd` 把工具的 `args`/`output`/`structured` 直接喂进来。后果两条:
@@ -232,7 +248,7 @@ export declare function redactedPreview(value: unknown, cap?: number): string |
  *
  * 🔴 **[ref] 展示半场(7.90.0 / core 7.24.0):两条正交的律合成一次,名表的射程缩到不可约的那一半**。
  * 改前内部只有一条:`redactSecrets(new URL(raw).href)` —— 自由文本那条**名单制**的律,query 的值只在键名
- * 落在 `CREDENTIAL_NAME_WORDS`(或值本身像个密钥)时才遮,于是**没人列过的那个键名**就是它的盲点
+ * 落在凭据名表 `CREDENTIAL_PARAM_NAMES`(或值本身像个密钥)时才遮,于是**没人列过的那个键名**就是它的盲点
  * (`?sig=…` / `?auth=…` / 部署自定义的网关参数名)。现在前面先跑 core 的 `displayUrlOf`,它是**位置制**的:
  *  · userinfo **落地**(不是遮成记号 —— 它从**解析**组合 `scheme://host + path + query`,userinfo 结构上
  *    进不了产物);凭据在 userinfo 这件事本身仍然响亮,只不过是在**声明关口**响