OpenFleet reference implementation: @logicsrc/openfleet, logicsrc fleet, and Claude Code hooks (#185)

* OpenFleet reference implementation: @logicsrc/openfleet 0.1.0 and logicsrc fleet

Ship what docs/openfleet.md describes. The new workspace package holds the
record (write once, never overwrite, 0600), the ledger (append-only JSON
Lines, merged across ledger*.jsonl by at), the ceiling rules (whole fleet
ceiling, narrowed swarm keys, a merge that never widens, refusals by key),
claiming and deriving exactly as the spec's "Claiming and deriving" and
rule 13, and fold(), which turns any $OPENFLEET_HOME plus the engine
rosters into the tree the landing page shows.

logicsrc fleet open|cap|tree|stop|log are the sysop's verbs, every one with
--json. open and cap exit 4 when OPENFLEET_MEMBER is set; stop exits 4
outside the caller's subtree, ends nested swarms first, goes through each
member's own engine (claude stop, moshcode herd kill, tmux kill-pane, a
signal for claude-p) and writes one swarm.end per swarm. tree reads claude
agents --json --all and ~/.moshcode/herd/sessions.json when it can, draws
recordless sessions as roster roots of the implicit fleet, and writes
member.end lost for a recorded member its engine no longer lists.

Claude Code takes part through hooks: logicsrc fleet hooks install merges
SessionStart, UserPromptSubmit, PreToolUse, Stop and SessionEnd into
~/.claude/settings.json without clobbering it, and logicsrc fleet hook
<Event> runs each one. SessionStart claims, derives or writes a root record
and hands the member its variables through CLAUDE_ENV_FILE; UserPromptSubmit
checks the ceiling with the permission mode the engine reports and writes
member.start, or refuses the first prompt with exit 2 and ceiling.refuse;
PreToolUse denies an edit outside piece.owns; Stop and SessionEnd write
member.end. A hand-started root takes the engine's reported approvals
before member.start, since the command line only guesses them. Hooks
never fail the engine: everything is caught and logged to hooks.log.

The spec and the landing page now say what ships, keep Status 0.1, and
record the two verified Claude Code limits: a background job dispatched from
claude agents gets no launcher environment, and OPENFLEET_* exported at
SessionStart reach the member's tools but not later hooks, so hooks key on
session_id through $OPENFLEET_HOME/sessions/<session_id>.json. PRD 0008
covers the work. CLI 0.2.1 -> 0.3.0; build and build:cli chains build the
package before the CLI; README and docs/cli.md list the group.

Tests: 95 in the package (record, ledger merge, every narrower case, the
worked example's claim and derive, the folded tree, hook install
idempotence, each hook handler including the exit-2 refusal and the
PreToolUse deny, every verb with fake deps) and 4 in the CLI.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RZV4zJ2pDZLNN3kE5jFCmV

* OpenFleet fix round: rebuild the ceiling from the ledger, once-markers, rule 6 in tree, lost only for what a roster can hold

The review of the reference implementation against moshcode found the two
readers disagreeing on the same files. This round applies the shared
rulings so both sides read a ledger the same way.

