@getpipher/armory-fleet 0.16.0 → 1.1.0

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,284 @@
+// 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;
+  /** #83: schedule registration (scheduler.register under the hood). Throws on an invalid
+   *  expression (surfaced as E-BAD-PARAMS); absent = scheduling not configured in this session. */
+  schedule?: (spec: Record<string, unknown>) => { scheduleId: string; nextFire: string | null };
+}
+
+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 "schedule": return gated ? this.scheduleVerb(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, schedule)`);
+    }
+  }
+
+  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/schedule)");
+  }
+
+  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 && (typeof p.lifecycle !== "string" || !p.lifecycle)) return this.err(id, "E-BAD-PARAMS", "params.lifecycle must be a non-empty string when set (#83)");
+    if (p.schedule !== undefined) return this.err(id, "E-BAD-PARAMS", "params.schedule is not a spawn param — schedules run lifecycles, not single delegates; use the 'schedule' verb (#83)");
+    if (p.modelFallback !== undefined && (typeof p.modelFallback !== "string" || !p.modelFallback)) return this.err(id, "E-BAD-PARAMS", "params.modelFallback must be a non-empty string when set (#83)");
+    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 } };
+  }
+
+  /** #83 D4: register a recurring lifecycle run. Reply shape { scheduleId, nextFire } — schedules
+   *  are NOT runs, so no runId (spawn's uniform { runId } contract stays unbranched). */
+  private scheduleVerb(id: string, params: unknown): RpcReply {
+    const p = this.obj(params);
+    if (!p) return this.err(id, "E-BAD-PARAMS", "schedule requires params: { task, expression, ... }");
+    if (typeof p.task !== "string" || !p.task) return this.err(id, "E-BAD-PARAMS", "params.task must be a non-empty string");
+    if (typeof p.expression !== "string" || !p.expression) return this.err(id, "E-BAD-PARAMS", "params.expression must be a non-empty string (cron or interval, e.g. '*/5 * * * *' or '30m')");
+    if (p.lifecycle !== undefined && (typeof p.lifecycle !== "string" || !p.lifecycle)) return this.err(id, "E-BAD-PARAMS", "params.lifecycle must be a non-empty string when set");
+    if (p.auto !== undefined && typeof p.auto !== "boolean") return this.err(id, "E-BAD-PARAMS", "params.auto must be a boolean");
+    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.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");
+    let cwd: string | undefined;
+    if (p.cwd !== undefined) {
+      const resolved = resolveDispatchCwd(p.cwd, this.deps.parentCwd);
+      if (resolved.error) return this.err(id, "E-BAD-PARAMS", resolved.error);
+      cwd = resolved.cwd;
+    }
+    if (!this.deps.schedule) {
+      return this.err(id, "E-BAD-PARAMS", "scheduling not configured in this session (scheduler missing)");
+    }
+    try {
+      const out = this.deps.schedule({
+        task: p.task, expression: p.expression,
+        ...(p.lifecycle !== undefined ? { lifecycle: p.lifecycle } : {}),
+        ...(p.auto !== undefined ? { auto: p.auto } : {}),
+        ...(p.isolation !== undefined ? { isolation: p.isolation } : {}),
+        ...(cwd !== undefined ? { cwd } : {}),
+      });
+      return { id, ok: true, data: { scheduleId: out.scheduleId, nextFire: out.nextFire } };
+    } catch (e) {
+      return this.err(id, "E-BAD-PARAMS", (e as Error).message || "schedule registration failed");
+    }
+  }
+
+  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,9 +26,14 @@ 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;
+  /** #83: per-run fallback model for the phase-spawn retry wrapper (wins over the host's
+   *  global default). Undefined = use the host default (back-compat). */
+  modelFallback?: string;
 }
 
 export type RunLifecycleFn = (task: string, lifecycleName: string, opts: RunLifecycleOpts) => Promise<FakeLifecycleResult>;
@@ -57,8 +62,16 @@ 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;
+  /** #83: per-run fallback model — forwarded to the runLifecycle adapter so its phase-spawn
+   *  retry wrapper prefers this over the host's global default. Undefined = host default. */
+  modelFallback?: string;
   /** #62: the dispatch target cwd (undefined = session cwd, back-compat). Scopes the run:
    *  isolation routing + worktree creation resolve against THIS cwd (via deps.worktreeFor),
    *  and in-place runs pass it as the lifecycle entryCwd. */
@@ -113,7 +126,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", ...(opts.modelFallback ? { modelFallback: opts.modelFallback } : {}) });
 
       if (res.status === "completed") {
         if (isolated) {
@@ -158,7 +171,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 +193,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 +203,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 */ }
     }
   }
 

package/src/settings/fleet-settings.ts

@@ -0,0 +1,103 @@
+// src/settings/fleet-settings.ts
+// #78: fleet-dir settings.json — the settings home for fleet-wide defaults that
+// aren't env-shaped (sibling of tiers.json in the same global+project scheme).
+//
+// Locations:
+//   global:  ~/.pi/agent/fleet/settings.json
+//   project: <cwd>/.pi/fleet/settings.json   (project wins per-field)
+//
+// Design rules:
+// - Absent files are normal (empty settings, no warning).
+// - Present-but-invalid content produces ACTIONABLE warnings (file + field + bad
+//   value) and drops the field — never a silent swallow (the TierStore ENOENT
+//   lesson: silent loaders make wrong docs doubly dangerous).
+// - The schema is intentionally small and additive; unknown keys warn so typos
+//   surface instead of no-oping.
+import { readFileSync } from "node:fs";
+import type { ThinkingLevel } from "../registry/frontmatter.ts";
+
+const THINKING_LEVELS: readonly ThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+
+export function isThinkingLevel(v: unknown): v is ThinkingLevel {
+  return typeof v === "string" && (THINKING_LEVELS as readonly string[]).includes(v);
+}
+
+/** Fleet-wide defaults. Intentionally additive — new fields land here. */
+export interface FleetSettings {
+  /** #78: applied to every subagent whose frontmatter does NOT pin `thinkingLevel`.
+   *  Precedence: agent.thinkingLevel > this > the backend/session default. */
+  defaultSubagentThinking?: ThinkingLevel;
+}
+
+export interface FleetSettingsResult {
+  settings: FleetSettings;
+  /** Actionable, source-labeled warnings (never empty-string; always name the file). */
+  warnings: string[];
+}
+
+/** Parse one settings file's content. `label` names the file in warnings. */
+export function parseFleetSettings(json: string, label = "settings.json"): FleetSettingsResult {
+  const warnings: string[] = [];
+  let raw: unknown;
+  try {
+    raw = JSON.parse(json);
+  } catch (e) {
+    return { settings: {}, warnings: [`${label}: invalid JSON (${(e as Error).message}) — fleet settings from this file ignored`] };
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { settings: {}, warnings: [`${label}: expected a JSON object, got ${raw === null ? "null" : Array.isArray(raw) ? "array" : typeof raw} — fleet settings from this file ignored`] };
+  }
+  const obj = raw as Record<string, unknown>;
+  const settings: FleetSettings = {};
+
+  const thinking = obj["defaultSubagentThinking"];
+  if (thinking !== undefined) {
+    if (isThinkingLevel(thinking)) {
+      settings.defaultSubagentThinking = thinking;
+    } else {
+      warnings.push(`${label}: defaultSubagentThinking must be one of ${THINKING_LEVELS.join("|")}, got ${JSON.stringify(thinking)} — ignored`);
+    }
+  }
+
+  const known = new Set(["defaultSubagentThinking"]);
+  const unknownKeys = Object.keys(obj).filter((k) => !known.has(k));
+  if (unknownKeys.length > 0) {
+    warnings.push(`${label}: unknown setting${unknownKeys.length > 1 ? "s" : ""} ${unknownKeys.map((k) => `"${k}"`).join(", ")} — ignored (valid: ${[...known].join(", ")})`);
+  }
+
+  return { settings, warnings };
+}
+
+export interface FleetSettingsStoreOpts {
+  projectPath: string;
+  globalPath: string;
+}
+
+/** Global+project fleet settings (project wins per-field), mirroring TierStore's scheme. */
+export class FleetSettingsStore {
+  constructor(private readonly opts: FleetSettingsStoreOpts) {}
+
+  private readOne(path: string, label: string): FleetSettingsResult {
+    let content: string;
+    try {
+      content = readFileSync(path, "utf8");
+    } catch (e) {
+      // ENOENT = the normal absent-file state, never a warning. Any OTHER read failure
+      // (EACCES, EISDIR, …) on a path that was expected to be readable must surface —
+      // silent swallows make misconfiguration invisible (the TierStore lesson).
+      const code = (e as NodeJS.ErrnoException).code;
+      if (code === "ENOENT") return { settings: {}, warnings: [] };
+      return { settings: {}, warnings: [`${label}: unreadable (${code ?? (e as Error).message}) — fleet settings from this file ignored`] };
+    }
+    return parseFleetSettings(content, label);
+  }
+
+  load(): FleetSettingsResult {
+    const global = this.readOne(this.opts.globalPath, this.opts.globalPath);
+    const project = this.readOne(this.opts.projectPath, this.opts.projectPath);
+    return {
+      settings: { ...global.settings, ...project.settings },
+      warnings: [...global.warnings, ...project.warnings],
+    };
+  }
+}