@signalridge/pi-workflows 1.7.4 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.8.0
+### Minor Changes
+
+- c2fd867: Buffer and coalesce completed workflow notifications until an owned session is safely idle. Persist context-only results and confirm them on the active branch before acknowledging pending markers, then wake through the ordinary user-message preparation hooks. Fence delivery and admission synchronously at bus-first shutdown and cancel stale handoffs on committed navigation. Validate private, bounded one-use wake admissions at input consumption to reject retired notifications held by earlier async input hooks, with internal command/template expansion disabled.
+  
+  Move keyword arming and standing effort guidance into hidden, turn-local model messages without appending raw reminders to native user text. Preserve queued follow-up and steering guidance through a bounded public context overlay, without changing native persistence, fork selection or editor history. Distinguish standing effort permission from an explicit keyword instead of inventing a user trigger. Preserve images and unrelated reminders, exclude synthetic input, and deny ambiguous or stale preparation admissions. Add real SDK/faux-provider and native user-component regressions for clean rendering, provider guidance, queued and consumed input, overlapping prompts, navigation and reload. The fix applies after updating/reloading the extension; previously persisted tagged user history is not rewritten. Idle and queued arming now use request-local overlays only, preserve repeated literal directive strings verbatim, and remove only legacy extension-owned hidden guidance from public summarization/compaction preparation.
+  
+  Move workflow-authored JavaScript and VM-created callbacks into an owned, plain-JavaScript Node helper while retaining runtime policy, dispatch, state, scheduling, journals, and managed cleanup in the parent. Bound initial evaluation and asynchronous/callback CPU stalls with a local heartbeat, startup deadline, memory/IPC/log limits, and actual-handle TERM/KILL/close ownership. Legitimate agent awaits continue heartbeats; Bun/compiled hosts require Node on PATH and debugger flags remain inherited. Preserve callback error classification, intermediate JS values, synchronous phase/log, shared budgets, replay and one-level nested execution; final results return their validated JSON projection. Drain all accepted native RPC operations and nested frames before helper/frame success, separating callback response settlement from reference-counted execution-context lifetime through accepted RPC descendant chains and cancelling/confirming owned work on failure. Track actual unresolved local promise lifetimes while the root is running, including descendants whose first native call follows a locally suspended promise and a later root-native await. Release completed contexts event-by-event after promise settlement and native response publication, retaining the original parent async-local budget/control attribution without reopening root admission or accepting retired/foreign identities. At root result retire local-only continuations before publication; only accepted native work and its unsettled callbacks retain descendant authority, so ignored pure-JavaScript awaits do not hang successful teardown. Bound live contexts and tracked promises separately from pending callbacks, recycle sequential contexts, and clean them at frame teardown. Add exact delayed-first-RPC, nested private-budget/control, local-only post-root rejection, retained-context capacity, ignored-promise success, and cancellation/native-cleanup/helper-close regressions. Observe ignored native RPC rejections without replacing author promises. Reconstruct intermediate snapshots with workflow-realm built-ins and standard error subclasses, retaining original callback closures. Grant parent-lag watchdog grace only after actual heartbeat progress, with one bounded I/O turn. Keep transient journal retries in accepted-fact order and drain them before terminal success so restored calls cannot regress to running. Add disposable strict-Node regressions for forgotten nested/control helpers, infinite-await cancellation, realm identity, ignored rejections and repeated parent stalls, plus terminal checkpoint/timeout and smoke-equivalent journal recovery. This is not an OS sandbox or a protocol change.
+  
+  Apply journaled terminal recovery before accepted failed-run resume, give checkpoints local attempt identity, record timeout terminal failure after exact-owner quiescence, and union run/per-call tool denials. Rearm owned delivery for every background resume, record per-run batch membership across partial ACK failures, and clear retired provider errors on restart. Sanitize display copies through pi-ui and bound detail viewports while keeping controls reachable. Add disposable-process external-deadline regressions for CPU loops, replay/schema/nesting/cancel/long-await, Node/Bun startup and debugger pause, alongside real SDK summary/compaction and viewport tests.
+
+### Patch Changes
+
+- Updated dependencies [c2fd867]
+  - @signalridge/pi-ui@1.4.0
+
+## 1.7.5
+### Patch Changes
+
+- 3364cc0: Declare `@sinclair/typebox` as a host-provided peer dependency with a `*` range instead of a runtime dependency, avoiding duplicate runtime modules and Pi extension-loader warnings.
+- 3364cc0: Adopt Pi 1.0.4's host-provided dependency contract: declare imported Pi and TypeBox modules as `*` peers rather than installing duplicate runtime modules, and align Pi development pins with the repository's tested 1.0.4 baseline. The wildcard identifies host module ownership; it does not promise compatibility with every Pi version.
+- 3364cc0: Bind code-review discovery and workflow executions (including resumes and nested scripts) to the session working directory. Preserve structured user content when deduplicating the workflow directive.
+- Updated dependencies [3364cc0]
+- Updated dependencies [3364cc0]
+  - @signalridge/pi-subagents-protocol@1.5.1
+
 ## 1.7.4
 ### Patch Changes
 

