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

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.