moshcoder
diff --git a/‎prd/0019-take-what-swamp-got-right.md‎
Lines changed: 58 additions & 5 deletions b/‎prd/0019-take-what-swamp-got-right.md‎
Lines changed: 58 additions & 5 deletions
diff --git a/‎src/cli-schema.mjs‎
Lines changed: 25 additions & 0 deletions b/‎src/cli-schema.mjs‎
Lines changed: 25 additions & 0 deletions
diff --git a/‎src/fleet-cli.mjs‎
Lines changed: 120 additions & 2 deletions b/‎src/fleet-cli.mjs‎
Lines changed: 120 additions & 2 deletions
@@ -99,9 +99,15 @@ for leaving precedence undocumented.
   landing directory searched. Done in this change.
 - R2 [P0] Heartbeat liveness. A moshcode-started run records a heartbeat, and herd state
   is derived from it first. Output pattern matching stays as a fallback for engines that
-  cannot report, and is labelled as inference rather than fact.
+  cannot report, and is labelled as inference rather than fact. Done: `moshcode fleet
+  beat` writes it, the engine's lifecycle hook calls it, `sessionState` reads it ahead of
+  the hook and the screen, and every answer carries `confidence`, `known` or `inferred`.
+  The roster marks an inferred state with a trailing `?`.
 - R3 [P0] A run record is immutable and versioned: inputs, the engine and model, every
   step, and outputs. It extends the OpenFleet ledger rather than opening a second store.
+  Done: an immutable `wx` header under `fleets/<fleet>/runs/` carrying `record_version`,
+  and `run.start`, `run.step`, `run.end` on the fleet's existing ledger. See the resolved
+  storage question below. Retention ships with it as `moshcode fleet gc`.
 - R4 [P1] Run history is searchable from the CLI, the TUI and the MCP bridge, per the
   house agent-surfaces rule. Any dashboard is hqtui, not a localhost web page.
 - R5 [P1] Swarm pieces declare dependencies, and the runner derives concurrency from the
@@ -158,16 +164,63 @@ interactive session, so it lives with railway, gh and supabase instead.
   transitional.
 - An immutable run record grows without bound. It needs a retention story before it
   ships, not after. omp's `gc` with per-directory retention is the shape to copy.
+  ANSWERED 2026-09-25: `moshcode fleet gc` keeps the newest 20 ended runs per working
+  directory and drops anything ended more than 30 days ago, with `--dry-run` to preview.
+  Per directory rather than globally, so one busy checkout cannot evict every other one.
+  A run with no `run.end` is never a candidate at any age. Only this host's `ledger.jsonl`
+  is rewritten, never a `ledger.<host>.jsonl` copied in from a box running its own
+  retention. And only `run.*` lines are dropped: `member.start`, `swarm.end` and
+  `ceiling.refuse` are the spec's record of what agents were allowed to do, and no
+  retention policy of ours decides those have expired.
 - A DAG is more expressive than the current phase list, which means a planner can now
   author a cycle or a deadlock. The runner must reject a cyclic graph up front with the
   cycle named.
 - The license boundary is real and easy to cross by accident, particularly for anyone
   reading swamp's YAML schemas while implementing R5 or R11. Requirements here describe
   behaviour on purpose and name no swamp file. If an implementation needs their schema,
   that is the moment to stop and take legal advice instead.
