@getpipher/armory-fleet 0.16.0 → 1.0.0

package/README.md

@@ -328,7 +328,71 @@ Every workflow run is **journaled** (`workflows/journal.ts`) and **resumable**.
 - **Panel Run-action:** a 3rd `cwd` input step (task → name → cwd), prefilled with the session cwd; Enter accepts, Escape cancels.
 - **bg/scheduled + worktree cwd-isolation (#62):** the `cwd` param now scopes background and scheduled runs too — in-place bg runs pass it as the lifecycle entry cwd, and `isolation: 'worktree'`/`'auto'` resolve isolation (and create the worktree) against the **dispatch cwd's** repo, not the session's. Cross-cwd bg worktrees land in `<child-cwd>/.pi/fleet/worktrees/`.
 
-## Cross-cwd everywhere (v0.16.0)
+## Event bus + RPC (v1.0)
+
+armory-fleet publishes every run on pi's cross-extension event bus and answers an RPC verb
+set — so your own extensions can spawn, steer, observe, and abort subagents programmatically.
+
+### Event stream (broadcast, `pi.events`)
+
+Two tiers, every event enveloped as `{ runId, seq, ts, ...payload }` (`seq` = per-run
+monotonic, one space per source store):
+
+| Channel | Payload |
+|---|---|
+| `fleet:run:started` | `{ agent, model?, cwd?, sessionCwd?, mode: foreground\|background\|scheduled\|workflow, task }` |
+| `fleet:phase:started` / `completed` / `failed` | `{ phase, … }` (lifecycle runs) |
+| `fleet:run:ended` | `{ status: completed\|failed\|aborted, result?, error?, filesTouched?, toolCallCount?, durationMs? }` |
+| `fleet:child:message` | `{ role, text }` (journal excerpts) |
+| `fleet:child:tool` | `{ toolName, args, result, isError }` (one per completed tool call) |
+
+### RPC (`fleet:rpc` → `fleet:rpc:result`)
+
+Emit `{ id, verb, params }`, get exactly one reply `{ id, ok, data }` or
+`{ id, ok: false, error: { code, message } }`. Verbs: `spawn` (returns `{ runId }`
+immediately; result arrives via `fleet:run:ended`), `status`, `observe` (replay dump —
+subscribe to the broadcast channels + dedupe by `(channel, runId, seq)` for the live tail),
+`steer`, `abort`.
+
+Error codes: `E-CONTROL-DISABLED`, `E-RUN-NOT-FOUND`, `E-RUN-FINISHED`, `E-BAD-VERB`,
+`E-BAD-PARAMS`, `E-STEER-UNSUPPORTED`, `E-INTERNAL`.
+
+### Client helper (~15 lines)
+
+```ts
+type FleetReply = { id: string; ok: true; data: any } | { id: string; ok: false; error: { code: string; message: string } };
+let n = 0;
+export function fleetRpc(pi: { events: { emit(c: string, d: unknown): void; on(c: string, h: (d: unknown) => void): () => void } }) {
+  return <T = any>(verb: string, params?: Record<string, unknown>): Promise<T> => {
+    const id = `fleet-${Date.now().toString(36)}-${++n}`;
+    return new Promise<T>((resolve, reject) => {
+      const unsub = pi.events.on("fleet:rpc:result", (raw) => {
+        const r = raw as FleetReply;
+        if (r.id !== id) return;
+        unsub();
+        r.ok ? resolve(r.data as T) : reject(new Error(`${r.error.code}: ${r.error.message}`));
+      });
+      pi.events.emit("fleet:rpc", { id, verb, params });
+    });
+  };
+}
+// const rpc = fleetRpc(pi); const { runId } = await rpc("spawn", { agent: "scout", task: "look" });
+```
+
+### Control gate
+
+`spawn`/`steer`/`abort` are on by default. Set `ARMORY_FLEET_RPC_CONTROL=0` (or `false`) to
+reject them with `E-CONTROL-DISABLED`; read-only `observe`/`status` stay available. Honest
+threat model: in-process extensions already have full system access through pi itself — the
+switch guards accidents, not adversaries.
+
+### Live conversation viewer
+
+`/fleet` → Runs → open a **running** run: the timeline overlay streams the child's
+conversation as it happens (tail-follows; scroll up to read, back to the bottom to re-pin).
+Finished runs replay from the journal exactly as before.
+
+
 
 The #62 tail of SPEC-6-5: `subagent({ cwd })` now scopes **background and scheduled** runs too, not just foreground —
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpipher/armory-fleet",
-  "version": "0.16.0",
+  "version": "1.0.0",
   "private": false,
   "description": "The armory suite's subagent orchestrator for the pi coding agent — a cross-harness, superpowers-native fleet where every agent is armory-native from birth.",
   "license": "MIT",

package/src/engine/spawnSubagent.ts

@@ -132,6 +132,10 @@ export interface SpawnOptions {
   visionPort?: VisionPort;
   signal?: AbortSignal;
   onEvent?: (e: ChildSessionEvent) => void;
+  /** SPEC-6-4: pre-minted runId (RPC spawn replies before the detached spawn resolves). Absent → mint. */
+  runId?: string;
+  /** SPEC-6-4: dispatch origin for RunMetaEvent.mode. Default "foreground". */
+  mode?: "foreground" | "background" | "scheduled" | "workflow";
   /** SPEC-4: when set, this spawn is a lifecycle phase child. It links to this lifecycle todo
    *  (not creates a new one) and finishRun skips mark-done/revert — the lifecycle engine owns
    *  the lifecycle todo's status + progress block. */
@@ -241,13 +245,13 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
   const readOnly = opts.readOnly ?? false;
   let runId: string;
   if (readOnly) {
-    runId = genRunId();
+    runId = opts.runId ?? genRunId();
   } else {
     // #31 tail: foreground concurrency lock. cap=1 (default) is FAIL-FAST (backward-compat — a
     // 2nd dispatch is rejected with the held runId + the cap + the env hint); cap>1 (opt-in via
     // ARMORY_FLEET_FOREGROUND_CONCURRENCY) QUEUES — up to `cap` writes run in parallel, the rest wait.
     // The cap is session-level (a shared lock can't be re-sized per dispatch); see concurrency-lock.ts.
-    runId = genRunId();
+    runId = opts.runId ?? genRunId();
     const acq = await opts.lock.acquire(runId);
     if (!acq.ok) {
       const hint = opts.lock.cap === 1
@@ -401,7 +405,7 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
       if (e.type === "session_init" && e.backendSessionId) {
         opts.runRegistry.update(runId, { backendSessionId: e.backendSessionId, sessionKey: agentDef.sessionKey });
         try {
-          opts.runLog?.append(runId, { type: "run:meta", runId, agent: agentDef.name, model, task: opts.task, startedAt, track, todoId, backendSessionId: e.backendSessionId, sessionKey: agentDef.sessionKey, cwd: childCwd, sessionCwd: opts.parentCwd, pid: (session as { proc?: { pid?: number } }).proc?.pid });
+          opts.runLog?.append(runId, { type: "run:meta", runId, agent: agentDef.name, model, task: opts.task, startedAt, track, todoId, backendSessionId: e.backendSessionId, sessionKey: agentDef.sessionKey, cwd: childCwd, sessionCwd: opts.parentCwd, mode: opts.mode ?? "foreground", pid: (session as { proc?: { pid?: number } }).proc?.pid });
         } catch { /* best-effort */ }
       } else if (e.type === "turn_start") {
         turnIdx++;

package/src/index.ts

@@ -8,7 +8,7 @@ import {
   getAgentDir,
 } from "@earendil-works/pi-coding-agent";
 import type { Model } from "@earendil-works/pi-ai";
-import { createSubagentTool, type SubagentToolDeps } from "./tools/subagent.ts";
+import { createSubagentTool, resolveDispatchCwd, type SubagentToolDeps } from "./tools/subagent.ts";
 // SPEC-6-3: /fleet uses openWorkflowPanelLoop (Task 12) instead of the raw openFleetPanel factory.
 import { discoverAgents } from "./registry/discovery.ts";
 import { RunRegistry } from "./engine/run-registry.ts";
@@ -40,6 +40,8 @@ import { ResultsInbox } from "./runtime/results-inbox.ts";
 import { runBackground, type AsyncRunnerDeps } from "./runtime/async-runner.ts";
 import { scanResumeCandidates } from "./runtime/resume.ts";
 import { RunLog } from "./runtime/run-log.ts";
+import { FleetEventBus } from "./rpc/event-bus.ts";
+import { RpcServer } from "./rpc/rpc-server.ts";
 import { reconcileRuns } from "./runtime/reconcile.ts";
 import { Scheduler } from "./scheduling/scheduler.ts";
 import { createFleetResultsTool } from "./tools/fleet-results.ts";
@@ -263,6 +265,9 @@ export default async function (pi: ExtensionAPI): Promise<void> {
   // SPEC-5b-2: the live widget (above editor) controller.
   // Display-only, independent of the /fleet panel; constructed per-session in session_start.
   let fleetWidget: FleetWidgetController | null = null;
+  // SPEC-6-4: hoisted so session_shutdown can dispose the bus + unsubscribe fleet:rpc.
+  let fleetBus: FleetEventBus | null = null;
+  let unsubscribeRpc: (() => void) | null = null;
   // SPEC-6-3: hoisted so /fleet command handler + session_shutdown can reach them.
   let wfController: WorkflowController | null = null;
   let wfStore: WorkflowRunStore | null = null;
@@ -289,6 +294,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
       ...(isolated ? { artifactDiscovery: ({ finalText, cwd, baseRef }: { finalText: string; cwd: string; baseRef: string }) => (deps.asyncRunner as AsyncRunnerDeps).diff.diffPhase(cwd, baseRef, finalText) } : {}),
       spawn: withModelFallbackRetry(async (o) => spawnSubagent({
         agent: o.agent, task: o.task, lifecycleTodoId: o.lifecycleTodoId, model: o.model,
+        mode: opts.fleetMode ?? "background",
         skillsOverride: o.skills, backendOverride: o.backend,
         registry: deps.registry, todoSync: deps.todoSync, runRegistry: deps.runRegistry, lock: bgLock,
         backendRegistry: deps.backendRegistry, parentModel: deps.parentModel,
@@ -359,6 +365,9 @@ export default async function (pi: ExtensionAPI): Promise<void> {
     // SPEC-5b-1: per-session RunLog at .pi/fleet/conversations/ (separate from the
     // SPEC-5a phase journal at .pi/fleet/runs/ — different granularity, no filename collision).
     deps.runLog = new RunLog(join(dir, "conversations"));
+    // SPEC-6-4: ONE shared RunJournal per session — the FleetEventBus subscribes to THIS
+    // instance, so every journal append (phases AND bookends) reaches the bus exactly once.
+    const fleetJournal = new RunJournal(join(dir, "runs"));
     // v0.10.2: pass the in-memory RunRegistry so reconcile syncs it too — otherwise orphaned
     // (process-gone) runs keep status:"running" in memory and the live widget shows a stale ▶ forever.
     // #22 bg-watchdog: pass todoSync so a process-gone run's linked TODO is reverted to open
@@ -378,7 +387,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
       // service would create it from the session's repo — the #62 gap). Same-cwd → shared.
       worktreeFor: (cwd: string) => (cwd === ctx.cwd ? sessionWorktree : new WorktreeService({ rootDir: cwd })),
       diff: new DiffService(),
-      journal: new RunJournal(join(dir, "runs")),
+      journal: fleetJournal,
       pool: new ConcurrencyPool(3),
       inbox: resultsInbox,
       runLifecycle: asyncRunLifecycle,
@@ -392,7 +401,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
       lockPath: join(dir, "schedules.lock"),
       onFire: (spec) => {
         if (!deps.asyncRunner) return;
-        runBackground(spec.task, { deps: deps.asyncRunner, lifecycle: spec.lifecycle ?? "default", mode: spec.auto ? "auto" : "checkpointed", isolation: spec.isolation, cwd: spec.cwd });
+        runBackground(spec.task, { deps: deps.asyncRunner, lifecycle: spec.lifecycle ?? "default", mode: spec.auto ? "auto" : "checkpointed", isolation: spec.isolation, cwd: spec.cwd, origin: "scheduled" });
       },
     });
     deps.scheduler.start();
@@ -400,6 +409,82 @@ export default async function (pi: ExtensionAPI): Promise<void> {
     if (cands.length > 0) {
       ctx.ui.notify(`${cands.length} interrupted fleet run${cands.length > 1 ? "s" : ""} — open /fleet to resume`, "info");
     }
+    // SPEC-6-4: defensive re-entrancy — a re-entered session_start must dispose the old
+    // bus/listener BEFORE constructing new ones (dispose-after-construction kills the fresh
+    // bus at birth and orphans the previous session's subscriptions).
+    fleetBus?.dispose();
+    fleetBus = null;
+    unsubscribeRpc?.();
+    unsubscribeRpc = null;
+    // SPEC-6-4: FleetEventBus — store appends → public fleet:* events on pi.events.
+    fleetBus = new FleetEventBus({
+      runLog: deps.runLog,
+      journal: fleetJournal,
+      emit: (channel, payload) => { pi.events.emit(channel, payload); },
+    });
+    // SPEC-6-4: fleet:rpc request surface — replies on fleet:rpc:result (null replies dropped).
+    const rpcServer = new RpcServer({
+      runRegistry: deps.runRegistry,
+      runLog: deps.runLog,
+      journal: fleetJournal,
+      parentCwd: ctx.cwd,
+      hasAsyncRunner: true,
+      spawn: (params: Record<string, unknown>, runId: string) => {
+        // Detached fire-and-forget: NEVER throws — spawnSubagent journals its own fail path
+        // (run:ended + todo revert), so the caller's pre-minted runId always resolves to events.
+        void (async () => {
+          const requestedCwd = typeof params.cwd === "string" ? params.cwd : undefined;
+          const { cwd: resolvedCwd } = resolveDispatchCwd(requestedCwd, ctx.cwd);
+          if (params.background === true) {
+            // RPC background: routed through the async runner (pool slot + isolation + origin),
+            // identical to the tool's runBackground path (spec §3.2). Ghost-runId prevention:
+            // a synchronous pre-flight failure journals run:ended failed under the caller's id.
+            const handle = runBackground(String(params.task), {
+              deps: deps.asyncRunner!,
+              lifecycle: "default",
+              mode: "auto",
+              isolation: params.isolation as "worktree" | "none" | "auto" | undefined,
+              cwd: resolvedCwd ?? ctx.cwd,
+              origin: "background",
+              runId,
+            });
+            if (handle.status === "failed") {
+              deps.runLog?.append(runId, { type: "run:ended", runId, status: "failed", endedAt: Date.now(), tokenTotal: 0, error: handle.error });
+            }
+            return;
+          }
+          // Foreground-semantics detached spawn (no mode — "foreground" is the truth).
+          const { spawnSubagent } = await import("./engine/spawnSubagent.ts");
+          await spawnSubagent({
+            agent: params.agent as string,
+            task: params.task as string,
+            todoId: typeof params.todoId === "string" ? params.todoId : undefined,
+            track: params.track === true,
+            model: typeof params.model === "string" ? params.model : undefined,
+            readOnly: params.readOnly === true,
+            skillsOverride: Array.isArray(params.skills) ? params.skills as string[] : undefined,
+            registry: deps.registry,
+            todoSync: deps.todoSync,
+            runRegistry: deps.runRegistry,
+            lock: deps.lock,
+            backendRegistry: deps.backendRegistry,
+            parentModel: deps.parentModel,
+            parentCwd: ctx.cwd,
+            runLog: deps.runLog,
+            maxTurns: typeof params.maxTurns === "number" ? params.maxTurns : undefined,
+            tierRegistry: deps.tierRegistry,
+            modelRegistry: deps.modelRegistry,
+            cwd: resolvedCwd ?? ctx.cwd,
+            runId,
+          });
+        })().catch(() => {});
+      },
+    });
+    unsubscribeRpc = pi.events.on("fleet:rpc", (data: unknown) => {
+      void rpcServer.handle(data).then((reply) => {
+        if (reply) pi.events.emit("fleet:rpc:result", reply);
+      });
+    });
     // SPEC-5b-2: live widget (above editor). Display-only, independent
     // of the /fleet panel. getTheme is a live getter (EditorTheme gotcha). Disposed on session end.
     const getModelContextWindow = (m: string): number | undefined => {
@@ -501,6 +586,11 @@ export default async function (pi: ExtensionAPI): Promise<void> {
   });
 
   pi.on("session_shutdown", () => {
+    // SPEC-6-4: dispose the event bus + unsubscribe fleet:rpc before the other resets.
+    fleetBus?.dispose();
+    fleetBus = null;
+    unsubscribeRpc?.();
+    unsubscribeRpc = null;
     if (fleetWidget) { fleetWidget.dispose(); fleetWidget = null; }
     // SPEC-6-3: abort in-flight workflow children via the session-wide adapter signal.
     // Terminal runs are not re-journaled — only non-terminal spawns observe the abort.
@@ -582,6 +672,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
         ...deps.lifecycleDeps,
         spawn: withModelFallbackRetry(async (o) => spawnSubagent({
           agent: o.agent, task: o.task, lifecycleTodoId: o.lifecycleTodoId, model: o.model,
+          mode: "workflow",
             skillsOverride: o.skills, backendOverride: o.backend,
           registry: deps.registry, todoSync: deps.todoSync, runRegistry: deps.runRegistry, lock: deps.lock,
           backendRegistry: deps.backendRegistry, parentModel: deps.parentModel, parentCwd: deps.parentCwd,

package/src/panel/fleet-panel.ts

@@ -16,6 +16,7 @@ import { runsRow, runTimelineRow } from "./runs-rows.ts";
 import { messageBody, toolBody, messageHeader, toolHeader } from "./conversation-rows.ts";
 import { buildRunsIndex } from "./runs-index.ts";
 import type { RunLog, RunMeta, RunLogEvent, MessageEvent, ToolEvent } from "../runtime/run-log.ts";
+import { LiveTimelineState } from "./live-timeline.ts";
 import type { Scheduler, Schedule } from "../scheduling/scheduler.ts";
 import type { BgRunsStore } from "./bg-runs-store.ts";
 import { spawnSubagent, type SpawnResult } from "../engine/spawnSubagent.ts";
@@ -132,6 +133,43 @@ export class FleetPanel extends Container {
    * so the panel re-renders the moment a (fore- or back-ground) run mutates, without a keypress. */
   private readonly unsubs: (() => void)[] = [];
   private closed = false;   // SPEC-5a proper-fix: guard against double-close calling onDone twice
+  // SPEC-6-4: live mode for the timeline overlay (running runs stream; finished runs replay).
+  private liveUnsub: (() => void) | null = null;
+  private liveState: LiveTimelineState | null = null;
+
+  private renderedTimelineCount(): number {
+    return (this.runTimeline ?? []).filter((e) => e.type === "message" || e.type === "tool").length;
+  }
+
+  /** SPEC-6-4: release the live subscription (overlay close / different run / panel close). */
+  private releaseLiveTimeline(): void {
+    this.liveUnsub?.();
+    this.liveUnsub = null;
+    this.liveState = null;
+  }
+
+  /** SPEC-6-4: shared timeline-open (Runs view + gate evidence). Hydrates replay; LIVE when the
+   *  run is still running — subscribes to appends and tail-follows via LiveTimelineState. */
+  private openRunTimeline(runId: string): void {
+    const runLog = this.deps.runLog;
+    if (!runLog) return;
+    const meta = buildRunsIndex(runLog.dir).find((r) => r.runId === runId) ?? null;
+    this.selectedRun = meta;
+    this.runTimeline = runLog.replay(runId);
+    this.releaseLiveTimeline();
+    if (meta?.status === "running") {
+      this.liveState = new LiveTimelineState();
+      this.liveState.index = Math.max(0, this.renderedTimelineCount() - 1);
+      this.liveUnsub = runLog.subscribe((rid, ev) => {
+        if (rid !== runId || (ev.type !== "message" && ev.type !== "tool")) return;
+        this.runTimeline = [...(this.runTimeline ?? []), ev];
+        const idx = this.liveState?.append(this.renderedTimelineCount());
+        this.selectedEventIndex = idx ?? null;
+        this.renderShell();
+      });
+    }
+    this.renderShell();
+  }
   // SPEC-6-3: Workflows view — inline Run prompt input state
   private wfRunMode = false;
   private wfPromptInput: Input | null = null;
@@ -205,6 +243,8 @@ export class FleetPanel extends Container {
     this.closed = true;
     for (const u of this.unsubs) u();
     this.unsubs.length = 0;
+    // SPEC-6-4: the live timeline subscription dies with the panel.
+    this.releaseLiveTimeline();
     this.onDone(intent ?? null);
   }
 
@@ -324,7 +364,7 @@ export class FleetPanel extends Container {
           this.selectedEventIndex = null;
         }
         // esc → back to Runs list (replaces the v0.6.0 panel-level escape catch).
-        tl.onCancel = () => { this.selectedRun = null; this.runTimeline = null; this.timelineList = null; this.renderShell(); };
+        tl.onCancel = () => { this.releaseLiveTimeline(); this.selectedRun = null; this.runTimeline = null; this.timelineList = null; this.renderShell(); };
         this.timelineList = tl;
         this.addChild(tl);
       }
@@ -512,8 +552,7 @@ export class FleetPanel extends Container {
           .flatMap((p) => p.gateResults ?? [])
           .find((gr) => gr.runId);
         if (agentGate?.runId && this.deps.runLog) {
-          this.selectedRun = buildRunsIndex(this.deps.runLog.dir).find((r) => r.runId === agentGate.runId) ?? null;
-          this.runTimeline = this.deps.runLog.replay(agentGate.runId);
+          this.openRunTimeline(agentGate.runId);
           this.selectedLifecycle = null;
           this.view = "runs";
           this.renderShell();
@@ -555,8 +594,17 @@ export class FleetPanel extends Container {
       return;
     }
     if (this.selectedRun) {
-      // SPEC-5b-3: forward to the timeline SelectList (arrows scroll; enter via onSelect opens the
-      // overlay; esc via onCancel returns to the Runs list). v0.6.0 swallowed all non-escape keys.
+      // SPEC-6-4: in live mode the panel owns up/down (tail-follow cursor) — intercepted before
+      // the SelectList forward; everything else forwards as before. Finished runs: replay path.
+      if (this.liveState && (matchesKey(data, "up") || matchesKey(data, "down"))) {
+        const total = this.renderedTimelineCount();
+        const key = matchesKey(data, "up") ? "up" : "down";
+        if (this.liveState.onKey(key, total)) {
+          this.selectedEventIndex = this.liveState.index;
+          this.renderShell();
+        }
+        return;
+      }
       this.timelineList?.handleInput(data);
       this.invalidate();
       return;
@@ -645,9 +693,7 @@ export class FleetPanel extends Container {
       if (matchesKey(data, "enter") || matchesKey(data, "i")) {
         const sel = this.list.getSelectedItem();
         if (sel) {
-          this.selectedRun = buildRunsIndex(this.deps.runLog.dir).find((r) => r.runId === sel.value) ?? null;
-          this.runTimeline = this.deps.runLog.replay(sel.value);
-          this.renderShell();
+          this.openRunTimeline(sel.value);
         }
         return;
       }

package/src/panel/live-timeline.ts

@@ -0,0 +1,32 @@
+// src/panel/live-timeline.ts
+// SPEC-6-4 — tail-follow state for the live timeline overlay. Pure logic (unit-tested);
+// the panel owns the SelectList and consults this on forwarded keys + live appends.
+export class LiveTimelineState {
+  /** 0-based cursor into the RENDERED (message/tool-filtered) event list. */
+  index = 0;
+  /** True while the cursor rides the newest row (live appends move the view). */
+  pinned = true;
+
+  /** Handle a forwarded scroll key. Returns true when the view must re-render. */
+  onKey(key: "up" | "down", total: number): boolean {
+    if (total === 0) return false;
+    if (key === "up") {
+      if (this.index <= 0) return false;
+      this.index--;
+      this.pinned = false;
+      return true;
+    }
+    // down
+    if (this.index >= total - 1) return false;
+    this.index++;
+    this.pinned = this.index === total - 1;
+    return true;
+  }
+
+  /** A new event arrived (list now has `total` rendered rows). Returns the cursor to restore:
+   *  the newest row while pinned, unchanged otherwise. */
+  append(total: number): number {
+    if (this.pinned) this.index = total - 1;
+    return this.index;
+  }
+}

package/src/rpc/event-bus.ts

@@ -0,0 +1,105 @@
+// src/rpc/event-bus.ts
+// SPEC-6-4 — FleetEventBus: translates RunLog/RunJournal appends into the public fleet:*
+// taxonomy. THE FROZEN SURFACE LIVES HERE: channel names + envelope shapes are pinned by
+// test/fleet-event-bus.test.mts — change them and every consumer breaks loudly.
+//
+// Seq spaces: one per source store (RunLog event order / journal event order), per run.
+// Replay (RpcServer) reconstructs identical seqs by walking the same orders — consumers
+// dedupe live-vs-replay by (channel, runId, seq).
+import type { RunJournal, JournalEvent } from "../runtime/run-journal.ts";
+import type { RunLog, RunLogEvent } from "../runtime/run-log.ts";
+
+export type FleetChannel =
+  | "fleet:run:started" | "fleet:run:ended"
+  | "fleet:phase:started" | "fleet:phase:completed" | "fleet:phase:failed"
+  | "fleet:child:message" | "fleet:child:tool";
+
+export interface FleetEnvelope {
+  runId: string;
+  seq: number;
+  /** Publish time (Date.now() at translation) — not the event's own timestamp. */
+  ts: number;
+  [key: string]: unknown;
+}
+
+export interface FleetEventBusDeps {
+  runLog: Pick<RunLog, "subscribe">;
+  journal: Pick<RunJournal, "subscribe">;
+  /** Transport seam. In-process = (c, p) => pi.events.emit(c, p). A future external bridge
+   *  re-implements ONLY this — the taxonomy above is its wire format. */
+  emit: (channel: FleetChannel, payload: FleetEnvelope) => void;
+}
+
+interface MetaLike { startedAt: number }
+
+export class FleetEventBus {
+  private readonly runSeq = new Map<string, number>();
+  private readonly phaseSeq = new Map<string, number>();
+  private readonly startedAt = new Map<string, number>();
+  private readonly unsubs: Array<() => void> = [];
+
+  constructor(private readonly deps: FleetEventBusDeps) {
+    this.unsubs.push(
+      deps.runLog.subscribe((runId, event) => this.safe(() => this.onRunLogEvent(runId, event))),
+      deps.journal.subscribe((runId, event) => this.safe(() => this.onJournalEvent(runId, event))),
+    );
+  }
+
+  /** Unsubscribe from both stores. Call from session_shutdown. */
+  dispose(): void {
+    for (const u of this.unsubs) u();
+    this.unsubs.length = 0;
+  }
+
+  /** A bus failure must never break a run's append path. */
+  private safe(fn: () => void): void {
+    try { fn(); } catch { /* swallow: telemetry must not kill the product */ }
+  }
+
+  private next(map: Map<string, number>, runId: string): number {
+    const n = (map.get(runId) ?? 0) + 1;
+    map.set(runId, n);
+    return n;
+  }
+
+  private publish(channel: FleetChannel, runId: string, seq: number, payload: Record<string, unknown>): void {
+    this.deps.emit(channel, { runId, seq, ts: Date.now(), ...payload });
+  }
+
+  private onRunLogEvent(runId: string, e: RunLogEvent): void {
+    const seq = this.next(this.runSeq, runId);
+    if (e.type === "run:meta") {
+      this.startedAt.set(runId, e.startedAt);
+      this.publish("fleet:run:started", runId, seq, {
+        agent: e.agent, model: e.model, cwd: e.cwd, sessionCwd: e.sessionCwd,
+        mode: e.mode ?? "foreground", task: e.task,
+      });
+    } else if (e.type === "message") {
+      this.publish("fleet:child:message", runId, seq, { role: e.role, text: e.text });
+    } else if (e.type === "tool") {
+      this.publish("fleet:child:tool", runId, seq, { toolName: e.toolName, args: e.args, result: e.result, isError: e.isError });
+    } else if (e.type === "run:ended") {
+      const start = this.startedAt.get(runId);
+      this.publish("fleet:run:ended", runId, seq, {
+        status: e.status,
+        ...(e.resultSummary !== undefined ? { result: e.resultSummary } : {}),
+        ...(e.error !== undefined ? { error: e.error } : {}),
+        ...(e.filesTouched !== undefined ? { filesTouched: e.filesTouched } : {}),
+        ...(e.toolCallCount !== undefined ? { toolCallCount: e.toolCallCount } : {}),
+        ...(start !== undefined ? { durationMs: e.endedAt - start } : {}),
+      });
+    }
+  }
+
+  private onJournalEvent(runId: string, e: JournalEvent): void {
+    // Only the phase tier is public; run:started/completed/aborted/checkpoint/agent:*/helper:*
+    // stay internal (run-level events come from RunLog, which every spawn writes).
+    if (e.type === "phase:started") {
+      this.publish("fleet:phase:started", runId, this.next(this.phaseSeq, runId), { phase: e.phase });
+    } else if (e.type === "phase:completed") {
+      this.publish("fleet:phase:completed", runId, this.next(this.phaseSeq, runId), { phase: e.phase, summary: e.summary, paths: e.paths });
+    } else if (e.type === "phase:failed") {
+      this.publish("fleet:phase:failed", runId, this.next(this.phaseSeq, runId), { phase: e.phase, error: e.error });
+    }
+  }
+}

package/src/rpc/rpc-server.ts

@@ -0,0 +1,244 @@
+// src/rpc/rpc-server.ts
+// SPEC-6-4 — the fleet:rpc verb surface. Frozen: verb names, param contracts, reply envelope
+// { id, ok, data | error{code,message} }, and the error-code enum — all pinned by
+// test/rpc-server.test.mts. handle() NEVER throws and replies EXACTLY once per request.
+import { genRunId } from "../engine/run-registry.ts";
+import type { RunRegistry, RunRecord } from "../engine/run-registry.ts";
+import type { RunLog } from "../runtime/run-log.ts";
+import type { RunJournal } from "../runtime/run-journal.ts";
+import { resolveDispatchCwd } from "../tools/subagent.ts";
+
+export type RpcErrorCode =
+  | "E-CONTROL-DISABLED" | "E-RUN-NOT-FOUND" | "E-RUN-FINISHED" | "E-BAD-VERB"
+  | "E-BAD-PARAMS" | "E-STEER-UNSUPPORTED" | "E-INTERNAL";
+
+export interface RpcRequest { id: string; verb: string; params?: unknown }
+export type RpcReply =
+  | { id: string; ok: true; data: unknown }
+  | { id: string; ok: false; error: { code: RpcErrorCode; message: string } };
+
+/** SPEC-6-4 gate: ON unless ARMORY_FLEET_RPC_CONTROL is "0"/"false" (case-insensitive).
+ *  Read-only verbs (observe/status) ignore this. Honest threat model: in-process extensions
+ *  already have full system access via pi itself — the gate guards accidents, not adversaries. */
+export function rpcControlEnabled(env: string | undefined = process.env.ARMORY_FLEET_RPC_CONTROL): boolean {
+  const v = (env ?? "").trim().toLowerCase();
+  return !(v === "0" || v === "false");
+}
+
+export interface RpcRunSummary {
+  runId: string; agent: string; model: string; status: string; startedAt: number;
+  endedAt?: number; task: string; cwd?: string; resultSummary?: string; tokenTotal?: number; sessionKey?: string;
+}
+
+export interface RpcServerDeps {
+  runRegistry: Pick<RunRegistry, "get" | "list">;
+  runLog: Pick<RunLog, "replay">;
+  journal: Pick<RunJournal, "replay">;
+  parentCwd: string;
+  hasAsyncRunner: boolean;
+  /** Detached spawn: index.ts builds the real spawnSubagent invocation (foreground or bg routing).
+   *  Never throws — runtime failures land via the registry + RunLog journal (spawnSubagent's own
+   *  fail path journals run:ended), so the caller's { runId } always resolves to a real run. */
+  spawn: (params: Record<string, unknown>, runId: string) => void;
+}
+
+const LIST_CAP = 25;
+const TASK_SUMMARY_CAP = 80;
+
+function summarize(r: RunRecord): RpcRunSummary {
+  const task = r.task.length > TASK_SUMMARY_CAP ? r.task.slice(0, TASK_SUMMARY_CAP - 1) + "…" : r.task;
+  return {
+    runId: r.runId, agent: r.agent, model: r.model, status: r.status, startedAt: r.startedAt,
+    ...(r.endedAt !== undefined ? { endedAt: r.endedAt } : {}),
+    task, ...(r.cwd ? { cwd: r.cwd } : {}),
+    ...(r.resultSummary !== undefined ? { resultSummary: r.resultSummary } : {}),
+    ...(r.tokenTotal !== undefined ? { tokenTotal: r.tokenTotal } : {}),
+    ...(r.sessionKey ? { sessionKey: r.sessionKey } : {}),
+  };
+}
+
+export class RpcServer {
+  constructor(
+    private readonly deps: RpcServerDeps,
+    private readonly controlEnabled: () => boolean = rpcControlEnabled,
+  ) {}
+
+  /** Returns the reply, or null for a malformed request with no usable id (caller drops).
+   *  Never throws — a handler exception becomes E-INTERNAL. */
+  async handle(req: unknown): Promise<RpcReply | null> {
+    const id = requestId(req);
+    try {
+      return await this.dispatch(req, id);
+    } catch (e) {
+      if (!id) return null;
+      return { id, ok: false, error: { code: "E-INTERNAL", message: `unexpected rpc failure: ${(e as Error).message}` } };
+    }
+  }
+
+  private async dispatch(req: unknown, id: string | null): Promise<RpcReply | null> {
+    if (!req || typeof req !== "object" || !id) return null;
+    const { verb, params } = req as Record<string, unknown>;
+    if (typeof verb !== "string") return this.err(id, "E-BAD-VERB", "missing verb");
+    const gated = this.controlEnabled();
+    switch (verb) {
+      case "spawn": return gated ? this.spawnVerb(id, params) : this.controlDisabled(id);
+      case "steer": return gated ? this.steerVerb(id, params) : this.controlDisabled(id);
+      case "abort": return gated ? this.abortVerb(id, params) : this.controlDisabled(id);
+      case "observe": return this.observeVerb(id, params);
+      case "status": return this.statusVerb(id, params);
+      default: return this.err(id, "E-BAD-VERB", `unknown verb '${verb}' (known: spawn, steer, observe, abort, status)`);
+    }
+  }
+
+  private controlDisabled(id: string): RpcReply {
+    return this.err(id, "E-CONTROL-DISABLED", "fleet rpc control is disabled (ARMORY_FLEET_RPC_CONTROL is set to off; remove it or set it to 1 to enable spawn/steer/abort)");
+  }
+
+  private err(id: string, code: RpcErrorCode, message: string): RpcReply {
+    return { id, ok: false, error: { code, message } };
+  }
+
+  private obj(params: unknown): Record<string, unknown> | null {
+    return params && typeof params === "object" ? params as Record<string, unknown> : null;
+  }
+
+  private spawnVerb(id: string, params: unknown): RpcReply {
+    const p = this.obj(params);
+    if (!p) return this.err(id, "E-BAD-PARAMS", "spawn requires params: { agent, task, ... }");
+    if (typeof p.agent !== "string" || !p.agent) return this.err(id, "E-BAD-PARAMS", "params.agent must be a non-empty string");
+    if (typeof p.task !== "string" || !p.task) return this.err(id, "E-BAD-PARAMS", "params.task must be a non-empty string");
+    if (p.lifecycle !== undefined) return this.err(id, "E-BAD-PARAMS", "params.lifecycle is not supported over RPC spawn yet (single-delegate + background only — spec §7)");
+    if (p.schedule !== undefined) return this.err(id, "E-BAD-PARAMS", "params.schedule is not supported over RPC spawn yet");
+    if (p.modelFallback !== undefined) return this.err(id, "E-BAD-PARAMS", "params.modelFallback is not supported over RPC spawn yet");
+    if (p.cwd !== undefined && (typeof p.cwd !== "string" || p.cwd === "")) return this.err(id, "E-BAD-PARAMS", "params.cwd must be a non-empty string when set");
+    if (p.cwd !== undefined) {
+      const { error } = resolveDispatchCwd(p.cwd, this.deps.parentCwd);
+      if (error) return this.err(id, "E-BAD-PARAMS", error);
+    }
+    if (p.background !== undefined && typeof p.background !== "boolean") return this.err(id, "E-BAD-PARAMS", "params.background must be a boolean");
+    if (p.background && !this.deps.hasAsyncRunner) return this.err(id, "E-BAD-PARAMS", "background runs not configured in this session (asyncRunner missing)");
+    if (p.isolation !== undefined && p.isolation !== "worktree" && p.isolation !== "none" && p.isolation !== "auto") {
+      return this.err(id, "E-BAD-PARAMS", "params.isolation must be 'worktree' | 'none' | 'auto'");
+    }
+    if (p.maxTurns !== undefined && (typeof p.maxTurns !== "number" || !Number.isInteger(p.maxTurns) || p.maxTurns < 1)) {
+      return this.err(id, "E-BAD-PARAMS", "params.maxTurns must be a positive integer");
+    }
+    if (p.readOnly !== undefined && typeof p.readOnly !== "boolean") return this.err(id, "E-BAD-PARAMS", "params.readOnly must be a boolean");
+    if (p.track !== undefined && typeof p.track !== "boolean") return this.err(id, "E-BAD-PARAMS", "params.track must be a boolean");
+    if (p.todoId !== undefined && typeof p.todoId !== "string") return this.err(id, "E-BAD-PARAMS", "params.todoId must be a string");
+    if (p.model !== undefined && (typeof p.model !== "string" || !p.model)) return this.err(id, "E-BAD-PARAMS", "params.model must be a non-empty string when set");
+    if (p.skills !== undefined && (!Array.isArray(p.skills) || !p.skills.every((s) => typeof s === "string"))) {
+      return this.err(id, "E-BAD-PARAMS", "params.skills must be an array of strings");
+    }
+    const runId = genRunId();
+    this.deps.spawn(p, runId);
+    return { id, ok: true, data: { runId } };
+  }
+
+  private statusVerb(id: string, params: unknown): RpcReply {
+    const p = this.obj(params) ?? {};
+    if (p.runId !== undefined) {
+      if (typeof p.runId !== "string" || !p.runId) return this.err(id, "E-BAD-PARAMS", "params.runId must be a non-empty string");
+      const rec = this.deps.runRegistry.get(p.runId);
+      if (!rec) return this.err(id, "E-RUN-NOT-FOUND", `no live run '${p.runId}' in the registry (finished runs older than the session are not listed)`);
+      return { id, ok: true, data: { runs: [summarize(rec)] } };
+    }
+    const runs = this.deps.runRegistry.list().slice(0, LIST_CAP).map(summarize);
+    return { id, ok: true, data: { runs } };
+  }
+
+  private observeVerb(id: string, params: unknown): RpcReply {
+    const p = this.obj(params);
+    if (!p) return this.err(id, "E-BAD-PARAMS", "observe requires params: { runId, tier? }");
+    if (typeof p.runId !== "string" || !p.runId) return this.err(id, "E-BAD-PARAMS", "params.runId must be a non-empty string");
+    const tier = p.tier ?? "both";
+    if (tier !== "lifecycle" && tier !== "child" && tier !== "both") {
+      return this.err(id, "E-BAD-PARAMS", "params.tier must be 'lifecycle' | 'child' | 'both'");
+    }
+    const logEvents = this.deps.runLog.replay(p.runId);
+    const journalEvents = this.deps.journal.replay(p.runId);
+    if (logEvents.length === 0 && journalEvents.length === 0) {
+      return this.err(id, "E-RUN-NOT-FOUND", `no journaled run '${p.runId}'`);
+    }
+    const events: Array<{ channel: string; payload: Record<string, unknown> }> = [];
+    // Seq = position in the FULL store event list (index + 1) — identical to the live bus's
+    // per-store dense counting, so the (channel, runId, seq) dedupe contract holds across
+    // the live→replay handoff. Tier filters decide WHICH entries emit, not how they count.
+    // Journal exception: the live bus increments phaseSeq ONLY on the three phase types, so
+    // replay filters to phases BEFORE counting — real lifecycle runs bookend the journal with
+    // run:started/completed, and position-in-full-list would overshoot by the bookends.
+    const phases = journalEvents.filter((e) => e.type === "phase:started" || e.type === "phase:completed" || e.type === "phase:failed");
+    if (tier === "lifecycle" || tier === "both") {
+      logEvents.forEach((e, i) => {
+        if (e.type === "run:meta") {
+          events.push({ channel: "fleet:run:started", payload: { seq: i + 1, agent: e.agent, model: e.model, cwd: e.cwd, sessionCwd: e.sessionCwd, mode: e.mode ?? "foreground", task: e.task, ts: e.startedAt } });
+        } else if (e.type === "run:ended") {
+          events.push({
+            channel: "fleet:run:ended",
+            payload: { seq: i + 1, status: e.status, ts: e.endedAt,
+              ...(e.resultSummary !== undefined ? { result: e.resultSummary } : {}),
+              ...(e.error !== undefined ? { error: e.error } : {}),
+              ...(e.filesTouched !== undefined ? { filesTouched: e.filesTouched } : {}),
+              ...(e.toolCallCount !== undefined ? { toolCallCount: e.toolCallCount } : {}) },
+          });
+        }
+      });
+      phases.forEach((e, i) => {
+        if (e.type === "phase:started") events.push({ channel: "fleet:phase:started", payload: { seq: i + 1, phase: e.phase, ts: e.ts } });
+        else if (e.type === "phase:completed") events.push({ channel: "fleet:phase:completed", payload: { seq: i + 1, phase: e.phase, summary: e.summary, paths: e.paths, ts: e.ts } });
+        else if (e.type === "phase:failed") events.push({ channel: "fleet:phase:failed", payload: { seq: i + 1, phase: e.phase, error: e.error, ts: e.ts } });
+      });
+    }
+    if (tier === "child" || tier === "both") {
+      logEvents.forEach((e, i) => {
+        if (e.type === "message") events.push({ channel: "fleet:child:message", payload: { seq: i + 1, role: e.role, text: e.text } });
+        else if (e.type === "tool") events.push({ channel: "fleet:child:tool", payload: { seq: i + 1, toolName: e.toolName, args: e.args, result: e.result, isError: e.isError } });
+      });
+    }
+    return { id, ok: true, data: { runId: p.runId, tier, events } };
+  }
+
+  private async steerVerb(id: string, params: unknown): Promise<RpcReply> {
+    const p = this.obj(params);
+    if (!p) return this.err(id, "E-BAD-PARAMS", "steer requires params: { runId, message }");
+    if (typeof p.runId !== "string" || !p.runId) return this.err(id, "E-BAD-PARAMS", "params.runId must be a non-empty string");
+    if (typeof p.message !== "string" || !p.message) return this.err(id, "E-BAD-PARAMS", "params.message must be a non-empty string");
+    const rec = this.deps.runRegistry.get(p.runId);
+    if (!rec) return this.err(id, "E-RUN-NOT-FOUND", `no live run '${p.runId}' in the registry`);
+    const session = rec.session;
+    if (!session) return this.err(id, "E-RUN-FINISHED", `run '${p.runId}' has no live session (status: ${rec.status})`);
+    if (!session.supportsSteer) return this.err(id, "E-STEER-UNSUPPORTED", `run '${p.runId}' backend has no steer support (claude children)`);
+    try {
+      await session.steer(p.message);
+    } catch (e) {
+      const msg = (e as Error).message ?? "steer failed";
+      if (msg.includes("not supported")) return this.err(id, "E-STEER-UNSUPPORTED", msg);
+      return this.err(id, "E-INTERNAL", `steer failed: ${msg}`);
+    }
+    return { id, ok: true, data: { steered: true } };
+  }
+
+  private async abortVerb(id: string, params: unknown): Promise<RpcReply> {
+    const p = this.obj(params);
+    if (!p) return this.err(id, "E-BAD-PARAMS", "abort requires params: { runId }");
+    if (typeof p.runId !== "string" || !p.runId) return this.err(id, "E-BAD-PARAMS", "params.runId must be a non-empty string");
+    const rec = this.deps.runRegistry.get(p.runId);
+    if (!rec) return this.err(id, "E-RUN-NOT-FOUND", `no live run '${p.runId}' in the registry`);
+    const session = rec.session;
+    if (!session) return this.err(id, "E-RUN-FINISHED", `run '${p.runId}' has no live session (status: ${rec.status})`);
+    try {
+      await session.abort();
+    } catch (e) {
+      const msg = (e as Error).message ?? "abort failed";
+      if (msg.includes("already")) return this.err(id, "E-RUN-FINISHED", msg);
+      return this.err(id, "E-INTERNAL", `abort failed: ${msg}`);
+    }
+    return { id, ok: true, data: { aborted: true } };
+  }
+}
+
+function requestId(req: unknown): string | null {
+  if (!req || typeof req !== "object") return null;
+  const id = (req as Record<string, unknown>).id;
+  return typeof id === "string" && id !== "" ? id : null;
+}

package/src/runtime/async-runner.ts

@@ -26,6 +26,8 @@ export interface RunLifecycleOpts {
   worktreePath?: string;
   branch?: string;
   mode: "auto" | "checkpointed";
+  /** SPEC-6-4: origin threading to the bg lifecycle spawn adapter (→ spawnSubagent mode → run:meta). */
+  fleetMode?: "background" | "scheduled";
   /** #62: the dispatch target cwd for in-place runs (isolated runs pass the worktree path).
    *  Flows into runLifecycle's SPEC-6-5 cwd resolution (lifecycle.cwd ?? entryCwd). */
   entryCwd?: string;
@@ -57,6 +59,11 @@ export interface RunBackgroundOpts {
   deps: AsyncRunnerDeps;
   lifecycle: string;
   mode: "auto" | "checkpointed";
+  /** SPEC-6-4: dispatch origin for fleet:run:started `mode`. "scheduled" when fired by the scheduler. */
+  origin?: "background" | "scheduled";
+  /** SPEC-6-4: pre-minted runId (RPC spawn replies with the id BEFORE the detached bg run starts).
+   *  Absent → the runner mints via deps.genRunId() exactly as before. */
+  runId?: string;
   /** v0.11.1: edit isolation for background runs. Default "auto" (worktree when cwd is a git repo, in-place otherwise). */
   isolation?: Isolation;
   /** #62: the dispatch target cwd (undefined = session cwd, back-compat). Scopes the run:
@@ -113,7 +120,7 @@ function runBackgroundInPlace(runId: string, task: string, opts: RunBackgroundOp
       deps.journal.append(runId, ev0);
       emitProgress(deps, runId, { status: "running", phase: "", phaseIndex: 0, phaseTotal: 0, lifecycle: opts.lifecycle, mode: opts.mode, task });
 
-      const res = await deps.runLifecycle(task, opts.lifecycle, { runId, worktreePath: isolated?.worktreePath, branch: isolated?.branch, mode: opts.mode, entryCwd: isolated ? isolated.worktreePath : opts.cwd });
+      const res = await deps.runLifecycle(task, opts.lifecycle, { runId, worktreePath: isolated?.worktreePath, branch: isolated?.branch, mode: opts.mode, entryCwd: isolated ? isolated.worktreePath : opts.cwd, fleetMode: opts.origin ?? "background" });
 
       if (res.status === "completed") {
         if (isolated) {
@@ -158,7 +165,7 @@ function runBackgroundIsolated(task: string, opts: RunBackgroundOpts): RunBackgr
   if (!worktree.isGitRepo()) {
     return { status: "failed", error: "isolation: 'worktree' requires a git repo; cwd is not one — use isolation: 'none' or run in a git repo" };
   }
-  const runId = opts.deps.genRunId();
+  const runId = opts.runId ?? opts.deps.genRunId();
   const baseRef = "HEAD";
   let wt: { path: string; branch: string };
   try {
@@ -180,7 +187,7 @@ function runBackgroundAuto(task: string, opts: RunBackgroundOpts): RunBackground
     inPlaceFallbackWarned = true;
     opts.deps.notify("background run in-place (no worktree isolation — parallel edits may conflict)", "warning");
   }
-  const runId = opts.deps.genRunId();
+  const runId = opts.runId ?? opts.deps.genRunId();
   runBackgroundInPlace(runId, task, opts, undefined, worktreeFor(opts.deps, opts.cwd));
   return { runId, status: "background" };
 }
@@ -190,7 +197,7 @@ export function runBackground(task: string, opts: RunBackgroundOpts): RunBackgro
   const isolation = opts.isolation ?? "auto";
   if (isolation === "worktree") return runBackgroundIsolated(task, opts);
   if (isolation === "none") {
-    const runId = opts.deps.genRunId();
+    const runId = opts.runId ?? opts.deps.genRunId();
     runBackgroundInPlace(runId, task, opts, undefined, worktreeFor(opts.deps, opts.cwd));
     return { runId, status: "background" };
   }

package/src/runtime/run-journal.ts

@@ -25,9 +25,20 @@ export class RunJournal {
     return join(this.dir, `${runId}.jsonl`);
   }
 
+  /** SPEC-6-4: append fan-out (FleetEventBus phase tier). Same contract as RunLog.subscribe. */
+  private readonly subscribers = new Set<(runId: string, event: JournalEvent) => void>();
+
+  subscribe(fn: (runId: string, event: JournalEvent) => void): () => void {
+    this.subscribers.add(fn);
+    return () => { this.subscribers.delete(fn); };
+  }
+
   append(runId: string, event: JournalEvent): void {
     mkdirSync(this.dir, { recursive: true });
     appendFileSync(this.file(runId), JSON.stringify(event) + "\n", "utf8");
+    for (const fn of this.subscribers) {
+      try { fn(runId, event); } catch { /* a faulty subscriber must not fail the append or others */ }
+    }
   }
 
   replay(runId: string): JournalEvent[] {

package/src/runtime/run-log.ts

@@ -17,6 +17,8 @@ export interface RunMetaEvent {
   cwd?: string;
   /** SPEC-6-5: the session cwd the dispatch originated from (= parentCwd). */
   sessionCwd?: string;
+  /** SPEC-6-4: dispatch origin — fleet:run:started `mode`. Default "foreground". */
+  mode?: "foreground" | "background" | "scheduled" | "workflow";
 }
 export interface MessageEvent {
   type: "message"; role: string; text: string;
@@ -77,12 +79,25 @@ export class RunLog {
 
   private file(runId: string): string { return join(this.dir, `${runId}.jsonl`); }
 
+  /** SPEC-6-4: append fan-out (the FleetEventBus + live overlay subscribe). Fired synchronously
+   *  after a successful write, in append order. A throwing subscriber never fails the append. */
+  private readonly subscribers = new Set<(runId: string, event: RunLogEvent) => void>();
+
+  subscribe(fn: (runId: string, event: RunLogEvent) => void): () => void {
+    this.subscribers.add(fn);
+    return () => { this.subscribers.delete(fn); };
+  }
+
   append(runId: string, event: RunLogEvent): void {
     try {
       mkdirSync(this.dir, { recursive: true });
       appendFileSync(this.file(runId), JSON.stringify(event) + "\n", "utf8");
     } catch {
       // best-effort: the run is the product; the journal is the index. Never fail the run.
+      return;
+    }
+    for (const fn of this.subscribers) {
+      try { fn(runId, event); } catch { /* a faulty subscriber must not fail the append or others */ }
     }
   }