@gorlitzer-labs/seldon 0.9.2 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -74,8 +74,28 @@ recorded in `~/.seldon/lanes.json`. A plan item shows the lane working on it.
74
74
  seldon lanes [--json] # every agent here
75
75
  seldon lane start [dir] --task "fix the save crash" [--agent codex]
76
76
  seldon lane stop|resume|open <name or key>
77
+ seldon lane why <name or key> # what Entire recorded: see below
77
78
  ```
78
79
 
80
+ ## Why each change was made: Entire
81
+
82
+ [Entire](https://entire.com) (`entire` CLI, MIT) records the agent session behind every
83
+ commit: the prompt, the redacted transcript, the files touched and the tokens. It links each one
84
+ to its commit with an `Entire-Checkpoint` trailer, which survives rebase and squash. It works from
85
+ lane worktrees, Claude's and seldon's alike.
86
+
87
+ ```bash
88
+ brew install --cask entireio/tap/entire
89
+ seldon setup entire [dir] [--remote origin] # turns it on for every harness installed here
90
+ git add .entire .claude && git commit -m "record agent sessions" # lanes get it from now on
91
+ seldon lane why fix-save-crash # recorded commits, then the newest explained
92
+ ```
93
+
94
+ Checkpoints are pushed to `--remote` with your branches, so **a public repository makes your
95
+ agents' transcripts public**. Use a private remote. Redaction is best effort. With the
96
+ [comb gate](../../modules/comb) installed globally, use comb 0.2.4 or later: earlier versions
97
+ skipped Entire's pre-push from worktrees.
98
+
79
99
  ## Codex and opencode: let them report their state
80
100
 
81
101
  Claude Code lists its own sessions. Codex and opencode do not, so out of the box their lanes
package/bin/seldon.js CHANGED
@@ -10,6 +10,7 @@ import { MODULES, byId, DEPS, RAW, MONOREPO, withRequires, platformOk } from "..
10
10
  import { ensureSiblingPath, loadState, resolveProject, adopt as fAdopt, staff as fStaff, attach as fAttach, hiveOf, sameDir } from "../lib/projects.mjs";
11
11
  import { readLanes, readPlan, addToPlan, projectRoot, writeReport } from "../lib/agents.mjs";
12
12
  import { openCommand, stopCommand, transitions, laneForItem, slugify, HARNESSES } from "../lib/lanes.mjs";
13
+ import { enableSteps, parseCheckpointLog, laneRange, LOG_FORMAT } from "../lib/entire.mjs";
13
14
  import { startLane, stopLane, resumeLane, findLane } from "../lib/actions.mjs";
14
15
  import { listMachines, addMachine, fetchLanes, remoteGroups, sshArgs, lastJsonLine } from "../lib/machines.mjs";
15
16
  import { notify } from "../lib/notify.mjs";
@@ -1438,6 +1439,8 @@ ${C.bold("seldon")} — the agent factory: your projects, and the stack that run
1438
1439
  ${C.dim("go takes --agent claude|codex, --model <id>, --effort <lvl>, --name <n>,")}
1439
1440
  ${C.dim(" --no-staff (do not start an agent), --no-attach (do not open the room) and")}
1440
1441
  ${C.dim(" --attach (open it even with no terminal detected — inside tmux, or from a script).")}
1442
+ ${C.bold("seldon setup entire")} record ${C.gold("why")} each agent change was made (Entire), in this repo · --remote <name>
1443
+ ${C.bold("seldon lane why")} <lane> a lane's recorded commits, and the prompt + transcript behind the newest
1441
1444
  ${C.bold("seldon install")} [ids…] install everything picked, or the named modules (no ids: the picker)
1442
1445
  ${C.bold("seldon uninstall")} ids… remove the named modules (global CLI / isolated venv)
1443
1446
  ${C.bold("seldon uninstall --all")} remove the whole stack (also drops ~/.seldon)
@@ -1505,9 +1508,10 @@ function laneCmd(verb, arg, flags) {
1505
1508
  const r = startLane({ root, name: path.basename(root), task, harness: flags.agent || "claude" });
1506
1509
  return r.ok ? console.log(C.green(`✓ started ${r.slug}`) + C.dim(` (${flags.agent || "claude"}) in ${root}`)) : fail(`could not start: ${r.error}`);
1507
1510
  }
1508
- if (!["stop", "resume", "open"].includes(verb)) return fail('usage: seldon lane start [dir] --task "…" [--agent claude|codex|opencode] · seldon lane stop|resume|open <key>');
1511
+ if (!["stop", "resume", "open", "why"].includes(verb)) return fail('usage: seldon lane start [dir] --task "…" [--agent claude|codex|opencode] · seldon lane stop|resume|open|why <key>');
1509
1512
  const lane = arg && findLane(arg);
1510
1513
  if (!lane) return fail(`no lane ${arg || ""} — see: seldon lanes`);
1514
+ if (verb === "why") return laneWhy(lane, fail);
1511
1515
  if (verb === "open") {
1512
1516
  const how = openCommand(lane);
1513
1517
  if (how.why) return fail(`can't open ${lane.name}: ${how.why}`);
