@sema-agent/core 5.34.0 → 5.36.0

package/dist/core/task-registry.js

@@ -10,7 +10,7 @@ import { registerWorkflowLane, pollWorkflowLane, stopWorkflowLane } from "./task
 import { mintCompletionId, canAccessWorkflowRun, formatWorkflowRun, clipTaskOutput, assertOwnership, sleepPollStep, statusFromBackground, rollSpoolText, accountDroppedBytes, renderSpoolBody, spoolDropNote, droppedGapNote, alreadyTerminalStopNote, terminalTaskSummary, TASK_OUTPUT_MAX_CHARS, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE, canAccess, DURABLE_AGENT_HANDLE_RE, } from "./task-registry-shared.js";
 export { normalizeAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR } from "./task-registry-shared.js";
 import { TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_CONTRACT, TASK_STOP_CONTRACT, TASK_OUTPUT_MISSING_ID_MESSAGE, TASK_STOP_MISSING_ID_MESSAGE, TASK_STOP_PARAMS, resolveTaskIdArg, REGISTRY_TASK_TOOL_CAPS, composeTaskOutputDescription, composeTaskOutputParams, composeTaskStopDescription, } from "./task-tool-shape.js";
-import { durableAgentArmedLane, durableAgentRowProbeLane, beginDurableClaimLane, endDurableClaimLane, reapDurableAgentsLane, noteBackgroundAgentActivityLane, reapStaleSessionBackgroundAgentsLane, releaseDurableTranscriptAnchorLane, bindBackgroundAgentSessionLane, registerBackgroundAgentLane, recordBackgroundAgentOrgAdmissionLane, parkBackgroundAgentLane, reconcileParkedAgentsLane, claimParkedAgentLane, rollbackParkedClaimLane, consumeParkedFlipLane, finalizeParkedResumeLane, settleBackgroundAgentLane, abortBackgroundAgentsForOwnerLane, serveDurableAgentRowLane, resolveBackgroundAgentByNameLane, markRetainedContinuationLane, reviveBackgroundAgentLane, settleRevivedAgentLane, unmarkRetainedContinuationLane, attachAgentNotifyLane, deliverToRunningAgentLane, runningBackgroundAgentLabelsLane, runningAgentFooterLane, notFoundRunningAgentsTail, pollBackgroundAgentLane, stopBackgroundAgentLane, } from "./task-registry-agent.js";
+import { durableAgentArmedLane, durableAgentRowProbeLane, beginDurableClaimLane, endDurableClaimLane, reapDurableAgentsLane, noteBackgroundAgentActivityLane, reapStaleSessionBackgroundAgentsLane, releaseDurableTranscriptAnchorLane, bindBackgroundAgentSessionLane, registerBackgroundAgentLane, recordBackgroundAgentOrgAdmissionLane, parkBackgroundAgentLane, reconcileParkedAgentsLane, claimParkedAgentLane, rollbackParkedClaimLane, consumeParkedFlipLane, finalizeParkedResumeLane, settleBackgroundAgentLane, abortBackgroundAgentsForOwnerLane, serveDurableAgentRowLane, resolveBackgroundAgentByNameLane, backgroundAgentCycleSeqLane, markRetainedContinuationLane, reviveBackgroundAgentLane, settleRevivedAgentLane, unmarkRetainedContinuationLane, attachAgentNotifyLane, deliverToRunningAgentLane, runningBackgroundAgentLabelsLane, runningAgentFooterLane, notFoundRunningAgentsTail, pollBackgroundAgentLane, stopBackgroundAgentLane, } from "./task-registry-agent.js";
 export { canAccessWorkflowRun, clipTaskOutput, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE };
 const BLOCK_DEFAULT_TIMEOUT_MS = 30_000;
 const BLOCK_MAX_TIMEOUT_MS = 600_000;
