@sema-agent/core 7.13.0 → 7.15.0

package/dist/index.d.ts

@@ -93,7 +93,7 @@ export { sanitizeUntrustedText, delimitUntrusted, inlineUntrusted } from "./core
 export { mintReminderMark, isValidReminderMark, openSystemReminder, mintSystemReminder, reminderMarkDeclaration } from "./core/reminder-mint.js";
 export { deriveInvariants, checkInvariants } from "./core/property-harness.js";
 export type { InvariantKind, FunctionContract, Invariant, InvariantViolation, CheckResult, } from "./core/property-harness.js";
-export { bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
+export { bashReversibilityProbe, bashReadBoundaryProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
 export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, type BashReadonlyRootBoundary, type CompoundReadonlyVerdict, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { READ_FACE_DEFAULT_DENY_ENTRIES, READ_FACE_BUILTIN_DENY_TABLE, READ_DENY_BUILTIN_TIERS, READ_DENY_DEFAULT_TIERS, resolveReadDenyBuiltins, compileReadDeny, type ReadDenyEntry, type ReadDenyMatcher, type NormalizedReadDenyEntry, type ReadDenyBuiltinTier, type ReadDenyBuiltinRow, type ReadDenyBuiltinConfig, } from "./tools/fs/index.js";
@@ -138,7 +138,7 @@ export { parkedToolIdentity } from "./core/tool-roster.js";
 export { type ToolCallIdentity } from "./core/fs-write-gate-policy.js";
 export { type RuleFaceView, catalogRuleFaceView } from "./core/permission-rules.js";
 export { DURABLE_HISTORY_NAMES } from "./engine/compaction/utils.js";
-export { describeStaticWiring, deriveWiringManifest, deriveAskEffective, resolveDeclaredDurability, resolveSubagentTranscriptTier, type SubagentTranscriptTier, resolveAskSeamForm, resolveQuestionSeam, countElicitOptIns, AUTO_MODE_ARM_REASONS, type AutoModeArmReason, type WiringManifest, type WiringManifestMcpEntry, type WiringFacts, type WiringLegKind, type AskSeamForm, type AskEffective, type QuestionChannelState, type SeamProvenance, type ParkLaneReason, type ManifestDurability, type StaticWiringDeps, type StaticWiringSpec, } from "./core/wiring-manifest.js";
+export { describeStaticWiring, deriveWiringManifest, deriveAskEffective, resolveDeclaredDurability, resolveSubagentTranscriptTier, type SubagentTranscriptTier, resolveAskSeamForm, resolveQuestionSeam, countElicitOptIns, AUTO_MODE_ARM_REASONS, type AutoModeArmReason, type AutoModeArmFact, type WiringManifest, type WiringManifestMcpEntry, type WiringFacts, type WiringLegKind, type AskSeamForm, type AskEffective, type QuestionChannelState, type SeamProvenance, type ParkLaneReason, type ManifestDurability, type StaticWiringDeps, type StaticWiringSpec, } from "./core/wiring-manifest.js";
 export { probeParkRoundTrip, durableParkGapOf, durableParkGapFor, PARK_SELFCHECK_SCOPE_PREFIX, type ParkSelfCheckResult, type ParkProbeFinding, type ParkProbeFindingCode, } from "./core/park-selfcheck.js";
 export { type StoreDurability } from "./core/checkpoint-store.js";
 export { type StoreFidelity } from "./core/checkpoint-store.js";
@@ -164,8 +164,9 @@ export { createSchedulerTools, type SchedulerToolContext, SCHEDULE_WAKEUP_TOOL_N
 export { resolveAutonomousLoopPrompt, AUTONOMOUS_LOOP_PREAMBLE, AUTONOMOUS_LOOP_PREAMBLE_PERSISTENT, type AutonomousLoopPromptOptions, } from "./tools/loop-tick.js";
 export { tightenTaskSpec, TaskSpecTightenError } from "./core/tighten-task-spec.js";
 export { createAllowDenyPolicy, createApprovalPolicy, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, decisionText, resolveAsk, toolPolicyNameSets, type ToolPolicyNameSets, type NamedToolPolicy, type ToolPolicyProjection, type ToolPolicyProjectionComponent, type ConstraintChainEntry, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, type ToolPolicy, type ToolCallRequest, type PermissionResult, type DecisionReason, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, type OnAsk, type AskOutcome, type ResolvedAsk, type AskRequest, type AskDelegationProvenance, type AskRuleEvidence, type AskEvidenceAbsence, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
-export { type AskOrigin, ASK_ORIGINS, isAskOrigin, classifierMayAnswer, ORIGIN_IMPLIES_REAL_APPROVAL } from "./core/ask-origin.js";
-export { SETTLEMENT_KINDS, type SettlementKind, isSettlementKind, type Settlement, SETTLEMENT_IS_REFUSAL, DENIED_BY_VALUES, type DeniedBy, isDeniedBy, DENIED_BY_MAY_VETO, type GateDisposition, type GateOutcome, screenGateOutcome } from "./core/gate-outcome.js";
+export { type AskOrigin, ASK_ORIGINS, isAskOrigin, classifierMayAnswer, ORIGIN_IMPLIES_REAL_APPROVAL, RULE_STORE_UNREADABLE_KINDS, type RuleStoreUnreadable, isRuleStoreUnreadable } from "./core/ask-origin.js";
+export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource, type AutoModeDenySource } from "./core/runtime-caps.js";
+export { SETTLEMENT_KINDS, type SettlementKind, isSettlementKind, type Settlement, SETTLEMENT_IS_REFUSAL, DENIED_BY_VALUES, type DeniedBy, isDeniedBy, DENIED_BY_MAY_VETO, CLASSIFIER_DENY_CAUSES, type ClassifierDenyCause, isClassifierDenyCause, DENIED_BY_MAY_CARRY_CAUSE, type GateDisposition, type GateOutcome, screenGateOutcome } from "./core/gate-outcome.js";
 export { type AskCarry } from "./core/hooks.js";
 export { SWAPPABLE_DEP_SEATS, SWAP_SEAT_NOTICE, isSwappableDepSeat, screenSwappableDeps, type SwappableDepSeat, type SwappableDeps } from "./core/swappable-deps.js";
 export { parseAutoModeResponse, createAutoModeDecider, AUTO_MODE_UNAVAILABLE_CAUSES, isAutoModeUnavailableCause, classifierUnavailableDenyMessage, CLASSIFIER_PARSE_FAILURE_DENY_MESSAGE, type AutoModeUnavailableCause, type AutoModeVerdict, type AutoModeDecider, type AutoModeDeciderOptions, type AutoModeClassified, type AutoModeClassifyFn, type AutoModeClassifyInput, createAutoModeDenialTracker, denialLimitFallbackMessage, denialLimitSentence, unarmedWindow, type AutoModeDenialTracker, type AutoModeDenialLimitOptions, type DenialLimitCounts, type DenialLimitFallbackFace, type UnarmedDenialLimitFallback, type DenialLimitFallback, type DenialLimitVerdict, } from "./core/auto-mode.js";
@@ -228,7 +229,7 @@ export { CenterPromptSource, FilePromptArtifactStore, FilePromptSourceStateStore
 export { stripEngineMetadata } from "./internal/llm.js";
 export { EVENT_PROMPT_REGISTRY, eventDefaultOn, type CompiledEventPrompt, type CompiledMessageInjection, type EventDedupe, type EventDefaultPolicy } from "./prompt-assembly/event-registry.js";
 export type { CompiledSection, ComposedPrompt, PackSectionDeclaration, PromptCacheClass, PromptCarrier, PromptMutability, PromptOwner, PromptPack, PromptRenderCadence, PromptRuntimeFacts, PromptSlot, PromptTrust, SectionRenderInputs, } from "./prompt-assembly/types.js";
-export { type ReasoningIntensity, type ReasoningResolution, type ResolvedReasoning, type ReasoningFormat, DEFAULT_EFFORT_LEVELS, REASONING_BUDGET_SHARE, isThinkingLevel, rankOf, resolveEffort, resolveBinary, reasoningBudgetShare, resolveReasoning, thinkingOffExpressible, declaredOffSpelling, type OffCapabilityModel, resolveReasoningProfile, type ReasoningTier, type ReasoningProfileFlags, } from "./brain/reasoning.js";
+export { type ReasoningIntensity, type ReasoningResolution, type ResolvedReasoning, type ReasoningFormat, DEFAULT_EFFORT_LEVELS, REASONING_BUDGET_SHARE, isThinkingLevel, rankOf, resolveEffort, reasoningEffortLevelsOf, resolveBinary, reasoningBudgetShare, resolveReasoning, thinkingOffExpressible, declaredOffSpelling, type OffCapabilityModel, resolveReasoningProfile, type ReasoningTier, type ReasoningProfileFlags, } from "./brain/reasoning.js";
 export { DESIGN_REVIEW_PROMPTS, CODE_REVIEW_PROMPT, SCENARIO_REGISTRY, runScenario, type ScenarioId, type CodeReviewMode, type ScenarioProfile, type RunScenarioOptions, type RunScenarioResult, } from "./scenarios/scenario-registry.js";
 export { teacherMode, TEACHER_PROFILE, type TeacherModePair, type TeacherProfile, } from "./scenarios/teacher-quickstart.js";
 export { loadOrchestrationEnv, DEFAULT_REASONING_INTENSITY, type OrchestrationMode, type OrchestrationEnv, } from "./scenarios/env.js";
@@ -317,7 +318,7 @@ export { ROUTE_ADJUDICATION_CONFORMANCE_CORPUS, type RouteAdjudicationVector } f
 export { type BrainTimeoutConfig } from "./brain/timeout.js";
 export { createAssistantMessageEventStream } from "./internal/llm.js";
 export type { AssistantMessage, AssistantMessageEvent, CompleteSimpleFn, Context, DocumentContent, ImageContent, Message, StopReason, StreamFn, TextContent, ThinkingContent, ToolCall, ToolResultMessage, Usage, UserMessage, } from "./internal/llm.js";
-export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, TrackFileEditHook, TrackEditRequest, TrackEditResult, FileEditedHook, FileEditedNotice, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, BrainRetryErrClass, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, A2aServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, ResumePreflightInfo, ResumePreflightVerdict, EngineNotice, RuntimeCaps, BackgroundChildEvent, DelegationLifecycleEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskLimits, StaleToolResultOffloadOptions, TaskResult, TerminalCause, PausedCause, EffectiveMemoryScopes, RemoteEnvFailureNote, TaskSpec, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ToolInputVerdict, ToolInputValidationContext, ReversibilityVerdict, ToolEffect, ToolContentOrigin, WorkflowGovernanceBaseline, DelegationTaskType, } from "./core/types.js";
+export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, TrackFileEditHook, TrackEditRequest, TrackEditResult, FileEditedHook, FileEditedNotice, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, BrainRetryErrClass, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, A2aServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, ResumePreflightInfo, ResumePreflightVerdict, EngineNotice, RuntimeCaps, BackgroundChildEvent, DelegationLifecycleEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskLimits, StaleToolResultOffloadOptions, TaskResult, TerminalCause, PausedCause, EffectiveMemoryScopes, RemoteEnvFailureNote, TaskSpec, ShellGateDoctrine, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ToolInputVerdict, ToolInputValidationContext, ReversibilityVerdict, ToolEffect, ToolContentOrigin, WorkflowGovernanceBaseline, DelegationTaskType, } from "./core/types.js";
 export { Type } from "typebox";
 export type { TSchema, Static } from "typebox";
 export { explainPromptAssembly, describeDefaultPack, type DefaultPackDescription, type ExplainInput } from "./prompt-assembly/explain.js";

package/dist/index.js

@@ -72,7 +72,7 @@ export { runExecGate } from "./core/exec-gate.js";
 export { sanitizeUntrustedText, delimitUntrusted, inlineUntrusted } from "./core/untrusted-text.js";
 export { mintReminderMark, isValidReminderMark, openSystemReminder, mintSystemReminder, reminderMarkDeclaration } from "./core/reminder-mint.js";
 export { deriveInvariants, checkInvariants } from "./core/property-harness.js";
-export { bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
+export { bashReversibilityProbe, bashReadBoundaryProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
 export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { READ_FACE_DEFAULT_DENY_ENTRIES, READ_FACE_BUILTIN_DENY_TABLE, READ_DENY_BUILTIN_TIERS, READ_DENY_DEFAULT_TIERS, resolveReadDenyBuiltins, compileReadDeny, } from "./tools/fs/index.js";
@@ -138,8 +138,9 @@ export { createSchedulerTools, SCHEDULE_WAKEUP_TOOL_NAME, AUTONOMOUS_LOOP_SENTIN
 export { resolveAutonomousLoopPrompt, AUTONOMOUS_LOOP_PREAMBLE, AUTONOMOUS_LOOP_PREAMBLE_PERSISTENT, } from "./tools/loop-tick.js";
 export { tightenTaskSpec, TaskSpecTightenError } from "./core/tighten-task-spec.js";
 export { createAllowDenyPolicy, createApprovalPolicy, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, decisionText, resolveAsk, toolPolicyNameSets, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
-export { ASK_ORIGINS, isAskOrigin, classifierMayAnswer, ORIGIN_IMPLIES_REAL_APPROVAL } from "./core/ask-origin.js";
-export { SETTLEMENT_KINDS, isSettlementKind, SETTLEMENT_IS_REFUSAL, DENIED_BY_VALUES, isDeniedBy, DENIED_BY_MAY_VETO, screenGateOutcome } from "./core/gate-outcome.js";
+export { ASK_ORIGINS, isAskOrigin, classifierMayAnswer, ORIGIN_IMPLIES_REAL_APPROVAL, RULE_STORE_UNREADABLE_KINDS, isRuleStoreUnreadable } from "./core/ask-origin.js";
+export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./core/runtime-caps.js";
+export { SETTLEMENT_KINDS, isSettlementKind, SETTLEMENT_IS_REFUSAL, DENIED_BY_VALUES, isDeniedBy, DENIED_BY_MAY_VETO, CLASSIFIER_DENY_CAUSES, isClassifierDenyCause, DENIED_BY_MAY_CARRY_CAUSE, screenGateOutcome } from "./core/gate-outcome.js";
 export {} from "./core/hooks.js";
 export { SWAPPABLE_DEP_SEATS, SWAP_SEAT_NOTICE, isSwappableDepSeat, screenSwappableDeps } from "./core/swappable-deps.js";
 export { parseAutoModeResponse, createAutoModeDecider, AUTO_MODE_UNAVAILABLE_CAUSES, isAutoModeUnavailableCause, classifierUnavailableDenyMessage, CLASSIFIER_PARSE_FAILURE_DENY_MESSAGE, createAutoModeDenialTracker, denialLimitFallbackMessage, denialLimitSentence, unarmedWindow, } from "./core/auto-mode.js";
@@ -186,7 +187,7 @@ export { buildTurnPromptSnapshot, loweringRecordFor, LOWERING_VERSION, PREFIX_IN
 export { CenterPromptSource, FilePromptArtifactStore, FilePromptSourceStateStore, MemoryPromptArtifactStore, MemoryPromptSourceStateStore, } from "./prompt-assembly/artifact-store.js";
 export { stripEngineMetadata } from "./internal/llm.js";
 export { EVENT_PROMPT_REGISTRY, eventDefaultOn } from "./prompt-assembly/event-registry.js";
-export { DEFAULT_EFFORT_LEVELS, REASONING_BUDGET_SHARE, isThinkingLevel, rankOf, resolveEffort, resolveBinary, reasoningBudgetShare, resolveReasoning, thinkingOffExpressible, declaredOffSpelling, resolveReasoningProfile, } from "./brain/reasoning.js";
+export { DEFAULT_EFFORT_LEVELS, REASONING_BUDGET_SHARE, isThinkingLevel, rankOf, resolveEffort, reasoningEffortLevelsOf, resolveBinary, reasoningBudgetShare, resolveReasoning, thinkingOffExpressible, declaredOffSpelling, resolveReasoningProfile, } from "./brain/reasoning.js";
 export { DESIGN_REVIEW_PROMPTS, CODE_REVIEW_PROMPT, SCENARIO_REGISTRY, runScenario, } from "./scenarios/scenario-registry.js";
 export { teacherMode, TEACHER_PROFILE, } from "./scenarios/teacher-quickstart.js";
 export { loadOrchestrationEnv, DEFAULT_REASONING_INTENSITY, } from "./scenarios/env.js";

package/dist/orchestration/run-workflow-tool.d.ts

@@ -277,7 +277,7 @@ export interface RunWorkflowToolDeps {
      *  tighten-only ruling; the workflow lane was the remaining gap — a read-only host's workflow
      *  children spawned with full write hands). Filled ONLY when the clamp is ON (`true`), exactly
      *  like the ctx seat, so an unclamped deployment's mount gains no key. Known at prepare-time
-     *  (frozen TaskSpec snapshot — no lazy getter needed, the `parentCheckpointStoreDisabled` shape). */
+     *  (frozen TaskSpec snapshot — no lazy getter needed, the `parentCheckpointStore` shape). */
     parentHandsReadOnly?: true;
     /** #345 ③ — the HOST task's hard-headless clamp (`interactiveTools: false`), same carriage rules
      *  as `parentHandsReadOnly` above: only the DISABLING value travels, mirroring the subagent lane's
@@ -352,13 +352,13 @@ export interface RunWorkflowToolDeps {
     autoModeReview?: () => {
         decider: import("../core/auto-mode.js").AutoModeDecider;
     } | undefined;
-    /** 5.30 merge-rescan round 2 — the HOST task's durable OFF SWITCH (`spec.checkpointStore === "disabled"`,
-     *  ruled 2026-08-04 to inherit into every spawned agent, see `buildWorkflowPrimitives`'s call
-     *  above). Known at prepare-time (no lazy getter needed — `spec` is available at mount). A dep for
-     *  the same reason as `forwardEvent`/`inheritedGateForChildren`: the auto-mounted tool's execute
-     *  ctx is minimal `{toolCallId, signal}`, so `ctx.checkpointStoreDisabledForChildren` was a DEAD
-     *  read there — the off-switch never actually reached this lane's children. */
-    parentCheckpointStoreDisabled?: boolean;
+    /** The HOST run's RESOLVED checkpoint seat — the store object the host parks in, else the word `"disabled"`
+     *  (the same two-state value the delegation ctx carries as `ToolExecuteContext.checkpointStoreForChildren`;
+     *  `ctx` wins on a rich-ctx mount). Every agent this workflow spawns inherits it verbatim unless its own
+     *  spec (baseline / trusted script) pinned a store — and `"disabled"` lands unconditionally (a removal the
+     *  baseline must not undo); see `buildWorkflowPrimitives`. A dep for the same reason as `forwardEvent`/
+     *  `inheritedGateForChildren`: the auto-mounted tool's execute ctx is minimal `{toolCallId, signal}`. */
+    parentCheckpointStore?: import("../core/checkpoint-store.js").CheckpointStore | "disabled";
     /** #235 — the deployment's structured notice sink (`RunnerDeps.onNotice`), forwarded into the governed
      *  build so the fields a script's agent spec wrote that did NOT reach the child are announced instead of
      *  vanishing (`workflow.governance_key_stripped`). #505 ① — the same seat now also carries the OPTIONS

package/dist/orchestration/run-workflow-tool.js

@@ -488,7 +488,7 @@ export async function createRunWorkflowTool(d) {
                 }
                 : governance;
             const scriptFn = (wfCtx) => {
-                const primitives = buildWorkflowPrimitives(wfCtx, runGovernance, d.onAgentSpawn, principal, ctx.checkpointStoreDisabledForChildren === true || d.parentCheckpointStoreDisabled === true, d.parentReadFace, d.parentReadDenyPatterns, ctx.handsReadOnly === true || d.parentHandsReadOnly === true, ctx.interactiveTools === false || d.parentInteractiveTools === false);
+                const primitives = buildWorkflowPrimitives(wfCtx, runGovernance, d.onAgentSpawn, principal, ctx.checkpointStoreForChildren ?? d.parentCheckpointStore, d.parentReadFace, d.parentReadDenyPatterns, ctx.handsReadOnly === true || d.parentHandsReadOnly === true, ctx.interactiveTools === false || d.parentInteractiveTools === false);
                 return d.scriptRunner.run({ scriptSource: script, primitives, scriptArgs: effectiveArgs, signal: wfCtx.signal }).then((r) => r.result);
             };
             if (ctx.signal?.aborted) {

package/dist/orchestration/workflow-primitives.d.ts

@@ -14,6 +14,7 @@
  */
 import type { Model } from "../internal/llm.js";
 import type { TaskSpec, WorkflowGovernanceBaseline } from "../core/types.js";
+import type { CheckpointStore } from "../core/checkpoint-store.js";
 import type { WorkflowAgentHandle, WorkflowRunContext } from "./workflow.js";
 import type { WorkflowPrimitives } from "./workflow-script-runner.js";
 import { type WorkflowChildCaps } from "./workflow-governance.js";
@@ -36,9 +37,9 @@ export interface WorkflowGovernance {
  * — filling them here ran ahead of the fold and made the fold's "when unset" guard permanently false.
  */
 export declare function buildWorkflowPrimitives(ctx: WorkflowRunContext, governance?: WorkflowGovernance, onAgentSpawn?: (handle: WorkflowAgentHandle) => void, parentPrincipal?: string, 
-/** ruled 2026-08-04 — the host run set `TaskSpec.checkpointStore: "disabled"` (the per-run durable off
- *  switch). Every agent this workflow spawns inherits it; see the injection below. */
-parentCheckpointStoreDisabled?: boolean, 
+/** The host run's RESOLVED checkpoint seat — the store object it parks in, else the word `"disabled"`.
+ *  Every agent this workflow spawns inherits it; see the injection below. */
+parentCheckpointStore?: CheckpointStore | "disabled", 
 /** 5.30 merge-rescan (design/199 parity gap) — the host run's RESOLVED read-face containment
  *  (post deps/org/mount resolution, not the raw spec value). `TaskSpec.readFace`'s own JSDoc
  *  promises "roots pins this task, and via the tighten-only clamp, its whole delegation subtree" —

package/dist/orchestration/workflow-primitives.js

@@ -65,7 +65,7 @@ function formatResourceClampNote(notes) {
     const parts = notes.map((n) => `${n.field}: requested ${n.requested === undefined ? "unset" : n.requested} → applied ${n.applied}`);
     return `workflow governance tightened this agent's resource limits (${parts.join("; ")})`;
 }
-export function buildWorkflowPrimitives(ctx, governance, onAgentSpawn, parentPrincipal, parentCheckpointStoreDisabled, parentReadFace, parentReadDenyPatterns, parentHandsReadOnly, parentInteractiveToolsOff) {
+export function buildWorkflowPrimitives(ctx, governance, onAgentSpawn, parentPrincipal, parentCheckpointStore, parentReadFace, parentReadDenyPatterns, parentHandsReadOnly, parentInteractiveToolsOff) {
     const agent = (spec, opts) => {
         if (typeof spec === "string")
             spec = { objective: spec };
@@ -77,8 +77,8 @@ export function buildWorkflowPrimitives(ctx, governance, onAgentSpawn, parentPri
         if (childSpec.principal === undefined && parentPrincipal !== undefined) {
             childSpec.principal = parentPrincipal;
         }
-        if (parentCheckpointStoreDisabled === true) {
-            childSpec.checkpointStore = "disabled";
+        if (parentCheckpointStore !== undefined && (parentCheckpointStore === "disabled" || childSpec.checkpointStore === undefined)) {
+            childSpec.checkpointStore = parentCheckpointStore;
         }
         if (parentReadFace) {
             const pf = parentReadFace();

package/dist/orchestration/workflow-types.d.ts

@@ -328,6 +328,20 @@ export interface WorkflowRun {
     rev?: number;
     /** Set when `status === "failed"`: the error the script threw. */
     error?: string;
+    /** #688 C4 (additive) — the MACHINE code of the failure that ended the run, in the same vocabulary as
+     *  {@link WorkflowAgentRun.errorCode} (`workflow.*` for the orchestration's own refusals, a task's terminal code
+     *  for a child's failure), so a consumer branches here and never on `error`'s text. Attribution, in order:
+     *   1. the thrown value's own string `code` — the run SUSPENDED on a parked agent ⇒ `workflow.agent_parked`
+     *      (whatever the body threw after the park), a refused spawn ⇒ `workflow.agent_blocked`, the budget /
+     *      nesting / schema / stall / max-agents refusals ⇒ their `WorkflowBudgetExceededError`… codes, a body that
+     *      re-threw a typed error ⇒ that error's code;
+     *   2. otherwise the FIRST failed agent record carrying a code (earliest `endedAt`, spawn order on a tie) —
+     *      the body gave up after a child failed and threw in its own words; with several failed children the
+     *      first to fail is the one taken (a body that threw for an unrelated reason beside a failed child still
+     *      reads that child's code — `error` keeps the body's own sentence);
+     *   3. absent — a body that threw a codeless error with no failed child on the record.
+     *  Absent on `completed` runs (their per-agent failures ride `agentFailures` + each `WorkflowAgentRun.errorCode`). */
+    errorCode?: string;
     /** The script's RETURN VALUE, bounded + redacted at completion time (same egress
      *  discipline as the notifier `result`), so a terminal `TaskOutput` poll can hand the
      *  model the result instead of sending it in poll circles. Absent on failed runs and runs recorded by

package/dist/orchestration/workflow.d.ts

@@ -547,10 +547,47 @@ export interface WorkflowHandle<T> {
 }
 /** Cap on items a single `parallel`/`pipeline` call accepts (matches the CC Workflow tool). */
 export declare const MAX_WORKFLOW_ITEMS = 4096;
-/** CC `MTy` (206-pretty.js:17501680; 198 `F0m`): no tool activity for this long marks the attempt STALLED
- *  (progress-based, unlike the governance perAgentTimeoutSec hard cap, which still bounds each attempt).
- *  `<= 0` DISABLES the watchdog (CC arms only `if (ae > 0)`, :17477830). */
-export declare const WORKFLOW_AGENT_STALL_MS = 180000;
+/**
+ * CC `MTy` (206-pretty.js:17501680; 198 `F0m`): no tool activity for this long marks the attempt STALLED
+ * (progress-based, unlike the governance perAgentTimeoutSec hard cap, which still bounds each attempt).
+ * `<= 0` DISABLES the watchdog (CC arms only `if (ae > 0)`, :17477830).
+ *
+ * DERIVED, not a number of its own (#682): an OUTER, COARSER clock must never fire before the engine's
+ * own. This watchdog does not re-send a model call — it aborts the attempt and restarts the whole agent
+ * on a FRESH session, so tool effects from before the stall can be repeated. The engine, one layer down,
+ * already answers a silent provider call the cheap way: it re-sends that ONE call. So the floor here is
+ * what a single provider call may legitimately occupy while producing NOTHING — the connect wait plus the
+ * first-token wait ({@link STALL_CONNECT_MS} + {@link STALL_FIRST_TOKEN_MS}). It was a hand-written
+ * 180_000 and CC-same until the first-token bound rose to 600s past it (measured: the same silent call
+ * then produced two agent runs on two sessions instead of one run with a re-sent call), which is the
+ * systematic inversion a derived value cannot re-open: raise or lower the engine's bound and this follows.
+ *
+ * WHAT THIS IS NOT (measured, adversarial round — do not read the sum as a proof of ordering). The two
+ * clocks do not start together and this one does not reset per inner retry, so it can still fire first:
+ * this timer starts before the Runner prepares the attempt (an execution-env factory, a hook, a store
+ * read all run inside this window and outside the engine's), and the first-token timer only starts once
+ * headers arrive — so the margin by which the inner deadline can land AFTER this one is preparation plus
+ * the connect time actually spent, less the {@link STALL_CONNECT_MS} this window already budgets for it
+ * (40s of preparation and instant headers puts the first inner deadline 10s past this timer). An engine retry does not re-arm this timer either, so two silent provider attempts
+ * exceed it by construction. The derivation removes the case that was guaranteed to invert; it does not
+ * make inversion impossible. A deployment that wants the old aggression passes `stallMs` explicitly, and
+ * a deployment that wants a real guarantee must set it from its own preparation budget.
+ */
+export declare const WORKFLOW_AGENT_STALL_MS: number;
+/**
+ * The "took suspiciously long" half of the throttle-shaped-degradation predicate (CC `Nt`,
+ * 206-pretty.js:17487400, which spells it `MTy * 0.5` = 90s). It used to be computed from the stall
+ * window here too, and that was safe only while the window was CC's own 180_000 — the moment the window
+ * became derived from the engine's bounds (#682/#693) the same expression silently moved the throttle
+ * threshold 90s → 315s, and a 2-minute empty answer that used to earn a 45s-sleep-and-retry was simply
+ * returned. Two unrelated meanings were riding one number. This is the second meaning, at CC's own
+ * value, so the progress window can move without touching it.
+ *
+ * Still a MINIMUM with the window, not a replacement for it: a deployment that shortens `stallMs` below
+ * this is asking for a tighter agent, and a throttle threshold above its own stall window could never
+ * fire. So the effective threshold is `min(stallMs / 2, this)` — one rule, both directions.
+ */
+export declare const WORKFLOW_THROTTLE_SLOW_MS = 90000;
 /** CC `j_d` (206-pretty.js:17501680; 198 `Mxl`): max stalled-attempt retries per `ctx.agent` call
  *  (initial + 5 = 6 attempts). */
 export declare const WORKFLOW_AGENT_MAX_RETRIES = 5;

package/dist/orchestration/workflow.js

@@ -21,6 +21,7 @@ import { OUTPUT_TOOL_NAME } from "../core/runner/synthetic-tools.js";
 import { compileOutputSchema } from "../core/runner/strict-output-schema.js";
 import { WorkflowBudgetExceededError, WorkflowNestingError, WorkflowAgentBlockedError, WorkflowAgentParkedError, WorkflowAgentSchemaError, WorkflowAgentStalledError, WorkflowMaxAgentsError, WORKFLOW_SPAWN_BLOCKED_ERROR_CODE } from "./workflow-types.js";
 import { WorkflowScriptError } from "./workflow-meta.js";
+import { STALL_CONNECT_MS, STALL_FIRST_TOKEN_MS } from "../brain/timeout.js";
 export * from "./workflow-types.js";
 const MAX_TRANSCRIPT_CHARS = 4000;
 const WORKFLOW_RESULT_MAX = 4000;
@@ -149,6 +150,7 @@ export function workflowAgentCallKey(ordinal, spec, opts) {
         signal: undefined,
         taskId: undefined,
         sessionId: undefined,
+        checkpointStore: undefined,
         tools: spec.tools?.map((t) => t.name).slice().sort(),
         mcp: spec.mcp?.map((m) => m.name).slice().sort(),
         outputSchema: opts.schema ?? spec.outputSchema,
@@ -278,7 +280,8 @@ function assertFanOutOptionsShape(v, position) {
             `Nothing was run.`);
     }
 }
-export const WORKFLOW_AGENT_STALL_MS = 180_000;
+export const WORKFLOW_AGENT_STALL_MS = STALL_CONNECT_MS + STALL_FIRST_TOKEN_MS;
+export const WORKFLOW_THROTTLE_SLOW_MS = 90_000;
 export const WORKFLOW_AGENT_MAX_RETRIES = 5;
 export const WORKFLOW_AGENT_THROTTLE_BACKOFF_MS = 45_000;
 function readLegPendingApproval(result, announce) {
@@ -1604,7 +1607,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                         result.structuredOutput === undefined &&
                         (result.stats.outputTokens ?? Number.POSITIVE_INFINITY) < 50 &&
                         lastStopReason === undefined &&
-                        durationMs > stallMs * 0.5;
+                        durationMs > Math.min(stallMs * 0.5, WORKFLOW_THROTTLE_SLOW_MS);
                     if (degraded && attempts === 1 && !throttleRetried && drive === undefined) {
                         throttleRetried = true;
                         lastAttemptReason = "throttled";
@@ -1689,7 +1692,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                             ...(err instanceof WorkflowAgentBlockedError ? { code: WORKFLOW_SPAWN_BLOCKED_ERROR_CODE } : err instanceof WorkflowBudgetExceededError ? { code: err.code } : {}),
                             message: boundedRedactedSummary(err instanceof Error ? err.message : String(err), 500),
                         },
-                        stats: { turns: 0, tokens: 0, costMicroUsd: 0 },
+                        stats: { turns: 0, tokens: 0, costMicroUsd: 0, usageMissing: true },
                     }, label).catch(() => undefined);
                     if (!((err instanceof WorkflowBudgetExceededError || err instanceof WorkflowAgentParkedError) && rec.startedAt === undefined))
                         await journaled;
@@ -1801,7 +1804,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     sessionId: "",
                     terminal: { kind: "failed", code: refusal.code, message: boundedRedactedSummary(refusal.message, 500) },
                     result: boundedRedactedSummary(refusal.message, 500),
-                    stats: { turns: 0, tokens: 0, costMicroUsd: 0 },
+                    stats: { turns: 0, tokens: 0, costMicroUsd: 0, usageMissing: true },
                 }).catch(() => undefined);
                 throw refusal;
             }
@@ -1875,7 +1878,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                         sessionId: "",
                         terminal: { kind: "failed", code: WORKFLOW_SPAWN_BLOCKED_ERROR_CODE, message: boundedRedactedSummary(err.message, 500) },
                         result: boundedRedactedSummary(err.message, 500),
-                        stats: { turns: 0, tokens: 0, costMicroUsd: 0 },
+                        stats: { turns: 0, tokens: 0, costMicroUsd: 0, usageMissing: true },
                     }).catch(() => undefined);
                 }
                 recordFailed();
@@ -2224,6 +2227,21 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 err = parkedError();
             run.error = err instanceof Error ? err.message : String(err);
             closeAbandonedAgents(run.endedAt);
+            {
+                let thrownCode;
+                try {
+                    thrownCode = err !== null && (typeof err === "object" || typeof err === "function") ? err.code : undefined;
+                }
+                catch {
+                    thrownCode = undefined;
+                }
+                const firstFailed = run.agents
+                    .filter((a) => a.status === "failed" && typeof a.errorCode === "string" && a.errorCode !== "")
+                    .sort((a, b) => (a.endedAt ?? Number.POSITIVE_INFINITY) - (b.endedAt ?? Number.POSITIVE_INFINITY))[0];
+                const code = typeof thrownCode === "string" && thrownCode !== "" ? thrownCode : firstFailed?.errorCode;
+                if (code !== undefined)
+                    run.errorCode = code;
+            }
             restampPhaseFailures();
             const failedRunFailures = countAgentFailures();
             if (failedRunFailures > 0)

package/dist/tools/fs/fs-bash.d.ts

@@ -56,6 +56,47 @@ import { type BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
  * that adds nothing the reader cannot already see.
  */
 export declare function bashReversibilityProbe(allow?: readonly string[], boundary?: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined)): (args: unknown) => ReversibilityVerdict;
+/**
+ * The READ-BOUNDARY seat of the full shell: a `ToolSpec.reversibilityProbe` that answers exactly ONE
+ * question — does the deployment's read boundary object to where this command reads? — and nothing about
+ * the command's shape. It is the shell face of the rule every read face obeys: the structured readers
+ * (Read/Grep/Glob) refuse a deny-listed or out-of-root target; the shell reader gets a MANDATED ask for the
+ * same target. The engine installs it on Bash and Monitor whenever a real writable shell is mounted and the
+ * shellGate doctrine adds no residual-risk classifier of its own (`shellGate:"off"`, the default); under
+ * `"classify"` the doctrine installs {@link bashReversibilityProbe} instead, which composes THIS judgment
+ * with the read-only shape classifier, and under `"always"` the tier itself is the mandate and no probe runs.
+ * The boundary is therefore judged under every doctrine; the doctrine decides only what happens to the
+ * residual shell risk.
+ *
+ * The verdict, in the probe vocabulary the gate reads (`reversible` here means "the boundary raised no
+ * question — the seat vouches the call may run"):
+ *  · the boundary DECLARED an objection — a deny-listed operand, a recursive walk under the deny judge, an
+ *    operand outside the roots — ⇒ `{ reversible: false, mandated: true }` (+ the recursive-reach `cause`);
+ *  · the boundary could NOT READ where the command reads — an unexpanded glob operand (the compound face
+ *    reports it as undecided), a `~`-rooted operand with no home declared, a working-directory move the walk
+ *    cannot model — ⇒ `{ reversible: false }` (fail-closed; a plain ask, which a stored allow rule may retire —
+ *    the seat did not declare anything, it declined to guess);
+ *  · otherwise ⇒ `{ reversible: true }`. This includes every command whose SHAPE the read faces refuse whole
+ *    (an unlisted program, a redirection, a substitution, a segment that is not a reader): those shapes carry
+ *    no read-face verdict, so this seat has no question to ask — the residual is the doctrine's, and under
+ *    `"off"` the doctrine asks nothing. `run_in_background` is likewise not this seat's question (it changes
+ *    WHEN the command runs, never WHERE it reads).
+ *
+ * Reach = the read faces' reach, and nothing wider: the compound face walks the operands of a command whose
+ * every segment is a listed reader, and the bounded poll-loop face walks a loop body of listed readers. A
+ * read hidden in a shape the faces refuse whole (`cat x | <unlisted>`, `$(cat x)`, `cat $DIR/x`, a launcher
+ * `env cat x`, a path-prefixed `/bin/cat x`) is not seen here — deny-listed or out-of-root alike — exactly
+ * the shapes the `"classify"` doctrine exists to ask about. The text-level containment gate the classify
+ * seat consults on its demotion arms is deliberately not consulted here ({@link boundaryDeclared}: it may
+ * add a mandate to an ask, never originate one). The poll-loop face reports its refusal as one sentence,
+ * so the boundary's share of it is read by removing the boundary's judging seats
+ * ({@link pollLoopBoundaryVerdict}).
+ *
+ * The reader set is the engine's classify set ({@link BASH_CLASSIFY_DEFAULT_ALLOW}) — here it is NOT an
+ * auto-allow list but the set of programs whose operands the faces read; a wider set means more reads are
+ * judged, never that more runs are vouched.
+ */
+export declare function bashReadBoundaryProbe(boundary: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined)): (args: unknown) => ReversibilityVerdict;
 /**
  * design/199 D-6 — the FULL shell's contract id, single-sourced: both shell faces share the wire
  * name "Bash", so this id is the ONE structural discriminator between the write-capable shell and

package/dist/tools/fs/fs-bash.js

@@ -25,40 +25,100 @@ function operandFamily(paths) {
 export function bashReversibilityProbe(allow, boundary) {
     const allowSet = new Set(allow ?? BASH_CLASSIFY_DEFAULT_ALLOW);
     return (args) => {
-        const a = args;
-        const command = a?.command;
-        if (typeof command !== "string")
+        const command = shellCommandOf(args);
+        if (command === undefined)
             return { reversible: false };
         const resolved = typeof boundary === "function" ? boundary() : boundary;
-        const outOfRootGate = () => resolved !== undefined && classifyOutOfRootReadGate(command, allowSet, resolved).gated ? { mandated: true } : {};
-        const boundaryGate = (verdict) => verdict.readDenied === true || (verdict.recursiveReadPaths !== undefined && verdict.recursiveReadPaths.length > 0) ? { mandated: true } : outOfRootGate();
-        const backgrounded = a?.run_in_background === true;
+        const boundaryGate = (verdict) => readBoundaryMandate(command, allowSet, resolved, verdict);
+        const outOfRootGate = () => readBoundaryMandate(command, allowSet, resolved, {});
+        const backgrounded = isBackgroundShellCall(args);
         const detailed = classifyCompoundReadonlyDetailed(command, allowSet, resolved);
         if (backgrounded)
             return { reversible: false, ...boundaryGate(detailed) };
         if (detailed.reason === undefined) {
             if (detailed.undecidedPaths !== undefined && detailed.undecidedPaths.length > 0) {
-                const recursive = detailed.recursiveReadPaths;
-                if (recursive !== undefined && recursive.length > 0) {
-                    const recursiveSet = new Set(recursive);
-                    const others = detailed.undecidedPaths.filter((p) => !recursiveSet.has(p));
-                    return {
-                        reversible: false,
-                        ...boundaryGate(detailed),
-                        cause: {
-                            code: RECURSIVE_READ_CAUSE_CODE,
-                            roots: operandFamily(recursive),
-                            ...(others.length > 0 ? { further: operandFamily(others) } : {}),
-                        },
-                    };
-                }
+                const cause = recursiveReadCause(detailed);
+                if (cause !== undefined)
+                    return { reversible: false, ...boundaryGate(detailed), cause };
                 return { reversible: false, ...outOfRootGate() };
             }
             return { reversible: true };
         }
-        return classifyBoundedReadonlyPollLoop(command, allowSet, resolved) === undefined
-            ? { reversible: true }
-            : { reversible: false, ...boundaryGate(detailed) };
+        const loopRefusal = classifyBoundedReadonlyPollLoop(command, allowSet, resolved);
+        if (loopRefusal === undefined)
+            return { reversible: true };
+        return { reversible: false, ...(pollLoopBoundaryVerdict(command, allowSet, resolved, loopRefusal) === "declared" ? { mandated: true } : boundaryGate(detailed)) };
+    };
+}
+function attributeRefusal(face, resolved, fullRefusal) {
+    if (resolved === undefined)
+        return "shape";
+    const { denyMatch: _deny, ...withoutDenyJudge } = resolved;
+    const opened = face({ ...withoutDenyJudge, face: "open" });
+    if (opened === undefined || opened !== fullRefusal)
+        return "declared";
+    return face(undefined) === opened ? "shape" : "unread";
+}
+function pollLoopBoundaryVerdict(command, allowSet, resolved, fullRefusal) {
+    return attributeRefusal((b) => classifyBoundedReadonlyPollLoop(command, allowSet, b), resolved, fullRefusal);
+}
+function boundaryDeclared(verdict) {
+    return denyJudgeSpoke(verdict) || verdict.outOfRootRead === true;
+}
+function denyJudgeSpoke(verdict) {
+    return verdict.readDenied === true || (verdict.recursiveReadPaths !== undefined && verdict.recursiveReadPaths.length > 0);
+}
+function shellCommandOf(args) {
+    const command = args?.command;
+    return typeof command === "string" ? command : undefined;
+}
+function isBackgroundShellCall(args) {
+    return args?.run_in_background === true;
+}
+function readBoundaryMandate(command, allowSet, resolved, verdict) {
+    if (denyJudgeSpoke(verdict))
+        return { mandated: true };
+    return resolved !== undefined && classifyOutOfRootReadGate(command, allowSet, resolved).gated ? { mandated: true } : {};
+}
+function recursiveReadCause(detailed) {
+    const recursive = detailed.recursiveReadPaths;
+    if (recursive === undefined || recursive.length === 0)
+        return undefined;
+    const recursiveSet = new Set(recursive);
+    const others = (detailed.undecidedPaths ?? []).filter((p) => !recursiveSet.has(p));
+    return {
+        code: RECURSIVE_READ_CAUSE_CODE,
+        roots: operandFamily(recursive),
+        ...(others.length > 0 ? { further: operandFamily(others) } : {}),
+    };
+}
+export function bashReadBoundaryProbe(boundary) {
+    const allowSet = new Set(BASH_CLASSIFY_DEFAULT_ALLOW);
+    return (args) => {
+        const command = shellCommandOf(args);
+        if (command === undefined)
+            return { reversible: false };
+        const resolved = typeof boundary === "function" ? boundary() : boundary;
+        if (resolved === undefined)
+            return { reversible: true };
+        const detailed = classifyCompoundReadonlyDetailed(command, allowSet, resolved);
+        if (boundaryDeclared(detailed)) {
+            const cause = recursiveReadCause(detailed);
+            return { reversible: false, mandated: true, ...(cause !== undefined ? { cause } : {}) };
+        }
+        if (detailed.reason === undefined) {
+            return detailed.undecidedPaths !== undefined && detailed.undecidedPaths.length > 0 ? { reversible: false } : { reversible: true };
+        }
+        const compound = attributeRefusal((b) => classifyCompoundReadonlyDetailed(command, allowSet, b).reason, resolved, detailed.reason);
+        if (compound === "declared")
+            return { reversible: false, mandated: true };
+        if (compound === "unread")
+            return { reversible: false };
+        const loopRefusal = classifyBoundedReadonlyPollLoop(command, allowSet, resolved);
+        if (loopRefusal === undefined)
+            return { reversible: true };
+        const loop = pollLoopBoundaryVerdict(command, allowSet, resolved, loopRefusal);
+        return loop === "shape" ? { reversible: true } : loop === "declared" ? { reversible: false, mandated: true } : { reversible: false };
     };
 }
 export { FULL_SHELL_CONTRACT_ID } from "../../core/tool-catalog-entries.js";
@@ -563,13 +623,10 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
             })),
         }),
         isConcurrencySafe: (args) => {
-            const cmd = args?.command;
-            if (typeof cmd !== "string")
-                return false;
-            const bg = args.run_in_background;
-            if (bg === true)
+            const command = shellCommandOf(args);
+            if (command === undefined || isBackgroundShellCall(args))
                 return false;
-            return coarseReadonlyCheck(cmd, new Set(BASH_READONLY_DEFAULT_ALLOW)) === undefined;
+            return coarseReadonlyCheck(command, new Set(BASH_READONLY_DEFAULT_ALLOW)) === undefined;
         },
         execute: async (args, ctx) => {
             const { command, timeout, run_in_background, description } = args;

package/dist/tools/fs/fs-shared.js

@@ -6,6 +6,7 @@ import { shellQuote } from "./search.js";
 import { isNotebookPath } from "./notebook.js";
 import { sharpImageDownsampler } from "../../core/mcp.js";
 import { deliverEngineNotice } from "../../core/types.js";
+import { announceEnvKnob } from "../../core/env-knob-announce.js";
 import { openSystemReminder } from "../../core/reminder-mint.js";
 export const MAX_READ_BYTES = 256 * 1024;
 export const SLICED_READ_MAX_BYTES = 64 * 1024 * 1024;
@@ -181,10 +182,15 @@ export function bashTimeoutCapsSec(caps) {
 const BASH_DEFAULT_MAX_OUTPUT_CHARS = 30_000;
 const BASH_MAX_OUTPUT_CHARS_CEILING = 150_000;
 export function bashMaxOutputChars() {
-    const raw = Number(process.env.BASH_MAX_OUTPUT_LENGTH);
-    if (!Number.isFinite(raw) || raw <= 0)
+    const rawEnv = process.env.BASH_MAX_OUTPUT_LENGTH;
+    if (rawEnv === undefined || rawEnv.trim() === "")
         return BASH_DEFAULT_MAX_OUTPUT_CHARS;
-    return Math.min(Math.floor(raw), BASH_MAX_OUTPUT_CHARS_CEILING);
+    const raw = Number(rawEnv);
+    if (!Number.isInteger(raw) || raw <= 0) {
+        announceEnvKnob(`BASH_MAX_OUTPUT_LENGTH=${rawEnv} was ignored — it is not a positive whole number of characters. Using ${BASH_DEFAULT_MAX_OUTPUT_CHARS} instead.`);
+        return BASH_DEFAULT_MAX_OUTPUT_CHARS;
+    }
+    return Math.min(raw, BASH_MAX_OUTPUT_CHARS_CEILING);
 }
 export const FILE_PATH_PARAMS = {
     file_path: Type.String({ description: "File path (within the configured root)." }),

package/dist/tools/fs/read-deny.d.ts

@@ -65,7 +65,7 @@ export interface ReadDenyMatcher {
  * exactly one. Unknown tier names refuse loudly (#123) — this array is the validation source and the
  * admin-face vocabulary, never re-spelled downstream.
  */
