@tt-a1i/openpi 0.1.0 → 0.2.0

package/extensions/workflows/invocation-ledger.ts

@@ -0,0 +1,368 @@
+export interface InvocationIdentity {
+  readonly runId: string;
+  readonly callIndex: number;
+}
+
+export type InvocationIntentState = "requested";
+export type InvocationAdmissionState =
+  | "pending"
+  | "claimed"
+  | "replayed"
+  | "rejected";
+export type InvocationExecutionState =
+  | "pending"
+  | "running"
+  | "settled"
+  | "uncertain";
+export type InvocationOutcome = "success" | "error" | "uncertain";
+
+/**
+ * Three-plane durable lifecycle for one workflow call.
+ *
+ * Intent says what the script requested, admission says whether the host
+ * accepted or replayed it, and execution says what the child runtime actually
+ * proved. Keeping them separate prevents a persisted `running` label from
+ * pretending that an interrupted side effect is known to have failed.
+ */
+export interface InvocationRecord {
+  readonly identity: InvocationIdentity;
+  readonly intentState: InvocationIntentState;
+  readonly admissionState: InvocationAdmissionState;
+  readonly executionState: InvocationExecutionState;
+  readonly outcome?: InvocationOutcome;
+  readonly requestedAt: number;
+  readonly claimedAt?: number;
+  readonly runningAt?: number;
+  readonly terminalAt?: number;
+}
+
+export type InvocationTransition =
+  | { readonly status: "claimed"; readonly at: number }
+  | { readonly status: "running"; readonly at: number }
+  | {
+      readonly status: "settled";
+      readonly outcome: "success" | "error";
+      readonly at: number;
+    }
+  | { readonly status: "replayed"; readonly at: number }
+  | { readonly status: "rejected"; readonly at: number };
+
+const ADMISSION_STATES: readonly InvocationAdmissionState[] = [
+  "pending",
+  "claimed",
+  "replayed",
+  "rejected",
+];
+const EXECUTION_STATES: readonly InvocationExecutionState[] = [
+  "pending",
+  "running",
+  "settled",
+  "uncertain",
+];
+
+function assertIdentity(identity: InvocationIdentity) {
+  if (typeof identity.runId !== "string" || identity.runId.trim() === "") {
+    throw new Error("runId must be a nonblank string");
+  }
+  if (!Number.isSafeInteger(identity.callIndex) || identity.callIndex <= 0) {
+    throw new Error("callIndex must be a positive safe integer");
+  }
+}
+
+function assertFinite(value: number | undefined, name: string) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`${name} must be finite`);
+  }
+  return value;
+}
+
+function immutableSnapshot(record: InvocationRecord) {
+  return Object.freeze({
+    ...record,
+    identity: Object.freeze({ ...record.identity }),
+  });
+}
+
+function lifecycleLabel(record: InvocationRecord) {
+  if (record.admissionState === "replayed") return "replayed";
+  if (record.admissionState === "rejected") return "rejected";
+  if (
+    record.executionState === "settled" ||
+    record.executionState === "uncertain"
+  ) {
+    return "settled";
+  }
+  if (record.executionState === "running") return "running";
+  if (record.admissionState === "claimed") return "claimed";
+  return "requested";
+}
+
+function assertRecord(record: InvocationRecord) {
+  assertIdentity(record.identity);
+  assertFinite(record.requestedAt, "requestedAt");
+  if (record.intentState !== "requested") {
+    throw new Error("Invalid invocation intent state");
+  }
+  if (!ADMISSION_STATES.includes(record.admissionState)) {
+    throw new Error("Invalid invocation admission state");
+  }
+  if (!EXECUTION_STATES.includes(record.executionState)) {
+    throw new Error("Invalid invocation execution state");
+  }
+  if (record.admissionState === "claimed") {
+    assertFinite(record.claimedAt, "claimedAt");
+  }
+  if (record.executionState === "running") {
+    assertFinite(record.runningAt, "runningAt");
+  }
+  if (
+    record.executionState === "settled" ||
+    record.executionState === "uncertain"
+  ) {
+    assertFinite(record.terminalAt, "terminalAt");
+  }
+  if (
+    record.admissionState === "replayed" &&
+    (record.executionState !== "settled" || record.outcome !== "success")
+  ) {
+    throw new Error("Invalid replayed invocation state");
+  }
+  if (
+    record.admissionState === "rejected" &&
+    (record.executionState !== "settled" || record.outcome !== "error")
+  ) {
+    throw new Error("Invalid rejected invocation state");
+  }
+  if (
+    record.admissionState === "pending" &&
+    record.executionState !== "pending" &&
+    record.executionState !== "uncertain"
+  ) {
+    throw new Error("Invalid pending invocation state");
+  }
+  if (
+    record.executionState === "settled" &&
+    record.outcome !== "success" &&
+    record.outcome !== "error"
+  ) {
+    throw new Error("Settled invocation requires a success or error outcome");
+  }
+  if (record.executionState === "uncertain" && record.outcome !== "uncertain") {
+    throw new Error("Uncertain invocation requires an uncertain outcome");
+  }
+  if (
+    (record.executionState === "pending" ||
+      record.executionState === "running") &&
+    record.outcome !== undefined
+  ) {
+    throw new Error("Nonterminal invocation cannot have an outcome");
+  }
+  if (
+    record.executionState !== "settled" &&
+    record.executionState !== "uncertain" &&
+    record.terminalAt !== undefined
+  ) {
+    throw new Error("Nonterminal invocation cannot have terminalAt");
+  }
+  if (record.admissionState !== "claimed" && record.claimedAt !== undefined) {
+    throw new Error("Only a claimed invocation can have claimedAt");
+  }
+  if (
+    record.runningAt !== undefined &&
+    (record.admissionState !== "claimed" ||
+      (record.executionState !== "running" &&
+        record.executionState !== "settled" &&
+        record.executionState !== "uncertain"))
+  ) {
+    throw new Error("Invalid runningAt for invocation state");
+  }
+  if (
+    record.admissionState === "claimed" &&
+    record.executionState === "settled" &&
+    record.runningAt === undefined
+  ) {
+    throw new Error("A normally settled invocation requires runningAt");
+  }
+
+  const timestamps = [
+    ["requestedAt", record.requestedAt],
+    ["claimedAt", record.claimedAt],
+    ["runningAt", record.runningAt],
+    ["terminalAt", record.terminalAt],
+  ] as const;
+  let previous = record.requestedAt;
+  for (const [name, timestamp] of timestamps.slice(1)) {
+    if (timestamp === undefined) continue;
+    assertFinite(timestamp, name);
+    if (timestamp < previous) {
+      throw new Error(`${name} cannot precede an earlier lifecycle timestamp`);
+    }
+    previous = timestamp;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Decode untrusted persisted data without inventing missing lifecycle facts. */
+export function decodeInvocationRecord(value: unknown) {
+  if (!isRecord(value) || !isRecord(value.identity)) return undefined;
+  const candidate = value as unknown as InvocationRecord;
+  try {
+    assertRecord(candidate);
+    return immutableSnapshot(candidate);
+  } catch {
+    return undefined;
+  }
+}
+
+function currentTransitionTime(record: InvocationRecord) {
+  if (record.terminalAt !== undefined) {
+    return {
+      name: "terminalAt",
+      at: assertFinite(record.terminalAt, "terminalAt"),
+    };
+  }
+  if (record.runningAt !== undefined) {
+    return {
+      name: "runningAt",
+      at: assertFinite(record.runningAt, "runningAt"),
+    };
+  }
+  if (record.claimedAt !== undefined) {
+    return {
+      name: "claimedAt",
+      at: assertFinite(record.claimedAt, "claimedAt"),
+    };
+  }
+  return { name: "requestedAt", at: record.requestedAt };
+}
+
+function assertChronology(record: InvocationRecord, at: number) {
+  assertFinite(at, "at");
+  const current = currentTransitionTime(record);
+  if (at < current.at) {
+    throw new Error(`Transition time cannot precede ${current.name}`);
+  }
+}
+
+function isLegalTransition(
+  record: InvocationRecord,
+  next: InvocationTransition["status"],
+) {
+  if (
+    record.admissionState === "pending" &&
+    record.executionState === "pending"
+  ) {
+    return next === "claimed" || next === "replayed" || next === "rejected";
+  }
+  if (
+    record.admissionState === "claimed" &&
+    record.executionState === "pending"
+  ) {
+    return next === "running";
+  }
+  if (
+    record.admissionState === "claimed" &&
+    record.executionState === "running"
+  ) {
+    return next === "settled";
+  }
+  return false;
+}
+
+/** Structured identity avoids ambiguous string concatenation of run and call. */
+export function createInvocationIdentity(runId: string, callIndex: number) {
+  const identity = { runId, callIndex };
+  assertIdentity(identity);
+  return Object.freeze(identity);
+}
+
+/** Start a call record without consulting a clock inside the ledger. */
+export function requestInvocation(identity: InvocationIdentity, at: number) {
+  assertIdentity(identity);
+  assertFinite(at, "at");
+  return immutableSnapshot({
+    identity,
+    intentState: "requested",
+    admissionState: "pending",
+    executionState: "pending",
+    requestedAt: at,
+  });
+}
+
+/** Apply one normal lifecycle or replay/rejection transition. */
+export function transitionInvocation(
+  record: InvocationRecord,
+  transition: InvocationTransition,
+) {
+  assertRecord(record);
+  if (!isLegalTransition(record, transition.status)) {
+    throw new Error(
+      `Illegal invocation transition: ${lifecycleLabel(record)} -> ${transition.status}`,
+    );
+  }
+  assertChronology(record, transition.at);
+
+  switch (transition.status) {
+    case "claimed":
+      return immutableSnapshot({
+        ...record,
+        admissionState: "claimed",
+        claimedAt: transition.at,
+      });
+    case "running":
+      return immutableSnapshot({
+        ...record,
+        executionState: "running",
+        runningAt: transition.at,
+      });
+    case "settled":
+      return immutableSnapshot({
+        ...record,
+        executionState: "settled",
+        outcome: transition.outcome,
+        terminalAt: transition.at,
+      });
+    case "replayed":
+      return immutableSnapshot({
+        ...record,
+        admissionState: "replayed",
+        executionState: "settled",
+        outcome: "success",
+        terminalAt: transition.at,
+      });
+    case "rejected":
+      return immutableSnapshot({
+        ...record,
+        admissionState: "rejected",
+        executionState: "settled",
+        outcome: "error",
+        terminalAt: transition.at,
+      });
+  }
+}
+
+/** Interrupt recovery is conservative: execution may have happened. */
+export function classifyInterruptedInvocation(
+  record: InvocationRecord,
+  at: number,
+) {
+  assertRecord(record);
+  if (
+    record.executionState === "settled" ||
+    record.executionState === "uncertain"
+  ) {
+    throw new Error(
+      `Cannot classify terminal invocation ${lifecycleLabel(record)} as uncertain`,
+    );
+  }
+  assertChronology(record, at);
+  return immutableSnapshot({
+    ...record,
+    executionState: "uncertain",
+    outcome: "uncertain",
+    terminalAt: at,
+  });
+}

package/extensions/workflows/model.ts

@@ -12,6 +12,12 @@ import { formatContextUtilization } from "../shared/context-utilization.ts";
 import { sanitizeTerminalText } from "../shared/terminal-text.ts";
 import type { WorktreeCleanup } from "../shared/worktree.ts";
 import type { AcceptanceLedger } from "./acceptance.ts";
+import {
+  projectWorkflowGraph,
+  type WorkflowGraphProjection,
+  type WorkflowGraphRecord,
+} from "./graph-projection.ts";
+import type { InvocationRecord } from "./invocation-ledger.ts";
 import { safeStringify } from "./serialization.ts";
 
 export type Theme = ExtensionContext["ui"]["theme"];
@@ -45,7 +51,11 @@ export type AgentState = "running" | "done" | "error";
 export type WorkflowStatus = "running" | "completed" | "failed" | "aborted";
 
 export type TranscriptRole =
-  "user" | "assistant" | "thinking" | "tool" | "toolResult";
+  | "user"
+  | "assistant"
+  | "thinking"
+  | "tool"
+  | "toolResult";
 
 export interface TranscriptEntry {
   role: TranscriptRole;
@@ -65,6 +75,15 @@ export interface TranscriptEntry {
 
 export interface AgentRecord {
   index: number;
+  /** Stable identity and independent intent/admission/execution status planes. */
+  callId?: string;
+  invocation?: InvocationRecord;
+  /** Ephemeral same-run child Session reused for this logical operator. */
+  operatorKey?: string;
+  /** Explicit result-reference dependencies used by the derived graph. */
+  inputCallIds?: string[];
+  /** Opaque same-run reference returned to the workflow script. */
+  resultRef?: string;
   label: string;
   phase?: string;
   state: AgentState;
@@ -122,9 +141,46 @@ export interface WorkflowDetails {
   resumedFrom?: string;
   /** Why a requested resume produced no cache, for an honest result message. */
   resumeNote?: string;
+  /** Read-only lineage projection; never execution or admission authority. */
+  graph?: WorkflowGraphProjection;
   error?: string;
 }
 
+export function workflowGraphRecords(
+  agents: readonly AgentRecord[],
+): WorkflowGraphRecord[] {
+  return agents.flatMap((agent) =>
+    agent.callId
+      ? [
+          {
+            callId: agent.callId,
+            index: agent.index,
+            label: agent.label,
+            state: agent.state,
+            ...(agent.invocation
+              ? {
+                  admissionState: agent.invocation.admissionState,
+                  executionState: agent.invocation.executionState,
+                }
+              : {}),
+            ...(agent.operatorKey ? { operatorKey: agent.operatorKey } : {}),
+            ...(agent.inputCallIds
+              ? { inputCallIds: [...agent.inputCallIds] }
+              : {}),
+            ...(agent.resultRef ? { resultRef: agent.resultRef } : {}),
+          },
+        ]
+      : [],
+  );
+}
+
+/** Refresh the descriptive graph without granting it scheduling authority. */
+export function refreshWorkflowGraph(details: WorkflowDetails) {
+  const records = workflowGraphRecords(details.agents);
+  details.graph = projectWorkflowGraph(records);
+  return details.graph;
+}
+
 export const MAX_LOG_ENTRIES = 100;
 export const MAX_LOG_TEXT = 300;
 

package/extensions/workflows/operator.ts

@@ -0,0 +1,131 @@
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+
+export interface WorkflowOperatorActivation {
+  key: string;
+  fingerprint: string;
+  cwd: string;
+  signal?: AbortSignal;
+}
+
+type OperatorEntry = {
+  fingerprint: string;
+  cwd: string;
+  sessionManager: SessionManager;
+  tail: Promise<void>;
+};
+
+export function normalizeWorkflowOperatorKey(key: string) {
+  if (typeof key !== "string" || !/^[A-Za-z0-9._:-]{1,80}$/.test(key)) {
+    throw new Error(
+      "Workflow operator key must be 1-80 ASCII letters, digits, or ._:- characters",
+    );
+  }
+  return key;
+}
+
+function abortError(signal: AbortSignal) {
+  if (signal.reason instanceof Error) return signal.reason;
+  const error = new Error("Workflow operator activation was aborted");
+  error.name = "AbortError";
+  return error;
+}
+
+function invokeAfter<T>(
+  turn: Promise<void>,
+  signal: AbortSignal | undefined,
+  invoke: () => T | PromiseLike<T>,
+) {
+  if (!signal) return turn.then(invoke);
+  if (signal.aborted) return Promise.reject(abortError(signal));
+
+  return new Promise<T>((resolve, reject) => {
+    let waiting = true;
+    const onAbort = () => {
+      if (!waiting) return;
+      waiting = false;
+      signal.removeEventListener("abort", onAbort);
+      reject(abortError(signal));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    void turn.then(
+      () => {
+        if (!waiting) return;
+        if (signal.aborted) {
+          onAbort();
+          return;
+        }
+        waiting = false;
+        signal.removeEventListener("abort", onAbort);
+        try {
+          Promise.resolve(invoke()).then(resolve, reject);
+        } catch (error) {
+          reject(error);
+        }
+      },
+      (error) => {
+        if (!waiting) return;
+        waiting = false;
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+/**
+ * Per-run, in-process operator sessions. Nothing in this registry is persisted
+ * or shared with another process.
+ */
+export class WorkflowOperatorRegistry {
+  private readonly operators = new Map<string, OperatorEntry>();
+  private closed = false;
+  private closePromise?: Promise<void>;
+
+  activate<T>(
+    activation: WorkflowOperatorActivation,
+    invoke: (sessionManager: SessionManager) => T | PromiseLike<T>,
+  ) {
+    if (this.closed) {
+      return Promise.reject(new Error("Workflow operator registry is closed"));
+    }
+
+    const key = normalizeWorkflowOperatorKey(activation.key);
+    let operator = this.operators.get(key);
+    if (!operator) {
+      operator = {
+        fingerprint: activation.fingerprint,
+        cwd: activation.cwd,
+        sessionManager: SessionManager.inMemory(activation.cwd),
+        tail: Promise.resolve(),
+      };
+      this.operators.set(key, operator);
+    } else if (
+      operator.fingerprint !== activation.fingerprint ||
+      operator.cwd !== activation.cwd
+    ) {
+      return Promise.reject(
+        new Error(`Workflow operator identity mismatch for "${key}"`),
+      );
+    }
+    const previous = operator.tail;
+    const result = invokeAfter(previous, activation.signal, () =>
+      invoke(operator.sessionManager),
+    );
+    operator.tail = Promise.allSettled([previous, result]).then(
+      () => undefined,
+    );
+    return result;
+  }
+
+  close() {
+    if (this.closePromise) return this.closePromise;
+    this.closed = true;
+    const queues = [...this.operators.values()].map(
+      (operator) => operator.tail,
+    );
+    this.closePromise = Promise.allSettled(queues).then(() => {
+      this.operators.clear();
+    });
+    return this.closePromise;
+  }
+}

package/extensions/workflows/prompt.ts

@@ -15,7 +15,7 @@ export const WORKFLOW_PARAMETER_DESCRIPTIONS = {
   background:
     "Run in the background: the tool returns a run id immediately and you receive a follow-up message when the workflow finishes. Defaults to false (blocking with live progress).",
   resumeFromRunId:
-    'Optional run id of a previous workflow (e.g. "wf_1a2b3c4d5e6f", or a unique suffix) to replay cached read-only agent results. A call replays only when its prompt, resolved agent type/schema/model/provider/effort, canonical cwd, repository state, loaded resources, and trust context match. Unrestricted/no-type agents, writable or unknown tool lists, worktree-isolated agents, failed calls, and calls whose context cannot be fingerprinted always run for real. Matching remains content-based and order-independent. Old or unknown journals simply run everything fresh.',
+    "Optional prior run id or unique suffix for safe read-only replay. See the workflows Skill for matching rules.",
 };
 
 /** Describes stopping a running background workflow, mirroring subagent_cancel/bg_kill. */
@@ -41,53 +41,25 @@ export const WORKFLOW_STATUS_PARAMETER_DESCRIPTIONS = {
 export const WORKFLOW_LIFECYCLE_PROMPT_SNIPPET =
   "Inspect (workflow_status) or cancel (workflow_stop) a background workflow by run id";
 
-/** Defines the workflow DSL, constraints, reliability guidance, and model-authored task examples. */
+/** Compact resident contract; the workflows Skill carries the complete guide. */
 export const WORKFLOW_TOOL_DESCRIPTION = [
   "Use the workflow tool when the user explicitly requests a workflow run or when the task clearly requires multi-phase dynamic orchestration.",
-  "Run a multi-agent workflow from a JavaScript orchestration script you write inline. Use this when a task benefits from fanning work out across several isolated subagents in ordered phases (research fan-out, per-file review, verify-then-synthesize pipelines).",
-  "The script runs as an async function body with these primitives:",
-  "• export const meta = { name, description, phases: [{ title, detail? }] } — metadata for the progress UI. Declare all phases up front.",
-  "• phase(title) — mark the current phase at runtime (use titles from meta.phases).",
-  "• log(message) — emit one progress line to the user and to your own final report. This is the run's narrator: use it for anything the reader needs while the run is still going, or that the return value would not capture — round counts, how many agents were dropped, why a branch was skipped. Unlike phase(), it does not touch the phase list. Lines are one row each (newlines are flattened); the most recent 100 are kept and any earlier ones are reported as dropped.",
-  "• usage() — read this run's cumulative token spend so far: { input, output, cacheRead, cacheWrite, total, cost, agents }. The reading refreshes as each agent settles, so evaluating it right after an `await` reflects that agent. `total` never decreases, but it is a LOWER BOUND rather than an exact figure: a child session that compacts drops the tokens of the messages it discarded. Use it to report or adapt cost — e.g. log a running total, or stop a discovery loop once the spend stops paying for itself — and expect a long run to have spent somewhat more than it says. It is a reading, not a limit: nothing is enforced for you.",
-  "• await agent(prompt, { agent_type?, label?, phase?, schema?, acceptance?, model?, provider?, effort?, isolation? }) — run ONE subagent in an isolated context and wait for it. `agent_type` applies the same named preset and enforced capabilities as subagent_spawn: specialized system prompt, tool allowlist, model assignment, and default effort. Prefer a matching type when one exists. Model precedence is explicit model/provider > type-file model > configured built-in role model > parent model; effort precedence is explicit effort > type default > parent effort. Omit `agent_type` for a general-purpose child. Always resolves to { ok, output, structured?, acceptance?, error? }. Check `ok` before using the result. When you pass a JSON `schema`, `structured` holds the validated object on success. Optional `acceptance: { criteria: [{ id, description, requiredEvidence? }] }` is explicit and adds no extra agent: the same structured result must include an evidence ledger; missing, malformed, or rejected criteria make `ok:false` while preserving output and ledger. Children receive normal built-ins and trust-appropriate extensions, settings, skills, and AGENTS.md context, but cannot recursively orchestrate or ask the user.",
-  "• isolation: 'worktree' runs that one agent in its own git worktree on its own branch, instead of the shared working directory. Use it for any fan-out where agents WRITE — without it, concurrent agents share one checkout and one git index, so their edits and `git add`s silently overwrite each other. Tell such an agent to COMMIT its work: on completion the worktree directory is reclaimed and its branch is kept for you to merge (an empty branch is deleted; uncommitted changes keep the directory instead). The branch name comes back in the run artifacts. Costs a fresh checkout, needs a git repo, and starts without gitignored files, so leave it off for read-only agents.",
-  "• await parallel([() => agent(...), () => agent(...)], { concurrency? }) — run zero-argument agent thunks concurrently and return results in order. This is a BARRIER: nothing after it starts until every thunk settles. A thunk that throws settles to null (filter it out) rather than failing the whole batch, so one bad item never discards the others' results. The package default is 8 concurrent agents per workflow and can be changed with /my-pi-setup (hard maximum 64).",
-  "• await pipeline(items, stage1, stage2, ...) — run each item through every stage independently, with NO barrier between stages: item A can be in stage 3 while item B is still in stage 1. Results come back in input order. Each stage receives (previousResult, originalItem, index), so a later stage can label its work without threading context through the earlier stage's return value. A stage that throws drops that item to null and skips its remaining stages, leaving siblings untouched.",
-  "PREFER pipeline() for multi-stage work. parallel() forces every item to wait for the slowest one in each stage, so wall-clock becomes the sum of per-stage worst cases (max stage1 + max stage2) instead of the slowest single chain. The gap is widest when different items are slow in different stages; when one item is slowest everywhere it is the critical path either way. Reach for a barrier only when a stage genuinely needs cross-item context from ALL of the previous one: deduping or merging the full result set, exiting early when the total count is zero, or a prompt that compares one finding against the others. Needing to flatten/map/filter in between is NOT a reason — do that inside a pipeline stage.",
-
-  "• args — the parsed value of the `args` tool parameter (or undefined).",
-  "Workflow JavaScript runs in a restricted, killable child with no imports, eval, timers, filesystem, network, or process APIs. The package default permits 128 agent calls per run and can be changed with /my-pi-setup (hard maximum 1024); there is no overall deadline. Each agent must receive its first assistant response event within 45 seconds so silent provider requests fail clearly; after that, agent() has no wall-clock deadline. Each individual child tool call times out independently after 3 minutes, becomes an error tool result, and leaves the agent loop free to recover. Use map/filter/if/await/template strings to orchestrate, and `return` a JSON-serializable aggregate.",
-  "Pass a `schema` to agent() whenever a later step branches on the result, so you get typed fields instead of prose. Artifacts are saved under ~/.pi/agent/workflows/<runId>/ for inspection. To re-run an edited workflow cheaply, pass `resume_from_run_id` with the previous run id: only provably read-only calls whose content and project/resource context are unchanged can replay; writable, unrestricted, unknown-tool, and worktree calls always run for real.",
-  "Example — each file is verified as soon as ITS OWN scan lands, instead of waiting for every scan:",
-  "export const meta = { name: 'reliability-review', description: 'Review modules for reliability risks, then report', phases: [{ title: 'Scan' }, { title: 'Verify' }, { title: 'Report' }] }",
-  "const FINDINGS = { type: 'object', properties: { issues: { type: 'array', items: { type: 'string' } }, ok: { type: 'boolean' } }, required: ['issues', 'ok'] }",
-  "phase('Scan')",
-  "const checked = await pipeline(args.files,",
-  "  (f) => agent(`Trace ${f} for candidate reliability risks with file:line evidence.`, { agent_type: 'explorer', label: `scan:${f}`, phase: 'Scan', schema: FINDINGS }),",
-  "  (scan, f) => scan.ok ? agent(`Review whether these candidate issues in ${f} are real: ${JSON.stringify(scan.structured.issues)}`, { agent_type: 'reviewer', label: `verify:${f}`, phase: 'Verify' }) : null)",
-  "const verified = checked.filter((r) => r && r.ok)",
-  "const dropped = checked.length - verified.length // agents that failed/dropped: surface, never silently swallow",
-  "if (dropped) log(`${dropped}/${checked.length} file(s) dropped before verification`)",
-  "phase('Report')",
-  "const report = await agent(`Synthesize tradeoffs and recommendations from these verified findings: ${JSON.stringify(verified.map((r) => r.output))}`, { agent_type: 'advisor', label: 'report', phase: 'Report' })",
-  "log(`done — ${verified.length} verified, ${usage().total} tokens`)",
-  "return { verified: verified.length, dropped, report: report.ok ? report.output : report.error }",
+  "Write an async JavaScript body using optional meta, phase(), log(), usage(), agent(), pipeline(), parallel(), args, and a JSON-serializable return.",
+  "agent() returns { ok, output, structured?, ref?, error? }; always check `.ok`, use a schema for branching, and surface failed or null results.",
+  "Prefer pipeline() for independent multi-stage items. Use parallel() only for a real barrier where the next step needs every prior result.",
+  "For concurrent writers use isolation: 'worktree' and tell each agent to commit. Read-only work should normally stay in the shared checkout.",
+  "Read the workflows Skill before a nontrivial script; it covers the restricted sandbox, full DSL, acceptance, result refs, replay, background lifecycle, limits, and examples.",
 ].join("\n");
 
 /** Adds workflow orchestration primitives and background execution to the model's tool prompt. */
 export const WORKFLOW_PROMPT_SNIPPET =
-  "Orchestrate isolated subagents from an inline JS script: phase()/agent()/pipeline()/parallel() with structured outputs, log() progress, usage() token readings, and optional background execution";
+  "Orchestrate subagents from an inline JS script; read the workflows Skill for the complete DSL";
 
 /** Guides the model on appropriate workflow fan-out and mandatory agent result checks. */
 export const WORKFLOW_PROMPT_GUIDELINES = [
   "Use workflow when a task needs several subagents with phase dependencies or dynamic fan-out; keep single small delegations in the main session.",
-  "For each workflow agent() call, select a matching agent_type when one exists (explorer, implementer, reviewer, advisor, or a loaded custom type) so its configured model, prompt, effort, and enforced tools apply; do not hardcode that role's model. Omit agent_type only for genuinely general-purpose work.",
-  "Default to pipeline() for multi-stage fan-out so each item advances as soon as its own previous stage lands; use parallel() only when a stage truly needs every prior result at once.",
-  "In workflow scripts, agent() never throws — check `.ok` before using `.output`/`.structured`; but parallel() and pipeline() settle a throwing thunk or stage to `null`, so guard those with `r && r.ok`.",
-  "A filtered-out or null result is a failed agent, not a clean pass: surface how many dropped (e.g. return a count) so a crashed or timed-out agent never reads as success.",
-  "log() anything the reader would want before the run ends — round counts, dropped agents, why a branch was skipped. A long run that narrates nothing is indistinguishable from a stalled one, and the return value only arrives at the end.",
-  "When several agents will edit files concurrently, give each one isolation: 'worktree' and tell it to commit; otherwise they share one checkout and one git index and overwrite each other. Read-only agents do not need it.",
+  "select a matching agent_type when available; use its configured model and do not hardcode that role's model.",
+  "Read the workflows Skill before a nontrivial script; check every agent result, surface dropped work, and use worktree isolation for concurrent writers.",
 ];
 
 /** Marks and forwards a workflow script's agent() task as an isolated child-model prompt. */