Ceiling (R-A, R-B, R-C, R1, R6, R10, R15, R17): memberCeiling rebuilds the
effective ceiling from the ledger on every read. The latest fleet-target
fleet.cap (else fleet.open, else the implicit fleet's) replaces the copy in
a record, so a sysop's widening cap reaches running members; then each
swarm.spawn narrowing down the path, then swarm caps last. In the implicit
fleet a parentless record's own approvals enters at the root; a ceiling a
writer left without the key is never read as native, and startMember fills
it with the engine's word while the record is unclaimed. A fleet.open or
cap with no hosts means the host it was written on (R23).

Once-markers (R-G, R28): member.start, member.end and swarm.end each take
an exclusive create under fleets/<fleet>/marks/<event>.<id> before the
append; a lost end takes <id>.lost so a real end can still supersede it.
The hooks let a real end follow a lost line (R9).

tree (R-F, R20): run by the sysop it enforces rule 6, stopping a member
past its effective until with state timeout and the members of a swarm or
fleet at its budget with state budget, then writes swarm.end for each swarm
touched once it is complete. An agent's tree stops nothing. lost is written
only for a member its engine's roster can hold: a claude-code background job
(8-hex member or session) or a moshcode pane, never an interactive session
claude agents does not list (R-E, R3, R14). A nested swarm is drawn under
the member that spawned it and its row shows the effective ceiling (R25).

stop and cap (R-D, R-H, R22, R27): swarm.end is written only once every
member and every nested swarm has an end line that counts; an engine that
will not end a member leaves it without an end line and the verb exits
non-zero. claude stop takes the job id: the member of a background job,
else the first eight characters of a session UUID; an interactive session
with no job id cannot be stopped and the tool says so. cap on a swarm
refuses a key that would widen. A derived claude-code job is named by its
job id and carries no pid.

Also: R-I (endMember ends only the engine-minted swarm of one), R35 (a
derived record's guessed approvals corrected at UserPromptSubmit), R32
(the UserPromptSubmit hook passes only exit 2 through), R31 (package
README), R36 (rule 13 says the launcher test is unimplemented in 0.1),
docs and PRD 0008 updated for lost, rule 6 and the markers. 113 openfleet
tests, 93 CLI tests, contract green.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RZV4zJ2pDZLNN3kE5jFCmV

* openfleet hooks: no member.end for a member that never started

A first prompt refused by the ceiling still lets the session wind down through Stop and SessionEnd; those handlers now write nothing when the ledger holds no member.start for the member, so a refused member is never drawn as done.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Claude-Session: https://claude.ai/code/session_01RZV4zJ2pDZLNN3kE5jFCmV

* logicsrc-mcp test: the next free PRD id is 0009 now that PRD 0008 exists

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Claude-Session: https://claude.ai/code/session_01RZV4zJ2pDZLNN3kE5jFCmV

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logicsrc/cli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "LogicSRC CLI: every LogicSRC standard and tool as one command.",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,6 +18,7 @@
     "@logicsrc/account-core": "file:../account-core",
     "@logicsrc/opencontext": "file:../opencontext",
     "@logicsrc/opencreds": "file:../opencreds",
+    "@logicsrc/openfleet": "file:../openfleet",
     "@logicsrc/openmcp": "^0.3.1",
     "@logicsrc/openontology": "file:../openontology",
     "@logicsrc/openprd": "file:../openprd",

packages/cli/src/fleet.test.ts

@@ -0,0 +1,99 @@
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Command } from "commander";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { Deps } from "@logicsrc/openfleet/commands";
+import { registerFleetCommands } from "./fleet.js";
+
+/** A program shaped like the real one: positional options on, no process.exit. */
+function program(): Command {
+  const p = new Command();
+  p.name("logicsrc").enablePositionalOptions().exitOverride();
+  return p;
+}
+
+const OPENFLEET_KEYS = ["OPENFLEET_HOME", "OPENFLEET_RECORD", "OPENFLEET_FLEET", "OPENFLEET_MEMBER", "OPENFLEET_SWARM"];
+
+describe("logicsrc fleet", () => {
+  let home: string;
+  let saved: Record<string, string | undefined>;
+  let out: string[];
+  let err: string[];
+  let deps: Partial<Deps>;
+
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), "logicsrc-fleet-"));
+    saved = Object.fromEntries(OPENFLEET_KEYS.map((key) => [key, process.env[key]]));
+    out = [];
+    err = [];
+    deps = {
+      env: { OPENFLEET_HOME: home, HOME: home },
+      now: () => new Date("2026-09-13T06:00:00Z"),
+      exec: async () => ({ code: 0, stdout: "", stderr: "" }),
+      kill: () => undefined,
+      rosters: {},
+      stdin: async () => "",
+      write: (line) => out.push(line),
+      error: (line) => err.push(line),
+      stdout: (text) => out.push(text),
+      stderr: (text) => err.push(text),
+      host: "dev",
+      user: "anthony",
+    };
+  });
+
+  afterEach(() => {
+    for (const key of OPENFLEET_KEYS) {
+      if (saved[key] === undefined) delete process.env[key];
+      else process.env[key] = saved[key];
+    }
+    rmSync(home, { recursive: true, force: true });
+    process.exitCode = 0;
+  });
+
+  it("registers the group with the five verbs and the hook verbs", () => {
+    const p = program();
+    registerFleetCommands(p, deps);
+    const fleet = p.commands.find((command) => command.name() === "fleet");
+    expect(fleet).toBeDefined();
+    expect(fleet!.commands.map((command) => command.name()).sort()).toEqual(["cap", "hook", "hooks", "log", "open", "stop", "tree"]);
+    expect(fleet!.description()).toContain("OpenFleet");
+  });
+
+  it("opens a fleet, then shows it in the tree and the log, over the injected home", async () => {
+    const p = program();
+    registerFleetCommands(p, deps);
+    await p.parseAsync(["node", "logicsrc", "fleet", "open", "--approvals", "bypass", "--depth", "2", "--json"]);
+    expect(process.exitCode).toBe(0);
+    expect(JSON.parse(out[0])).toMatchObject({ fleet: "fleet-20260913", sysop: "anthony@dev", ceiling: { approvals: "bypass", depth: 2, hosts: ["dev"] } });
+    expect(readFileSync(join(home, "current"), "utf8")).toBe("fleet-20260913\n");
+
+    const tree = program();
+    registerFleetCommands(tree, deps);
+    await tree.parseAsync(["node", "logicsrc", "fleet", "tree"]);
+    expect(out[1]).toBe("fleet-20260913  (fleet, sysop anthony@dev, approvals bypass, depth 2, hosts dev)");
+
+    const log = program();
+    registerFleetCommands(log, deps);
+    await log.parseAsync(["node", "logicsrc", "fleet", "log", "--json"]);
+    expect(JSON.parse(out[2])).toMatchObject({ event: "fleet.open", by: "sysop", fleet: "fleet-20260913", host: "dev" });
+  });
+
+  it("refuses the sysop's verbs with exit 4 when the process is an agent", async () => {
+    const p = program();
+    registerFleetCommands(p, { ...deps, env: { ...deps.env, OPENFLEET_MEMBER: "create-two-0541-1" } });
+    await p.parseAsync(["node", "logicsrc", "fleet", "open"]);
+    expect(process.exitCode).toBe(4);
+    expect(err[0]).toContain("OPENFLEET_MEMBER=create-two-0541-1");
+    expect(out).toEqual([]);
+  });
+
+  it("inspects the hooks of a settings file given by flag, never the real one", async () => {
+    const file = join(home, "settings.json");
+    const p = program();
+    registerFleetCommands(p, deps);
+    await p.parseAsync(["node", "logicsrc", "fleet", "hooks", "status", "--settings-file", file, "--json"]);
+    expect(JSON.parse(out[0])).toMatchObject({ file, present: false, installed: false });
+  });
+});

