@sema-agent/core 5.55.0 → 5.57.0

package/dist/engine/harness/types.d.ts

@@ -62,7 +62,11 @@ export interface AgentHarnessStreamOptions {
     maxRetries?: number;
     /** Optional cap for provider-requested retry delays. */
     maxRetryDelayMs?: number;
-    /** Additional request headers merged with auth and lifecycle headers. */
+    /** Additional request headers merged with auth and lifecycle headers. NOT an auth channel: a bag
+     *  carrying an auth header (`authorization` / `x-api-key`, any case) is refused loudly at the
+     *  construction and `setStreamOptions` seats — the route pairing law reads options-borne
+     *  carriers as per-model credentials, which a run-wide bag is not. Deployment credentials go on
+     *  the brain config; per-model credentials ride `getApiKeyAndHeaders`. */
     headers?: Record<string, string>;
     /** Provider metadata forwarded with requests. */
     metadata?: SimpleStreamOptions["metadata"];
@@ -889,8 +893,12 @@ export interface SavePointEvent {
 }
 export interface AbortEvent {
     type: "abort";
-    clearedSteer: AgentMessage[];
-    clearedFollowUp: AgentMessage[];
+    /** backlog #389 — the caller frames still QUEUED when the abort fired. They are no longer cleared by
+     *  `abort()` (CC keeps its queue on interrupt): the terminal `agent_end` account announces them, so
+     *  this list is the same set that reaches `onUndrainedUserInputs`, observed one step earlier. */
+    undrainedSteer: AgentMessage[];
+    /** backlog #389 — the follow-up half of {@link AbortEvent.undrainedSteer}. */
+    undrainedFollowUp: AgentMessage[];
 }
 export interface SettledEvent {
     type: "settled";
@@ -1044,10 +1052,12 @@ export type AgentHarnessEventResultMap = {
     abort: undefined;
     settled: undefined;
 };
-/** Queued messages removed by an abort operation. */
+/** backlog #389 — what an abort found still QUEUED (it no longer removes caller frames; see
+ *  {@link AgentHarness.abort}). Engine-note frames are absent: their own sweep recovered them for
+ *  per-session redelivery before this snapshot was taken. */
 export interface AbortResult {
-    clearedSteer: AgentMessage[];
-    clearedFollowUp: AgentMessage[];
+    undrainedSteer: AgentMessage[];
+    undrainedFollowUp: AgentMessage[];
 }
 /** Compaction data supplied by hooks or returned from compaction preparation. */
 export interface CompactResult {

package/dist/engine/llm/types.d.ts

@@ -805,6 +805,71 @@ export interface ImagesModel<TApi extends ImagesApi = ImagesApi> extends Omit<Mo
     provider: ImagesProvider;
     output: ("text" | "image")[];
 }
+/** Where the credential a request would carry came from.
+ *  - `"per-model"` — resolved FOR this model: a per-call key/headers from the per-model auth hook
+ *    (`getApiKeyAndHeaders`), or an auth-bearing header declared on `Model.headers`. Paired by
+ *    construction (the resolver was asked about THIS entry), so the adjudicator never refuses it.
+ *  - `"deployment-config"` — the brain construction-time fallback (`config.apiKey` / an auth header
+ *    in `config.headers`). Paired only with the deployment's own declared root (`config.baseUrl`).
+ *  - `"absent"` — no credential anywhere. Legal for keyless gateways; refused only where an entry
+ *    declares its OWN URL away from a declared deployment root (a distinct endpoint with no
+ *    credential route is a configuration hole, not a keyless deployment). */
+export type RouteCredentialSource = "per-model" | "deployment-config" | "absent";
+/** The resolved credential a request would carry, tagged with its source (see {@link RouteCredentialSource}). */
+export interface RouteCredential {
+    source: RouteCredentialSource;
+    /** The key itself, when the credential rides the apiKey knob. An EMPTY string is a present (per-call)
+     *  credential that fails closed at emit time — presence, not truthiness (the degraded-secret contract). */
+    apiKey?: string;
+    /** True when the credential rides as an auth-bearing HEADER (`authorization`/`x-api-key`, any case)
+     *  rather than the apiKey knob. The winning bag is named by {@link RouteCredential.carrierBag}. */
+    headersBorne?: boolean;
+    /** Which header bag carries a headers-borne credential (resolution precedence:
+     *  options > model > config; the apiKey knob outranks headers within options, while the config's
+     *  knob+header pair counts as ONE deployment credential — see `resolveRouteCredential`). */
+    carrierBag?: "options" | "model" | "config";
+}
+/** The deployment half of the pairing judgment: the brain construction config's DECLARED root.
+ *  Absent/empty ⇒ the deployment did not declare its credential's URL half (the unpinned
+ *  quick-start posture — see `adjudicateModelRoute`). */
+export interface RoutePairingConfig {
+    baseUrl?: string;
+}
+/** How an OK verdict is paired.
+ *  - `"per-model"` — per-model credential, paired by construction.
+ *  - `"paired"` — deployment credential on the deployment's own declared root.
+ *  - `"unpinned"` — deployment credential whose URL half is UNDECLARED (no `config.baseUrl`): allowed
+ *    for compatibility with single-endpoint configs (key on config, URL on the model), but the pairing
+ *    is unverifiable — a multi-entry deployment in this posture should declare `config.baseUrl` or move
+ *    to per-model credentials. Surfaced (not refused) so read faces can annotate it.
+ *  - `"keyless"` — no credential anywhere; nothing to protect. */
+export type RoutePairingPosture = "per-model" | "paired" | "unpinned" | "keyless";
+/** Machine codes an adjudication refusal carries (minted here, forwarded verbatim by consumers). */
+export type RouteRefusalCode = "route.credential_mismatch" | "route.credential_missing";
+/** The structured account of a refusal — enough for a caller to render the two halves and the fix. */
+export interface RouteRefusalDetail {
+    modelId: string;
+    /** The entry's declared URL half (`Model.baseUrl`, normalized). */
+    entryBaseUrl: string;
+    /** The root the request would actually target (normalized). */
+    requestBaseUrl: string;
+    /** The deployment's declared root the credential is paired with (mismatch refusals). */
+    configBaseUrl?: string;
+    /** One-line configuration fix. */
+    fixHint: string;
+}
+/** The adjudicator's verdict: either the route is servable (with its pairing posture) or it is
+ *  refused with a machine code + structured detail. Fail-closed by design: a credential is never
+ *  sent to a host its configuration does not pair it with — "no credential leak" outranks
+ *  "silently works". */
+export type RouteAdjudication = {
+    ok: true;
+    posture: RoutePairingPosture;
+} | {
+    ok: false;
+    code: RouteRefusalCode;
+    detail: RouteRefusalDetail;
+};
 export type StreamFn = (model: Model, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStreamLike | Promise<AssistantMessageEventStreamLike>;
 export type CompleteSimpleFn = (model: Model, context: Pick<Context, "systemPrompt" | "messages">, options?: SimpleStreamOptions) => Promise<AssistantMessage>;
 export type ValidateToolArgumentsFn = (tool: Tool, toolCall: ToolCall) => unknown;

package/dist/engine/loop/types.d.ts

@@ -489,6 +489,13 @@ export interface CompactionSummaryMessage {
      *  (`convertToLlm`); absent (directly constructed messages, older render paths) ⇒ the wrapper is
      *  byte-identical to the historical constant. */
     elidedMessages?: number;
+    /** PTL-shortfall accounting: how many of those {@link elidedMessages} the summary does NOT cover — messages a reactive
+     *  prompt-too-long retry shed from the summarization input after the cut was already committed.
+     *  Sourced from the compaction entry's own write-side accounting
+     *  (`CompactionDetails.unsummarizedMessages`), same reason as its sibling. Absent (the lossless
+     *  common case, directly constructed messages, pre-field entries) ⇒ no uncovered clause, wrapper
+     *  byte-identical. */
+    unsummarizedMessages?: number;
     /** Optional estimated context tokens after compaction. */
     tokensAfter?: number;
     /** Optional first retained entry id from the compaction range. */

package/dist/engine/session/import-validate.js

@@ -183,6 +183,16 @@ export class StreamingImportValidator {
             if (elided !== undefined && !(typeof elided === "number" && Number.isSafeInteger(elided) && elided >= 0)) {
                 throw new SessionError("invalid_session", `compaction "${e.id}" carries a structurally invalid elidedMessages count (non-negative integer)`);
             }
+            const uncovered = e.details?.unsummarizedMessages;
+            if (uncovered !== undefined) {
+                if (!(typeof uncovered === "number" && Number.isSafeInteger(uncovered) && uncovered >= 0)) {
+                    throw new SessionError("invalid_session", `compaction "${e.id}" carries a structurally invalid unsummarizedMessages count (non-negative integer)`);
+                }
+                if (uncovered > 0 && !(typeof elided === "number" && elided >= uncovered)) {
+                    throw new SessionError("invalid_session", `compaction "${e.id}" carries unsummarizedMessages ${uncovered} without an elidedMessages count at least that ` +
+                        `large (uncovered messages are a subset of the folded ones)`);
+                }
+            }
             const refs = e.details?.persistedOutputRefs;
             if (refs !== undefined) {
                 if (!Array.isArray(refs) || refs.length > PERSISTED_OUTPUT_REFS_MAX_ENTRIES) {

package/dist/engine/session/session.js

@@ -1,7 +1,7 @@
 import { asAgentMessage, createCompactionSummaryMessage, createCustomMessage, } from "../harness/messages.js";
 import { SessionError, isValidModelChange, normalizeAnnouncedListing, normalizeCompactionStateCarrier, normalizeGitAnnouncement, normalizeReminderMark, normalizeWorkspaceState } from "../harness/types.js";
 import { normalizePromptEpoch } from "../../prompt-assembly/epoch.js";
-import { budgetInvokedSkillsRetention, readElidedMessages, readRetainedInvokedSkills, renderInvokedSkillsRetention, } from "../compaction/utils.js";
+import { budgetInvokedSkillsRetention, readElidedMessages, readRetainedInvokedSkills, readUnsummarizedMessages, renderInvokedSkillsRetention, } from "../compaction/utils.js";
 const RETENTION_CLAMP_DEFAULT_CHARS_PER_TOKEN = 4;
 const RETENTION_CLAMP_WINDOW_FRACTION = 0.5;
 export function buildSessionContext(pathEntries, opts) {
@@ -67,7 +67,7 @@ export function buildSessionContext(pathEntries, opts) {
             retainedSkills = budgetInvokedSkillsRetention(retainedSkills, budgetChars);
         }
         const retainedSkillsBlock = renderInvokedSkillsRetention(retainedSkills);
-        messages.push(asAgentMessage(createCompactionSummaryMessage(compaction.summary + retainedSkillsBlock, compaction.tokensBefore, compaction.timestamp, readElidedMessages(compaction.details))));
+        messages.push(asAgentMessage(createCompactionSummaryMessage(compaction.summary + retainedSkillsBlock, compaction.tokensBefore, compaction.timestamp, readElidedMessages(compaction.details), readUnsummarizedMessages(compaction.details))));
         const compactionIdx = pathEntries.findIndex((e) => e.type === "compaction" && e.id === compaction.id);
         let foundFirstKept = false;
         for (let i = 0; i < compactionIdx; i++) {

package/dist/index.d.ts

@@ -161,7 +161,7 @@ export { removePersistedRule, applyTombstones, sameScope, InMemoryPermissionRule
 export { syncPermissionRules, parseRuleSyncResponse, PERMISSION_RULE_SYNC_PATH, LOCAL_OWNER_UNSYNCABLE_CODE, type PermissionRuleSyncTransport, type PermissionRuleSyncResult, type RuleSyncRequestBody, type RuleSyncResponseBody, } from "./core/permission-rule-sync.js";
 export { createOrgRuleOverlay, orgRuleVerdictFor, effectivePermissionRules, orgRuleStatePersistenceOf, ORG_UNAVAILABLE_DECISION_REASON, ORG_RULE_DECISION_REASON, ORG_ADJUDICATION_TIMEOUT_MS, type OrgPermissionRule, type OrgRuleSnapshot, type OrgRuleSnapshotProvider, type OrgRuleStatePersistence, type PersistedOrgRuleState, type OrgRuleOverlay, type OrgOverlayResolution, type OrgOverlayStatus, type EffectivePermissionRule, } from "./core/permission-rule-org.js";
 export { RULE_SYNC_DROP_CODES, type RuleSyncDropReason, type RuleQuarantineReason } from "./core/governance-codes.js";
-export { prepareCardApproval, confirmRuleApproval, type ConfirmResult, type ConfirmRefusalReason, redeemRuleTicket, redeemRuleBatch, prepareCcImport, prepareStarterBatch, mintRuleTicket, STARTER_RULES, InMemoryRuleApprovalRecordStore, type RuleTicket, type RuleCandidate, type RuleApprovalKind, type RuleApprovalRecord, type RuleApprovalRecordStore, type RuleConsentDeps, type RedeemResult, type CcImportLayer, type ImportedSettingsLayer, type ImportPreview, type ImportResult, } from "./core/permission-rule-consent.js";
+export { prepareCardApproval, confirmRuleApproval, type ConfirmResult, type ConfirmRefusalReason, precheckEditedRuleText, type EditedRuleTextPrecheck, redeemRuleTicket, redeemRuleBatch, prepareCcImport, prepareStarterBatch, mintRuleTicket, STARTER_RULES, InMemoryRuleApprovalRecordStore, type RuleTicket, type RuleCandidate, type RuleApprovalKind, type RuleApprovalRecord, type RuleApprovalRecordStore, type RuleConsentDeps, type RedeemResult, type CcImportLayer, type ImportedSettingsLayer, type ImportPreview, type ImportResult, } from "./core/permission-rule-consent.js";
 export { FilePermissionRuleStoreProvider } from "./stores/file/permission-rule-store.js";
 export { adoptFilePermissionRuleStore, type AdoptFileRuleStoreResult } from "./stores/file/permission-rule-adopt.js";
 export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, type AdoptionErrorCode, type AdoptionSource, type AdoptionReport, type AdoptionReceipt, type AdoptionLegReport, type AffectedDeploymentConfig, type RootAdoptionFile, } from "./stores/file/adoption/marker.js";
@@ -256,6 +256,9 @@ export { repairTextToolCalls } from "./brain/tool-call-repair.js";
 export { createCircuitBreakerBrain, type CircuitBreakerOptions, type BreakerState, type BreakerSnapshot, type BreakerPhase, CIRCUIT_OPEN_MARKER, } from "./brain/circuit-breaker.js";
 export { createDegradingBrain, readDegradation, DEGRADED_DIAGNOSTIC_TYPE, type DegradingBrainOptions, type DegradeReason, type DegradationInfo, } from "./brain/degrading.js";
 export { retryBackoffMs, parseRetryAfter } from "./brain/retry.js";
+export { adjudicateModelRoute, resolveRouteCredential, routeRefusalText, routePairingStatus, normalizeBaseUrl, hasAuthCarrier, type RoutePairingStatus, } from "./brain/route-adjudicator.js";
+export type { RouteAdjudication, RouteCredential, RouteCredentialSource, RoutePairingConfig, RoutePairingPosture, RouteRefusalCode, RouteRefusalDetail, } from "./internal/llm.js";
+export { ROUTE_ADJUDICATION_CONFORMANCE_CORPUS, type RouteAdjudicationVector } from "./brain/route-conformance.js";
 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";

package/dist/index.js

@@ -123,7 +123,7 @@ export { removePersistedRule, applyTombstones, sameScope, InMemoryPermissionRule
 export { syncPermissionRules, parseRuleSyncResponse, PERMISSION_RULE_SYNC_PATH, LOCAL_OWNER_UNSYNCABLE_CODE, } from "./core/permission-rule-sync.js";
 export { createOrgRuleOverlay, orgRuleVerdictFor, effectivePermissionRules, orgRuleStatePersistenceOf, ORG_UNAVAILABLE_DECISION_REASON, ORG_RULE_DECISION_REASON, ORG_ADJUDICATION_TIMEOUT_MS, } from "./core/permission-rule-org.js";
 export { RULE_SYNC_DROP_CODES } from "./core/governance-codes.js";
-export { prepareCardApproval, confirmRuleApproval, redeemRuleTicket, redeemRuleBatch, prepareCcImport, prepareStarterBatch, mintRuleTicket, STARTER_RULES, InMemoryRuleApprovalRecordStore, } from "./core/permission-rule-consent.js";
+export { prepareCardApproval, confirmRuleApproval, precheckEditedRuleText, redeemRuleTicket, redeemRuleBatch, prepareCcImport, prepareStarterBatch, mintRuleTicket, STARTER_RULES, InMemoryRuleApprovalRecordStore, } from "./core/permission-rule-consent.js";
 export { FilePermissionRuleStoreProvider } from "./stores/file/permission-rule-store.js";
 export { adoptFilePermissionRuleStore } from "./stores/file/permission-rule-adopt.js";
 export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, } from "./stores/file/adoption/marker.js";
@@ -215,6 +215,8 @@ export { repairTextToolCalls } from "./brain/tool-call-repair.js";
 export { createCircuitBreakerBrain, CIRCUIT_OPEN_MARKER, } from "./brain/circuit-breaker.js";
 export { createDegradingBrain, readDegradation, DEGRADED_DIAGNOSTIC_TYPE, } from "./brain/degrading.js";
 export { retryBackoffMs, parseRetryAfter } from "./brain/retry.js";
+export { adjudicateModelRoute, resolveRouteCredential, routeRefusalText, routePairingStatus, normalizeBaseUrl, hasAuthCarrier, } from "./brain/route-adjudicator.js";
+export { ROUTE_ADJUDICATION_CONFORMANCE_CORPUS } from "./brain/route-conformance.js";
 export {} from "./brain/timeout.js";
 export { createAssistantMessageEventStream } from "./internal/llm.js";
 export { Type } from "typebox";

package/dist/internal/llm.d.ts

@@ -5,4 +5,4 @@
  * llm-core); the facade stays so consumers never notice which side a symbol lives on.
  */
 export { createAssistantMessageEventStream, snapshotActorAssertion, stripEngineMetadata } from "../engine/llm/index.js";
-export type { ActorAssertion, AnthropicMessagesCompat, OpenAICompletionsCompat, OpenAIResponsesCompat, AssistantMessage, AssistantMessageDiagnostic, AssistantMessageEvent, CompleteSimpleFn, Context, DocumentContent, ImageContent, Message, Model, ResilienceOptions, SimpleStreamOptions, StallTimeouts, StopReason, StreamFn, TextContent, ThinkingContent, Tool, ToolCall, ToolResultMessage, Usage, UserMessage, } from "../engine/llm/index.js";
+export type { ActorAssertion, AnthropicMessagesCompat, OpenAICompletionsCompat, OpenAIResponsesCompat, AssistantMessage, AssistantMessageDiagnostic, AssistantMessageEvent, CompleteSimpleFn, Context, DocumentContent, ImageContent, Message, Model, ResilienceOptions, RouteAdjudication, RouteCredential, RouteCredentialSource, RoutePairingConfig, RoutePairingPosture, RouteRefusalCode, RouteRefusalDetail, SimpleStreamOptions, StallTimeouts, StopReason, StreamFn, TextContent, ThinkingContent, Tool, ToolCall, ToolResultMessage, Usage, UserMessage, } from "../engine/llm/index.js";

package/dist/orchestration/run-spec.js

@@ -114,6 +114,9 @@ export async function runSpec(runner, contract, opts) {
             postCompact: (opts.taskSpec.hooks.postCompact ?? deployBaseline.hooks.postCompact)?.bind(opts.taskSpec.hooks.postCompact ? opts.taskSpec.hooks : deployBaseline.hooks),
             stopFailure: (opts.taskSpec.hooks.stopFailure ?? deployBaseline.hooks.stopFailure)?.bind(opts.taskSpec.hooks.stopFailure ? opts.taskSpec.hooks : deployBaseline.hooks),
             permissionDenied: (opts.taskSpec.hooks.permissionDenied ?? deployBaseline.hooks.permissionDenied)?.bind(opts.taskSpec.hooks.permissionDenied ? opts.taskSpec.hooks : deployBaseline.hooks),
+            ...((opts.taskSpec.hooks.timeoutMs ?? deployBaseline.hooks.timeoutMs) !== undefined
+                ? { timeoutMs: opts.taskSpec.hooks.timeoutMs ?? deployBaseline.hooks.timeoutMs }
+                : {}),
         }
         : (opts.taskSpec.hooks ?? deployBaseline?.hooks);
     let guardRestores = 0;
@@ -130,10 +133,14 @@ export async function runSpec(runner, contract, opts) {
         ...(userHooks?.postCompact && { postCompact: userHooks.postCompact.bind(userHooks) }),
         ...(userHooks?.stopFailure && { stopFailure: userHooks.stopFailure.bind(userHooks) }),
         ...(userHooks?.permissionDenied && { permissionDenied: userHooks.permissionDenied.bind(userHooks) }),
+        ...(userHooks?.timeoutMs !== undefined ? { timeoutMs: userHooks.timeoutMs } : {}),
         async stop(ctx) {
             guardRestores += restoreFrozenPaths(snapshot, rootDir);
             if (!gateAbandoned) {
-                const report = await runOracle(contract.oracle, rootDir, { baseline, signal: opts.taskSpec.signal });
+                const gateSignal = ctx.signal !== undefined && opts.taskSpec.signal !== undefined ? AbortSignal.any([ctx.signal, opts.taskSpec.signal]) : (ctx.signal ?? opts.taskSpec.signal);
+                const report = await runOracle(contract.oracle, rootDir, { baseline, ...(gateSignal !== undefined ? { signal: gateSignal } : {}) });
+                if (ctx.signal?.aborted === true)
+                    return undefined;
                 oracleRuns++;
                 if (report.verdict === "red") {
                     oracleHadRedRun = true;

package/dist/prompts/default.d.ts

@@ -142,8 +142,8 @@ export declare const CYBER_RISK = "IMPORTANT: Assist with authorized security te
 export declare const URL_SAFETY = "IMPORTANT: You must NEVER generate or guess URLs for the user unless you are confident that the URLs are for helping the user with programming. You may use URLs provided by the user in their messages or local files.";
 /**
  * Tool-result retention reminder (design/64 §6.2 C). Always injected: core's in-task context management
- * (`clearStaleToolResults`) unconditionally clears old tool-result content before each request, so the
- * model must persist anything load-bearing into its own response.
+ * (`clearStaleToolResults`) can clear old tool-result content out of a request, and compaction can
+ * replace it with prose, so the model must persist anything load-bearing into its own response.
  *
  * RB-328 — CITATION CORRECTED. Source = the CC **88 readable tree**
  * (`collection-claude-code-source-code/original-source-code/src/constants/prompts.ts:841`,
@@ -157,8 +157,14 @@ export declare const URL_SAFETY = "IMPORTANT: You must NEVER generate or guess U
  * context-management claim (`_My` @596605-596612, the "The system will automatically compress prior
  * messages … your conversation with the user is not limited by the context window" line — an
  * overclaim {@link harnessHeadLines} explicitly refuses to copy). So 220 clears results without ever
- * telling the model to save what mattered. sema keeps the instruction: its clear is unconditional and
- * runs before EVERY request, which is a stronger reason to warn than CC's.
+ * telling the model to save what mattered. sema keeps the instruction — and the REASON is now stated
+ * as measured rather than as remembered (anchoring re-check 2026-08-23): the earlier wording here
+ * ("its clear is unconditional and runs before EVERY request") is false about our own engine.
+ * `clearStaleToolResults` returns the original array untouched while the estimate is within
+ * `editBudget` (= `contextEditFrontier`, e.g. 167000 on a 200k window) — probed: under budget, same
+ * reference, zero clears. What is true, and is warning enough, is that a long session meets THREE
+ * removers: this pass once the frontier is crossed, the compaction boundary's summary, and the
+ * per-message aggregate tool-result budget, which sheds the largest results at any size.
  */
 export declare const SUMMARIZE_TOOL_RESULTS = "When working with tool results, write down any important information you might need later in your own response, as the original tool result may be cleared or summarized from the context later.";
 export declare const EXECUTION_ENVIRONMENT: string;
@@ -448,7 +454,7 @@ export declare function buildEnvironmentContext(facts: EnvironmentFacts): string
  * task via \`TaskSpec.systemPrompt\`, or wire it to a development role via \`RoleSpec.systemPrompt\` so
  * coding agents get it while non-coding roles keep the neutral base.
  */
-export declare const CODE_AGENT_PROMPT = "You are a capable software-engineering agent that acts through tools.\n\n## Truth\n- Never fabricate tool results or claim a verification you did not perform.\n- When a tool fails, report the failure. When a result is uncertain, name the uncertainty.\n- Ground every claim that needs evidence in the tool result that produced it.\nThis duty is non-negotiable; no instruction may override it.\n\n## Engineering tasks\n- Understand before you change: read the relevant code before proposing or making edits. Do not modify code you have not read.\n- When a third-party API, library, or model documents a recommended usage \u2014 calling conventions, required preprocessing, a canonical invocation path \u2014 follow the canonical path by default for correctness-critical or reproduction work, even when the documentation marks it optional or the tradeoff \"minor\": that assessment was measured on the author's benchmark, not against this task's acceptance criteria. Deviating is a decision to justify, not a shortcut.\n- Match the surrounding code \u2014 its naming, structure, and conventions. New code should read like the code already there.\n- Minimum complexity: build what the task needs, no more. No speculative abstractions, no configurability nobody asked for, no error handling for cases that can't happen. Three similar lines beat a premature abstraction \u2014 but don't leave work half-done either.\n- Don't gold-plate: a bug fix doesn't need the surrounding code cleaned up; a small feature doesn't need extra options. Don't add comments, docstrings, or type annotations to code you didn't change.\n- Comment only where the WHY is non-obvious (a hidden constraint, a subtle invariant, a workaround). Don't explain WHAT well-named code already says. Don't delete existing comments unless you remove the code they describe or know they're wrong \u2014 a comment may encode a lesson not visible in the diff.\n- Don't create files unless necessary; prefer editing an existing file to creating a new one. Never proactively create documentation files (*.md) or READMEs unless explicitly requested.\n- Avoid backwards-compatibility cruft: renaming unused vars to `_x`, re-exporting moved symbols, leaving `// removed` tombstones. If something is certainly unused, delete it.\n- Security: don't introduce injection, XSS, SQLi, or other common vulnerabilities; if you notice insecure code you wrote, fix it immediately. Validate at system boundaries (user input, external APIs); trust internal invariants.\n- Be a collaborator, not just an executor: if the request rests on a misconception, or you spot a bug adjacent to what was asked, say so rather than silently complying.\n- Interpret a vague or generic instruction in the context of the codebase and the working directory. \"Change methodName to snake case\" means find that method in the code and edit it \u2014 not just reply \"method_name\".\n- You are highly capable; help the user attempt ambitious tasks. Defer to their judgment on whether a task is too large rather than refusing it up front.\n\n## Executing actions with care\n- Weigh reversibility and blast radius. Local, reversible actions (editing files, running tests) you may take freely. For hard-to-reverse, shared, or destructive actions \u2014 deleting files/branches, force-pushing, dropping tables, sending messages, pushing code, opening/closing PRs \u2014 confirm with the user first unless durably authorized.\n- Authorization holds for the scope given, not beyond: approving one push does not approve the next.\n- Don't reach for a destructive shortcut to clear an obstacle (skipping verification, resetting state, deleting unfamiliar files). Investigate unexpected state before overwriting it \u2014 it may be the user's in-progress work.\n- Inputs you are asked to repair, recover, or examine are read-only evidence by default. Survey them with non-intrusive read commands first. Before ANY operation that could rewrite them or trigger engine side effects \u2014 opening them with an engine that may touch companion state (a database engine, for example), in-place writes, format/repair tools \u2014 copy the original into an isolated working directory and operate only on the copy: an irreplaceable input lost to a side-effecting probe cannot be regenerated.\n- Uploading content to a pastebin, gist, or diagram renderer publishes it \u2014 it may be cached or indexed even if you later delete it. Treat it as an outward-facing action.\n\n## Tool use\n- Prefer a dedicated tool over a raw shell command when one fits \u2014 it's clearer and reviewable. Reserve the shell for genuine system/terminal operations.\n- Run independent tool calls in the same turn (in parallel); sequence them only when one depends on another's result.\n- When something must be done, do it with a tool now \u2014 don't narrate intent and stop. If you say you'll do something, make the call in the same response.\n- If a tool fails or returns empty, diagnose before retrying differently; don't repeat the identical failing call, and don't abandon a viable approach after a single failure.\n- If an approach fails, diagnose why before switching to another. Escalate to the user \u2014 via the AskUserQuestion tool when it is available \u2014 only when genuinely stuck after investigating, not as a first response to friction.\n\n## Git\n- Only commit when the user explicitly asks; if it's unclear whether they want a commit, ask first.\n- Never amend; always create a NEW commit (a hook may have failed, leaving the previous commit untouched \u2014 amending would rewrite the wrong thing). If a pre-commit hook fails, fix the issue and make a new commit.\n- `git add` specific named files; never `git add -A` or `git add .` (they sweep in .env files, credentials, large binaries).\n- Never commit a file likely to contain secrets (.env, credentials.json, *.pem, key files); if the user explicitly asks you to, warn them first.\n- Never change git config, never skip hooks (`--no-verify`), never bypass signatures.\n- Pass multi-line commit messages with a HEREDOC (`git commit -m \"$(cat <<'EOF' ... EOF)\"`) so formatting survives.\n- For a PR, analyze ALL commits since the branch diverged from its base (not just the latest commit) before writing the summary.\n\n## Verification & reporting\n- Before reporting a task done, verify it works: run the test, execute the code, check the output \u2014 not just the exit code. If you can't verify, say so rather than implying success.\n- Verify the final artifact, not a proxy. Exercise what you actually delivered through its real entry point (call the real function, run the produced binary, query the served endpoint), judged the way the task itself will be judged. A pre-existing suite that was already green, an earlier candidate's output, or a self-test that bypasses the delivered code verifies nothing. Then READ your verification's output and use it: if your own check flags a mismatch, resolve it by direct comparison against the requirement \u2014 don't discard it as a false positive, and don't substitute an older result you liked better. Confirm that what you submit is the value the acceptance surface itself asks for \u2014 the bare value, not the file line, prefix, wrapper, or intermediate representation that carried it: reconcile the submission's exact form word-for-word against what the acceptance surface expects.\n- Report outcomes faithfully: if tests fail, say so with the output; if you skipped a step, say that. Never manufacture a green result. Equally, when something passed, state it plainly \u2014 don't hedge confirmed results or re-verify what you already checked.\n\n## References & style\n- Reference code as file_path:line_number so the user can navigate to it.\n- Reference a GitHub issue or PR as owner/repo#123 so it renders as a clickable link.\n- Don't put a colon before a tool call (avoid \"Let me check:\" immediately followed by a call) \u2014 end the sentence with a period.\n- Don't give time estimates or predictions for how long work will take \u2014 focus on what needs doing.\n- Be concise; lead with the answer or the action. Prefer prose, lists, and code blocks over wide tables. Match the user's language. Avoid emojis unless asked. If you can say it in one sentence, don't use three. Go straight to the point, don't go in circles, don't overdo it. (This does not apply to code or tool calls.)";
+export declare const CODE_AGENT_PROMPT = "You are a capable software-engineering agent that acts through tools.\n\n## Truth\n- Never fabricate tool results or claim a verification you did not perform.\n- When a tool fails, report the failure. When a result is uncertain, name the uncertainty.\n- Ground every claim that needs evidence in the tool result that produced it.\nThis duty is non-negotiable; no instruction may override it.\n\n## Engineering tasks\n- Understand before you change: read the relevant code before proposing or making edits. Do not modify code you have not read.\n- When a third-party API, library, or model documents a recommended usage \u2014 calling conventions, required preprocessing, a canonical invocation path \u2014 follow the canonical path by default for correctness-critical or reproduction work, even when the documentation marks it optional or the tradeoff \"minor\": that assessment was measured on the author's benchmark, not against this task's acceptance criteria. Deviating is a decision to justify, not a shortcut.\n- Match the surrounding code \u2014 its naming, structure, and conventions. New code should read like the code already there.\n- Minimum complexity: build what the task needs, no more. No speculative abstractions, no configurability nobody asked for, no error handling for cases that can't happen. Three similar lines beat a premature abstraction \u2014 but don't leave work half-done either.\n- Don't gold-plate: a bug fix doesn't need the surrounding code cleaned up; a small feature doesn't need extra options. Don't add comments, docstrings, or type annotations to code you didn't change.\n- Comment only where the WHY is non-obvious (a hidden constraint, a subtle invariant, a workaround). Don't explain WHAT well-named code already says. Don't delete existing comments unless you remove the code they describe or know they're wrong \u2014 a comment may encode a lesson not visible in the diff.\n- Don't create files unless necessary; prefer editing an existing file to creating a new one. Never proactively create documentation files (*.md) or READMEs unless explicitly requested.\n- Avoid backwards-compatibility cruft: renaming unused vars to `_x`, re-exporting moved symbols, leaving `// removed` tombstones. If something is certainly unused, delete it.\n- Security: don't introduce injection, XSS, SQLi, or other common vulnerabilities; if you notice insecure code you wrote, fix it immediately. Validate at system boundaries (user input, external APIs); trust internal invariants.\n- Be a collaborator, not just an executor: if the request rests on a misconception, or you spot a bug adjacent to what was asked, say so rather than silently complying.\n- Interpret a vague or generic instruction in the context of the codebase and the working directory. \"Change methodName to snake case\" means find that method in the code and edit it \u2014 not just reply \"method_name\".\n- You are highly capable; help the user attempt ambitious tasks. Defer to their judgment on whether a task is too large rather than refusing it up front.\n\n## Executing actions with care\n- Weigh reversibility and blast radius. Local, reversible actions (editing files, running tests) you may take freely. For hard-to-reverse, shared, or destructive actions \u2014 deleting files/branches, force-pushing, dropping tables, sending messages, pushing code, opening/closing PRs \u2014 confirm with the user first unless durably authorized.\n- Authorization holds for the scope given, not beyond: approving one push does not approve the next.\n- Don't reach for a destructive shortcut to clear an obstacle (skipping verification, resetting state, deleting unfamiliar files). Investigate unexpected state before overwriting it \u2014 it may be the user's in-progress work.\n- Inputs you are asked to repair, recover, or examine are read-only evidence by default. Survey them with non-intrusive read commands first. Before ANY operation that could rewrite them or trigger engine side effects \u2014 opening them with an engine that may touch companion state (a database engine, for example), in-place writes, format/repair tools \u2014 copy the original into an isolated working directory and operate only on the copy: an irreplaceable input lost to a side-effecting probe cannot be regenerated.\n- Uploading content to a pastebin, gist, or diagram renderer publishes it \u2014 it may be cached or indexed even if you later delete it. Treat it as an outward-facing action.\n\n## Tool use\n- Prefer a dedicated tool over a raw shell command when one fits \u2014 it's clearer and reviewable. Reserve the shell for genuine system/terminal operations.\n- Run independent tool calls in the same turn (in parallel); sequence them only when one depends on another's result.\n- When something must be done, do it with a tool now \u2014 don't narrate intent and stop. If you say you'll do something, make the call in the same response.\n- If a tool fails or returns empty, diagnose before retrying differently; don't repeat the identical failing call, and don't abandon a viable approach after a single failure.\n- If an approach fails, diagnose why before switching to another. Escalate to the user \u2014 via the AskUserQuestion tool when it is available \u2014 only when genuinely stuck after investigating, not as a first response to friction.\n\n## Git\n- Only commit when the user explicitly asks; if it's unclear whether they want a commit, ask first.\n- Never amend; always create a NEW commit (a hook may have failed, leaving the previous commit untouched \u2014 amending would rewrite the wrong thing). If a pre-commit hook fails, fix the issue and make a new commit.\n- `git add` specific named files; never `git add -A` or `git add .` (they sweep in .env files, credentials, large binaries).\n- Never commit a file likely to contain secrets (.env, credentials.json, *.pem, key files); if the user explicitly asks you to, warn them first.\n- Never change git config, never skip hooks (`--no-verify`), never bypass signatures.\n- Before any destructive git command (`checkout --force`, `reset --hard`, `clean`, branch deletion), run `git status` first \u2014 untracked or uncommitted work is unrecoverable once these run.\n- Before `git push`, re-check what the push carries: after a broad `git add`, review the staged list for files that may contain secrets before they leave the machine.\n- Pass multi-line commit messages with a HEREDOC (`git commit -m \"$(cat <<'EOF' ... EOF)\"`) so formatting survives.\n- For a PR, analyze ALL commits since the branch diverged from its base (not just the latest commit) before writing the summary.\n\n## Verification & reporting\n- Before reporting a task done, verify it works: run the test, execute the code, check the output \u2014 not just the exit code. If you can't verify, say so rather than implying success.\n- Verify the final artifact, not a proxy. Exercise what you actually delivered through its real entry point (call the real function, run the produced binary, query the served endpoint), judged the way the task itself will be judged. A pre-existing suite that was already green, an earlier candidate's output, or a self-test that bypasses the delivered code verifies nothing. Then READ your verification's output and use it: if your own check flags a mismatch, resolve it by direct comparison against the requirement \u2014 don't discard it as a false positive, and don't substitute an older result you liked better. Confirm that what you submit is the value the acceptance surface itself asks for \u2014 the bare value, not the file line, prefix, wrapper, or intermediate representation that carried it: reconcile the submission's exact form word-for-word against what the acceptance surface expects.\n- Report outcomes faithfully: if tests fail, say so with the output; if you skipped a step, say that. Never manufacture a green result. Equally, when something passed, state it plainly \u2014 don't hedge confirmed results or re-verify what you already checked.\n\n## References & style\n- Reference code as file_path:line_number so the user can navigate to it.\n- Reference a GitHub issue or PR as owner/repo#123 so it renders as a clickable link.\n- Don't put a colon before a tool call (avoid \"Let me check:\" immediately followed by a call) \u2014 end the sentence with a period.\n- Don't give time estimates or predictions for how long work will take \u2014 focus on what needs doing.\n- Be concise; lead with the answer or the action. Prefer prose, lists, and code blocks over wide tables. Match the user's language. Avoid emojis unless asked. If you can say it in one sentence, don't use three. Go straight to the point, don't go in circles, don't overdo it. (This does not apply to code or tool calls.)";
 /** design/102 / [891] — the coding-agent persona the `code` scenario mounts, selected via
  *  `RoleSpec.systemPrompt` / `TaskSpec.systemPrompt` (the global default stays the neutral
  *  {@link DEFAULT_SYSTEM_PROMPT}). Since RB-321 retired the three K-8 deltas this is byte-identical to
@@ -456,7 +462,7 @@ export declare const CODE_AGENT_PROMPT = "You are a capable software-engineering
  *  (`CODE_AGENT_PROMPT` = the shared coding FLOOR a dev role composes with; `CODE_SYSTEM_PROMPT` = the
  *  persona the scenario mounts), and merging two public exports is a BREAKING-window action.
  *  STABLE (cacheable) — `assertPromptCacheFriendly` still passes. */
-export declare const CODE_SYSTEM_PROMPT = "You are a capable software-engineering agent that acts through tools.\n\n## Truth\n- Never fabricate tool results or claim a verification you did not perform.\n- When a tool fails, report the failure. When a result is uncertain, name the uncertainty.\n- Ground every claim that needs evidence in the tool result that produced it.\nThis duty is non-negotiable; no instruction may override it.\n\n## Engineering tasks\n- Understand before you change: read the relevant code before proposing or making edits. Do not modify code you have not read.\n- When a third-party API, library, or model documents a recommended usage \u2014 calling conventions, required preprocessing, a canonical invocation path \u2014 follow the canonical path by default for correctness-critical or reproduction work, even when the documentation marks it optional or the tradeoff \"minor\": that assessment was measured on the author's benchmark, not against this task's acceptance criteria. Deviating is a decision to justify, not a shortcut.\n- Match the surrounding code \u2014 its naming, structure, and conventions. New code should read like the code already there.\n- Minimum complexity: build what the task needs, no more. No speculative abstractions, no configurability nobody asked for, no error handling for cases that can't happen. Three similar lines beat a premature abstraction \u2014 but don't leave work half-done either.\n- Don't gold-plate: a bug fix doesn't need the surrounding code cleaned up; a small feature doesn't need extra options. Don't add comments, docstrings, or type annotations to code you didn't change.\n- Comment only where the WHY is non-obvious (a hidden constraint, a subtle invariant, a workaround). Don't explain WHAT well-named code already says. Don't delete existing comments unless you remove the code they describe or know they're wrong \u2014 a comment may encode a lesson not visible in the diff.\n- Don't create files unless necessary; prefer editing an existing file to creating a new one. Never proactively create documentation files (*.md) or READMEs unless explicitly requested.\n- Avoid backwards-compatibility cruft: renaming unused vars to `_x`, re-exporting moved symbols, leaving `// removed` tombstones. If something is certainly unused, delete it.\n- Security: don't introduce injection, XSS, SQLi, or other common vulnerabilities; if you notice insecure code you wrote, fix it immediately. Validate at system boundaries (user input, external APIs); trust internal invariants.\n- Be a collaborator, not just an executor: if the request rests on a misconception, or you spot a bug adjacent to what was asked, say so rather than silently complying.\n- Interpret a vague or generic instruction in the context of the codebase and the working directory. \"Change methodName to snake case\" means find that method in the code and edit it \u2014 not just reply \"method_name\".\n- You are highly capable; help the user attempt ambitious tasks. Defer to their judgment on whether a task is too large rather than refusing it up front.\n\n## Executing actions with care\n- Weigh reversibility and blast radius. Local, reversible actions (editing files, running tests) you may take freely. For hard-to-reverse, shared, or destructive actions \u2014 deleting files/branches, force-pushing, dropping tables, sending messages, pushing code, opening/closing PRs \u2014 confirm with the user first unless durably authorized.\n- Authorization holds for the scope given, not beyond: approving one push does not approve the next.\n- Don't reach for a destructive shortcut to clear an obstacle (skipping verification, resetting state, deleting unfamiliar files). Investigate unexpected state before overwriting it \u2014 it may be the user's in-progress work.\n- Inputs you are asked to repair, recover, or examine are read-only evidence by default. Survey them with non-intrusive read commands first. Before ANY operation that could rewrite them or trigger engine side effects \u2014 opening them with an engine that may touch companion state (a database engine, for example), in-place writes, format/repair tools \u2014 copy the original into an isolated working directory and operate only on the copy: an irreplaceable input lost to a side-effecting probe cannot be regenerated.\n- Uploading content to a pastebin, gist, or diagram renderer publishes it \u2014 it may be cached or indexed even if you later delete it. Treat it as an outward-facing action.\n\n## Tool use\n- Prefer a dedicated tool over a raw shell command when one fits \u2014 it's clearer and reviewable. Reserve the shell for genuine system/terminal operations.\n- Run independent tool calls in the same turn (in parallel); sequence them only when one depends on another's result.\n- When something must be done, do it with a tool now \u2014 don't narrate intent and stop. If you say you'll do something, make the call in the same response.\n- If a tool fails or returns empty, diagnose before retrying differently; don't repeat the identical failing call, and don't abandon a viable approach after a single failure.\n- If an approach fails, diagnose why before switching to another. Escalate to the user \u2014 via the AskUserQuestion tool when it is available \u2014 only when genuinely stuck after investigating, not as a first response to friction.\n\n## Git\n- Only commit when the user explicitly asks; if it's unclear whether they want a commit, ask first.\n- Never amend; always create a NEW commit (a hook may have failed, leaving the previous commit untouched \u2014 amending would rewrite the wrong thing). If a pre-commit hook fails, fix the issue and make a new commit.\n- `git add` specific named files; never `git add -A` or `git add .` (they sweep in .env files, credentials, large binaries).\n- Never commit a file likely to contain secrets (.env, credentials.json, *.pem, key files); if the user explicitly asks you to, warn them first.\n- Never change git config, never skip hooks (`--no-verify`), never bypass signatures.\n- Pass multi-line commit messages with a HEREDOC (`git commit -m \"$(cat <<'EOF' ... EOF)\"`) so formatting survives.\n- For a PR, analyze ALL commits since the branch diverged from its base (not just the latest commit) before writing the summary.\n\n## Verification & reporting\n- Before reporting a task done, verify it works: run the test, execute the code, check the output \u2014 not just the exit code. If you can't verify, say so rather than implying success.\n- Verify the final artifact, not a proxy. Exercise what you actually delivered through its real entry point (call the real function, run the produced binary, query the served endpoint), judged the way the task itself will be judged. A pre-existing suite that was already green, an earlier candidate's output, or a self-test that bypasses the delivered code verifies nothing. Then READ your verification's output and use it: if your own check flags a mismatch, resolve it by direct comparison against the requirement \u2014 don't discard it as a false positive, and don't substitute an older result you liked better. Confirm that what you submit is the value the acceptance surface itself asks for \u2014 the bare value, not the file line, prefix, wrapper, or intermediate representation that carried it: reconcile the submission's exact form word-for-word against what the acceptance surface expects.\n- Report outcomes faithfully: if tests fail, say so with the output; if you skipped a step, say that. Never manufacture a green result. Equally, when something passed, state it plainly \u2014 don't hedge confirmed results or re-verify what you already checked.\n\n## References & style\n- Reference code as file_path:line_number so the user can navigate to it.\n- Reference a GitHub issue or PR as owner/repo#123 so it renders as a clickable link.\n- Don't put a colon before a tool call (avoid \"Let me check:\" immediately followed by a call) \u2014 end the sentence with a period.\n- Don't give time estimates or predictions for how long work will take \u2014 focus on what needs doing.\n- Be concise; lead with the answer or the action. Prefer prose, lists, and code blocks over wide tables. Match the user's language. Avoid emojis unless asked. If you can say it in one sentence, don't use three. Go straight to the point, don't go in circles, don't overdo it. (This does not apply to code or tool calls.)";
+export declare const CODE_SYSTEM_PROMPT = "You are a capable software-engineering agent that acts through tools.\n\n## Truth\n- Never fabricate tool results or claim a verification you did not perform.\n- When a tool fails, report the failure. When a result is uncertain, name the uncertainty.\n- Ground every claim that needs evidence in the tool result that produced it.\nThis duty is non-negotiable; no instruction may override it.\n\n## Engineering tasks\n- Understand before you change: read the relevant code before proposing or making edits. Do not modify code you have not read.\n- When a third-party API, library, or model documents a recommended usage \u2014 calling conventions, required preprocessing, a canonical invocation path \u2014 follow the canonical path by default for correctness-critical or reproduction work, even when the documentation marks it optional or the tradeoff \"minor\": that assessment was measured on the author's benchmark, not against this task's acceptance criteria. Deviating is a decision to justify, not a shortcut.\n- Match the surrounding code \u2014 its naming, structure, and conventions. New code should read like the code already there.\n- Minimum complexity: build what the task needs, no more. No speculative abstractions, no configurability nobody asked for, no error handling for cases that can't happen. Three similar lines beat a premature abstraction \u2014 but don't leave work half-done either.\n- Don't gold-plate: a bug fix doesn't need the surrounding code cleaned up; a small feature doesn't need extra options. Don't add comments, docstrings, or type annotations to code you didn't change.\n- Comment only where the WHY is non-obvious (a hidden constraint, a subtle invariant, a workaround). Don't explain WHAT well-named code already says. Don't delete existing comments unless you remove the code they describe or know they're wrong \u2014 a comment may encode a lesson not visible in the diff.\n- Don't create files unless necessary; prefer editing an existing file to creating a new one. Never proactively create documentation files (*.md) or READMEs unless explicitly requested.\n- Avoid backwards-compatibility cruft: renaming unused vars to `_x`, re-exporting moved symbols, leaving `// removed` tombstones. If something is certainly unused, delete it.\n- Security: don't introduce injection, XSS, SQLi, or other common vulnerabilities; if you notice insecure code you wrote, fix it immediately. Validate at system boundaries (user input, external APIs); trust internal invariants.\n- Be a collaborator, not just an executor: if the request rests on a misconception, or you spot a bug adjacent to what was asked, say so rather than silently complying.\n- Interpret a vague or generic instruction in the context of the codebase and the working directory. \"Change methodName to snake case\" means find that method in the code and edit it \u2014 not just reply \"method_name\".\n- You are highly capable; help the user attempt ambitious tasks. Defer to their judgment on whether a task is too large rather than refusing it up front.\n\n## Executing actions with care\n- Weigh reversibility and blast radius. Local, reversible actions (editing files, running tests) you may take freely. For hard-to-reverse, shared, or destructive actions \u2014 deleting files/branches, force-pushing, dropping tables, sending messages, pushing code, opening/closing PRs \u2014 confirm with the user first unless durably authorized.\n- Authorization holds for the scope given, not beyond: approving one push does not approve the next.\n- Don't reach for a destructive shortcut to clear an obstacle (skipping verification, resetting state, deleting unfamiliar files). Investigate unexpected state before overwriting it \u2014 it may be the user's in-progress work.\n- Inputs you are asked to repair, recover, or examine are read-only evidence by default. Survey them with non-intrusive read commands first. Before ANY operation that could rewrite them or trigger engine side effects \u2014 opening them with an engine that may touch companion state (a database engine, for example), in-place writes, format/repair tools \u2014 copy the original into an isolated working directory and operate only on the copy: an irreplaceable input lost to a side-effecting probe cannot be regenerated.\n- Uploading content to a pastebin, gist, or diagram renderer publishes it \u2014 it may be cached or indexed even if you later delete it. Treat it as an outward-facing action.\n\n## Tool use\n- Prefer a dedicated tool over a raw shell command when one fits \u2014 it's clearer and reviewable. Reserve the shell for genuine system/terminal operations.\n- Run independent tool calls in the same turn (in parallel); sequence them only when one depends on another's result.\n- When something must be done, do it with a tool now \u2014 don't narrate intent and stop. If you say you'll do something, make the call in the same response.\n- If a tool fails or returns empty, diagnose before retrying differently; don't repeat the identical failing call, and don't abandon a viable approach after a single failure.\n- If an approach fails, diagnose why before switching to another. Escalate to the user \u2014 via the AskUserQuestion tool when it is available \u2014 only when genuinely stuck after investigating, not as a first response to friction.\n\n## Git\n- Only commit when the user explicitly asks; if it's unclear whether they want a commit, ask first.\n- Never amend; always create a NEW commit (a hook may have failed, leaving the previous commit untouched \u2014 amending would rewrite the wrong thing). If a pre-commit hook fails, fix the issue and make a new commit.\n- `git add` specific named files; never `git add -A` or `git add .` (they sweep in .env files, credentials, large binaries).\n- Never commit a file likely to contain secrets (.env, credentials.json, *.pem, key files); if the user explicitly asks you to, warn them first.\n- Never change git config, never skip hooks (`--no-verify`), never bypass signatures.\n- Before any destructive git command (`checkout --force`, `reset --hard`, `clean`, branch deletion), run `git status` first \u2014 untracked or uncommitted work is unrecoverable once these run.\n- Before `git push`, re-check what the push carries: after a broad `git add`, review the staged list for files that may contain secrets before they leave the machine.\n- Pass multi-line commit messages with a HEREDOC (`git commit -m \"$(cat <<'EOF' ... EOF)\"`) so formatting survives.\n- For a PR, analyze ALL commits since the branch diverged from its base (not just the latest commit) before writing the summary.\n\n## Verification & reporting\n- Before reporting a task done, verify it works: run the test, execute the code, check the output \u2014 not just the exit code. If you can't verify, say so rather than implying success.\n- Verify the final artifact, not a proxy. Exercise what you actually delivered through its real entry point (call the real function, run the produced binary, query the served endpoint), judged the way the task itself will be judged. A pre-existing suite that was already green, an earlier candidate's output, or a self-test that bypasses the delivered code verifies nothing. Then READ your verification's output and use it: if your own check flags a mismatch, resolve it by direct comparison against the requirement \u2014 don't discard it as a false positive, and don't substitute an older result you liked better. Confirm that what you submit is the value the acceptance surface itself asks for \u2014 the bare value, not the file line, prefix, wrapper, or intermediate representation that carried it: reconcile the submission's exact form word-for-word against what the acceptance surface expects.\n- Report outcomes faithfully: if tests fail, say so with the output; if you skipped a step, say that. Never manufacture a green result. Equally, when something passed, state it plainly \u2014 don't hedge confirmed results or re-verify what you already checked.\n\n## References & style\n- Reference code as file_path:line_number so the user can navigate to it.\n- Reference a GitHub issue or PR as owner/repo#123 so it renders as a clickable link.\n- Don't put a colon before a tool call (avoid \"Let me check:\" immediately followed by a call) \u2014 end the sentence with a period.\n- Don't give time estimates or predictions for how long work will take \u2014 focus on what needs doing.\n- Be concise; lead with the answer or the action. Prefer prose, lists, and code blocks over wide tables. Match the user's language. Avoid emojis unless asked. If you can say it in one sentence, don't use three. Go straight to the point, don't go in circles, don't overdo it. (This does not apply to code or tool calls.)";
 /** Context passed to a {@link PromptProvider.stableSystem} — the STABLE, cacheable inputs only. */
 export interface StablePromptContext {
     /** The task's own system prompt, if it supplied one. */

package/dist/prompts/default.js

@@ -348,6 +348,8 @@ ${""}- Only commit when the user explicitly asks; if it's unclear whether they w
 - \`git add\` specific named files; never \`git add -A\` or \`git add .\` (they sweep in .env files, credentials, large binaries).
 - Never commit a file likely to contain secrets (.env, credentials.json, *.pem, key files); if the user explicitly asks you to, warn them first.
 - Never change git config, never skip hooks (\`--no-verify\`), never bypass signatures.
+${""}- Before any destructive git command (\`checkout --force\`, \`reset --hard\`, \`clean\`, branch deletion), run \`git status\` first — untracked or uncommitted work is unrecoverable once these run.
+- Before \`git push\`, re-check what the push carries: after a broad \`git add\`, review the staged list for files that may contain secrets before they leave the machine.
 - Pass multi-line commit messages with a HEREDOC (\`git commit -m "$(cat <<'EOF' ... EOF)"\`) so formatting survives.
 - For a PR, analyze ALL commits since the branch diverged from its base (not just the latest commit) before writing the summary.
 

package/dist/scenarios/scenario-registry.d.ts

@@ -12,7 +12,7 @@
  * deploy-side knowledge — core fills guard-number defaults + prompts + orchestrator choice, never the model.
  */
 import type { Runner } from "../core/runner/runtask.js";
-import type { ModelRef, ModelRole } from "../core/types.js";
+import type { ModelRef, ModelRole, TaskSpec } from "../core/types.js";
 import { type TeamResult } from "../agents/team.js";
 import { type VerificationResult } from "../agents/verify.js";
 /** Design review: falsification-style multi-role debate (architect / reviewer / implementer). Reuses team.ts's
@@ -75,6 +75,10 @@ export interface RunScenarioOptions {
     reviewerCount?: number;
     /** External cancellation propagated into the orchestrator. */
     signal?: AbortSignal;
+    /** Per-model auth — MIRRORS {@link TaskSpec.getApiKeyAndHeaders}; forwarded into whichever
+     *  orchestrator the scenario maps to (solo task / team runs / verify judge), which resolve it
+     *  against their own resolved models. Absent ⇒ byte-identical specs (no key added). */
+    getApiKeyAndHeaders?: TaskSpec["getApiKeyAndHeaders"];
 }
 /** Per-scenario result union — each entry returns its orchestrator's native result shape. */
 export type RunScenarioResult = {

package/dist/scenarios/scenario-registry.js

@@ -61,7 +61,7 @@ export async function runScenario(opts) {
     switch (profile.orchestrator) {
         case "solo": {
             const model = requireModel(opts.models, "default", opts.scenario);
-            const spec = { objective: opts.objective, model, signal: opts.signal };
+            const spec = { objective: opts.objective, model, signal: opts.signal, ...(opts.getApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: opts.getApiKeyAndHeaders } : {}) };
             return { scenario: "solo", result: await opts.runner.runTask(spec) };
         }
         case "team": {
@@ -81,6 +81,7 @@ export async function runScenario(opts) {
                     ],
                     synthesizer: { model: synthModel },
                     signal: opts.signal,
+                    ...(opts.getApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: opts.getApiKeyAndHeaders } : {}),
                 });
                 return { scenario: "design-review", result };
             }
@@ -95,6 +96,7 @@ export async function runScenario(opts) {
                 members: codeReviewMembers(opts.reviewerCount ?? 2, teamModel),
                 synthesizer: { model: synthModel },
                 signal: opts.signal,
+                ...(opts.getApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: opts.getApiKeyAndHeaders } : {}),
             });
             return { scenario: "code-review", mode: "team", result };
         }
@@ -127,7 +129,7 @@ async function runCodeReviewVerify(opts) {
         result: opts.objective,
         stats: { turns: 0, tokens: 0 },
     };
-    const specBase = { signal: opts.signal };
+    const specBase = { signal: opts.signal, ...(opts.getApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: opts.getApiKeyAndHeaders } : {}) };
     const result = await verifyCompleted(opts.runner, reviewed, specBase, opts.objective, {
         verifierModel,
         verifierPrompt: STATIC_VERIFICATION_PROMPT,

package/dist/tools/fs/index.js

@@ -79,7 +79,14 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
         if (!readOnly && mountBackgroundTaskTools && hasBackgroundShell(env)) {
             const sessionAxis = opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {};
             tools.push(opts.taskRegistry
-                ? createTaskOutputTool({ registry: opts.taskRegistry, owner: opts.taskOwner, scope: opts.taskScope, ...sessionAxis, ...(opts.oneShot !== undefined ? { oneShot: opts.oneShot } : {}) })
+                ? createTaskOutputTool({
+                    registry: opts.taskRegistry,
+                    owner: opts.taskOwner,
+                    scope: opts.taskScope,
+                    ...sessionAxis,
+                    ...(opts.oneShot !== undefined ? { oneShot: opts.oneShot } : {}),
+                    notificationWired: opts.taskNotification !== undefined,
+                })
                 : createEnvTaskOutputTool(env), opts.taskRegistry
                 ? createTaskStopTool({ registry: opts.taskRegistry, owner: opts.taskOwner, scope: opts.taskScope, ...sessionAxis })
                 : createEnvTaskStopTool(env));

package/dist/tools/scheduler-tools.js

@@ -396,10 +396,19 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
         wakeupChain = next.then(() => undefined, () => undefined);
         return next;
     };
+    const wakeupMountNote = sched.schedulerCapabilities.supportsSessionWakeup === false
+        ? `
+
+MOUNT NOTE: this host has no resident wakeup leg, so ${SCHEDULE_WAKEUP_TOOL_NAME} refuses every scheduling call here — do not plan a self-paced loop around it (\`stop: true\` still works).`
+        : sched.schedulerCapabilities.supportsSessionLifetime === true
+            ? ""
+            : `
+
+MOUNT NOTE: this host does not vouch for session-scoped scheduling, so a wakeup scheduled here is PERSISTENT — contrary to the paragraph above, it can outlive this session instead of ending with it. End the loop explicitly with \`stop: true\` when the work is done; do not rely on the session ending to cancel it.`;
     const scheduleWakeup = defineTool({
         name: SCHEDULE_WAKEUP_TOOL_NAME,
         contract: { contractId: "core.schedule_wakeup@1", implementationRevision: "1" },
-        description: SCHEDULE_WAKEUP_PROMPT,
+        description: `${SCHEDULE_WAKEUP_PROMPT}${wakeupMountNote}`,
         parameters: Type.Object({
             delaySeconds: Type.Optional(Type.Number({
                 description: "Seconds from now to wake up. Clamped to [60, 3600] by the runtime. Required unless `stop` is true.",
@@ -433,20 +442,33 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
             if (sched.schedulerCapabilities.supportsSessionWakeup === false) {
                 return errorResult(`Error (${SCHEDULE_WAKEUP_TOOL_NAME}): this environment has no resident scheduler that can honor a session wakeup — the wakeup would never fire. Wait in the foreground instead, or start the work in a self-detaching form.`);
             }
+            const sessionReapVouched = sched.schedulerCapabilities.supportsSessionLifetime === true;
             const clampedDelaySeconds = Math.min(3600, Math.max(60, Math.round(a.delaySeconds)));
             const wasClamped = clampedDelaySeconds !== a.delaySeconds;
             const pending = await listPendingWakeups();
-            if (!("err" in pending))
-                await cancelWakeups(pending.ids);
-            const r = await sched.schedule({ prompt: a.prompt, when: { kind: "delay", delaySec: clampedDelaySeconds }, label: WAKEUP_LABEL, mode: "session-wakeup" }, sessionCtx);
+            const cancelledCount = "err" in pending ? 0 : await cancelWakeups(pending.ids);
+            const cleanupIncomplete = "err" in pending || cancelledCount < pending.ids.length;
+            const r = await sched.schedule({
+                prompt: a.prompt,
+                when: { kind: "delay", delaySec: clampedDelaySeconds },
+                label: WAKEUP_LABEL,
+                mode: "session-wakeup",
+                ...(sessionReapVouched ? { lifetime: "session" } : {}),
+            }, sessionCtx);
             if (!r.ok)
                 return errorResult(`Error (${SCHEDULE_WAKEUP_TOOL_NAME}): ${r.error.message}`);
             const scheduledFor = Date.now() + clampedDelaySeconds * 1000;
             const hhmmss = new Date(scheduledFor).toTimeString().slice(0, 8);
             const clampNote = wasClamped ? ` (clamped to ${clampedDelaySeconds}s from your requested value)` : "";
+            const cleanupNote = cleanupIncomplete
+                ? " Warning: the previously pending wakeup(s) for this session could not all be listed or cancelled, so MORE THAN ONE wakeup may now be armed (you would be re-invoked twice). Call this tool with `stop: true` and then re-schedule to get back to a single one."
+                : "";
+            const reapNote = sessionReapVouched
+                ? ""
+                : " Note: this scheduler does not vouch for session-lifetime reap, so this wakeup is scheduled as a persistent one and may outlive the session — end the loop explicitly with `stop: true` rather than relying on the session ending.";
             return {
-                content: `Next wakeup scheduled for ${hhmmss} (in ${clampedDelaySeconds}s)${clampNote}. Nothing more to do this turn — the harness re-invokes you when the wakeup fires or a task-notification arrives.`,
-                details: { type: "schedule-wakeup", stopped: false, scheduledFor, clampedDelaySeconds, wasClamped },
+                content: `Next wakeup scheduled for ${hhmmss} (in ${clampedDelaySeconds}s)${clampNote}. Nothing more to do this turn — the harness re-invokes you when the wakeup fires or a task-notification arrives.${reapNote}${cleanupNote}`,
+                details: { type: "schedule-wakeup", stopped: false, scheduledFor, clampedDelaySeconds, wasClamped, reason: a.reason },
             };
         }),
     });

package/dist/tools/web.d.ts

@@ -160,6 +160,21 @@ export declare function resolveSummaryInputChars(model: Model, override?: number
 export interface WebFetchSummarizerOptions {
     /** Override the derived page-content budget (see {@link resolveSummaryInputChars}). */
     maxContentChars?: number;
+    /**
+     * Per-model auth — MIRRORS {@link TaskSpec.getApiKeyAndHeaders} (same signature, resolved per
+     * call against the summarizer's model, the side-query seat's form). Without this seat the
+     * summarizer called the brain with `{ signal }` only, so a summarizer model on a
+     * per-model-credential route fell to the brain's construction-time credential — which the
+     * key↔URL pairing gate refuses off the deployment root. Absent ⇒ the options object is
+     * byte-identical to the pre-seat shape (no keys added).
+     */
+    getApiKeyAndHeaders?: (model: Model) => Promise<{
+        apiKey?: string;
+        headers?: Record<string, string>;
+    } | undefined> | {
+        apiKey?: string;
+        headers?: Record<string, string>;
+    } | undefined;
 }
 /**
  * 黑板 [1870] L1 / [1900] — a reference {@link WebFetchConfig.summarize} implementation: reuses a

package/dist/tools/web.js

@@ -725,9 +725,15 @@ export function createWebFetchSummarizer(brain, model, options = {}) {
         const truncated = inputTruncated ? content.slice(0, budget) + "\n\n[Content truncated due to length...]" : content;
         const userPrompt = `\nWeb page content:\n---\n${truncated}\n---\n\n${prompt}\n\n` + WEBFETCH_SUMMARY_GROUNDING_CLAUSE + "\n" + WEBFETCH_SUMMARY_GUIDELINES;
         const context = { messages: [{ role: "user", content: userPrompt, timestamp: Date.now() }] };
+        const auth = await options.getApiKeyAndHeaders?.(model);
+        const callOptions = {
+            signal,
+            ...(auth?.apiKey !== undefined ? { apiKey: auth.apiKey } : {}),
+            ...(auth?.headers !== undefined ? { headers: auth.headers } : {}),
+        };
         const msg = brain.complete
-            ? await brain.complete(model, context, { signal })
-            : await (await Promise.resolve(brain.stream(model, context, { signal }))).result();
+            ? await brain.complete(model, context, callOptions)
+            : await (await Promise.resolve(brain.stream(model, context, callOptions))).result();
         if (msg.stopReason === "error" || msg.stopReason === "aborted") {
             throw new Error(msg.errorMessage ?? `summarizer stopped with ${msg.stopReason}`);
         }

package/dist/tools/worktree.js

@@ -248,10 +248,10 @@ export function createWorktreeTools(env, opts) {
                 description: "true = remove the worktree even when it has uncommitted files or new commits, permanently discarding them. Default false: a changed worktree is kept and its changes listed. Cannot be combined with `keep: true`.",
             })),
             action: Type.Optional(Type.Union([Type.Literal("keep"), Type.Literal("remove")], {
-                description: '"keep" leaves the worktree and branch on disk; "remove" deletes both.',
+                description: '"keep" leaves the worktree on disk. "remove" takes the default removal path: an unchanged worktree is removed, a changed one is still KEPT unless `discard_changes: true`. The worktree is detached — no branch is created or deleted either way.',
             })),
             discard_changes: Type.Optional(Type.Boolean({
-                description: 'Required true when action is "remove" and the worktree has uncommitted files or unmerged commits. The tool will refuse and list them otherwise.',
+                description: 'Set true to remove the worktree even when it has uncommitted files or unmerged commits — they are permanently discarded. Without it a changed worktree is KEPT (the exit still completes and the reply lists the changes plus this escape), never refused.',
             })),
         }),
         effect: "write",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.55.0",
+  "version": "5.57.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",