-export declare const READ_DENY_BUILTIN_TIERS: readonly ["credentials", "shell-history", "browser", "wallet"];
+export declare const READ_DENY_BUILTIN_TIERS: readonly ["credentials", "shell-history", "browser", "wallet", "agent-config"];
 /** One member of {@link READ_DENY_BUILTIN_TIERS}. */
 export type ReadDenyBuiltinTier = (typeof READ_DENY_BUILTIN_TIERS)[number];
 /**
@@ -90,17 +90,33 @@ export interface ReadDenyBuiltinRow {
  * and a false refusal on a fixture is the cheap direction (deny errs strict).
  *
  * NOT listed, deliberately: `.env`/`.env.*` (ruled out — workspace material; the WRITE guard still
- * covers them); `*.pem`/`*.key`/`*.p12`/`*.pfx` (repo certificates/test keys are routinely READ —
- * refusing them breaks ordinary work, the write guard covers the mutation direction); `.git/hooks`/
- * `.git/config` (reads are harmless; writes are the escalation and stay guarded); `.claude*`/
- * `.mcp.json` (agent config is routinely read for debugging); the engine's own data root
- * (transcript integrity policy owns it with an ask on the write face).
+ * covers them; the ENGINE's own `.env` under its data root is a different file and IS listed, see the
+ * agent-config tier); `*.pem`/`*.key`/`*.p12`/`*.pfx` (repo certificates/test keys are routinely
+ * READ — refusing them breaks ordinary work, the write guard covers the mutation direction);
+ * `.git/hooks`/`.git/config` (reads are harmless; writes are the escalation and stay guarded); the
+ * engine's own data root as a WHOLE (transcript integrity policy owns it with an ask on the write
+ * face, and the memory library the model is told to read and edit lives under it).
+ *
+ * agent-config tier — the agent's OWN configuration files whose `env` / server blocks carry API keys
+ * in cleartext (the shell's `settings.json` env block, a project `.mcp.json` server env, the engine
+ * host's data-root `.env`). A structured read of one of these used to land the key verbatim in the
+ * tool result and therefore in the session record. Rows name FILES, not the config DIRECTORIES:
+ * `.sema`/`.claude` also hold agents, skills, hooks and (under the shell's layout,
+ * `~/.sema/engine-data`) the engine data root with the memory library — material the model reads
+ * and edits as ordinary work, and a directory-wide row would need a data-root passthrough (one more
+ * rule) to keep it readable. The write face guards the directories (`sensitive-path-policy.ts`): a
+ * write there is self-authorization; a read of a non-credential file there is debugging. Token
+ * STORES of the same tooling (`.credentials.json`, `.codex/auth.json`, …) are credentials rows, not
+ * agent-config rows: a deployment that switches this tier off to debug its agent configuration must
+ * not also expose the OAuth stores beside it.
  */
 export declare const READ_FACE_BUILTIN_DENY_TABLE: readonly ReadDenyBuiltinRow[];
 /**
  * The DEFAULT tier selection (#245 ruling ②): every tier EXCEPT `shell-history` — history files are
- * unrestricted unless a deployment opts the tier in. Derived, not re-listed: a future tier added to
- * the closed set is default-ON unless this expression is deliberately revisited.
+ * unrestricted unless a deployment opts the tier in. Derived, not re-listed: a tier added to the
+ * closed set is default-ON unless this expression is deliberately revisited (`agent-config` joined
+ * default-ON this way: an unconfigured deployment refuses the agent's own key-bearing settings files;
+ * a deployment that debugs agent configuration selects `tiers` without it).
  */
 export declare const READ_DENY_DEFAULT_TIERS: readonly ReadDenyBuiltinTier[];
 /**