@@ -191,6 +191,9 @@ export class TaskRegistry {
     markRetainedContinuation(id) {
         return markRetainedContinuationLane(this.core, id);
     }
+    backgroundAgentCycleSeq(id) {
+        return backgroundAgentCycleSeqLane(this.core, id);
+    }
     reviveBackgroundAgent(id, access, abort) {
         return reviveBackgroundAgentLane(this.core, id, access, abort);
     }

package/dist/core/tool-errors.d.ts

@@ -117,8 +117,8 @@ export type WorkerErrorClass = "budget" | "limit" | "output" | "suspend" | "revi
  * are NOT all terminal-errorCode-shaped — see {@link EXACT_CODE_CLASS}'s comment), plus the flat 1.36 codes.
  * The `limits.` namespace splits into the `budget` and `limit` classes by exact code — see
  * {@link EXACT_CODE_CLASS}. Operation-level dotted codes that are surfaced to a *caller* and never become a
- * task outcome are deliberately OUT of scope: `steering.*` (`steering.not_running`/`steering.invalid_content`,
- * rejected to the `steer()` caller) and `mcp.*` (`mcp.server_unavailable`, an `onWarn` warning code) — neither
+ * task outcome are deliberately OUT of scope: `steering.*` (`steering.not_running`/`steering.invalid_content`/
+ * `steering.duplicate_input_id`, rejected to the `steer()` caller) and `mcp.*` (`mcp.server_unavailable`, an `onWarn` warning code) — neither
  * reaches `TaskResult.errorCode`, so a caller will never pass them here. A genuinely unmapped code → `"unknown"` (which therefore means
  * "known-but-foreign or no code", e.g. a leaked fs/Node code, NOT "an OUR terminal class we forgot to add").
  */

package/dist/core/tool-policy.d.ts

@@ -118,6 +118,34 @@ export type ApprovalSettledBy = "human" | "timeout" | "aborted";
 export declare const APPROVAL_SETTLED_BY_VALUES: readonly ApprovalSettledBy[];
 /** True iff `v` is one of the three {@link ApprovalSettledBy} words. */
 export declare function isApprovalSettledBy(v: unknown): v is ApprovalSettledBy;
+/**
+ * design/252 G-7 — how long an approver-attribution identifier may be.
+ *
+ * Sized for the identifiers approval channels actually carry (a login, an email, an opaque account id,
+ * a queue name) with room to spare, and bounded at all because this value lands on an operator-plane
+ * frame that a deployment may persist: an unbounded field on a record channel is its own denial of a
+ * readable record. An over-long value is REFUSED, never truncated — a cut identifier names a different
+ * party, or nobody, and either is worse than the honest refusal.
+ */
+export declare const APPROVER_ATTRIBUTION_MAX_CHARS = 256;
+/**
+ * design/252 G-7 — screen a deployment-supplied approver identifier before it becomes an observation.
+ *
+ * THE POSTURE, stated so it is not mistaken for something stronger: core does not authenticate this
+ * value, does not compare it to anything, and never reads it back to decide anything. It is a
+ * TRANSCRIPTION of what the approval channel said about its own settlement — the channel (a server's
+ * approval card, an HMAC-verified callback, an operator console) is where identity is established, and
+ * a library that holds no identity surface cannot second-guess it. What core owns is that the value is
+ * a value: a string, bounded, free of control bytes, or else loudly refused.
+ *
+ * Returns `{}` for "nothing supplied" (absent, and an empty string — an id of no characters is the
+ * absence of an id, the same truthiness fold the deny-note seat uses), `{ approver }` for a value to
+ * carry, or `{ defect }` with the sentence a caller puts in its own refusal.
+ */
+export declare function screenApproverAttribution(v: unknown): {
+    approver?: string;
+    defect?: string;
+};
 /**
  * A three-state permission decision for a tool call (design/37). Upgrades the old two-state
  * `{allow|deny}`:
@@ -162,6 +190,7 @@ export type PermissionResult = {
     message?: string;
     decisionReason?: DecisionReason;
     settledBy?: Extract<ApprovalSettledBy, "human">;
+    approver?: string;
 } | {
     action: "ask";
     updatedInput?: unknown;
@@ -199,13 +228,86 @@ export type PermissionResult = {
      *  when ANY folded-away concurrent ask bore it (monotone, tighten-only); it is consumed inside the
      *  gate and deliberately NOT copied onto the park/approval-card request. */
     matchedAskRule?: string;
+    /** design/252 G-2 (additive): the RULE-PROVENANCE evidence behind this ask — see
+     *  {@link AskRuleEvidence}. ENGINE-STAMPED inside the gate, once, after the org layer and the
+     *  persisted-rule lane have both spoken; a policy that self-declares it is overwritten there
+     *  (the member is a record of what the ENGINE's own governance layers did, so a layer's claim
+     *  about itself is not evidence). Carried onto the approval request by the gate's own ask mint
+     *  site. Display/reconciliation metadata, never adjudication input. */
+    ruleEvidence?: AskRuleEvidence;
 } | {
     action: "deny";
     updatedInput?: unknown;
     message?: string;
     decisionReason?: DecisionReason;
     settledBy?: ApprovalSettledBy;
+    approver?: string;
 };
