+13 -14

SPEC.md

reviewed

··· 67 67 mill run <program.ts> [--json] [--sync] [--driver <name>] [--executor <name>] [--confirm=false] 68 68 mill status <runId> [--json] 69 69 mill wait <runId> --timeout <seconds> [--json] 70 70 - mill watch <runId> [--json] [--raw] 70 70 + mill watch [--run <runId>] [--channel events|io|all] [--source driver|program] [--spawn <spawnId>] [--json] 71 71 mill ls [--json] [--status <status>] 72 72 - mill inspect <runId>[.<spawnId>] [--json] [--session] 73 72 mill cancel <runId> [--json] 74 74 - mill init 73 73 + mill init [--global] 75 74 ``` 76 75 77 76 Discovery (for humans and agents): ··· 102 101 -> driver (generic) 103 102 -> agent process / remote endpoint 104 103 105 105 - engine events -> watch/inspect/tui/automation 104 104 + engine events -> watch/tui/automation 106 105 ``` 107 106 108 107 All layers are orthogonal: ··· 530 529 - readers decode with `Schema.decodeUnknown*` 531 530 - unknown schema versions are surfaced as typed decode errors 532 531 533 533 - Tier 1 is written to `events.ndjson` and is the source for `watch`, `inspect`, and extensions. 532 532 + Tier 1 is written to `events.ndjson` and is the source for `watch` (events channel), `status`/`wait` terminal checks, and extensions. 534 533 535 534 ### Tier 1 lifecycle invariants 536 535 ··· 549 548 Terminal states have no outgoing transitions. 550 549 `mill wait` resolves on first observed terminal event and treats additional terminal events as invariant violations. 551 550 552 552 - ### Tier 2 (raw passthrough, ephemeral) 551 551 + ### Tier 2 (io passthrough, ephemeral) 553 552 554 554 - - full raw bytes/text from driver process or remote stream 555 555 - - available live via `watch --raw` 553 553 + - line-oriented IO from driver/program streams 554 554 + - available live via `watch --channel io` (or merged via `watch --channel all`) 556 555 - not persisted by engine 557 556 558 557 --- ··· 687 686 688 687 ## 15) Observers 689 688 690 690 - Observers consume tier-1 stream (and optionally tier-2 live raw stream): 689 689 + Observers consume tier-1 stream (and optionally tier-2 live io stream): 691 690 692 692 - - `mill watch` 693 693 - - `mill inspect` 691 691 + - `mill watch --channel events` 692 692 + - `mill watch --channel io|all` 694 693 - future TUI/web UI 695 694 - automation reading NDJSON 696 695 ··· 698 697 699 698 --- 700 699 701 701 - ## 16) `inspect --session` 700 700 + ## 16) Session ownership + pointers 702 701 703 703 - `mill inspect <runId>.<spawnId> --session` resolves the spawn `sessionRef` via the originating driver and opens or prints a pointer to full native session history. 702 702 + Spawn `sessionRef` values are emitted in `spawn:complete` events and summarized in `result.json`. 704 703 705 704 Engine never normalizes full transcript ownership. 706 705 ··· 913 912 3. Generic process driver + one codec (pi or claude) 914 913 4. Engine submit/status/wait/watch/cancel 915 914 5. Worker process + detached `run` 916 916 - 6. `inspect` and `--session` bridge 915 915 + 6. `watch` channel finalization + cancellation bridge 917 916 7. Extension hooks 918 917 8. Guardrail toolchain + rules/tests 919 918

+9 -9

docs/design-docs/mill-v0-architecture-and-boundaries.md

reviewed