-- Open question: does the run record belong in SQLite like swamp's, or in the JSON and
-  append-only files OpenFleet already uses? SQLite buys search cheaply. Files keep the
-  "no daemon, no database, one host" property PRD 0016 chose deliberately. Deciding this
-  is the first task, because R3 and R4 both depend on it.
+- RESOLVED 2026-09-25: the run record lives in the files OpenFleet already writes, not
+  in SQLite. Implemented in `src/run-record.mjs`.
+
+  Four reasons, in the order they decided it.
+
+  PRD 0016 chose "no daemon, no database, one host" on purpose and named it a goal, not
+  an accident of what was easy. A database is the one change that takes that property
+  away, and nothing in R3 or R4 needs it taken away. Reversing a deliberate design
+  decision wants a concrete reason and there was not one.
+
+  The record is append-only by nature. What a run produces is a start, a sequence of
+  steps and an end, written once each and never updated. That is the exact shape a JSONL
+  ledger is already good at and the shape a relational store is least rewarded for. The
+  ledger also already carries `member.start` and `swarm.end` for the same runs, so
+  putting the steps anywhere else would mean two stores to read and two clocks to merge
+  for one question.
+
+  Other tools read these files. `logicsrc fleet` reads the same ledger, and so does a
+  shell script, and so does a person with `cat` on a box where moshcode is not
+  installed. That reach survives only while the files stay plain. A SQLite file is
+  readable by anything with the library and by nothing without it.
+
+  The search R4 wants is small. The volume here is hundreds of runs on one host, not
+  millions, and a full scan of a JSONL ledger at that size is faster than the process
+  start that would open a database. If a box ever holds enough runs for that to stop
+  being true, an index derived from the files is an addition rather than a migration,
+  because the files would still be the source of truth.
+
+  What the decision costs, stated rather than hidden: no transactions, so a torn line is
+  skipped rather than rolled back, which is what `readLedger` already does; no query
+  language, so R4 writes its own filters; and a retention policy that has to rewrite a
+  file rather than issue a delete, which `moshcode fleet gc` does with a write and a
+  rename. None of those is a correctness problem at this size.
+
+  Three consequences of the shape, since they are what a reader of the code will meet:
+  a run's header is one immutable JSON file under `fleets/<fleet>/runs/`, written with
+  `wx` exactly the way a member's record is; its steps are `run.start`, `run.step` and
+  `run.end` lines on the fleet's existing `ledger.jsonl`, so `moshcode fleet log` reads
+  them with no second tool; and a heartbeat is deliberately NOT in the ledger, because
+  it is the one fact here that is worthless the moment it is superseded. A beat is a
+  small mutable file under `fleets/<fleet>/beats/` that is rewritten in place and deleted
+  when the run ends. Appending every beat would grow the ledger without bound to hold a
+  value only its last line ever answers.
 - Open question: `.agents/skills` is a convention, not a standard. Worth checking whether
   anything beyond swamp reads it before treating it as a destination.
@@ -1597,6 +1597,31 @@ export const FLEET_VERBS = [
       ["--json", "one JSON object per line, as the ledger holds them", ""],
     ],
     note: "who did what, in order: by is sysop or a member id; what each member spent, how each ended, what was refused and why." },
+  // PRD 0019 R2 and R3. Two verbs, additive to the spec's five: one an engine's
+  // hook calls on every turn, one a person runs when the record has grown.
+  { name: "beat", description: "record that a run is alive, and what it is doing (PRD 0019 R2)",
+    synopsis: [["moshcode fleet beat <run> [--state working|blocked|done|idle] [--session <name>] [--ttl 10m] [--json]", ""]],
+    flags: [
+      ["--state <state>", "what the run is doing. a beat with a state is reported as known rather than inferred", "liveness only"],
+      ["--kind <kind>", "for a blocked state: permission, question or menu", ""],
+      ["--fleet <id>", "the fleet the run belongs to", "$MOSHCODE_RUN_FLEET, else this process's fleet"],
+      ["--session <name>", "the herd session the run drives", "$MOSHCODE_HERD_NAME"],
+      ["--ttl <dur>", "how long the beat is worth believing, capped at 10m", "10m"],
+      ["--json", "the beat as written", ""],
+    ],
+    note: "the verb an engine's lifecycle hook calls. a run that beats is shown on the roster as known; a session with no run is inferred "
+      + "from its screen and prints a trailing ?. heartbeats exist only for runs moshcode started, so both tiers are permanent." },
+  { name: "gc", description: "prune ended runs, newest first per working directory (PRD 0019 retention)",
+    synopsis: [["moshcode fleet gc [fleet] [--keep 20] [--older-than 30d] [--dry-run] [--json]", ""]],
+    flags: [
+      ["--keep <n>", "ended runs to keep per working directory", "20"],
+      ["--older-than <dur>", "drop any ended run older than this, however few there are", "30d"],
+      ["--dry-run", "say what would go and remove nothing", ""],
+      ["--json", "the report: what was removed, why, and what was kept", ""],
+    ],
+    note: "an immutable run record grows without bound, so this is how it is allowed to be immutable. a run with no run.end is never a "
+      + "candidate at any age, only this host's ledger is rewritten, and only run.* lines are dropped: member.start, swarm.end and "
+      + "ceiling.refuse are the record of what agents were allowed to do and no retention policy removes those." },
 ];
 
 // The business layer's verbs. Flatter than the herd's on purpose: these are
 
@@ -15,8 +15,10 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { EXIT, herdKill, roster as herdRoster } from "./herd-cli.mjs";
+import { STATES } from "./herd-state.mjs";
 import { herdDir, slugifyName } from "./herd.mjs";
 import * as fleet from "./openfleet.mjs";
