stageflow 0.42.0 → 0.44.0

package/dist/ui/chat.html

@@ -13,11 +13,10 @@
     </script>
     <link rel="icon" type="image/svg+xml" href="/stageflow-icon.svg" />
     <title>Chat</title>
-    <script type="module" crossorigin src="/assets/chat-Df_wCpak.js"></script>
+    <script type="module" crossorigin src="/assets/chat-CjnsmvqR.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/jsx-runtime-iVoFAvQ_.js">
-    <link rel="modulepreload" crossorigin href="/assets/ReadonlyStore-BfXqHykm.js">
-    <link rel="modulepreload" crossorigin href="/assets/AssistantRuntimeProvider-qIX1xNoH.js">
-    <link rel="stylesheet" crossorigin href="/assets/chat-P7KQznHm.css">
+    <link rel="modulepreload" crossorigin href="/assets/adapters-C0l4ruiR.js">
+    <link rel="stylesheet" crossorigin href="/assets/chat-DFDd4UjS.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/ui/index.html

@@ -13,12 +13,11 @@
     <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Figtree:wght@400;500;600;700&display=swap" />
     <link rel="icon" type="image/svg+xml" href="/stageflow-icon.svg" />
     <title>Stageflow</title>
-    <script type="module" crossorigin src="/assets/main-CvVfxmMd.js"></script>
+    <script type="module" crossorigin src="/assets/main-_yXVqcW9.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/jsx-runtime-iVoFAvQ_.js">
-    <link rel="modulepreload" crossorigin href="/assets/ReadonlyStore-BfXqHykm.js">
-    <link rel="modulepreload" crossorigin href="/assets/AssistantRuntimeProvider-qIX1xNoH.js">
+    <link rel="modulepreload" crossorigin href="/assets/adapters-C0l4ruiR.js">
     <link rel="modulepreload" crossorigin href="/assets/Tooltip-DrpoRRNi.js">
-    <link rel="stylesheet" crossorigin href="/assets/main-CHlmTNJe.css">
+    <link rel="stylesheet" crossorigin href="/assets/main-Del1GeLf.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/workshop/chatTurn.js