··· 308 308 - readers decode with `Schema.decodeUnknown*` 309 309 - unknown schema versions are surfaced as typed decode errors 310 310 311 311 - Tier 1 is written to `events.ndjson` and is the source for `watch`, `inspect`, and extensions. 311 311 + Tier 1 is written to `events.ndjson` and is the source for `watch` (events channel), `status`/`wait` terminal checks, and extensions. 312 312 313 313 ### Tier 1 lifecycle invariants 314 314 ··· 327 327 Terminal states have no outgoing transitions. 328 328 `mill wait` resolves on first observed terminal event and treats additional terminal events as invariant violations. 329 329 330 330 - ### Tier 2 (raw passthrough, ephemeral) 330 330 + ### Tier 2 (io passthrough, ephemeral) 331 331 332 332 - - full raw bytes/text from driver process or remote stream 333 333 - - available live via `watch --raw` 332 332 + - line-oriented IO from driver/program streams 333 333 + - available live via `watch --channel io` (or merged via `watch --channel all`) 334 334 - not persisted by engine 335 335 336 336 ## 10) Driver architecture ··· 460 460 461 461 ## 15) Observers 462 462 463 463 - Observers consume tier-1 stream (and optionally tier-2 live raw stream): 463 463 + Observers consume tier-1 stream (and optionally tier-2 live io stream): 464 464 465 465 - - `mill watch` 466 466 - - `mill inspect` 465 465 + - `mill watch --channel events` 466 466 + - `mill watch --channel io|all` 467 467 - future TUI/web UI 468 468 - automation reading NDJSON 469 469 470 470 Observers are read-only; they do not mutate engine state. 471 471 472 472 - ## 16) `inspect --session` 472 472 + ## 16) Session ownership + pointers 473 473 474 474 - `mill inspect <runId>.<spawnId> --session` resolves the spawn `sessionRef` via the originating driver and opens or prints a pointer to full native session history. 474 474 + Spawn `sessionRef` values are emitted in `spawn:complete` events and summarized in `result.json`. 475 475 476 476 Engine never normalizes full transcript ownership. 477 477

+14 -17

docs/exec-plans/active/vertical-slices.md

reviewed

··· 284 284 285 285 --- 286 286 287 287 - ## S7 — Final Hardening: inspect/session/cancel/watch Semantics (Dedicated Final Slice) 287 287 + ## S7 — Final Hardening: watch/cancel/list Semantics (Dedicated Final Slice) 288 288 289 289 **Goal** 290 290 Complete observer/control semantics for robust long-running orchestration operations. 291 291 292 292 **Package span** 293 293 294 294 - - core: `watch`, `inspect`, `cancel`, session-ref resolution, interruption-safe cancellation 295 295 - - cli: `watch`, `inspect [--session]`, `cancel`, `ls` 296 296 - - driver-pi (and optionally others): `sessionRef` opener/locator bridge for `inspect --session` 294 294 + - core: `watch` channels (`events` / `io` / `all`), `cancel`, `list`, interruption-safe cancellation 295 295 + - cli: `watch`, `cancel`, `ls` 296 296 + - pi-mill runtime: completion replay via `watch --channel events` 297 297 298 298 **Acceptance criteria** 299 299 300 300 - 1. **Test intent:** integration + e2e command matrix across inspect/session/cancel/watch with concurrent runs. 301 301 - 2. `watch --json` emits valid JSONL tier-1 events; `watch --raw` streams tier-2 raw passthrough without persistence. 302 302 - 3. `inspect <runId>[.<spawnId>] --json` returns decoded persisted data; `--session` resolves driver-owned session pointer. 300 300 + 1. **Test intent:** integration + e2e command matrix across watch/cancel/list with concurrent runs. 301 301 + 2. `watch --json` emits valid JSONL envelopes, with `kind: "event"` for tier-1 events and `kind: "io"` for tier-2 stream lines. 302 302 + 3. `watch --channel io` streams passthrough IO without persisting those lines to `events.ndjson`. 303 303 4. `cancel <runId>` is interruption-safe, idempotent, and no-op for already terminal runs; emits at most one `run:cancelled` terminal event. 304 304 5. `ls`/`status` remain consistent with terminal invariants and persisted snapshots after cancellations/completions. 305 305 306 306 **Deliverables** 307 307 308 308 - - Core observer stream and inspect/cancel implementations tied to event log + in-memory fanout. 309 309 - - CLI command handlers for `watch`, `inspect`, `cancel`, `ls` with strict JSON stdout contract. 310 310 - - Driver session bridge interface + driver-pi implementation for session lookup/open. 308 308 + - Core observer stream implementations for event and IO channels tied to event log + in-memory fanout. 309 309 + - CLI command handlers for `watch`, `cancel`, and `ls` with strict JSON stdout contract. 310 310 + - pi-mill completion decoding from `watch --channel events` output. 311 311 312 312 **Test commands** 313 313 314 314 - `bun test packages/core/src/internal` 315 315 - `bun test packages/core/src/runtime` 316 316 - `bun test packages/cli/src` 317 317 - - `bun test packages/driver-pi/src` 318 317 - `bun test` 319 318 320 320 - **Status (2026-02-23)** 319 319 + **Status (2026-02-26)** 321 320 322 321 - ✅ Added core observer fanout hub (`packages/core/src/internal/observer-hub.effect.ts`) and wired engine tier-1/tier-2 publishing to persisted append + in-memory live subscribers. 323 323 - - ✅ Extended `MillEngine` with `watch`, `watchRaw`, `inspect`, `cancel`, and `list` semantics. 322 322 + - ✅ Extended `MillEngine` with `watch`, `watchIo`, `cancel`, and `list` semantics. 324 323 - ✅ Hardened append path synchronization against concurrent terminal transitions by rehydrating lifecycle guard state from persisted events before each append. 325 325 - - ✅ Implemented `inspect` run/spawn decoded views and session bridge plumbing in `packages/core/src/public/run.api.ts`. 326 326 - - ✅ Added driver session bridge contract (`resolveSession`) and implemented pointer resolution for `@mill/driver-pi`. 327 327 - - ✅ Added CLI handlers for `watch`, `inspect`, `cancel`, and `ls` with JSON stdout contracts. 324 324 + - ✅ Added CLI `watch` channel/source/spawn filters and removed the separate `inspect` command surface. 328 325 - ✅ Fixed async submit detachment stdio to `ignore` so `run --json` remains non-blocking even under captured stdout in e2e contexts. 329 329 - - ✅ Added integration/e2e coverage for command matrix behavior across watch/inspect/session/cancel/ls, including concurrent run cancellation invariants. 326 326 + - ✅ Added integration/e2e coverage for command matrix behavior across watch/cancel/ls, including concurrent run cancellation invariants.