@@ -1520,6 +1524,40 @@ function laneCmd(verb, arg, flags) {
1520
1524
  console.log(C.green(`✓ ${verb === "stop" ? "stopped" : "resumed"} ${lane.name}`) + (r.fresh ? C.dim(" (new conversation, same task + worktree)") : ""));
1521
1525
  }
1522
1526
 
1527
+ // `seldon lane why <key>` — the lane's commits that Entire recorded, then the newest one
1528
+ // explained: the prompt, the files and the transcript that produced it.
1529
+ function laneWhy(lane, fail) {
1530
+ if (!has("entire")) return fail("entire is not installed: brew install --cask entireio/tap/entire, then seldon setup entire");
1531
+ const cwd = lane.cwd;
1532
+ if (!cwd || !fs.existsSync(cwd)) return fail(`${lane.name}'s worktree is gone (${cwd || "unknown"})`);
1533
+ const git = (args) => spawnSync("git", ["-C", cwd, ...args], { encoding: "utf8" });
1534
+ const range = laneRange(git(["rev-parse", "--abbrev-ref", "origin/HEAD"]).stdout);
1535
+ const log = git(["log", range, `--format=${LOG_FORMAT}`]);
1536
+ if (log.status !== 0) return fail(`can't read ${lane.name}'s commits: ${log.stderr.trim()}`);
1537
+ const commits = parseCheckpointLog(log.stdout);
1538
+ if (!commits.length) { console.log(C.dim(`${lane.name}: no recorded commits in ${range} yet. Is Entire on here? seldon setup entire`)); return; }
1539
+ console.log(C.bold(lane.name) + C.dim(` ${commits.length} recorded commit(s), newest first`));
1540
+ for (const c of commits) console.log(` ${C.cyan(c.sha)} ${c.subject} ${C.dim(c.ids.join(", "))}`);
1541
+ console.log("");
1542
+ process.exitCode = spawnSync("entire", ["checkpoint", "explain", commits[0].ids[0]], { cwd, stdio: "inherit" }).status ?? 1;
1543
+ }
1544
+
1545
+ // `seldon setup entire [dir] [--remote <name>]` — record why each agent change was made, in
1546
+ // this project. Entire's own output lists the files to commit; until they are committed, lane
1547
+ // worktrees (which check out committed files only) do not get the agent hooks.
1548
+ function entireSetupCmd(dir, flags) {
1549
+ const fail = (msg) => { console.log(C.red(msg)); process.exitCode = 1; };
1550
+ if (!has("entire")) return fail("entire is not installed: brew install --cask entireio/tap/entire (or curl -fsSL https://entire.com/install.sh | bash)");
1551
+ const root = projectRoot(path.resolve(dir || "."));
1552
+ if (!root) return fail("not inside a git repository");
1553
+ const remote = typeof flags.remote === "string" ? flags.remote : "origin";
1554
+ for (const [bin, args] of enableSteps({ remote, harnesses: HARNESSES.filter((h) => has(h)) })) {
1555
+ if (spawnSync(bin, args, { cwd: root, stdio: "inherit" }).status !== 0) return fail(`${bin} ${args.join(" ")} failed`);
1556
+ }
1557
+ console.log("\n" + C.gold("before you push: ") + `checkpoints hold your agents' transcripts and go to ${C.bold(remote)}. If that repository is public, so are they; secret redaction is best effort.`);
1558
+ console.log(C.dim(" commit the files Entire listed, so every new lane worktree gets the hooks · then: seldon lane why <lane>"));
1559
+ }
1560
+
1523
1561
  // `seldon machines` — the other computers the panel shows (bifrost's realms, one list).