+/**
+ * design/252 G-2 — WHY a piece of rule-provenance evidence is not on an ask.
+ *
+ * The vocabulary exists because a bare `undefined` reads the same for facts that are opposite: "no
+ * governance layer is wired here, so there is nothing to name" and "the layer ran and we could not
+ * read what it said" are not the same audit answer, and collapsing them is how an evidence chain
+ * comes to be reconstructed as "nothing governed this call". Every member of {@link AskRuleEvidence}
+ * therefore ships as a value OR a named absence, never as silence.
+ *
+ *  - `"not_wired"` — the lane does not exist on this leg (an ungoverned deployment, no rule store).
+ *    The field cannot apply; nothing was lost.
+ *  - `"not_adjudicated"` — the lane exists but this call never reached it (an exempt tool, a call
+ *    the rule grammar cannot describe). Applicable in principle, skipped in fact.
+ *  - `"unavailable"` — the lane was consulted and could not read its source. The evidence is LOST,
+ *    not absent, and this is the one member of the vocabulary that means an auditor should treat the
+ *    chain as broken rather than empty.
+ *  - `"no_match"` — consulted, readable, and nothing spoke for this call. A real negative answer.
+ *  - `"not_reported"` — the supplying seam answered without the identity (a foreign overlay/store
+ *    implementation, or one written before the identity was projected). Evidence lost at the seam.
+ */
+export type AskEvidenceAbsence = "not_wired" | "not_adjudicated" | "unavailable" | "no_match" | "not_reported";
+/** The closed set above, for runtime domain checks at the seams that accept a caller-supplied value. */
+export declare const ASK_EVIDENCE_ABSENCE_VALUES: readonly AskEvidenceAbsence[];
+/**
+ * design/252 G-2 — the machine-reconcilable provenance of the governance decision behind ONE ask.
+ *
+ * WHAT THIS IS: a PROJECTION of identity keys the engine's governance layers already hold — the org
+ * snapshot's `revision`, the personal rule's add `dot`s — onto the surface a consumer can actually
+ * read. It performs no new judgment and changes no verdict; removing it would leave every decision
+ * byte-identical. The prose channels ({@link PermissionResult}'s ask `message`,
+ * {@link AskRequest.persistedRuleShadowed}) say the same things to a PERSON; those are sanitized,
+ * capped, display-shaped strings, and reconciling a decision against a published policy revision by
+ * regexing them is not an audit trail. This member is the machine's copy.
+ *
+ * WHAT THIS IS NOT: an authority channel. Nothing in the engine reads it back to decide anything, and
+ * a host that ignores it entirely is governed exactly as before.
+ *
+ * ABSENCE DISCIPLINE (the reason each member has a `…Absent` twin): see {@link AskEvidenceAbsence}.
+ * Exactly one of each pair is present — a member and its absence reason are never both set, and never
+ * both missing, on evidence the engine stamped.
+ */
+export interface AskRuleEvidence {
+    /** The org snapshot `revision` this call was adjudicated against — the published-policy version an
+     *  auditor reconciles the decision against. Absent ⇒ {@link orgRevisionAbsent} names why. */
+    readonly orgRevision?: number;
+    /** Present iff {@link orgRevision} is not. `"unavailable"` here is the load-bearing one: the org
+     *  layer spoke, its answer was "this deployment cannot see the organization's rules", and the ask
+     *  in hand is the fail-closed tighten that followed — not an ask any published rule asked for. */
+    readonly orgRevisionAbsent?: AskEvidenceAbsence;
+    /** The org rule that spoke for this call, verbatim as published (org rules are administrator
+     *  authored and are relayed unmodified — the prose channel's copy is the same text). Absent ⇒
+     *  {@link orgRuleAbsent} names why. */
+    readonly orgRule?: string;
+    /** Present iff {@link orgRule} is not. */
+    readonly orgRuleAbsent?: AskEvidenceAbsence;
+    /** The add dots of the PERSONAL allow rule that matched this call but did not clear the ask (the
+     *  #144 shadowed arm). The dots are the rule's durable identity — unlike
+     *  {@link AskRequest.persistedRuleShadowed}, which is a sanitized, length-capped DISPLAY value and
+     *  deliberately not an identity channel. A rule is a set of adds (concurrent approvals on one text
+     *  each redeem their own dot), so this is an array by construction: render/reconcile the entries as
+     *  data, never re-derive one scalar id by joining them. Absent ⇒ {@link personalRuleDotsAbsent}. */
+    readonly personalRuleDots?: readonly import("./permission-rule-model.js").RuleDot[];
+    /** Present iff {@link personalRuleDots} is not. */
+    readonly personalRuleDotsAbsent?: AskEvidenceAbsence;
+}
 /** The human/model-readable text of a decision. */
 export declare function decisionText(d: PermissionResult): string | undefined;
 /**
@@ -682,6 +784,15 @@ export interface AskRequest {
      *  structure: render the entries as data, never re-derive structure by splitting or joining them.
      *  The durable park route carries the same value as `RiskDescriptor.probeCause`. */
     readonly probeCause?: import("./checkpoint-store.js").ProbeCause;
+    /** design/252 G-2: the RULE-PROVENANCE evidence behind this ask — the org snapshot revision and the
+     *  matched rules' own identity keys, each present as a value or as a named absence (see
+     *  {@link AskRuleEvidence}). Present on EVERY ask the engine mints, so a consumer never has to tell a
+     *  missing field from a field that means something: the gate's own mint site fills it from what its
+     *  layers did, and the three INHERITED-lane sites — which present an ANCESTOR policy's decision, from
+     *  upstream of both lanes — fill it with an all-`"not_adjudicated"` record rather than a fabricated
+     *  revision. Optional on the TYPE only because a deployment may invoke its approver directly.
+     *  RECONCILIATION metadata, never adjudication input. */
+    readonly ruleEvidence?: AskRuleEvidence;
     toolCallId: string;
     /** The (post-rewrite) args the tool would run with. */
     args: unknown;