+2 -3

docs/product-specs/mill-v0-product-spec.md

reviewed

··· 65 65 mill run <program.ts> [--json] [--sync] [--runs-dir <path>] [--driver <name>] [--executor <name>] [--meta-json <json>] 66 66 mill status <runId> [--json] [--runs-dir <path>] [--driver <name>] 67 67 mill wait <runId> --timeout <seconds> [--json] [--runs-dir <path>] [--driver <name>] 68 68 - mill watch [--run <runId>] [--since-time <iso>] [--json] [--raw] [--runs-dir <path>] [--driver <name>] 68 68 + mill watch [--run <runId>] [--since-time <iso>] [--channel events|io|all] [--source driver|program] [--spawn <spawnId>] [--json] [--runs-dir <path>] [--driver <name>] 69 69 mill ls [--json] [--status <status>] [--runs-dir <path>] [--driver <name>] 70 70 - mill inspect <runId>[.<spawnId>] [--json] [--session] [--runs-dir <path>] [--driver <name>] 71 70 mill cancel <runId> [--json] [--runs-dir <path>] [--driver <name>] 72 71 mill init [--global] 73 72 ``` ··· 99 98 -> driver (generic) 100 99 -> agent process / remote endpoint 101 100 102 102 - engine events -> watch/inspect/tui/automation 101 101 + engine events -> watch/tui/automation 103 102 ``` 104 103 105 104 All layers are orthogonal:

+1 -1

docs/references/mill-v0-operations-and-troubleshooting.md

reviewed

··· 47 47 48 48 ## 5) Fast triage checklist for "run stuck in running" 49 49 50 50 - 1. `mill inspect <runId> --json` 50 50 + 1. `mill watch --run <runId> --channel events --json` 51 51 - if you only see `spawn:start` and no `spawn:complete`, the child driver call is still in-flight. 52 52 2. Check process liveness using `worker.pid` + OS process list. 53 53 3. `mill cancel <runId> --json`

+1 -1

docs/references/mill-v0-toolchain-and-invariants.md

reviewed

··· 164 164 3. Generic process driver + one codec (pi or claude) 165 165 4. Engine submit/status/wait/watch/cancel 166 166 5. Worker process + detached `run` 167 167 - 6. `inspect` and `--session` bridge 167 167 + 6. `watch` channel finalization + cancellation bridge 168 168 7. Extension hooks 169 169 8. Guardrail toolchain + rules/tests 170 170