package/README.md

@@ -1,7 +1,7 @@
 # @signalridge/pi-workflows
 
 JavaScript orchestration for Pi. A workflow is a raw JavaScript module executed
-in a determinism-guarded `node:vm` realm; the runtime supplies `agent()`,
+in a determinism-guarded `node:vm` realm inside an owned Node helper; the runtime supplies `agent()`,
 `parallel()`, `pipeline()`, `orchestrate()`, `workflow()`, quality helpers (`verify`,
 `judgePanel`, `loopUntilDry`, `completenessCheck`, `retry`, `gate`), human
 `checkpoint()`, `phase()`, `log()`, `args`, `cwd`, restricted `process`, and
@@ -40,6 +40,52 @@ registration.
 
 Pi activates each package from its own `pi.extensions` manifest.
 
+### JavaScript execution boundary
+
+Only workflow-authored JavaScript and its callbacks run in the helper. Agent
+policy/dispatch, scheduling, limits, shared state, journals, and managed-child
+cleanup stay in the parent. Callback arguments cross bounded, validated IPC as
+opaque callback identities; the parent never executes workflow function objects.
+Nested saved workflows get their own helper frame, share the same parent-owned
+limits, and remain limited to one nested level. There are no new public globals,
+protocol changes, TypeScript helper loaders, or extra runtime dependencies.
+
+A Node host uses its Node executable. Bun or a compiled host requires `node` on
+PATH; missing Node fails with an actionable diagnostic. `NODE_OPTIONS` is inherited
+unchanged, including debugger flags. A helper that does not announce readiness
+within five seconds fails (including `--inspect-brk` awaiting a debugger).
+
+Initial synchronous evaluation retains its one-second VM guard. A local-process
+heartbeat detects JavaScript CPU stalls after awaits and in callbacks (including
+DAG, gate, retry, and loop callbacks); a stalled heartbeat fails after 1.5 seconds.
+This is not a wall-clock deadline for legitimate agent awaits, and never polls a
+model. Cancellation/failure closes the actual owned helper through TERM, KILL
+escalation after 250ms, and a bounded 1.5-second close wait. Managed children must
+still settle exact-owner cleanup before terminal publication or resumability; a
+cleanup failure is fenced, not claimed as success. A returned value closes new
+root-call admission but drains every accepted native operation and nested frame
+before success; callbacks needed by those operations remain available. Infinite
+awaits in forgotten helpers still require cancellation. Ignored native RPC promises
+are observed without changing their awaited/caught values or helper error policy.
+Repeated parent event-loop lag earns only one I/O turn per actual heartbeat advance,
+never a synthetic heartbeat or an indefinitely renewed stall exemption.
+
+Helpers have a 128MiB V8 heap limit, 4MiB IPC message limit, bounded 32MiB queued
+and retained request payloads, 8,192 callbacks/pending requests, 100,000 non-heartbeat
+messages, and intermediate value limits of 100,000 nodes/64 levels. Log entries
+are bounded to 64KiB characters and 1MiB total bytes per frame. Intermediate arrays,
+plain objects, maps, sets, dates, regexes, bigint values, registered callback
+references, and error names/classification cross IPC. Input and callback snapshots
+use the workflow realm's built-in constructors (including standard error subclasses),
+preserve cycles, array holes and undefined, and return registered callbacks to their
+original closures. Data transfers do not preserve arbitrary custom prototypes or
+cross-transfer object identity.
+VM-origin exceptions retain their provenance rather than acquiring native provider
+classification from words like "quota"; exception coercion stays in the helper.
+Final results must serialize to JSON and return their JSON projection. `phase()`
+and `log()` remain synchronous; budget reads mirror parent accounting at RPC replies.
+These bounds are guardrails for trusted scripts, **not an OS/security sandbox**.
+
 ## Writing a workflow
 
 A workflow script starts with the only legal export — a literal-only meta