@@ -859,12 +970,26 @@ export type OnAsk = "deny" | "allow" | ((req: AskRequest, signal?: AbortSignal)
  *    domain the durable leg enforces pre-CAS for the same field), a THROWING read is a fail-closed
  *    deny naming the true cause (never a raw rejection out of the gate), and the empty string reads
  *    as absent (truthiness, the durable consumer's own read).
+ *
+ * `approver` (design/252 G-7) — the ATTRIBUTION seat: the identifier the approval channel reports for
+ * the party that ended this wait. Core does not authenticate it, compare it, or read it back to decide
+ * anything; it transcribes it onto the settlement observation next to `settledBy`, so an audit that can
+ * already say "a person ended this wait" can also say which one, without core growing an identity
+ * surface it deliberately does not have. Read the two together: `settledBy:"timeout"` with an
+ * `approver` names the queue whose window elapsed, NOT someone who refused.
+ * Screened, not trusted (see {@link screenApproverAttribution}): a non-string, an over-long value or one
+ * carrying control characters is a loud fail-closed refusal at {@link resolveAsk}, the same posture this
+ * seam takes for every other out-of-contract value — and the same reason, since a defective attribution
+ * that were quietly dropped would leave a settlement looking unattributed rather than misreported. It is
+ * carried on the arms where the CALLER settled something (its allow, its human/timeout deny) and never
+ * on an end the engine produced (an abort, a throw, an unclonable edit): nobody approved those.
  */
 export type AskOutcome = boolean | "unavailable" | {
     allow: boolean;
     updatedInput?: unknown;
     settledBy?: Extract<ApprovalSettledBy, "human" | "timeout">;
     reason?: string;
+    approver?: string;
 };
 /**
  * ruled 2026-08-04 — forward an approver into a delegated child, stamping every ask it raises with the

package/dist/core/tool-policy.js

@@ -13,6 +13,26 @@ export const APPROVAL_SETTLED_BY_VALUES = ["human", "timeout", "aborted"];
 export function isApprovalSettledBy(v) {
     return typeof v === "string" && APPROVAL_SETTLED_BY_VALUES.includes(v);
 }
+export const APPROVER_ATTRIBUTION_MAX_CHARS = 256;
+const APPROVER_REFUSED_CHARS_RE = /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]/u;
+export function screenApproverAttribution(v) {
+    if (v === undefined || v === "")
+        return {};
+    if (typeof v !== "string") {
+        return { defect: `an approver attribution must be a plain string (got ${v === null ? "null" : typeof v})` };
+    }
+    if (v.length > 2 * APPROVER_ATTRIBUTION_MAX_CHARS || [...v].length > APPROVER_ATTRIBUTION_MAX_CHARS) {
+        return { defect: `an approver attribution is capped at ${APPROVER_ATTRIBUTION_MAX_CHARS} characters and this one is longer; it is refused rather than truncated, because a cut identifier names someone else` };
+    }
+    if (/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(v)) {
+        return { defect: "an approver attribution contains an unpaired surrogate; it is not well-formed text and would collapse to a replacement character in a UTF-8 sink, so two distinct approvers could converge into one record" };
+    }
+    if (APPROVER_REFUSED_CHARS_RE.test(v)) {
+        return { defect: "an approver attribution carries control characters, line separators or bidirectional overrides; an identifier whose bytes can forge a line — or reorder what a reader sees — in whatever renders it is refused" };
+    }
+    return { approver: v };
+}
+export const ASK_EVIDENCE_ABSENCE_VALUES = ["not_wired", "not_adjudicated", "unavailable", "no_match", "not_reported"];
 export function decisionText(d) {
     return d.message;
 }
@@ -899,10 +919,12 @@ export async function resolveAsk(req, onAsk, signal) {
         let supplied;
         let allowed;
         let suppliedEdit;
+        let suppliedApprover;
         try {
             supplied = ok.settledBy;
             allowed = ok.allow;
             suppliedEdit = ok.updatedInput;
+            suppliedApprover = ok.approver;
         }
         catch (err) {
             return {
@@ -930,6 +952,16 @@ export async function resolveAsk(req, onAsk, signal) {
                 settledBy: "aborted",
             };
         }
+        const attribution = screenApproverAttribution(suppliedApprover);
+        if (attribution.defect !== undefined) {
+            return {
+                action: "deny",
+                message: `the approver for "${req.toolName}" reported an attribution this seam refuses: ${attribution.defect}; denied fail-closed`,
+                decisionReason: "mode",
+                settledBy: "aborted",
+            };
+        }
+        const attributionCell = attribution.approver !== undefined ? { approver: attribution.approver } : {};
         if (supplied === "timeout" && allowed === true) {
             return {
                 action: "deny",
@@ -969,10 +1001,11 @@ export async function resolveAsk(req, onAsk, signal) {
                     : humanRefusalMessage(req, reasonText),
                 decisionReason: "mode",
                 settledBy: supplied === "timeout" ? "timeout" : "human",
+                ...attributionCell,
             };
         }
         if (suppliedEdit === undefined)
-            return { action: "allow", decisionReason: "mode", presentedInput: presented.value, settledBy: "human" };
+            return { action: "allow", decisionReason: "mode", presentedInput: presented.value, settledBy: "human", ...attributionCell };
         const edit = tryCloneArgs(suppliedEdit);
         if (!edit.ok) {
             return {
@@ -982,7 +1015,7 @@ export async function resolveAsk(req, onAsk, signal) {
                 settledBy: "aborted",
             };
         }
-        return { action: "allow", updatedInput: edit.value, decisionReason: "mode", settledBy: "human" };
+        return { action: "allow", updatedInput: edit.value, decisionReason: "mode", settledBy: "human", ...attributionCell };
     }
     const okRaw = ok;
     if (okRaw === true)

package/dist/core/types.d.ts

@@ -3437,6 +3437,26 @@ export type TaskEvent = ({
      * must not treat "absent" as "a human decided".
      */
     settledBy?: import("./tool-policy.js").ApprovalSettledBy;
+    /**
+     * design/252 G-7 — WHOSE settlement that was: the identifier the approval channel reported for
+     * the party that ended this wait, beside the {@link settledBy} word that says what KIND of end
+     * it was. The two are read together and neither substitutes for the other:
+     * `settledBy:"timeout"` with an `approver` names the queue whose window elapsed, NOT someone
+     * who refused.
+     *
+     * WHAT CORE PROMISES ABOUT IT — exactly one thing: it is what the settling caller said, screened
+     * for shape (a plain string, bounded, no control characters) and otherwise untouched. Core does
+     * NOT authenticate it, does not compare it to a principal, and never reads it back to decide
+     * anything. Identity is established by the approval channel a deployment integrates (its card,
+     * its signature, its console); this is the transcription that lets an audit which already knows
+     * a person ended a wait also say which person, without the engine growing an identity surface it
+     * deliberately does not have. Treat it accordingly: it is a RECORD of a claim, and its
+     * trustworthiness is exactly the trustworthiness of the channel that made it.
+     *
+     * ABSENT on every frame that settled no approval, and on a settled approval whose channel named
+     * nobody. Absence means nobody SAID — never "nobody approved this", and never "a human did".
+     */
+    approver?: string;
     /**
      * design/99 §E1 — `true` when {@link output} was SIZE-bounded by core (the full body exceeded the cap and
      * was degraded to a truncated string). Lets a consumer detect truncation programmatically instead of
@@ -3627,9 +3647,15 @@ export type TaskEvent = ({
      * (one event per attachment; a multi-attachment boundary still coalesces into ONE steer message
      * on the model lane). [c209-C]: the listing family's FIRST-FRAME deliveries (initial roster /
      * `<skills>` block riding the first user message, not a steer) emit the same echo frames.
+     *
+     * `git_status` (env-tail migration, additive member): the git-status frame — the turn-dynamic
+     * git facts' carrier since they left the system prompt. Emitted at the frame's append RECEIPT
+     * (first-frame / resume-continuation / compaction re-assert deliveries alike). Its `preview`
+     * is a CONSTANT wording on purpose (never frame bytes): branch names and status text are
+     * repo-controlled and must not enter the event telemetry plane through this echo.
      */
     type: "steering_injected";
-    source: "limit_approach" | "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "workflow_size_guideline_change" | "budget_usd" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools" | "final_verification";
+    source: "limit_approach" | "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "workflow_size_guideline_change" | "budget_usd" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools" | "final_verification" | "git_status";
     preview: string;
 } & TaskEventIdentity) | ({
     /**
@@ -3770,6 +3796,18 @@ export type TaskEvent = ({
      * read absence as "not an agent".
      */
     taskType?: DelegationTaskType;
+    /**
+     * #258 — the registry row's STOP-CYCLE generation this tick reports from (fresh
+     * spawn = 1, every launched revival bumps it), the same counter `TaskNotificationPayload.seq`
+     * and `BackgroundChildEvent.seq` already speak — one axis, not a third spelling. It answers
+     * the one question a fleet consumer cannot otherwise decide when a frame arrives late: "late
+     * first frame of the cycle I know (same value), or a revived run I have not folded yet
+     * (higher value)?" Advisory observation, stamped at spawn/revive from the registry's own
+     * counter; the settle-time ledger stays the authority. ABSENT is a fact, not a gap: a run
+     * with no `a*` registry row (a SYNCHRONOUS delegated child, a workflow `wa*` agent, a
+     * top-level run) has no generation concept, and absence must never be read as "cycle 1".
+     */
+    seq?: number;
     /** [1611] workflow-lane self-identification (server field-proof: the SSE-forwarded tick of a
      *  WORKFLOW child previously carried a bare uuid with no workflow identity — indistinguishable
      *  from an unknown nested subagent; the fleet lane had `wa*`+workflowRunId but this lane had
@@ -3876,8 +3914,12 @@ export interface TaskStream extends AsyncIterable<TaskEvent> {
     /**
      * Inject a mid-task **steering** message (design/47) that the running task sees at the start of its
      * next turn (delivered via the harness steering queue). Resolves once queued; **throws** (code
-     * `steering.not_running`) if the task hasn't started yet or has already finished — never silently
-     * dropped. By default the text enters as a normal **user** message (in an orchestration the caller IS
+     * `steering.not_running`) once the task has finished (teardown included) — never silently dropped. A
+     * steer issued BEFORE the run has ISSUED ITS FIRST PROMPT is not refused: it is HELD for the birth
+     * window and enters the queue as soon as the loop goes live, so the model sees it at the next turn
+     * boundary like any other steer — it is refused if the loop ends first, or if that BOUNDED wait runs
+     * out while the run still has not started (ruled 2026-08-05; a retry under the same `inputId` is then
+     * clean — a refusal reserves nothing). By default the text enters as a normal **user** message (in an orchestration the caller IS
      * the task's user). Pass `trusted: true` ONLY for operator/system-level guidance: it is wrapped as a
      * `<system-reminder>` (elevated authority) — do NOT use it for caller/third-party content that could
      * carry a prompt injection. The seam gives the channel; the caller owns the judgement (design/43 §6).
@@ -3885,10 +3927,55 @@ export interface TaskStream extends AsyncIterable<TaskEvent> {
      * design/171 §5.2 — `actor` attributes WHO steered (a shared session's second voice): the text gets
      * the speaker envelope from the single projection point and the queued message carries the
      * metadata seat. Attribution only, never authority; absent = anonymous (bytes unchanged).
+     *
+     * design/171 §6.3 (additive) — `inputId` is the caller's correlation/idempotency key, the SAME key
+     * space as the parked queue's `PendingSteerEntry.inputId` and the `human_input` event's `inputId`
+     * (an ingress that already minted a message id passes it here, and the emitted frame carries it
+     * VERBATIM instead of a fresh uuidv7). It exists because the two legs of one steering ingress must be
+     * equally replay-safe: the parked leg has taken this key since the queue landed, so a retried request
+     * that arrives while the task is LIVE was the only one that injected twice.
+     *  - **Absent ⇒ nothing changes**: a uuidv7 is minted for the event, nothing is recorded for the call,
+     *    and the delivered bytes are what they always were. Every pre-existing caller is on this arm.
+     *  - **Replay ⇒ idempotent no-op**: re-steering an id this stream already ACCEPTED, with an identical
+     *    payload (same text, same `trusted`, same `actor`), injects nothing and emits no second
+     *    `human_input` frame. What is remembered is exactly what QUEUED: a delivery that was refused
+     *    (not running) can be retried under its own id, and a call whose DELIVERED payload is
+     *    whitespace-only — which the harness discards without minting a frame; note a `trusted` steer is
+     *    wrapped first, so it queues even for blank text — reserves nothing, leaving that id usable.
+     *  - **Same id, DIFFERENT instruction ⇒ typed throw** `steering.duplicate_input_id`: a key is not
+     *    evidence of a replay, and two callers colliding on one id must not silently lose the second
+     *    (the parked leg's `appendPendingSteer` refuses it identically). Re-issue under a fresh id.
+     *  - **Bad value ⇒ typed throw** `steering.invalid_content`, never a silent fallback to "no id": the
+     *    value domain is the parked leg's (a non-empty string of at most `MAX_STEER_INPUT_ID_CHARS`
+     *    characters, and never the reserved `LEGACY_PENDING_STEER_INPUT_ID`), so one key is accepted or
+     *    refused the same way on both legs. Validated before the liveness check, like the parked leg's.
+     *  - **Liveness outranks the key**: once the run's loop-liveness latch has flipped (the same signal
+     *    the injection path stops polling on) a replay is refused `steering.not_running` like any other
+     *    steer, never answered "already accepted" — the parked leg's row CAS answers `false` for a
+     *    resolved checkpoint on a replayed id for the same reason. The one asymmetry, stated rather than
+     *    papered over: in the sub-window where the harness has gone idle but the latch has not yet
+     *    flipped, a FRESH steer polls (and is refused when the latch flips) while a replay answers
+     *    immediately with the SAME outcome its original call reported — a key whose answer depended on
+     *    microsecond timing would defeat its own purpose. Note what that outcome has always meant on this
+     *    verb: ACCEPTED INTO THE QUEUE, not consumed by the model. A steer accepted in the last moments of
+     *    a run can be stranded by the run ending before the next boundary drains it (true of every steer,
+     *    keyed or not); a caller that needs delivery evidence reads the run's own events, not this receipt.
+     *  - **The receipt does NOT distinguish the two**: a fresh accept and a replay both resolve `void`,
+     *    exactly as `setPendingSteer` answers `true` for both. The observable difference is on the event
+     *    stream (a fresh accept emits the `human_input` frame; a replay emits none), which is also where
+     *    the parked leg's difference shows (a replay adds no queue entry, so the resume drains one frame).
+     *  - **Honest window** (weaker than the parked leg's, deliberately stated): the live dedup domain is
+     *    THIS stream object — one run leg, in this process. It is not persisted, so it does not span a
+     *    restart, a replica, or a second `runTaskStream`/`resumeStream` call on the same session; and it
+     *    holds only what the LIVE verb accepted, so an id already delivered by the parked leg (drained
+     *    into this run's resume prompt) is NOT in it and WOULD inject again. A deployment that needs
+     *    cross-leg or cross-process idempotency owns that half (its own key ledger), the same division
+     *    of labor `notify`'s park-window dedup states.
      */
     steer(text: string, options?: {
         trusted?: boolean;
         actor?: ActorAssertion;
+        inputId?: string;
     }): Promise<void>;
     /**
      * design/144 §2 — inject an EXTERNAL structured event into this run's task-notification lane, as a
@@ -4225,12 +4312,14 @@ export interface BackgroundChildEvent {
     resumable?: boolean;
     /** terminal: the settled status. */
     status?: "completed" | "killed" | "failed";
-    /** terminal (PAIR-REVIEW-01 C-3 half): the stop-cycle number — MIRROR of the sibling
-     *  task_notification's `TaskNotificationPayload.seq` (same settle, same X3 snapshot), so a
-     *  fleet-lane consumer can key multi-cycle events (`taskId:status[:seq]`) without the notify lane.
-     *  Same honest downgrade: present whenever a cycle number is knowable (the retain ledger's `cycleSeq`,
-     *  or the durable row's `seq` on a tier-3 revival / parked resume), absent when neither carrier exists
-     *  (single-cycle child; forging a period would lie). */
+    /** terminal + spawn/tick (#258 widened the carriers): the stop-cycle number — on a TERMINAL frame
+     *  a MIRROR of the sibling task_notification's `TaskNotificationPayload.seq` (same settle, same X3
+     *  snapshot); on SPAWN and TICK frames the registry row's generation at emit (fresh spawn = 1, a
+     *  revived cycle's bumped counter), so a fleet consumer can tell a LATE first frame from a revived
+     *  cycle's frame without waiting for the terminal. One axis with `task_progress`'s `seq` — the tick
+     *  mirrors the frame's own stamp. Same honest downgrade as ever: present whenever a cycle number is
+     *  knowable (the registry handle / retain ledger's `cycleSeq`, the durable row's `seq` on a tier-3
+     *  revival / parked resume), absent when no carrier exists (forging a period would lie). */
     seq?: number;
     /** terminal, P1-3(黑板 [1920]/[1921]/[1924]/[1925]): the cross-channel completion correlation id —
      *  MIRROR of the sibling task_notification's `TaskNotificationPayload.completionId` (same settle,

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

@@ -498,6 +498,53 @@ export interface WorkspaceState {
 export interface WorkspaceStateEntry extends SessionTreeEntryBase, WorkspaceState {
     type: "workspace_state";
 }
+/** The closed kind set of a git-status announcement (the availability half of the `(kind, hash)`
+ *  comparison tuple): `full` = five-segment snapshot frame; `degraded` = branch+dirty two-line frame
+ *  (the snapshot round-trip failed while the basic probe succeeded); `unavailable` / `non-repo` =
+ *  tombstone frames announcing that earlier git frames no longer describe the tree. */
+export type GitAnnouncementKind = "full" | "degraded" | "unavailable" | "non-repo";
+/**
+ * The git-status frame ANNOUNCED STATE — which rendered git view the model has last been shown on
+ * this branch, as a `(kind, hash)` tuple (hash = content hash of the rendered frame body with the
+ * frame format version and the canonical repo root bound into the digest domain). Two-phase receipt
+ * protocol: `pending: true` = a re-announcement is OWED but its frame append has not produced a
+ * receipt (a compaction restates the tuple as pending in the same CAS that lands the summary; the
+ * announced form is written only once the frame's own append returned an entry id) — any reader
+ * that finds pending nearest MUST conservatively re-announce. `entryId` = the session entry of the
+ * message CARRYING the announced frame; an announced state whose entryId is not on the active
+ * branch (rewind cut it) is treated as pending by the read walk (branch-authority read ladder).
+ */
+export interface GitAnnouncementState {
+    kind: GitAnnouncementKind;
+    hash: string;
+    /** Session entry id of the message carrying the announced frame (absent on a pending restatement). */
+    entryId?: string;
+    /** Two-phase receipt: the tuple is owed but its frame append has no receipt yet. */
+    pending?: true;
+}
+/**
+ * The git-status announced state as a FIRST-CLASS typed entry (same snapshot doctrine as
+ * {@link AnnouncedListingEntry}): the nearest carrier on the branch IS the announced state.
+ * Written at every frame COMMIT point (first-frame receipt / resume-continuation receipt /
+ * compaction re-assertion receipt); a compaction additionally restates the tuple as `pending`
+ * inside its own `details.gitAnnouncement` (same-CAS with the new baseline) until the re-asserted
+ * frame's append receipt lands. The checkpoint mirror (`CheckpointState.gitAnnouncement`) is the
+ * lower seed rung, consulted only when the branch carries no mirror at all.
+ */
+export interface GitAnnouncementEntry extends SessionTreeEntryBase, GitAnnouncementState {
+    type: "git_announcement";
+}
+/** Bounded cap for {@link normalizeGitAnnouncement} entry ids (self-generated ids are short; an
+ *  oversize value is a forgery signal, same posture as the sibling caps). */
+export declare const GIT_ANNOUNCEMENT_MAX_ENTRY_ID_CHARS = 256;
+/**
+ * Strict shape gate for the git announced state — the SINGLE normalization the read walk, the
+ * public append, and the import-validate door all use (the {@link normalizeAnnouncedListing}
+ * posture). Returns a shaped copy carrying ONLY the known keys, or undefined when the value is not
+ * structurally valid: closed kind set, full `sha256:<hex64>` hash grammar (a prefix-only check
+ * would accept junk), bounded entryId, `pending` only as literal `true`.
+ */
+export declare function normalizeGitAnnouncement(v: unknown): GitAnnouncementState | undefined;
 /** Bounded cap for {@link normalizeWorkspaceState} paths (a sha is capped by its hex shape check). */
 export declare const WORKSPACE_STATE_MAX_PATH_CHARS = 4096;
 /**
@@ -544,7 +591,7 @@ export declare function normalizeAnnouncedListing(v: unknown): {
     models?: string[];
 } | undefined;
 /** All persisted session tree entry variants. */
-export type SessionTreeEntry = MessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | CompactionEntry | CustomEntry | CustomMessageEntry | LabelEntry | SessionInfoEntry | LeafEntry | PromptEpochEntry | AnnouncedListingEntry | WorkspaceStateEntry;
+export type SessionTreeEntry = MessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | CompactionEntry | CustomEntry | CustomMessageEntry | LabelEntry | SessionInfoEntry | LeafEntry | PromptEpochEntry | AnnouncedListingEntry | GitAnnouncementEntry | WorkspaceStateEntry;
 export interface SessionContext {
     messages: AgentMessage[];
     thinkingLevel: string;
@@ -684,6 +731,23 @@ export interface Session<TMetadata extends SessionMetadata = SessionMetadata> {
      *  epoch restatement) calls it with `?.()` — an implementer without it degrades to the pre-epoch
      *  path (no restatement), never a crash. */
     getPromptEpoch?(): Promise<import("../../prompt-assembly/epoch.js").PromptEpochDescriptor | undefined>;
+    /** Persist the git-status announced state as a first-class {@link GitAnnouncementEntry}
+     *  (snapshot semantics; see `Session.appendGitAnnouncement`). OPTIONAL on the interface — same
+     *  external-implementer posture as `getPromptEpoch`; consumers call it with `?.()` and an
+     *  implementer without it degrades to conservative re-announcement every leg (duplicate-tolerant
+     *  by design), never a crash. */
+    appendGitAnnouncement?(state: GitAnnouncementState): Promise<string>;
+    /** Branch-authority read of the git announced state (see `Session.getGitAnnouncement`): nearest
+     *  carrier on the active branch, with a pending restatement — or an announced state whose frame
+     *  entryId is NOT on the active branch — surfaced as `status:"pending"` (the reader must
+     *  conservatively re-announce). Undefined ⇒ no carrier visible on this branch. OPTIONAL, same
+     *  posture as `appendGitAnnouncement`. */
+    getGitAnnouncement?(): Promise<{
+        kind: GitAnnouncementKind;
+        hash: string;
+        status: "announced" | "pending";
+        entryId?: string;
+    } | undefined>;
 }
 export interface SessionCreateOptions {
     id?: string;

package/dist/engine/harness/types.js

@@ -66,6 +66,26 @@ export class AgentHarnessError extends Error {
         this.code = code;
     }
 }
+export const GIT_ANNOUNCEMENT_MAX_ENTRY_ID_CHARS = 256;
+export function normalizeGitAnnouncement(v) {
+    if (typeof v !== "object" || v === null)
+        return undefined;
+    const src = v;
+    if (src.kind !== "full" && src.kind !== "degraded" && src.kind !== "unavailable" && src.kind !== "non-repo")
+        return undefined;
+    if (typeof src.hash !== "string" || !/^sha256:[0-9a-f]{64}$/.test(src.hash))
+        return undefined;
+    if (src.entryId !== undefined && (typeof src.entryId !== "string" || src.entryId.length === 0 || src.entryId.length > GIT_ANNOUNCEMENT_MAX_ENTRY_ID_CHARS))
+        return undefined;
+    if (src.pending !== undefined && src.pending !== true)
+        return undefined;
+    return {
+        kind: src.kind,
+        hash: src.hash,
+        ...(src.entryId !== undefined ? { entryId: src.entryId } : {}),
+        ...(src.pending === true ? { pending: true } : {}),
+    };
+}
 export const WORKSPACE_STATE_MAX_PATH_CHARS = 4096;
 export function normalizeWorkspaceState(value) {
     if (value === null || typeof value !== "object")

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

@@ -1,4 +1,4 @@
-import { SessionError, normalizeAnnouncedListing, normalizeWorkspaceState, normalizeCompactionStateCarrier, isValidThinkingLevelChange, isValidModelChange, isOptionalDisplayString, } from "../harness/types.js";
+import { SessionError, normalizeAnnouncedListing, normalizeGitAnnouncement, normalizeWorkspaceState, normalizeCompactionStateCarrier, isValidThinkingLevelChange, isValidModelChange, isOptionalDisplayString, } from "../harness/types.js";
 import { leafIdAfterEntry } from "./storage-base.js";
 import { parseSessionTimestampMs } from "./timestamps.js";
 import { flattenableUserText, normalizeEngineSegments } from "../../core/untrusted-text.js";
@@ -87,6 +87,11 @@ export class StreamingImportValidator {
                 throw new SessionError("invalid_session", `workspace_state entry "${e.id}" is structurally invalid`);
             }
         }
+        else if (e.type === "git_announcement") {
+            if (!normalizeGitAnnouncement(e)) {
+                throw new SessionError("invalid_session", `git_announcement entry "${e.id}" is structurally invalid`);
+            }
+        }
         if (e.type === "thinking_level_change" && !isValidThinkingLevelChange(e)) {
             throw new SessionError("invalid_session", `thinking_level_change entry "${e.id}" carries an invalid thinkingLevel`);
         }
@@ -119,6 +124,10 @@ export class StreamingImportValidator {
             if (restatedListings !== undefined && !normalizeAnnouncedListing(restatedListings)) {
                 throw new SessionError("invalid_session", `compaction "${e.id}" carries a structurally invalid announcedListings restatement`);
             }
+            const restatedGit = e.details?.gitAnnouncement;
+            if (restatedGit !== undefined && !normalizeGitAnnouncement(restatedGit)) {
+                throw new SessionError("invalid_session", `compaction "${e.id}" carries a structurally invalid gitAnnouncement restatement`);
+            }
             const carrier = e.details;
             const shaped = normalizeCompactionStateCarrier(e.details);
             if (carrier?.thinkingLevel !== undefined && shaped.thinkingLevel === undefined) {