+12 -33

packages/cli/src/public/index.e2e.test.ts

reviewed

··· 153 153 await writeFile( 154 154 programPath, 155 155 [ 156 156 - "const output = await mill.spawn({", 157 157 - ' agent: "scout",', 158 158 - ' systemPrompt: "You are concise.",', 159 159 - ' prompt: "Inspect repository layout.",', 160 160 - ' model: "google-gemini-cli/gemini-2.0-flash",', 161 161 - "});", 162 162 - "return output.text;", 156 156 + "await new Promise((resolve) => setTimeout(resolve, 50));", 157 157 + "return 'driver-executor-selected';", 163 158 ].join("\n"), 164 159 "utf-8", 165 160 ); ··· 186 181 const runPayload = Schema.decodeUnknownSync(RunSyncEnvelope)(runOutput); 187 182 expect(runPayload.run.driver).toBe("pi"); 188 183 expect(runPayload.run.executor).toBe("direct"); 189 189 - expect(runPayload.result.spawns[0]?.driver).toBe("pi"); 184 184 + expect(runPayload.result.spawns).toHaveLength(0); 190 185 } finally { 191 186 await rm(tempDirectory, { recursive: true, force: true }); 192 187 } ··· 200 195 await writeFile( 201 196 programPath, 202 197 [ 203 203 - "const scan = await mill.spawn({", 204 204 - ' agent: "scout",', 205 205 - ' systemPrompt: "You are concise.",', 206 206 - ' prompt: "Inspect repository layout.",', 207 207 - "});", 208 208 - "globalThis.__millAsyncProgramText = scan.text;", 198 198 + "await new Promise((resolve) => setTimeout(resolve, 150));", 199 199 + "globalThis.__millAsyncProgramText = 'async-complete';", 209 200 ].join("\n"), 210 201 "utf-8", 211 202 ); ··· 268 259 "utf-8", 269 260 ); 270 261 271 271 - expect(copiedProgram).toContain("mill.spawn"); 262 262 + expect(copiedProgram).toContain("setTimeout"); 272 263 expect(workerLog.length).toBeGreaterThan(0); 273 264 274 265 const workerExitCode = await commandExitCode( ··· 315 306 await writeFile( 316 307 programPath, 317 308 [ 318 318 - "const first = await mill.spawn({", 319 319 - ' agent: "scout",', 320 320 - ' systemPrompt: "You are concise.",', 321 321 - ' prompt: "Inspect repository layout.",', 322 322 - "});", 323 323 - "const second = await mill.spawn({", 324 324 - ' agent: "synth",', 325 325 - ' systemPrompt: "You summarize findings.",', 326 326 - " prompt: first.text,", 327 327 - "});", 328 328 - "globalThis.__millSecondText = second.text;", 309 309 + "await new Promise((resolve) => setTimeout(resolve, 80));", 310 310 + "await new Promise((resolve) => setTimeout(resolve, 80));", 311 311 + "globalThis.__millSecondText = 'sync-complete';", 329 312 ].join("\n"), 330 313 "utf-8", 331 314 ); ··· 350 333 expect(runPayload.run.driver).toBe("pi"); 351 334 expect(runPayload.run.executor).toBe("direct"); 352 335 expect(runPayload.result.status).toBe("complete"); 353 353 - expect(runPayload.result.spawns).toHaveLength(2); 336 336 + expect(runPayload.result.spawns).toHaveLength(0); 354 337 355 338 const statusOutput = await commandOutput( 356 339 Command.make( ··· 409 392 await writeFile( 410 393 completeProgramPath, 411 394 [ 412 412 - "const scan = await mill.spawn({", 413 413 - ' agent: "scout",', 414 414 - ' systemPrompt: "You are concise.",', 415 415 - ' prompt: "Inspect repository layout.",', 416 416 - "});", 417 417 - "return scan.text;", 395 395 + "await new Promise((resolve) => setTimeout(resolve, 150));", 396 396 + "return 'quick-complete';", 418 397 ].join("\n"), 419 398 "utf-8", 420 399 );