1524
1562
  function machinesCmd(verb, name, target) {
1525
1563
  if (verb === "add") {
@@ -1556,7 +1594,8 @@ function stableSeldonBin() {
1556
1594
  // `seldon setup [codex|opencode] [--remove]` — install the reporter into each harness.
1557
1595
  const CODEX_HOOKS = path.join(process.env.HOME, ".codex", "hooks.json");
1558
1596
  const OPENCODE_PLUGIN = path.join(process.env.HOME, ".config", "opencode", "plugins", "seldon.js");
1559
- function setupCmd(which, flags) {
1597
+ function setupCmd(which, flags, dir) {
1598
+ if (which === "entire") return entireSetupCmd(dir, flags);
1560
1599
  const targets = which ? [which] : ["codex", "opencode"].filter((h) => has(h) || flags.remove);
1561
1600
  if (!targets.length) { console.log(C.dim("neither codex nor opencode is installed — Claude needs no setup")); return; }
1562
1601
  // The `seldon` on PATH (e.g. ~/Library/pnpm/bin/seldon), not the file running now: that one
@@ -1700,7 +1739,7 @@ const ids = tokens.filter((id) => byId[id]); // only the valid module
1700
1739
  if (cmd === "lanes") return lanesCmd(flags);
1701
1740
  if (cmd === "machines") return machinesCmd(tokens[0], tokens[1], tokens[2]);
1702
1741
  if (cmd === "lane") return laneCmd(tokens[0], tokens[1], flags);
1703
- if (cmd === "setup") return setupCmd(tokens[0], flags);
1742
+ if (cmd === "setup") return setupCmd(tokens[0], flags, tokens[1]);
1704
1743
  if (cmd === "panel" || cmd === "board") return panel();
1705
1744
  if (cmd && cmd !== "install") { help(); process.exitCode = 1; return; }
1706
1745
  if (cmd === "install") return install_picker({ dev }); // `install` with no ids
package/lib/entire.mjs ADDED
@@ -0,0 +1,46 @@
1
+ // Entire: why each lane's agent made each change.
2
+ //
3
+ // Entire (https://entire.com, `entire` CLI, MIT) hooks into the agent and into git. When an agent
4
+ // commits, it links the commit to the agent session that produced it with an
5
+ // `Entire-Checkpoint: <id>` trailer, and keeps the prompt, the redacted transcript, the files
6
+ // touched and the token count under refs/entire/checkpoints/*, pushed alongside your branches.
7
+ // seldon does not store any of it: it turns it on for a project and reads it back per lane.
8
+ //
9
+ // Pure, like lanes.mjs: callers run the commands and pass the output in.
10
+
11
+ export const TRAILER = "Entire-Checkpoint";
12
+
13
+ // seldon's harness names → Entire's agent names.
14
+ export const ENTIRE_AGENT = { claude: "claude-code", codex: "codex", opencode: "opencode" };
15
+
16
+ // One line per commit: short sha, subject, checkpoint ids (comma-separated, usually one).
17
+ export const LOG_FORMAT = `%h%x1f%s%x1f%(trailers:key=${TRAILER},valueonly,separator=%x2C)`;
18
+
19
+ /** Commits on a lane that carry a checkpoint, newest first: [{ sha, subject, ids }]. */
20
+ export function parseCheckpointLog(text) {
21
+ return String(text || "").split("\n").filter(Boolean).map((line) => {
22
+ const [sha, subject = "", ids = ""] = line.split("\x1f");
23
+ return { sha, subject, ids: ids.split(",").map((s) => s.trim()).filter(Boolean) };
24
+ }).filter((c) => c.ids.length);
25
+ }
26
+
27
+ /**
28
+ * The commands that turn Entire on for a project: Claude Code first (it is the one `enable`
29
+ * configures), then one `agent add` per other harness installed here. Checkpoints go to
30
+ * `remote` only; telemetry stays off.
31
+ */
32
+ export function enableSteps({ remote = "origin", harnesses = [] } = {}) {
33
+ const steps = [["entire", ["enable", "--agent", ENTIRE_AGENT.claude, "--telemetry=false", "--checkpoint-push-remote", remote]]];
34
+ for (const h of harnesses) if (h !== "claude" && ENTIRE_AGENT[h]) steps.push(["entire", ["agent", "add", ENTIRE_AGENT[h]]]);
35
+ return steps;
36
+ }
37
+
38
+ /**
39
+ * The commits a lane added: everything on its HEAD that the project's default branch lacks.
40
+ * `defaultRef` is what `git rev-parse --abbrev-ref origin/HEAD` printed (e.g. "origin/main"),
41
+ * or empty when the clone has no remote HEAD.
42
+ */
43
+ export function laneRange(defaultRef) {
44
+ const ref = String(defaultRef || "").trim();
45
+ return `${ref && ref !== "origin/HEAD" ? ref : "main"}..HEAD`;
46
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gorlitzer-labs/seldon",
3
- "version": "0.9.2",
3
+ "version": "0.10.0",
4
4
  "description": "Install the Seldon stack — pick your tools from a checklist; each installs via its native method.",
5
5
  "type": "module",
6
6
  "bin": {