@@ -84,9 +130,9 @@ user's own LLM and run on the user's own machine.
   plain JSON Schema; the reply is parsed and validated client-side with bounded
   repair across attempts, and exhaustion throws `SCHEMA_NONCOMPLIANCE`.
   `strength` is the provider-neutral workflow route; `thread` chains sequential turns
-  within a named conversation thread. A legacy programmatic `model` option may
-  still be accepted by non-managed callers, but workflow meta/phase model or
-  thinking fields are rejected and are never a workflow policy source. Pre-schema-v4
+  within a named conversation thread. Per-call `model`, `thinking`, and `tier`
+  options are rejected; workflow meta/phase model or thinking fields are also
+  rejected and are never a workflow policy source. Pre-schema-v4
   journal runs are quarantined and cannot be resumed.
 - `parallel(thunks)` — run thunks concurrently, preserve input order. Recoverable
   thunk failures become `null`; non-recoverable failures (token budget, agent
@@ -125,7 +171,13 @@ original invocation `args` and execution limits are frozen and reused on manual
 or automatic resume. Pass `resumeFromRunId` with the edited script; unchanged
 calls report zero tokens,
 and edited calls rotate their managed spawn key generation so pi-subagents
-never raises a fingerprint conflict.
+never raises a fingerprint conflict. A failed run accepted through
+`resumeFromRunId` first appends/applies a legal interrupted recovery after owned
+cleanup and journal settlement; terminal status is never mutated directly to
+running. Intentional stops and unconfirmed cleanup remain non-resumable. Local
+checkpoints journal attempt identity without inventing a managed child, and a
+timed-out call journals its terminal failure after quiescence before returning
+recoverable `null`.
 
 ## Skills
 
@@ -189,13 +241,63 @@ workflow, and the review skill before accepting a topology or recovery change.
   `session_start` (Pi cannot unregister commands, so registration happens there
   rather than at factory time, and existing commands are never overwritten).
 
+### Background result notifications
+
+Completed background runs are buffered in branch-local pending-delivery markers
+(up to 256, expiring after seven days). Notifications wait for an owned, idle
+session with no queued input, input preparation, compaction, or navigation in
+progress. A cancellable one-shot timer defers handoff out of the notification-only
+`agent_settled` handler and rechecks ownership and readiness; later handlers can navigate
+or compact without receiving an old result. Up to eight results are coalesced
+per notification, each preview bounded to 8,000 characters. There is no model
+polling or repeating delivery timer.
+
+Results first enter context as a `pi-workflows:delivery` custom message with
+`triggerTurn: false`. The active branch must actually contain that message before
+pending markers are acknowledged. Delivery details record individual run IDs,
+so a partial acknowledgement failure cannot resend an already persisted member
+of a batch. Every accepted background resume (tool, navigator, or provider timer)
+rearms its generation-owned observer; suspension is not final delivery.
+Pi's void `sendMessage` return is not an
+acceptance promise. A short `sendUserMessage` notification then uses the normal
+input and `before_agent_start` path, so prompt preparation hooks still run.
+Internal wakes disable command/template expansion and carry private, unique,
+one-use admission tokens (at most 256 in memory). Our input hook checks the
+original generation, engine, context, and branch ownership before accepting a
+wake and removes its token from model-facing text. If an earlier input hook
+awaits while navigation or shutdown retires the owner, the obsolete
+extension-sourced wake is handled without starting a turn. Interactive/RPC
+input and other extensions' messages are not consumed by this guard.
+
+This is a handoff check, not a navigation lock: public hooks cannot fence an
+arbitrary later async input or preparation handler that navigates after our
+input hook has accepted the wake. Earlier transforms must preserve the private
+token until this check; a hook that removes it also removes its ownership evidence.
+
+Unacknowledged markers recover from the active branch on session start or tree
+commit; siblings never inherit abandoned-branch results. A blocked or failed
+handoff waits for a later lifecycle boundary, not a retry loop. If input or
+navigation is abandoned without a completion event, delivery stays conservative
+until a fresh prompt (and its eventual settlement) or session/tree rebind.
+
+Shutdown immediately retires both admission and delivery before aborting the
+engine, including a peer's bus-first shutdown handshake. Cleanup retains the
+outgoing journal until native shutdown finishes; late results cannot wake the
+retiring session.
+
 ### Keyword arming
 
 Typing the bounded word `workflow` or `workflows` in an ordinary message counts
-as an explicit opt-in to multi-agent orchestration: the message is annotated to
-tell the model the `workflow` tool is authorized for this turn.
-
-Arming **authorizes; it does not compel**. The annotation says the model may run
+as an explicit opt-in to multi-agent orchestration. A request-local hidden
+`context` overlay tells the model the `workflow` tool is authorized for this turn;
+`before_agent_start` admits idle guidance but persists nothing. Keyword and standing
+`/effort high|ultra` guidance never append reminders or effort text to native user
+messages. Original text/images remain exact, even repeated literal copies of either
+directive; only extension-owned custom guidance is filtered/rebuilt. Legacy owned
+hidden arming entries are excluded from public branch-summary/compaction preparation,
+without rewriting historical user text or stored entries.
+
+Arming **authorizes; it does not compel**. The hidden guidance says the model may run
 a workflow and may still decline, so "how do workflows work?" stays an ordinary
 question with an ordinary answer. Nothing is swallowed and no UI opens.
 This is **model guidance, not an execution permission gate**: the extension does
@@ -211,6 +313,39 @@ sentence-ending dot is not a filename dot: "please run a workflow." arms, and
 <word>` (matched exactly — only the default word also matches its plural) or
 turn it off entirely with `/workflows-trigger off`.
 
+Only observed interactive/RPC input can arm a turn; extension-sourced
+notifications cannot. Idle admission is one-use and requires unchanged prompt
+text, images, session and leaf. Queued follow-up and steering input can also arm:
+Pi continues them without a fresh `before_agent_start`, so one bounded queued
+admission binds to its public `message_start` and a unique persisted user entry
+on the owning branch. The public `context` hook adds a model-only overlay; it
+never enters native history. Both paths retire guidance after settlement,
+navigation or reload. Standing `/effort high|ultra` permission identifies the
+standing setting, not a keyword the user did not type.
+
+Pi's public preparation event has no input source/request ID, and chained input
+handlers have no public post-`handled` notification. Overlapping or unmatched
+input is therefore denied rather than transferring authorization to another
+prompt, even if the text is identical. Multiple unresolved queued observations
+are ambiguous and suppress queued guidance until settlement. A consumed idle
+prompt may similarly suppress arming on the next ordinary turn. Template
+expansion, later text/image transforms, or non-unique native-message evidence
+also fail closed. These limits affect advisory guidance only, never direct tool
+authorization.
+
+The fix applies to **new messages after updating and reloading the extension**;
+source changes do not update an already installed/running package. Previously
+persisted user messages containing raw reminders remain unchanged. Pi's public
+UI API does not provide a history rewrite: those messages can still appear in
+the native TUI, fork selector or editor history. No private renderer patch or
+generic reminder stripping is used. Regression tests exercise the real SDK,
+faux provider, and native user-message component, not a physical terminal or a
+live model service.
+
+Navigator/result metadata is sanitized only in display copies through `pi-ui`;
+stored results and journals stay original. Detail screens keep actions reachable
+in a row-bounded viewport; PgUp/PgDn scroll the detail independently of ↑↓ actions.
+
 Saved workflows use project scope first and a user scope fallback; writes are atomic and names are path-safe.
 
 ## Model routing
@@ -396,4 +531,4 @@ used it.
 - **Agent registry and tier catalogue ownership.** `agentType` and the tier catalogue resolve in pi-subagents; the workflow package supplies only a tier key its own `strengths` table chose, avoiding a second model/thinking policy.
 - **Schema validation is client-side.** The managed request does not assume a structured-output tool; the runtime asks for JSON, parses, validates (including `additionalProperties`), and repairs across bounded attempts.
 
-State is persisted as `pi.appendEntry("pi-workflows:journal", ...)` custom entries (schema v4), including frozen invocation args, resolved tier identity, terminal result previews, script revisions, named nested-workflow result boundaries, and durable removals. Interrupted/provider-limited runs replay from the journal; pre-schema-v4 journals are quarantined rather than replayed. Foreground `AbortSignal`s stop owned children through explicit owner-scoped stop/quiescence, and dispose/branch replacement reject stale waiters. For tree navigation, bus and native pre-tree notifications share quiescence within one host signal; a later attempt rechecks runs started since a veto, after any earlier cleanup settles. This only prevents reuse of stale quiescence: Pi does not provide a post-veto, precommit hook, so the initial canceled attempt can still interrupt active runs. Hosts without a pre-tree signal retain legacy deduplication.
+State is persisted as `pi.appendEntry("pi-workflows:journal", ...)` custom entries (schema v4), including frozen invocation args, resolved tier identity, terminal result previews, script revisions, named nested-workflow result boundaries, and durable removals. Interrupted/provider-limited runs replay from the journal; pre-schema-v4 journals are quarantined rather than replayed. Foreground `AbortSignal`s stop owned children through explicit owner-scoped stop/quiescence, and dispose/branch replacement reject stale waiters. Navigation preflight vetoes while agents or workflows are active or cleaning up, without interrupting them. An accepted tree commit fences old callbacks in either extension load order and restores only the committed branch; preflight itself is not a commit point.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-workflows",
-  "version": "1.7.4",
+  "version": "1.8.0",
   "description": "Deterministic JavaScript orchestration workflows backed by pi-subagents managed spawning.",
   "type": "module",
   "license": "MIT",
@@ -15,13 +15,14 @@
     "lifecycle": "stable"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.0 || ^0.85.0 || ^0.86.0 || ^0.87.0 || ^0.99.1",
-    "@earendil-works/pi-tui": "^0.84.0 || ^0.85.0 || ^0.86.0 || ^0.87.0 || ^0.99.1",
-    "@signalridge/pi-subagents": ">=1.9.0"
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@signalridge/pi-subagents": ">=1.9.0",
+    "@sinclair/typebox": "*"
   },
   "dependencies": {
-    "@signalridge/pi-subagents-protocol": "^1.5.0",
-    "@sinclair/typebox": "^0.34.50",
+    "@signalridge/pi-subagents-protocol": "^1.5.1",
+    "@signalridge/pi-ui": "^1.4.0",
     "acorn": "^8.16.0"
   },
   "pi": {

package/skills/workflow-authoring/SKILL.md

@@ -2,7 +2,7 @@
 name: workflow-authoring
 description: Design, write, review, and debug Pi JavaScript workflows that coordinate multiple subagents. Use when a request needs named dependencies, bounded fan-out, per-item pipelines, quality gates, saved or nested workflows, pause/resume, or workflow progress; do not use it merely to run an existing named workflow.
 metadata:
-  version: "1.7.4"
+  version: "1.8.0"
 ---
 
 # Workflow authoring

package/skills/workflow-authoring/references/capabilities.md

@@ -2,7 +2,7 @@
 # Workflow capability index
 
 Contract format: `2.0.0`<br>
-Contract content / skill / extension: `1.7.4`
+Contract content / skill / extension: `1.8.0`
 
 This compact generated index covers supported runtime globals and workflow-tool inputs. For constraints, compatibility behavior, internal boundaries, and dynamic-reference ownership, follow the [exhaustive generated facts](capability-details.md).
 

package/skills/workflow-authoring/references/capability-details.md

@@ -2,7 +2,7 @@
 # Exhaustive workflow capability facts
 
 Contract format: `2.0.0`<br>
-Contract content / skill / extension: `1.7.4`
+Contract content / skill / extension: `1.8.0`
 
 Every exact fact below is projected from the installed extension's capability contract. Explanatory judgment belongs in the hand-written references next to this file.
 

package/skills/workflow-patterns/SKILL.md

@@ -2,7 +2,7 @@
 name: workflow-patterns
 description: Choose and run one of Pi's built-in multi-agent workflows for research, adversarial review, code review, multi-perspective analysis, or codebase auditing. Use when the request matches a named pattern; use workflow-authoring instead for a new script or custom topology.
 metadata:
-  version: "1.7.4"
+  version: "1.8.0"
 ---
 
 # Built-in workflow patterns

package/skills/workflow-review/SKILL.md

@@ -2,7 +2,7 @@
 name: workflow-review
 description: Audit an existing Pi JavaScript workflow for topology, prompt/data flow, limits, failure handling, cancellation, resume safety, and publication compatibility. Use when reviewing or debugging a workflow script or saved run; do not use to run a standard named workflow.
 metadata:
-  version: "1.7.4"
+  version: "1.8.0"
 ---
 
 # Workflow review

package/src/arming.ts

@@ -1,10 +1,19 @@
+import { createHash, randomUUID } from "node:crypto";
+import type {
+  BeforeAgentStartEvent,
+  ContextEvent,
+  ExtensionContext,
+  InputEvent,
+  MessageStartEvent,
+} from "@earendil-works/pi-coding-agent";
+
 /**
  * arming.ts — a keyword that tells the model a workflow is appropriate this turn.
  * It is advisory prompt guidance, not an execution-time permission gate.
  *
  * Typing the bounded word `workflow` (or `workflows`, or a configured synonym)
  * in an ordinary message is an explicit opt-in to multi-agent orchestration, so
- * the message is annotated to tell the model the tool is available for this
+ * hidden model context tells the model the tool is available for this
  * turn. Two properties matter, and both are easy to get wrong:
  *
  *  1. **Arming authorizes; it does not compel.** The directive says the model
@@ -23,14 +32,20 @@
 export const DEFAULT_TRIGGER_WORD = "workflow";
 
 /**
- * Appended to an armed message. Phrased as permission with an explicit escape
+ * Hidden guidance for an armed turn. Phrased as permission with an explicit escape
  * hatch: the model is told the user opted in, and told it may still answer
  * directly when a workflow would be overkill.
  */
 export const WORKFLOW_ARMED_DIRECTIVE =
   "<system-reminder>You typed the workflow trigger word, which counts as an explicit opt-in to multi-agent orchestration: the `workflow` tool is authorized for this turn. It runs in the background by default — the turn ends and the result is delivered back into the conversation when it finishes, which is expected rather than a stall, so you need not stay and block. Pass background:false only when the user is waiting for the result inline. This is permission, not an instruction: if the request is conversational, trivial, or better answered directly, answer it directly and do not run a workflow.</system-reminder>";
 
-/** Keep one copy when an earlier input transform already added this directive. */
+/** Standing effort is permission, but does not imply the user typed a keyword. */
+export const WORKFLOW_EFFORT_ARMED_DIRECTIVE = WORKFLOW_ARMED_DIRECTIVE.replace(
+  "You typed the workflow trigger word, which counts as an explicit opt-in to multi-agent orchestration:",
+  "The standing /effort setting permits multi-agent orchestration:",
+);
+
+/** Legacy explicit-call helper. Never apply it to native user text or context. */
 export function deduplicateWorkflowDirective(text: string): string {
   let seen = false;
   return text.replaceAll(WORKFLOW_ARMED_DIRECTIVE, (directive) => {
@@ -78,3 +93,249 @@ function triggerRegex(word: string): RegExp {
 export function hasTriggerWord(text: string, configuredWord?: string): boolean {
   return triggerRegex(configuredWord ?? DEFAULT_TRIGGER_WORD).test(text);
 }
+
+export const WORKFLOW_ARMING_MESSAGE_TYPE = "pi-workflows:turn-arming";
+
+function effortDirective(level: "off" | "high" | "ultra"): string {
+  return level === "ultra"
+    ? 'Effort: ULTRA. Be exhaustive: use broad parallel review, verification, and completeness checks. Width is where the exhaustiveness goes: keep steps at strength: "medium" and reserve "high" for a step whose error is expensive to reverse, if the run has one at all.'
+    : level === "high"
+      ? "Effort: HIGH. Be thorough: use several independent reviewers and an adversarial verification pass."
+      : "";
+}
+
+type NativeUserMessage = Extract<ContextEvent["messages"][number], { role: "user" }>;
+
+function userText(message: NativeUserMessage): string {
+  return typeof message.content === "string"
+    ? message.content
+    : message.content
+        .filter((part) => part.type === "text")
+        .map((part) => part.text)
+        .join("\n");
+}
+
+function inputKey(text: string, images: InputEvent["images"]): string {
+  return createHash("sha256")
+    .update(JSON.stringify([text, (images ?? []).map((image) => [image.mimeType, image.data])]))
+    .digest("hex");
+}
+
+function nativeKey(message: NativeUserMessage): string {
+  return inputKey(
+    userText(message),
+    typeof message.content === "string" ? [] : message.content.filter((part) => part.type === "image"),
+  );
+}
+
+type NativeUserIdentity = { key: string; timestamp: number };
+
+function nativeIdentity(message: NativeUserMessage): NativeUserIdentity {
+  return { key: nativeKey(message), timestamp: message.timestamp };
+}
+
+function sameNativeUser(left: NativeUserIdentity, right: ContextEvent["messages"][number]): boolean {
+  return right.role === "user" && right.timestamp === left.timestamp && nativeKey(right) === left.key;
+}
+
+/**
+ * Public before_agent_start has no source or input ID. Admit only one observed,
+ * idle ordinary input, with unchanged text/images/session/leaf. Chained handled
+ * input has no public completion event: an unmatched observation makes a later
+ * overlapping ordinary input ambiguous rather than transferring its permission.
+ * Extension input replaces permission with a denied observation; settlement
+ * and navigation retire all observations. Queued input instead binds one bounded
+ * admission to a public user message_start, then adds only model context. Multiple
+ * unresolved queue admissions are ambiguous. Expanded/transformed input fails
+ * closed, and no path changes native history.
+ */
+export class WorkflowTurnArming {
+  private pending:
+    | {
+        text: string;
+        images: string;
+        sessionId: string;
+        leaf: string | null;
+        content?: string;
+      }
+    | undefined;
+  private ambiguous = false;
+  private current:
+    | {
+        id: string;
+        key: string;
+        message?: NativeUserIdentity;
+        sessionId: string;
+        anchor: string | null;
+        content: string;
+      }
+    | undefined;
+  // One unresolved queued observation is enough. Do not accumulate large input
+  // bodies or infer ownership when later handlers consume/reorder/transform them.
+  private queued: { key: string; sessionId: string; anchor: string | null; content?: string } | undefined;
+  private queuedAmbiguous = false;
+  private queuedCurrent:
+    | { id: string; message: NativeUserIdentity; sessionId: string; anchor: string | null; content: string }
+    | undefined;
+
+  retire(): void {
+    this.pending = undefined;
+    this.current = undefined;
+    this.ambiguous = false;
+    this.queued = undefined;
+    this.queuedCurrent = undefined;
+    this.queuedAmbiguous = false;
+  }
+
+  observe(
+    event: InputEvent,
+    ctx: ExtensionContext,
+    armed: boolean,
+    effort: "off" | "high" | "ultra",
+    explicitTrigger = true,
+  ): void {
+    const ordinary = event.source === "interactive" || event.source === "rpc";
+    const directive = explicitTrigger ? WORKFLOW_ARMED_DIRECTIVE : WORKFLOW_EFFORT_ARMED_DIRECTIVE;
+    const content = ordinary && armed ? [directive, effortDirective(effort)].filter(Boolean).join("\n") : undefined;
+    if (event.streamingBehavior === "steer" || event.streamingBehavior === "followUp") {
+      this.queuedAmbiguous ||= this.queued !== undefined || this.pending !== undefined || this.ambiguous;
+      this.queued = undefined;
+      try {
+        if (this.queuedAmbiguous || ctx.isIdle() || event.text.trim().startsWith("/")) return;
+        this.queued = {
+          key: inputKey(event.text, event.images ?? []),
+          sessionId: ctx.sessionManager.getSessionId(),
+          anchor: ctx.sessionManager.getLeafId(),
+          content,
+        };
+      } catch {
+        this.queuedAmbiguous = true;
+      }
+      return;
+    }
+    this.ambiguous ||= this.queued !== undefined || this.queuedAmbiguous;
+    this.queued = undefined;
+    this.queuedCurrent = undefined;
+    this.ambiguous ||= this.pending !== undefined || this.current !== undefined;
+    this.current = undefined;
+    this.pending = undefined;
+    try {
+      if (!ctx.isIdle() || event.text.trim().startsWith("/")) return;
+      this.pending = {
+        text: event.text,
+        images: inputKey("", event.images),
+        sessionId: ctx.sessionManager.getSessionId(),
+        leaf: ctx.sessionManager.getLeafId(),
+        content,
+      };
+    } catch {
+      this.pending = undefined;
+      this.ambiguous = true; // No public ownership evidence, no arming until settlement.
+    }
+  }
+
+  consume(event: BeforeAgentStartEvent, ctx: ExtensionContext): void {
+    const pending = this.pending;
+    const ambiguous = this.ambiguous;
+    this.pending = undefined; // one-use, also for mismatched/consumed prompts
+    this.current = undefined;
+    try {
+      if (
+        ambiguous ||
+        !pending?.content ||
+        !ctx.isIdle() ||
+        event.prompt !== pending.text ||
+        inputKey("", event.images) !== pending.images ||
+        ctx.sessionManager.getSessionId() !== pending.sessionId ||
+        ctx.sessionManager.getLeafId() !== pending.leaf
+      )
+        return;
+      const id = randomUUID();
+      this.current = {
+        id,
+        key: inputKey(event.prompt, event.images ?? []),
+        sessionId: pending.sessionId,
+        anchor: pending.leaf,
+        content: pending.content,
+      };
+    } catch {
+      this.retire();
+      return;
+    }
+  }
+
+  messageStarted(event: MessageStartEvent, ctx: ExtensionContext): void {
+    if (event.message.role !== "user") return;
+    const message = event.message;
+    // The ordinary first message follows its own before_agent_start admission.
+    if (this.current && !this.current.message && nativeKey(message) === this.current.key) {
+      this.current.message = nativeIdentity(message);
+      return;
+    }
+    this.current = undefined;
+    this.queuedCurrent = undefined;
+    const queued = this.queued;
+    this.queued = undefined; // one-use, even for an unmatched/synthetic message
+    try {
+      if (
+        this.queuedAmbiguous ||
+        !queued?.content ||
+        queued.key !== nativeKey(message) ||
+        queued.sessionId !== ctx.sessionManager.getSessionId() ||
+        (queued.anchor !== null && !ctx.sessionManager.getBranch().some((entry) => entry.id === queued.anchor))
+      )
+        return;
+      this.queuedCurrent = {
+        id: randomUUID(),
+        message: nativeIdentity(message),
+        sessionId: queued.sessionId,
+        anchor: queued.anchor,
+        content: queued.content,
+      };
+    } catch {
+      this.queuedAmbiguous = true;
+    }
+  }
+
+  filterContext(event: ContextEvent, ctx: ExtensionContext): { messages: ContextEvent["messages"] } | undefined {
+    const lastUser = [...event.messages].reverse().find((message) => message.role === "user");
+    // Only extension-owned messages are removed. User content is opaque, even
+    // when it quotes our directive verbatim. Rebuild a single request-local copy.
+    const messages = event.messages.filter(
+      (message) => message.role !== "custom" || message.customType !== WORKFLOW_ARMING_MESSAGE_TYPE,
+    );
+    const queued = this.queuedCurrent ?? this.current;
+    const identity = queued?.message;
+    let injected = false;
+    try {
+      // Public context dispatch clones messages. Match the emitted timestamp and
+      // content against a UNIQUE native entry on this branch and in model context;
+      // equal-text collisions or transformations must not transfer permission.
+      if (
+        queued &&
+        identity &&
+        lastUser &&
+        sameNativeUser(identity, lastUser) &&
+        event.messages.filter((message) => sameNativeUser(identity, message)).length === 1 &&
+        queued.sessionId === ctx.sessionManager.getSessionId() &&
+        ctx.sessionManager
+          .getBranch()
+          .filter((entry) => entry.type === "message" && sameNativeUser(identity, entry.message)).length === 1 &&
+        (queued.anchor === null || ctx.sessionManager.getBranch().some((entry) => entry.id === queued.anchor))
+      ) {
+        injected = true;
+        messages.push({
+          role: "custom",
+          customType: WORKFLOW_ARMING_MESSAGE_TYPE,
+          content: queued.content,
+          display: false,
+          details: { id: queued.id },
+          timestamp: identity.timestamp,
+        });
+      }
+    } catch {
+      this.queuedCurrent = undefined;
+    }
+    return injected || messages.length !== event.messages.length ? { messages } : undefined;
+  }
+}