+import * as runs from "./run-record.mjs";
 import { acid, amber, ash, bone, dim, err, info, ok, warn } from "./ui.mjs";
 
 /** The exit a refused open, cap or stop returns. logicsrc fleet uses the same number. */
@@ -28,6 +30,8 @@ const USAGE = {
   tree: "usage: moshcode fleet tree [fleet] [--json]",
   stop: "usage: moshcode fleet stop <member|swarm> | --fleet <fleet> [--json]",
   log: "usage: moshcode fleet log [fleet] [--since 1h] [--member <id>] [--swarm <id>] [--json]",
+  beat: "usage: moshcode fleet beat <run> [--state working|blocked|done|idle] [--fleet <id>] [--session <name>] [--ttl 10m] [--json]",
+  gc: "usage: moshcode fleet gc [fleet] [--keep 20] [--older-than 30d] [--dry-run] [--json]",
 };
 
 /* ----------------------------------------------------------------- parsing */
@@ -526,14 +530,19 @@ function describeLine(l) {
     case "member.end": return `${l.member} · ${l.state}${l.total ? ` · ${l.total}` : ""}${l.summary ? ` · ${clip(String(l.summary).replace(/\s+/g, " "), 80)}` : ""}`;
     case "swarm.end": return `${l.swarm} · ${l.state}${l.verdict ? ` · ${l.verdict.length} verdict${l.verdict.length === 1 ? "" : "s"}` : ""}${l.summary ? ` · ${clip(String(l.summary).replace(/\s+/g, " "), 80)}` : ""}`;
     case "ceiling.refuse": return `${l.member ? `${l.member} · ` : ""}${l.action} refused on ${l.key}: wanted ${JSON.stringify(l.wanted)}, allowed ${JSON.stringify(l.allowed)}`;
+    // The run record rides the same ledger (PRD 0019 R3), so `fleet log`
+    // reads it without a second tool and without being taught a second format.
+    case "run.start": return `${l.run} · ${l.engine || "?"}${l.model ? ` ${l.model}` : ""}${l.session ? ` (${l.session})` : ""}${l.task ? ` · "${clip(l.task, 50)}"` : ""}`;
+    case "run.step": return `${l.run} · ${l.kind}${l.name ? ` ${l.name}` : ""}${l.summary ? ` · ${clip(String(l.summary).replace(/\s+/g, " "), 80)}` : ""}`;
+    case "run.end": return `${l.run} · ${l.state}${l.summary ? ` · ${clip(String(l.summary).replace(/\s+/g, " "), 80)}` : ""}`;
     default: return "";
   }
 }
 
 const paintEvent = (event) => {
   if (event === "ceiling.refuse") return amber(event);
   if (event.endsWith(".end")) return ash(event);
-  if (event === "swarm.spawn" || event === "member.start") return acid(event);
+  if (event === "swarm.spawn" || event === "member.start" || event === "run.start") return acid(event);
   return bone(event);
 };
 
@@ -577,9 +586,118 @@ async function fleetLog(argv, o) {
   return EXIT.matched;
 }
 