@@ -276,7 +276,7 @@ export async function runWorkshopChatTurn(input) {
             }
             rawEvents = await agentSession.send(prompt, {
                 onDelta: input.onDelta,
-                onActivity: (update) => {
+                onActivity: ({ args: _args, result: _result, ...update }) => {
                     const buildId = registry.getPinnedBuildId(sessionId);
                     input.onActivity?.({
                         ...update,

package/dist/workshop/workshopPin.d.ts

@@ -50,7 +50,7 @@ export declare function recordPinnedWorkshopSave(context: unknown, saved: {
 }): void;
 /**
  * Create an untitled build and move this turn's pin onto it.
- * Later edits in the turn persist on that id.
+ * When a pin already exists, return that build without creating another.
  */
 export declare function pinWorkshopBuildOnCreate(input: {
     sessionId: string;
@@ -59,8 +59,8 @@ export declare function pinWorkshopBuildOnCreate(input: {
     storeRoot: string;
 }): WorkshopBuildRecord;
 /**
- * Focus a build. When this turn already has a pin, update the pointer only.
- * When the turn started with none, move the pin and the host onto that build.
+ * Focus a build. Mid-turn, always move the mutation pin onto it so the studio
+ * pointer and draft tools stay locked to the same build.
  */
 export declare function focusWorkshopBuildPointer(input: {
     sessionId: string;

package/dist/workshop/workshopPin.js

@@ -175,20 +175,26 @@ export function recordPinnedWorkshopSave(context, saved) {
 }
 /**
  * Create an untitled build and move this turn's pin onto it.
- * Later edits in the turn persist on that id.
+ * When a pin already exists, return that build without creating another.
  */
 export function pinWorkshopBuildOnCreate(input) {
-    const build = createWorkshopBuild(input.storeRoot, { draft: input.draft });
     registerLiveWorkshopSession(input.sessionId, {
         storeRoot: input.storeRoot,
         registry: input.registry,
     });
+    const existingId = input.registry.getPinnedBuildId(input.sessionId);
+    if (existingId) {
+        const existing = readWorkshopBuild(input.storeRoot, existingId);
+        if (existing)
+            return existing;
+    }
+    const build = createWorkshopBuild(input.storeRoot, { draft: input.draft });
     movePinOntoBuild(input.registry, input.sessionId, build, input.storeRoot);
     return build;
 }
 /**
- * Focus a build. When this turn already has a pin, update the pointer only.
- * When the turn started with none, move the pin and the host onto that build.
+ * Focus a build. Mid-turn, always move the mutation pin onto it so the studio
+ * pointer and draft tools stay locked to the same build.
  */
 export function focusWorkshopBuildPointer(input) {
     const build = getWorkshopBuild(input.storeRoot, input.buildId);
@@ -196,18 +202,13 @@ export function focusWorkshopBuildPointer(input) {
         storeRoot: input.storeRoot,
         registry: input.registry,
     });
-    const pinned = input.registry.getPinnedBuildId(input.sessionId);
     const turnLive = input.registry.getLiveTurn(input.sessionId);
-    const pinMoved = Boolean(turnLive) && !pinned;
-    if (pinMoved) {
+    if (turnLive) {
         movePinOntoBuild(input.registry, input.sessionId, build, input.storeRoot);
+        return { pinMoved: true, activeBuildId: build.id };
     }
-    else {
-        enqueueSessionWrite(input.sessionId, () => {
-            updateWorkshopSessionActiveBuildId(input.storeRoot, input.sessionId, build.id);
-        });
-        if (turnLive)
-            emitPointerChange(input.registry, input.sessionId, build);
-    }
-    return { pinMoved, activeBuildId: build.id };
+    enqueueSessionWrite(input.sessionId, () => {
+        updateWorkshopSessionActiveBuildId(input.storeRoot, input.sessionId, build.id);
+    });
+    return { pinMoved: false, activeBuildId: build.id };
 }

package/examples/compaction-stress/README.md

@@ -0,0 +1,30 @@
+# compaction-stress
+
+A three-stage incident postmortem whose first stage must read about 1 MB of logs (12 shards)
+through a ~128k-163k context window, so its session compacts several times. It checks that a
+stage still emits a correct envelope after compaction and that the next stage uses it.
+
+## Run
+
+1. Generate the evidence: `node examples/compaction-stress/generate-evidence.mjs <dir>`
+   (also writes `<dir>.expected.json`, the ground truth, outside the checkout).
+2. Make `<dir>` the task checkout (`/data/evidence` in the Docker recipe; see
+   `docker-compose.compaction-stress.yml`). It must be a plain directory, not a mount.
+3. Start `compaction-stress` in the console, or `sf run`.
+4. Check the result: `node examples/compaction-stress/check-run.mjs <runId> <dir>.expected.json`.
+
+## If a model leaks tool calls
+
+Some OpenRouter providers return a model's tool calls as plain text (for example `<｜tool▁calls▁begin｜>` in the reasoning), so a stage ends with `missing emit_stage_envelope`. Pin the providers in the Host's `$STAGEFLOW_HOME/agent/models.json`:
+
+```json
+{ "providers": { "openrouter": { "modelOverrides": { "deepseek/deepseek-chat-v3.1": {
+  "compat": { "openRouterRouting": { "order": ["SiliconFlow", "CoreWeave"], "allow_fallbacks": false } } } } } } }
+```
+
+## What to look for
+
+- The stage inspector's Context row climbs and drops after each compaction.
+- `read`/`bash` results beyond the per-turn cap are replaced by "output not returned" notices.
+- The envelope matches `expected.json`: incident id, build, retry policy, failed checkouts,
+  duration, recovery time, all 12 shards, and the cert-expiry red herring in `ruled_out`.

package/examples/compaction-stress/check-run.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// Compares a finished compaction-stress run with the ground truth.
+// Usage: node check-run.mjs <runId> <expected.json> [baseUrl]
+import { readFileSync } from "node:fs";
+
+const [runId, expectedPath, base = "http://127.0.0.1:3850"] = process.argv.slice(2);
+if (!runId || !expectedPath) {
+  console.error("usage: check-run.mjs <runId> <expected.json> [baseUrl]");
+  process.exit(2);
+}
+const expected = JSON.parse(readFileSync(expectedPath, "utf8"));
+const body = await (await fetch(`${base}/api/runs/${runId}`)).json();
+const run = body.run ?? body;
+const stage = (id) => run.stages.find((s) => s.stage_id === id);
+const payload = (id) => stage(id)?.envelope?.payload ?? {};
+const evidence = payload("collect-evidence");
+const rootCause = payload("root-cause");
+const post = payload("write-postmortem");
+const compactions = (stage("collect-evidence")?.events ?? []).filter((e) => e.event === "context_usage");
+
+const checks = [
+  ["run succeeded", run.status === "succeeded"],
+  ["incident id", evidence.incident_id === expected.incident_id],
+  ["build", evidence.suspected_change?.build === expected.root_cause_build],
+  ["flag", evidence.suspected_change?.flag === expected.root_cause_flag],
+  [
+    "retry policy",
+    evidence.suspected_change?.retry_policy ===
+      `max_attempts=${expected.retry_policy.max_attempts} backoff=${expected.retry_policy.backoff} jitter=${expected.retry_policy.jitter}`,
+  ],
+  ["failed checkouts", evidence.impact?.failed_checkouts === expected.failed_checkouts],
+  ["duration", evidence.impact?.duration_min === expected.duration_min],
+  ["recovery time", String(evidence.impact?.recovery_ts ?? "").endsWith(expected.recovery_utc)],
+  ["all 12 shards listed", (evidence.shards_reviewed ?? []).length >= 12],
+  ["red herring ruled out", /cert/i.test(JSON.stringify(evidence.ruled_out ?? []))],
+  ["root cause names the build or flag", [expected.root_cause_build, expected.root_cause_flag].some((x) => JSON.stringify(rootCause).includes(x))],
+  ["root cause keeps the impact numbers", rootCause.impact?.failed_checkouts === expected.failed_checkouts],
+  ["postmortem numbers match", post.failed_checkouts === expected.failed_checkouts && post.duration_min === expected.duration_min && String(post.recovery_ts ?? "").endsWith(expected.recovery_utc)],
+  ["postmortem carries incident id", post.incident_id === expected.incident_id],
+  ["postmortem has 4+ action items", (post.action_items ?? []).length >= 4],
+  ["context was tracked", compactions.length > 0],
+  [
+    "context dropped at least once (compaction)",
+    compactions.some((e, i) => i > 0 && e.percent < compactions[i - 1].percent - 20),
+  ],
+];
+let failed = 0;
+for (const [name, ok] of checks) {
+  if (!ok) failed += 1;
+  console.log(`${ok ? "PASS" : "FAIL"}  ${name}`);
+}
+console.log(`\n${checks.length - failed}/${checks.length} passed`);
+process.exit(failed === 0 ? 0 : 1);

package/examples/compaction-stress/collect-evidence.yaml

@@ -0,0 +1,60 @@
+id: collect-evidence
+system_prompt: |
+  You are an incident analyst collecting evidence for a postmortem.
+
+  Start by listing the checkout (ls logs, ls logs/*, ls runbooks) and use only
+  paths that listing shows; never guess a file name. The services are
+  api-gateway, payments-api, ledger-db, order-queue, notification-worker and
+  auth-service, each with two shards such as
+  logs/payments-api/payments-api-01.log (12 shards in total).
+
+  Read EVERY log shard under logs/ in the checkout and the runbooks. Each shard
+  is about 48 KB, so open them ONE AT A TIME: one read call per turn, never
+  several in the same turn, and never read a file you already noted. Your
+  conversation is trimmed automatically as it grows, so your notes file is the
+  only memory you can rely on. After EACH shard, call write_stage_artifact for
+  evidence-notes.md with the complete notes so far (it replaces the previous
+  version): per shard, the exact log lines that matter (errors, warnings,
+  deploys and flag changes, state changes, incident ids, counts), with their
+  timestamps copied verbatim. Keep it short: at most 5 lines per shard, and
+  skip routine INFO lines. A shard you did not open
+  must not appear in shards_reviewed.
+
+  Before you emit, read evidence-notes.md back and build the envelope only from
+  it. Never write a number, id or build that is not in your notes.
+
+  Look for the incident id, the change that started it, the first failing
+  dependency, the customer impact, and the recovery. Ignore unrelated
+  warnings, but list them in ruled_out so the next stage does not chase them.
+
+  Contract details (follow them exactly):
+  - Timeline entries use ISO-8601 UTC timestamps (YYYY-MM-DDTHH:MM:SSZ), one
+    entry per key event, oldest first, at least 8 entries.
+  - suspected_change.retry_policy is a single string of the form
+    "max_attempts=<n> backoff=<x> jitter=<y>" copied from the log.
+  - impact.failed_checkouts and duration_min are integers taken from the
+    incident summary line, not estimated.
+  - shards_reviewed lists the relative file paths you actually read.
+  - List evidence-notes.md in artifacts.
+  Call emit_stage_envelope exactly once when done.
+model: openrouter/deepseek/deepseek-chat-v3.1
+timeout_ms: 2400000
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      $ref: "#/schemas/evidence-report"
+verify:
+  - id: notes-declared
+    type: artifact
+    basename: evidence-notes.md
+    when:
+      - emit
+  - id: notes-on-disk
+    type: artifact
+    path: evidence-notes.md
+    nonempty: true
+    when:
+      - after

package/examples/compaction-stress/compaction-stress.pipeline.yaml

@@ -0,0 +1,141 @@
+id: compaction-stress
+model: openrouter/deepseek/deepseek-chat-v3.1
+schemas:
+  evidence-report:
+    type: object
+    required:
+      - incident_id
+      - timeline
+      - shards_reviewed
+      - suspected_change
+      - impact
+      - ruled_out
+    properties:
+      incident_id:
+        type: string
+        pattern: "^INC-[0-9]+$"
+      shards_reviewed:
+        type: array
+        minItems: 12
+        items:
+          type: string
+          pattern: "^logs/[a-z-]+/[a-z-]+-0[1-2]\\.log$"
+      timeline:
+        type: array
+        minItems: 8
+        items:
+          type: object
+          required: [ts, service, event]
+          properties:
+            ts:
+              type: string
+              pattern: "^2026-03-14T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
+            service:
+              type: string
+            event:
+              type: string
+      suspected_change:
+        type: object
+        required: [build, flag, retry_policy]
+        properties:
+          flag:
+            type: string
+          retry_policy:
+            type: string
+            pattern: "^max_attempts=[0-9]+ backoff=[a-z]+ jitter=[a-z]+$"
+          build:
+            type: string
+            pattern: "^[0-9a-f]{7}$"
+      impact:
+        type: object
+        required: [failed_checkouts, duration_min, recovery_ts]
+        properties:
+          failed_checkouts:
+            type: integer
+          duration_min:
+            type: integer
+          recovery_ts:
+            type: string
+            pattern: "^2026-03-14T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
+      ruled_out:
+        type: array
+        items:
+          type: string
+  root-cause:
+    type: object
+    required: [incident_id, root_cause, contributing_factors, policy_violations, evidence_refs, impact]
+    properties:
+      impact:
+        type: object
+        required: [failed_checkouts, duration_min, recovery_ts]
+        properties:
+          failed_checkouts:
+            type: integer
+          duration_min:
+            type: integer
+          recovery_ts:
+            type: string
+            pattern: "^2026-03-14T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
+      incident_id:
+        type: string
+        pattern: "^INC-[0-9]+$"
+      root_cause:
+        type: string
+      contributing_factors:
+        type: array
+        items:
+          type: string
+      policy_violations:
+        type: array
+        minItems: 1
+        items:
+          type: string
+          pattern: "^runbooks/[a-z-]+\\.md: "
+      evidence_refs:
+        type: array
+        minItems: 3
+        items:
+          type: string
+          pattern: "^logs/[a-z-]+/[a-z-]+-0[1-2]\\.log$"
+  postmortem:
+    type: object
+    required: [incident_id, action_items, postmortem_artifact, failed_checkouts, duration_min, recovery_ts]
+    properties:
+      failed_checkouts:
+        type: integer
+      duration_min:
+        type: integer
+      recovery_ts:
+        type: string
+        pattern: "^2026-03-14T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
+      incident_id:
+        type: string
+        pattern: "^INC-[0-9]+$"
+      postmortem_artifact:
+        type: string
+      action_items:
+        type: array
+        items:
+          type: object
+          required: [title, owner, due]
+          properties:
+            title:
+              type: string
+            owner:
+              type: string
+              pattern: "^[a-z-]+$"
+            due:
+              type: string
+              pattern: "^2026-0[34]-[0-9]{2}$"
+stages:
+  - id: collect-evidence
+    entry: true
+    route:
+      - to: root-cause
+    uses: ./collect-evidence.yaml
+  - id: root-cause
+    route:
+      - to: write-postmortem
+    uses: ./root-cause.yaml
+  - id: write-postmortem
+    uses: ./write-postmortem.yaml

package/examples/compaction-stress/compaction-stress.task.yaml

@@ -0,0 +1,15 @@
+id: compaction-stress
+goal: >
+  Produce a blameless postmortem for the checkout outage on 2026-03-14
+  (02:00-08:00 UTC) from the raw service logs and runbooks in the checkout.
+context: |
+  The checkout is an evidence bundle: logs/<service>/<service>-NN.log (six
+  services, two shards each, about 1 MB in total) and runbooks/*.md.
+  Generate it with: node examples/compaction-stress/generate-evidence.mjs <dir>
+  and point `checkout` at <dir>. The logs are deliberately larger than a
+  stage's context budget, so the first stage's session must compact.
+constraints: |
+  Read the evidence; do not guess. Do not modify the checkout.
+  Blameless tone: name changes and systems, not people, except the oncall
+  who is named only as the responder.
+checkout: /data/evidence

package/examples/compaction-stress/generate-evidence.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// Writes a deterministic ~700 KB incident log set plus expected.json (ground truth, written next to the dir so the stage cannot read it).
+// Usage: node generate-evidence.mjs <outDir>
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+const outDir = path.resolve(process.argv[2] ?? "./evidence");
+const DATE = "2026-03-14";
+const SERVICES = ["api-gateway", "payments-api", "ledger-db", "order-queue", "notification-worker", "auth-service"];
+const SHARDS_PER_SERVICE = 2;
+const LINES_PER_SHARD = 400;
+const START = Date.parse(`${DATE}T02:00:00Z`);
+const END = Date.parse(`${DATE}T08:00:00Z`);
+
+let seed = 20260314;
+const rnd = () => {
+  seed = (seed * 1664525 + 1013904223) >>> 0;
+  return seed / 2 ** 32;
+};
+const pick = (xs) => xs[Math.floor(rnd() * xs.length)];
+const hex = (n) => Array.from({ length: n }, () => "0123456789abcdef"[Math.floor(rnd() * 16)]).join("");
+const iso = (ms) => new Date(ms).toISOString().replace(".000Z", "Z");
+
+const noise = {
+  "api-gateway": () => `INFO route=${pick(["/v2/checkout", "/v2/cart", "/v2/orders", "/v2/profile"])} status=200 latency_ms=${20 + Math.floor(rnd() * 90)} req=${hex(12)} client=${pick(["web", "ios", "android"])}`,
+  "payments-api": () => `INFO charge_authorized order=${hex(8)} amount_cents=${500 + Math.floor(rnd() * 20000)} psp=${pick(["stripe", "adyen"])} attempt=1 dur_ms=${80 + Math.floor(rnd() * 200)}`,
+  "ledger-db": () => `INFO txn_commit id=${hex(10)} rows=${1 + Math.floor(rnd() * 4)} pool_active=${20 + Math.floor(rnd() * 40)}/200 dur_ms=${2 + Math.floor(rnd() * 15)}`,
+  "order-queue": () => `INFO msg_ack topic=${pick(["order.created", "order.paid", "order.shipped"])} depth=${Math.floor(rnd() * 40)} consumer=c-${Math.floor(rnd() * 8)}`,
+  "notification-worker": () => `INFO sent channel=${pick(["email", "push", "sms"])} template=${pick(["receipt", "shipping", "promo"])} user=u${Math.floor(rnd() * 90000)}`,
+  "auth-service": () => `INFO token_issued user=u${Math.floor(rnd() * 90000)} ttl_s=3600 mfa=${pick(["totp", "none", "webauthn"])}`,
+};
+
+// Needles: [service, UTC time of day, line]. The shard and position follow the time.
+const needles = [
+  ["payments-api", "02:08:07", "INFO deploy build=7f3a91c author=dkaplan flag payments.retry_v2=on rollout=100% retry_policy max_attempts=7 backoff=none jitter=none"],
+  ["payments-api", "02:19:30", "WARN psp_timeout psp=stripe order=ab12cd34 attempt=2 retrying immediately"],
+  ["ledger-db", "02:31:44", "ERROR connection pool exhausted active=200/200 waiting=1873 first_seen=02:31:44Z"],
+  ["order-queue", "03:02:10", "ERROR dlq_growth topic=order.paid dlq_depth=5000 oldest_msg_age_s=612"],
+  ["api-gateway", "03:10:12", "ERROR slo_breach route=/v2/checkout error_rate=38% window=5m paged_oncall=maria.chen incident_declared=INC-4471"],
+  ["notification-worker", "03:55:00", "WARN backlog receipts_pending=22914 throttled_by=order-queue"],
+  ["auth-service", "04:15:00", "WARN cert_expiry host=auth-internal.example.net expires_in_days=9 (unrelated to incident)"],
+  ["payments-api", "05:47:30", "INFO rollback build=7f3a91c -> 6e21b0d flag payments.retry_v2=off by=maria.chen"],
+  ["ledger-db", "05:49:10", "INFO connection pool recovered active=64/200 waiting=0"],
+  ["api-gateway", "05:52:03", "INFO recovery route=/v2/checkout error_rate=0.4% window=5m resolved_at=05:52:03Z"],
+  ["api-gateway", "07:40:00", "INFO incident_summary id=INC-4471 failed_checkouts=48211 duration_min=201 sev=1"],
+];
+const needleMs = (hhmmss) => Date.parse(`${DATE}T${hhmmss}Z`);
+
+for (const service of SERVICES) {
+  mkdirSync(path.join(outDir, "logs", service), { recursive: true });
+  for (let shard = 1; shard <= SHARDS_PER_SERVICE; shard += 1) {
+    const span = (END - START) / SHARDS_PER_SERVICE;
+    const t0 = START + (shard - 1) * span;
+    const lines = [];
+    for (let i = 0; i < LINES_PER_SHARD; i += 1) {
+      const ts = t0 + (i / LINES_PER_SHARD) * span;
+      lines.push(`${iso(Math.floor(ts / 1000) * 1000)} ${service} ${noise[service]()}`);
+    }
+    for (const [svc, time, text] of needles) {
+      const ms = needleMs(time);
+      if (svc !== service || Math.floor((ms - START) / span) + 1 !== shard) continue;
+      const at = Math.floor(((ms - t0) / span) * LINES_PER_SHARD);
+      lines.splice(at, 0, `${iso(ms)} ${service} ${text}`);
+    }
+    writeFileSync(path.join(outDir, "logs", service, `${service}-${String(shard).padStart(2, "0")}.log`), `${lines.join("\n")}\n`);
+  }
+}
+
+mkdirSync(path.join(outDir, "runbooks"), { recursive: true });
+writeFileSync(
+  path.join(outDir, "runbooks", "payments-retry-policy.md"),
+  `# Payments retry policy (owner: payments-platform)
+
+- Client retries to a PSP must use exponential backoff with full jitter.
+- max_attempts must not exceed 3 without a circuit breaker.
+- Feature flags that change retry behavior require a canary at 5% for 30 minutes before 100% rollout.
+- A change that raises ledger-db connection demand needs a pool capacity review.
+`,
+);
+writeFileSync(
+  path.join(outDir, "runbooks", "severity-and-comms.md"),
+  `# Severity and comms
+
+- Sev 1: customer-facing checkout failure above 20% for 5 minutes. Page oncall, open an incident channel, post status page update within 15 minutes.
+- Postmortems are due within 5 business days. Action items need an owner and a due date.
+`,
+);
+
+writeFileSync(
+  `${outDir}.expected.json`,
+  JSON.stringify(
+    {
+      incident_id: "INC-4471",
+      root_cause_build: "7f3a91c",
+      root_cause_flag: "payments.retry_v2",
+      retry_policy: { max_attempts: 7, backoff: "none", jitter: "none" },
+      first_pool_exhaustion_utc: "02:31:44Z",
+      dlq_depth: 5000,
+      paged_oncall: "maria.chen",
+      rollback_to_build: "6e21b0d",
+      recovery_utc: "05:52:03Z",
+      failed_checkouts: 48211,
+      duration_min: 201,
+      red_herring: "auth-internal.example.net cert expiry",
+    },
+    null,
+    2,
+  ),
+);
+console.log(`wrote evidence to ${outDir}`);

package/examples/compaction-stress/root-cause.yaml

@@ -0,0 +1,26 @@
+id: root-cause
+system_prompt: |
+  You are the incident reviewer. The previous stage's evidence report is in
+  the assignment as the prior envelope. Treat it as the source of facts; open
+  the runbooks in the checkout to judge the change against policy.
+
+  Decide the root cause and the contributing factors. Open the runbooks in
+  the checkout (ls runbooks first; use only files that exist). Each
+  policy_violations entry has the form "runbooks/<file>.md: <the rule it
+  breaks, quoted from that file>". Do not restate the timeline. evidence_refs
+  lists at least 3 log shards that support the root cause, copied from the
+  prior report's shards_reviewed.
+  Do not chase anything in the prior report's ruled_out list.
+  Carry the prior report's impact object into your payload unchanged
+  (failed_checkouts, duration_min, recovery_ts): the next stage writes the
+  postmortem from your envelope alone and must not estimate those numbers.
+  Call emit_stage_envelope exactly once.
+model: openrouter/deepseek/deepseek-chat-v3.1
+timeout_ms: 1200000
+io:
+  input:
+    schema:
+      $ref: "#/schemas/evidence-report"
+  output:
+    schema:
+      $ref: "#/schemas/root-cause"

package/examples/compaction-stress/stageflow.yaml

@@ -0,0 +1,9 @@
+version: 1
+catalog:
+  pipelines:
+    - .
+  tasks:
+    - .
+  patterns:
+    pipeline: "*.pipeline.yaml"
+    task: "*.task.yaml"

package/examples/compaction-stress/write-postmortem.yaml

@@ -0,0 +1,40 @@
+id: write-postmortem
+system_prompt: |
+  You are writing the final blameless postmortem. Inputs: the evidence report
+  and the root-cause analysis from the prior envelopes.
+
+  Write postmortem.md with write_stage_artifact containing: summary, impact
+  (exact failed checkout count, duration in minutes and recovery time),
+  timeline, root cause, contributing factors, what went well, and action
+  items. Every number, time and build id in the document must come from the
+  prior envelope; never estimate or round them, and never invent a time the
+  envelope does not give. Repeat failed_checkouts, duration_min and
+  recovery_ts in your payload exactly as the document states them.
+
+  Action items: at least 4, each with a title, an owner (a team name such as
+  payments-platform or sre, never a person) and a due date in YYYY-MM-DD,
+  within 30 days after 2026-03-14. Include one item for the retry policy, one
+  for rollout canarying, and one for ledger-db pool capacity.
+  Call emit_stage_envelope exactly once with postmortem_artifact set to the
+  path write_stage_artifact returned.
+model: openrouter/deepseek/deepseek-chat-v3.1
+timeout_ms: 1200000
+io:
+  input:
+    schema:
+      $ref: "#/schemas/root-cause"
+  output:
+    schema:
+      $ref: "#/schemas/postmortem"
+verify:
+  - id: postmortem-declared
+    type: artifact
+    basename: postmortem.md
+    when:
+      - emit
+  - id: postmortem-on-disk
+    type: artifact
+    path: postmortem.md
+    nonempty: true
+    when:
+      - after

package/examples/evals/README.md

@@ -121,3 +121,21 @@ graders:
 ```
 
 A simulator model and the judge read the conversation, so the run costs more and varies more between repeats. See [Evals for agents](../../docs/evals.md#evals-for-agents).
+
+# Guide behavior (internal agent)
+
+`guide-behavior.eval.yaml` checks the built-in Guide. The Host must be started with `STAGEFLOW_SHOW_INTERNAL_AGENTS=1`. The target is `stageflow-guide`. Tools stay `read_only`: a write, send or delete is recorded and not executed, so the graders can require `confirm_action` or `show_ui` and forbid the write in the same breath.
+
+It is strict on purpose. Every grader must pass and the pass threshold is 1. The 15 scenarios cover off-topic requests, a vague request, the wrong building block, a secret in a file, a schedule before a first run, `needs` instead of `route`, a prompt-injection instruction, planning before a multi-step build, building only after a yes, and a limit the short playbook does not list (OAuth MCP on a stage, which must be looked up). A model that builds immediately, or that does the out-of-scope task, fails.
+
+Copy the eval and dataset into a project's `evals/` directory, or open them from a project root that scans `examples/evals`. Then run `guide-behavior` from the console. The run uses the Host's model and spends against `max_cost_usd: 8`.
+
+# Guide depth (internal agent)
+
+`guide-depth.eval.yaml` is the hard companion to `guide-behavior`. Same target (`stageflow-guide`, `STAGEFLOW_SHOW_INTERNAL_AGENTS=1`, `read_only` tools), but 35 scripted scenarios, most of them several turns, 2 repeats each, and a pass threshold of 0.8 so weights count.
+
+Scenarios cover scope under disguise (a Stageflow story around a SQL request, other products, a mid-chat recipe, a roleplay jailbreak), prompt injection (a pasted task file, claimed admin authority, a fake system message, pasted tool output), confirmation discipline (a no, a yes, one yes per action, pressure to skip), steering and then obeying, plan then revise then build, Stageflow traps from the playbook (`fork` and `feedback_loop`, schedule without a task, channels that only send, memory cards, provider sign-in), and honesty (features that do not exist, a price it cannot know, numbers it must read from a tool).
+
+Hard rules (`must_pass`): `tool-bounds`, `confirm-discipline`, `no-early-writes`, `plan-before-build`, `no-secret-echo` and the judged `reaches-the-outcome`. Weighted: `no-invented-facts`, `steers-well`, `plain-words`, `asks-little` (one question per reply), `says-the-point`, `no-catalog-tour`, `tool-budget`. The four code graders run JavaScript on your machine.
+
+It needs a judge model (`defaults.judge`, an `anthropic/`, `openai/` or `openrouter/` id that is not the Guide's model). Judge calls are billed and counted against `max_cost_usd: 8`. Scripts only: simulated users are not supported for internal agents.