packages/cli/src/fleet.ts

@@ -0,0 +1,26 @@
+import type { Command } from "commander";
+import { registerOpenFleetCommands, type Deps } from "@logicsrc/openfleet/commands";
+
+/**
+ * `logicsrc fleet …`
+ *
+ * The commands themselves live in `@logicsrc/openfleet`, the same package that
+ * holds the record, the ledger and the Claude Code hooks, so the sysop tool
+ * and the engine side read the same files through the same code. The spec
+ * treats the five verbs (open, cap, tree, stop, log) and their refusals as a
+ * conformance surface; keeping them in one place is how they stay one contract.
+ *
+ * `deps` is injectable so the umbrella tests drive the group with a fake
+ * clock, environment, roster and process runner, and never touch
+ * `~/.openfleet` or a real engine.
+ */
+export function registerFleetCommands(program: Command, deps: Partial<Deps> = {}): void {
+  const fleet = program
+    .command("fleet")
+    .description(
+      "OpenFleet: agents under a human. open, cap, tree, stop and log over $OPENFLEET_HOME, " +
+        "plus the Claude Code hooks (`hooks install`) that make every session a recorded member.",
+    );
+
+  registerOpenFleetCommands(fleet, deps);
+}

packages/cli/src/index.ts

@@ -36,6 +36,7 @@ import { parsePositiveInteger } from "./numeric-options.js";
 import { exportOpenSpecSummary, importOpenSpec, writeOpenSpecChange } from "./openspec.js";
 import { registerOpenContextCommands } from "./context.js";
 import { registerOpenCredsCommands } from "./creds.js";
+import { registerFleetCommands } from "./fleet.js";
 import { registerOntologyCommands } from "./ontology.js";
 import { registerPrdCommands } from "./prd.js";
 import { registerOpenMcpCommands } from "./openmcp.js";
@@ -1057,6 +1058,7 @@ registerOpenContextCommands(program);
 registerOpenCredsCommands(program);
 registerOntologyCommands(program);
 registerPrdCommands(program);
+registerFleetCommands(program);
 registerOpenMcpCommands(program);
 registerMcpCommands(program);
 // Every other word under `logicsrc openspec` is OpenSpec.dev's own CLI.