+/* ------------------------------------------------------- beat and retention */
+
+/**
+ * `moshcode fleet beat <run>`: this run is alive, and here is what it is doing.
+ *
+ * The verb an engine's lifecycle hook calls (PRD 0019 R2). It is deliberately
+ * the cheapest thing in this file: one file written, no ledger read, no tree
+ * folded, because it runs on every turn of every session in the herd and a
+ * beat that costs a tenth of a second is a beat somebody turns off.
+ *
+ * Unlike `open` and `cap` this is not the sysop's alone. A member beating for
+ * its own run is the normal case and the reason the verb exists.
+ */
+export function fleetBeat(argv, { write = console.log, env = process.env, now = () => Date.now() } = {}) {
+  const { flags, positional, errors } = parseArgs(argv, {
+    valued: ["state", "kind", "fleet", "session", "member", "ttl"], flags: ["json"],
+  });
+  for (const e of errors) write(err(e));
+  if (errors.length) { write(err(USAGE.beat)); return EXIT.usage; }
+
+  const run = positional[0] || env.MOSHCODE_RUN || null;
+  if (!run) { write(err(USAGE.beat)); return EXIT.usage; }
+
+  // The fleet the run belongs to, in the order a caller can actually supply
+  // it: the flag, the variable moshcode set beside MOSHCODE_RUN when it
+  // started the session, then the fleet this process sits in.
+  const name = flags.fleet || env.MOSHCODE_RUN_FLEET || env.OPENFLEET_FLEET
+    || fleet.currentFleet(env) || fleet.implicitFleet(env);
+
+  if (flags.state && !STATES.includes(flags.state)) {
+    write(err(`--state is one of ${STATES.join(", ")}`));
+    return EXIT.usage;
+  }
+  let ttl;
+  if (flags.ttl !== undefined) {
+    ttl = parseDurationMs(flags.ttl);
+    if (ttl === null) { write(err("--ttl is a duration like 10m")); return EXIT.usage; }
+  }
+
+  const written = runs.beat(name, run, {
+    state: flags.state, kind: flags.kind, ttl,
+    session: flags.session || env.MOSHCODE_HERD_NAME, member: flags.member || env.OPENFLEET_MEMBER,
+  }, { env, now: now() });
+
+  if (!written.ok) {
+    write(err(String(written.error?.message || written.error)));
+    return EXIT.infra;
+  }
+  if (flags.json) { write(JSON.stringify(written.beat, null, 2)); return EXIT.matched; }
+  write(ok(`${bone(run)} beat${flags.state ? ` · ${flags.state}` : ""} · fleet ${name}`));
+  return EXIT.matched;
+}
+
+/**
+ * `moshcode fleet gc`: the retention the run record needs to be allowed to be
+ * immutable (PRD 0019, Risks).
+ *
+ * An immutable record grows without bound, which is a reason not to ship one
+ * unless the pruning ships with it. omp's shape: keep the newest N runs per
+ * working directory rather than N overall, so one busy checkout cannot evict
+ * every other one, plus an age cap for the directories nobody has touched in a
+ * month. An unfinished run is never a candidate at any age.
+ *
+ * `--dry-run` first is the polite default to recommend, not to impose: this
+ * deletes history somebody may want, and a verb that is hard to preview is a
+ * verb people run blind.
+ */
+export function fleetGc(argv, { write = console.log, env = process.env, now = () => Date.now() } = {}) {
+  const { flags, positional, errors } = parseArgs(argv, {
+    valued: ["keep", "older-than", "fleet"], flags: ["json", "dry-run"],
+  });
+  for (const e of errors) write(err(e));
+  if (errors.length) { write(err(USAGE.gc)); return EXIT.usage; }
+
+  let keep = runs.GC_KEEP_PER_DIR;
+  if (flags.keep !== undefined) {
+    keep = Number(flags.keep);
+    if (!Number.isInteger(keep) || keep < 0) { write(err("--keep is a whole number")); return EXIT.usage; }
+  }
+  let maxAgeMs = runs.GC_MAX_AGE_MS;
+  if (flags["older-than"] !== undefined) {
+    maxAgeMs = parseDurationMs(flags["older-than"]);
+    if (maxAgeMs === null) { write(err("--older-than is a duration like 30d")); return EXIT.usage; }
+  }
+
+  const only = flags.fleet || positional[0] || null;
+  const report = runs.gcRuns({ env, now: now(), keep, maxAgeMs, fleet: only, dryRun: Boolean(flags["dry-run"]) });
+
+  if (flags.json) { write(JSON.stringify(report, null, 2)); return EXIT.matched; }
+  const verb = report.dryRun ? "would remove" : "removed";
+  if (!report.removed.length) {
+    write(info(`nothing to remove. ${report.kept} run${report.kept === 1 ? "" : "s"} kept, ${keep} per directory.`));
+    return EXIT.matched;
+  }
+  for (const r of report.removed) {
+    write(`${dim(r.ended)}  ${bone(r.run)}  ${ash(tildeHome(r.cwd))}  ${dim(r.why === "age" ? "older than the age cap" : "beyond the per-directory count")}`);
+  }
+  write(ok(`${verb} ${report.removed.length} run${report.removed.length === 1 ? "" : "s"} and ${report.lines} ledger line${report.lines === 1 ? "" : "s"}. ${report.kept} kept.`));
+  return EXIT.matched;
+}
+
+const tildeHome = (p) => {
+  const h = process.env.HOME || "";
+  return h && String(p).startsWith(h) ? `~${String(p).slice(h.length)}` : String(p ?? "");
+};
+
 /* --------------------------------------------------------------- dispatch */
 
-const VERBS = { open: fleetOpen, cap: fleetCap, tree: fleetTree, stop: fleetStop, log: fleetLog };
+const VERBS = {
+  open: fleetOpen, cap: fleetCap, tree: fleetTree, stop: fleetStop, log: fleetLog,
+  beat: fleetBeat, gc: fleetGc,
+};
 
 export async function fleetCommand(argv = [], { write = console.log, ...deps } = {}) {
   const o = {