@oxagen/cli 0.5.0 → 0.6.1

package/dist/agent/fleet/git-isolation.js

@@ -0,0 +1,290 @@
+/**
+ * Git isolation protocol for the fleet — the safety layer that makes it
+ * *physically impossible* for two parallel subagents to clobber each other's
+ * files, and that makes it *impossible to lose* any work an agent committed.
+ *
+ * The original fleet ran every subagent against one shared working tree and
+ * tried to avoid collisions with a guess: tasks whose *predicted* `files[]`
+ * overlapped were serialized. That guess fails the moment an agent edits a file
+ * it didn't predict — two writes interleave and you get a half-written file,
+ * before any commit exists to recover from. The fix is not "commit more
+ * cleverly", it's isolation: give each agent its own checkout.
+ *
+ * The model (a correct, minimal version of "branch-per-change, replay-on-merge"):
+ *
+ *   1. SPAWN   — each task gets its own `git worktree` on its own branch, cut
+ *                from a single frozen base ref. Separate index, separate HEAD,
+ *                separate files: file-level clobbering is now structurally
+ *                impossible, not merely discouraged.
+ *   2. CHECKPOINT — the agent's changes are committed atomically, and every
+ *                commit hash is pinned under `refs/oxagen/agents/<task>/<n>`.
+ *                A pinned commit is content-addressed and immune to branch
+ *                deletion and `git gc`: work can be orphaned but never lost.
+ *   3. INTEGRATE — task branches are merged back into one integration branch
+ *                *one at a time* (a mutex), with `rerere` enabled. A merge that
+ *                conflicts is **aborted**, leaving the integration tree clean,
+ *                and the conflict is *surfaced* (the files are returned) instead
+ *                of silently corrupting anything. Conflicts are relocated to an
+ *                explicit, owned step — they are not made to disappear, because
+ *                for *code* that is impossible in general (two semantically
+ *                contradictory edits can't both be right).
+ *   4. DISPOSE  — worktrees and branches are torn down, but the
+ *                `refs/oxagen/agents/*` pins are kept. `git for-each-ref
+ *                refs/oxagen/agents` is then a durable log of every atomic
+ *                change the fleet ever made, recoverable by hash.
+ *
+ * Git is shelled via {@link GitRunner} (injectable) so the orchestrator's unit
+ * tests stay filesystem-free; the real runner uses `node:child_process`,
+ * matching the rest of the CLI (no git library dependency).
+ */
+import { execFile } from "node:child_process";
+import { mkdirSync, existsSync, readFileSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+const pexec = promisify(execFile);
+/** The real runner: `git <args>` via child_process, rooted at the repo. */
+export function defaultGitRunner(repoRoot) {
+    return async (args, cwd) => {
+        try {
+            const { stdout, stderr } = await pexec("git", args, {
+                cwd: cwd ?? repoRoot,
+                maxBuffer: 64 * 1024 * 1024,
+            });
+            return { stdout, stderr, code: 0 };
+        }
+        catch (e) {
+            const err = e;
+            return {
+                stdout: err.stdout ?? "",
+                stderr: err.stderr ?? err.message ?? "",
+                code: typeof err.code === "number" ? err.code : 1,
+            };
+        }
+    };
+}
+/** Allowed characters in a branch/path segment derived from a task id. */
+function safeSegment(id) {
+    return id.replace(/[^A-Za-z0-9._-]/g, "-").replace(/^-+|-+$/g, "") || "task";
+}
+/**
+ * Owns the worktrees, branches, and durability pins for one fleet run.
+ *
+ * One instance per {@link Fleet}. Methods are safe to call from many concurrent
+ * agents: `spawn`/`checkpoint`/`dispose` operate on disjoint worktrees, and
+ * `integrate` is serialized internally so two merges never race on the
+ * integration branch.
+ */
+export class WorktreeManager {
+    opts;
+    git;
+    ns;
+    repoRoot;
+    root;
+    /** The frozen commit every task branch is cut from. */
+    baseRef = "";
+    /** Lazily-created integration worktree path + branch. */
+    integration = null;
+    initialized = false;
+    /** Per-task pin sequence + recorded checkpoints (the durability log). */
+    seq = new Map();
+    commits = new Map();
+    /** Worktrees handed out, by task id. */
+    worktrees = new Map();
+    /** Serializes `integrate` so concurrent finishers can't race the merge. */
+    integrateLock = Promise.resolve();
+    constructor(opts) {
+        this.opts = opts;
+        this.git = opts.git ?? defaultGitRunner(opts.repoRoot);
+        this.ns = safeSegment(opts.namespace ?? "fleet");
+        this.repoRoot = opts.repoRoot;
+        this.root = opts.root ?? join(opts.repoRoot, ".oxagen", "worktrees");
+    }
+    /**
+     * Resolve the repo toplevel, freeze the base ref, enable `rerere`, and keep
+     * the worktree root out of git's sight. Idempotent.
+     */
+    async init() {
+        if (this.initialized)
+            return;
+        const top = await this.git(["rev-parse", "--show-toplevel"]);
+        if (top.code !== 0) {
+            throw new Error(`git isolation: not a git repository (${top.stderr.trim()})`);
+        }
+        this.repoRoot = top.stdout.trim();
+        if (!this.opts.root)
+            this.root = join(this.repoRoot, ".oxagen", "worktrees");
+        const head = await this.git(["rev-parse", "HEAD"]);
+        if (head.code !== 0)
+            throw new Error(`git isolation: cannot resolve HEAD (${head.stderr.trim()})`);
+        this.baseRef = head.stdout.trim();
+        // rerere makes repeated conflict resolutions idempotent — a resolver agent
+        // (or human) resolves a given conflict once and git replays it thereafter.
+        await this.git(["config", "rerere.enabled", "true"]);
+        this.excludeWorktreeRoot();
+        mkdirSync(this.root, { recursive: true });
+        this.initialized = true;
+    }
+    /** The frozen base every task fans out from. */
+    get base() {
+        return this.baseRef;
+    }
+    /**
+     * Create an isolated worktree for `taskId` and return its path. The agent runs
+     * with this as its `cwd`; nothing it does can touch another agent's tree.
+     */
+    async spawn(taskId) {
+        await this.init();
+        const seg = safeSegment(taskId);
+        const branch = `fleet/${this.ns}/t/${seg}`;
+        const path = join(this.root, this.ns, `t-${seg}`);
+        // A re-run may leave a stale worktree/branch behind; clear it first.
+        await this.removeWorktree(path);
+        await this.git(["branch", "-D", branch]); // ignore "not found"
+        const add = await this.git(["worktree", "add", "-b", branch, path, this.baseRef]);
+        if (add.code !== 0) {
+            throw new Error(`git isolation: worktree add failed for ${taskId}: ${add.stderr.trim()}`);
+        }
+        this.worktrees.set(taskId, { path, branch });
+        return path;
+    }
+    /**
+     * Atomically commit whatever the agent changed in its worktree and pin the
+     * commit under `refs/oxagen/agents/<task>/<n>`. Returns the checkpoint, or
+     * `null` when the agent changed nothing.
+     */
+    async checkpoint(taskId, message) {
+        const wt = this.worktrees.get(taskId);
+        if (!wt)
+            throw new Error(`git isolation: no worktree for ${taskId} (call spawn first)`);
+        await this.git(["add", "-A"], wt.path);
+        const status = await this.git(["status", "--porcelain"], wt.path);
+        if (status.code === 0 && status.stdout.trim() === "")
+            return null; // nothing changed
+        // --no-verify: these are fine-grained per-step commits; the gate runs at
+        // integration / CI, not on every micro-commit.
+        const commit = await this.git(["commit", "--no-verify", "-m", message], wt.path);
+        if (commit.code !== 0) {
+            throw new Error(`git isolation: commit failed for ${taskId}: ${commit.stderr.trim()}`);
+        }
+        const rev = await this.git(["rev-parse", "HEAD"], wt.path);
+        const hash = rev.stdout.trim();
+        const n = (this.seq.get(taskId) ?? 0) + 1;
+        this.seq.set(taskId, n);
+        const ref = `refs/oxagen/agents/${safeSegment(taskId)}/${n}`;
+        await this.git(["update-ref", ref, hash]); // pin: survives branch deletion + gc
+        const cp = { taskId, hash, ref, message };
+        const list = this.commits.get(taskId) ?? [];
+        list.push(cp);
+        this.commits.set(taskId, list);
+        return cp;
+    }
+    /** Every pinned checkpoint recorded for a task — the durability log. */
+    recordedCommits(taskId) {
+        return this.commits.get(taskId) ?? [];
+    }
+    /**
+     * Merge a task's branch into the integration branch. Serialized so two merges
+     * never race. A conflicting merge is aborted (integration tree left clean) and
+     * the conflicting files are returned — never a corrupt half-merge.
+     */
+    integrate(taskId, message) {
+        return this.withIntegrateLock(() => this.doIntegrate(taskId, message));
+    }
+    async doIntegrate(taskId, message) {
+        const wt = this.worktrees.get(taskId);
+        if (!wt)
+            throw new Error(`git isolation: no worktree for ${taskId}`);
+        const int = await this.ensureIntegration();
+        const msg = message ?? `fleet(${taskId}): integrate`;
+        const merge = await this.git(["merge", "--no-ff", "-m", msg, wt.branch], int.path);
+        if (merge.code === 0) {
+            const tip = await this.git(["rev-parse", "HEAD"], int.path);
+            return { ok: true, commit: tip.stdout.trim(), taskBranch: wt.branch };
+        }
+        // Conflict. rerere may already have replayed a recorded resolution — if no
+        // files remain unmerged, commit it and report success.
+        const unmerged = await this.git(["diff", "--name-only", "--diff-filter=U"], int.path);
+        const conflicts = unmerged.stdout.split("\n").map((l) => l.trim()).filter(Boolean);
+        if (conflicts.length === 0) {
+            const done = await this.git(["commit", "--no-verify", "--no-edit"], int.path);
+            if (done.code === 0) {
+                const tip = await this.git(["rev-parse", "HEAD"], int.path);
+                return { ok: true, commit: tip.stdout.trim(), taskBranch: wt.branch, autoResolved: true };
+            }
+        }
+        // Real conflict: abort so the integration tree stays clean, and surface it.
+        await this.git(["merge", "--abort"], int.path);
+        const tip = await this.git(["rev-parse", wt.branch]);
+        return { ok: false, conflicts, taskBranch: wt.branch, taskTip: tip.stdout.trim() };
+    }
+    /** The integration branch + its worktree path, once at least one integrate ran. */
+    integrationRef() {
+        return this.integration;
+    }
+    /**
+     * Remove a task's worktree. Keeps the branch and the `refs/oxagen/agents` pins
+     * (so nothing is lost). Pass `keep` to leave the worktree on disk — e.g. after
+     * a conflict, so a resolver agent or human can work in it.
+     */
+    async dispose(taskId, opts = {}) {
+        const wt = this.worktrees.get(taskId);
+        if (!wt || opts.keep)
+            return;
+        await this.removeWorktree(wt.path);
+        this.worktrees.delete(taskId);
+    }
+    /**
+     * Tear down every worktree and prune. Keeps the integration branch (the
+     * result) and all `refs/oxagen/agents` pins (the durability log).
+     */
+    async cleanupAll() {
+        for (const [id, wt] of this.worktrees) {
+            await this.removeWorktree(wt.path);
+            this.worktrees.delete(id);
+        }
+        if (this.integration)
+            await this.removeWorktree(this.integration.path);
+        await this.git(["worktree", "prune"]);
+    }
+    // ── internals ────────────────────────────────────────────────────────────
+    async ensureIntegration() {
+        if (this.integration)
+            return this.integration;
+        const branch = `fleet/${this.ns}/integration`;
+        const path = join(this.root, this.ns, "integration");
+        await this.removeWorktree(path);
+        await this.git(["branch", "-D", branch]);
+        const add = await this.git(["worktree", "add", "-b", branch, path, this.baseRef]);
+        if (add.code !== 0) {
+            throw new Error(`git isolation: integration worktree failed: ${add.stderr.trim()}`);
+        }
+        this.integration = { path, branch };
+        return this.integration;
+    }
+    async removeWorktree(path) {
+        if (!existsSync(path))
+            return;
+        await this.git(["worktree", "remove", "--force", path]);
+    }
+    async withIntegrateLock(fn) {
+        const run = this.integrateLock.then(fn, fn);
+        this.integrateLock = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /** Keep `.oxagen/` out of git's untracked list without touching tracked .gitignore. */
+    excludeWorktreeRoot() {
+        try {
+            const exclude = join(this.repoRoot, ".git", "info", "exclude");
+            if (!existsSync(exclude))
+                return;
+            const body = readFileSync(exclude, "utf8");
+            if (!body.split("\n").some((l) => l.trim() === ".oxagen/")) {
+                appendFileSync(exclude, `${body.endsWith("\n") ? "" : "\n"}.oxagen/\n`);
+            }
+        }
+        catch {
+            /* best-effort; isolation still works if we can't write the exclude */
+        }
+    }
+}
+//# sourceMappingURL=git-isolation.js.map

package/dist/agent/fleet/git-isolation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-isolation.js","sourceRoot":"","sources":["../../../src/agent/fleet/git-isolation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC9E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAYlC,2EAA2E;AAC3E,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,OAAO,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QACzB,IAAI,CAAC;YACH,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE;gBAClD,GAAG,EAAE,GAAG,IAAI,QAAQ;gBACpB,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;aAC5B,CAAC,CAAC;YACH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QACrC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,GAAG,GAAG,CAAmF,CAAC;YAChG,OAAO;gBACL,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE;gBACxB,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,OAAO,IAAI,EAAE;gBACvC,IAAI,EAAE,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;aAClD,CAAC;QACJ,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAsDD,0EAA0E;AAC1E,SAAS,WAAW,CAAC,EAAU;IAC7B,OAAO,EAAE,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC;AAC/E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,eAAe;IACT,IAAI,CAAyB;IAC7B,GAAG,CAAY;IACf,EAAE,CAAS;IACpB,QAAQ,CAAS;IACjB,IAAI,CAAS;IAErB,uDAAuD;IAC/C,OAAO,GAAG,EAAE,CAAC;IACrB,yDAAyD;IACjD,WAAW,GAA4C,IAAI,CAAC;IAC5D,WAAW,GAAG,KAAK,CAAC;IAE5B,yEAAyE;IACxD,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IAChC,OAAO,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC3D,wCAAwC;IACvB,SAAS,GAAG,IAAI,GAAG,EAA4C,CAAC;IAEjF,2EAA2E;IACnE,aAAa,GAAqB,OAAO,CAAC,OAAO,EAAE,CAAC;IAE5D,YAAY,IAA4B;QACtC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACvD,IAAI,CAAC,EAAE,GAAG,WAAW,CAAC,IAAI,CAAC,SAAS,IAAI,OAAO,CAAC,CAAC;QACjD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;IACvE,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI;QACR,IAAI,IAAI,CAAC,WAAW;YAAE,OAAO;QAE7B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,iBAAiB,CAAC,CAAC,CAAC;QAC7D,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,wCAAwC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAChF,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAClC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;QAE7E,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;QACnD,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACnG,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAElC,2EAA2E;QAC3E,2EAA2E;QAC3E,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,gBAAgB,EAAE,MAAM,CAAC,CAAC,CAAC;QAErD,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC3B,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1C,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAC1B,CAAC;IAED,gDAAgD;IAChD,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK,CAAC,MAAc;QACxB,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,MAAM,GAAG,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;QAChC,MAAM,MAAM,GAAG,SAAS,IAAI,CAAC,EAAE,MAAM,GAAG,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,GAAG,EAAE,CAAC,CAAC;QAElD,qEAAqE;QACrE,MAAM,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;QAChC,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,qBAAqB;QAE/D,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QAClF,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,0CAA0C,MAAM,KAAK,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC5F,CAAC;QACD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QAC7C,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,UAAU,CAAC,MAAc,EAAE,OAAe;QAC9C,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACtC,IAAI,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,MAAM,qBAAqB,CAAC,CAAC;QAExF,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,aAAa,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;QAClE,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,OAAO,IAAI,CAAC,CAAC,kBAAkB;QAErF,yEAAyE;QACzE,+CAA+C;QAC/C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;QACjF,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,oCAAoC,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACzF,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;QAC3D,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAE/B,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QACxB,MAAM,GAAG,GAAG,sBAAsB,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,YAAY,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,qCAAqC;QAEhF,MAAM,EAAE,GAAe,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;QACtD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC5C,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACd,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC/B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,wEAAwE;IACxE,eAAe,CAAC,MAAc;QAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACxC,CAAC;IAED;;;;OAIG;IACH,SAAS,CAAC,MAAc,EAAE,OAAgB;QACxC,OAAO,IAAI,CAAC,iBAAiB,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACzE,CAAC;IAEO,KAAK,CAAC,WAAW,CAAC,MAAc,EAAE,OAAgB;QACxD,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACtC,IAAI,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,MAAM,EAAE,CAAC,CAAC;QACrE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAC3C,MAAM,GAAG,GAAG,OAAO,IAAI,SAAS,MAAM,cAAc,CAAC;QAErD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QACnF,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACrB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;YAC5D,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,UAAU,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC;QACxE,CAAC;QAED,2EAA2E;QAC3E,uDAAuD;QACvD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,aAAa,EAAE,iBAAiB,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QACtF,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAEnF,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,aAAa,EAAE,WAAW,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;YAC9E,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;gBACpB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;gBAC5D,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,UAAU,EAAE,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;YAC5F,CAAC;QACH,CAAC;QAED,4EAA4E;QAC5E,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QAC/C,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;QACrD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;IACrF,CAAC;IAED,mFAAmF;IACnF,cAAc;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAAC,MAAc,EAAE,OAA2B,EAAE;QACzD,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACtC,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,IAAI;YAAE,OAAO;QAC7B,MAAM,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,UAAU;QACd,KAAK,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,MAAM,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;YACnC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC5B,CAAC;QACD,IAAI,IAAI,CAAC,WAAW;YAAE,MAAM,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QACvE,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;IACxC,CAAC;IAED,4EAA4E;IAEpE,KAAK,CAAC,iBAAiB;QAC7B,IAAI,IAAI,CAAC,WAAW;YAAE,OAAO,IAAI,CAAC,WAAW,CAAC;QAC9C,MAAM,MAAM,GAAG,SAAS,IAAI,CAAC,EAAE,cAAc,CAAC;QAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,aAAa,CAAC,CAAC;QACrD,MAAM,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;QAChC,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QACzC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QAClF,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,+CAA+C,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACtF,CAAC;QACD,IAAI,CAAC,WAAW,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QACpC,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAEO,KAAK,CAAC,cAAc,CAAC,IAAY;QACvC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO;QAC9B,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;IAC1D,CAAC;IAEO,KAAK,CAAC,iBAAiB,CAAI,EAAoB;QACrD,MAAM,GAAG,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QAC5C,IAAI,CAAC,aAAa,GAAG,GAAG,CAAC,IAAI,CAC3B,GAAG,EAAE,CAAC,SAAS,EACf,GAAG,EAAE,CAAC,SAAS,CAChB,CAAC;QACF,OAAO,GAAiB,CAAC;IAC3B,CAAC;IAED,uFAAuF;IAC/E,mBAAmB;QACzB,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;YAC/D,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;gBAAE,OAAO;YACjC,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC3C,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,UAAU,CAAC,EAAE,CAAC;gBAC3D,cAAc,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,CAAC;YAC1E,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,sEAAsE;QACxE,CAAC;IACH,CAAC;CACF"}

package/dist/agent/fleet/memory.d.ts

@@ -0,0 +1,21 @@
+import type { MemoryRecord } from "./types.js";
+export interface FleetMemory {
+    /** Append a weighted lesson. Never throws — recording must not break a run. */
+    record(rec: Omit<MemoryRecord, "id" | "createdAt">): void;
+    /** Return the most relevant lessons for a query, best first. */
+    recall(query: string, opts?: {
+        limit?: number;
+        files?: string[];
+    }): MemoryRecord[];
+    /** All records, newest first (for the agents screen memory panel). */
+    all(): MemoryRecord[];
+}
+/**
+ * Open (or create) the project's fleet memory. Reads are cached in-process and
+ * invalidated on every write, so a long-lived REPL/agents screen sees its own
+ * appends without re-reading the file each recall.
+ */
+export declare function openFleetMemory(cwd: string): FleetMemory;
+/** Render recalled lessons as a compact context block for prompt injection. */
+export declare function formatLessons(records: MemoryRecord[]): string;
+//# sourceMappingURL=memory.d.ts.map

package/dist/agent/fleet/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../src/agent/fleet/memory.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAwB/C,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,WAAW,CAAC,GAAG,IAAI,CAAC;IAC1D,gEAAgE;IAChE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,YAAY,EAAE,CAAC;IACnF,sEAAsE;IACtE,GAAG,IAAI,YAAY,EAAE,CAAC;CACvB;AAQD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAkExD;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAS7D"}

package/dist/agent/fleet/memory.js

@@ -0,0 +1,129 @@
+/**
+ * Fleet memory — a local, dependency-free record of what the agent army builds
+ * and fixes, with lexical recall.
+ *
+ * This complements the engram/DuckDB episodic store ({@link openSessionMemory}).
+ * That store is best-effort and silently disables itself when its optional native
+ * dependency is missing; this one is plain JSON Lines on disk, so memory
+ * recording is *guaranteed* — which is what the user asked for ("record the
+ * memories as it fixes/builds things"). It mirrors the platform's weighted
+ * `agent.memory.write` shape (kind + weight + lesson) so the same lessons can be
+ * promoted to the knowledge graph later.
+ *
+ * Recall is a transparent lexical scorer (term overlap + file overlap + weight),
+ * not embeddings: it needs no model call, works offline, and is good enough to
+ * surface the handful of relevant lessons that should steer the next task.
+ */
+import { mkdirSync, appendFileSync, readFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+/** Stable per-project key from the working directory name. */
+function projectKey(cwd) {
+    return basename(cwd) || "default";
+}
+function memoryPath(cwd) {
+    return join(homedir(), ".config", "oxagen", "memories", `${projectKey(cwd)}.jsonl`);
+}
+const STOPWORDS = new Set([
+    "the", "a", "an", "and", "or", "to", "of", "in", "on", "for", "with", "is",
+    "are", "be", "this", "that", "it", "as", "at", "by", "from", "into", "we",
+    "you", "i", "fix", "add", "the", "use", "code", "file", "files",
+]);
+/** Split text into lowercased, de-stopped terms for lexical scoring. */
+function terms(text) {
+    return (text.toLowerCase().match(/[a-z0-9_]+/g) ?? []).filter((t) => t.length > 2 && !STOPWORDS.has(t));
+}
+let counter = 0;
+function newId() {
+    counter = (counter + 1) % 1_000_000;
+    return `mem_${Date.now().toString(36)}_${counter.toString(36)}`;
+}
+/**
+ * Open (or create) the project's fleet memory. Reads are cached in-process and
+ * invalidated on every write, so a long-lived REPL/agents screen sees its own
+ * appends without re-reading the file each recall.
+ */
+export function openFleetMemory(cwd) {
+    const path = memoryPath(cwd);
+    let cache = null;
+    function load() {
+        if (cache)
+            return cache;
+        if (!existsSync(path)) {
+            cache = [];
+            return cache;
+        }
+        try {
+            const lines = readFileSync(path, "utf8").split("\n").filter(Boolean);
+            cache = lines
+                .map((l) => {
+                try {
+                    return JSON.parse(l);
+                }
+                catch {
+                    return null;
+                }
+            })
+                .filter((r) => r !== null);
+        }
+        catch {
+            cache = [];
+        }
+        return cache;
+    }
+    return {
+        record(rec) {
+            const full = { ...rec, id: newId(), createdAt: Date.now() };
+            try {
+                mkdirSync(dirname(path), { recursive: true });
+                appendFileSync(path, JSON.stringify(full) + "\n", "utf8");
+                if (cache)
+                    cache.push(full);
+                else
+                    cache = [full];
+            }
+            catch {
+                /* memory is best-effort — never break the run over a failed append */
+            }
+        },
+        recall(query, opts = {}) {
+            const limit = opts.limit ?? 5;
+            const qTerms = new Set(terms(query));
+            const qFiles = new Set((opts.files ?? []).map((f) => f));
+            const weightBoost = { low: 0, high: 1, critical: 2 };
+            const scored = load()
+                .map((r) => {
+                const rTerms = terms(r.lesson + " " + r.files.join(" "));
+                let overlap = 0;
+                for (const t of rTerms)
+                    if (qTerms.has(t))
+                        overlap++;
+                let fileOverlap = 0;
+                for (const f of r.files)
+                    if (qFiles.has(f))
+                        fileOverlap++;
+                const score = overlap + fileOverlap * 3 + weightBoost[r.weight];
+                return { r, score };
+            })
+                .filter((s) => s.score > 0)
+                .sort((a, b) => b.score - a.score || b.r.createdAt - a.r.createdAt);
+            return scored.slice(0, limit).map((s) => s.r);
+        },
+        all() {
+            return [...load()].sort((a, b) => b.createdAt - a.createdAt);
+        },
+    };
+}
+/** Render recalled lessons as a compact context block for prompt injection. */
+export function formatLessons(records) {
+    if (records.length === 0)
+        return "";
+    return records
+        .map((r) => {
+        const mark = r.weight === "critical" ? "‼" : r.weight === "high" ? "!" : "·";
+        const files = r.files.length ? ` [${r.files.slice(0, 3).join(", ")}]` : "";
+        return `${mark} (${r.kind}) ${r.lesson}${files}`;
+    })
+        .join("\n");
+}
+//# sourceMappingURL=memory.js.map

package/dist/agent/fleet/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../../src/agent/fleet/memory.ts"],"names":[],"mappings":"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"}

package/dist/agent/fleet/orchestrator.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The fleet orchestrator — an army of coding subagents working one tree at once.
+ *
+ * Each task is run by a subagent: the local coding loop ({@link runAgent}) on the
+ * cheapest sufficient model, against the same working directory. The orchestrator
+ * keeps as many running as the concurrency cap allows while respecting two safety
+ * rules so parallel agents never corrupt the tree or each other:
+ *
+ *   1. Dependencies — a task waits until every task it `dependsOn` is `done`; if a
+ *      dependency fails, the task (and its dependents) are marked `blocked`.
+ *   2. File ownership — two tasks whose predicted `files` overlap are serialized,
+ *      so two agents never edit the same file at the same time.
+ *
+ * It records a weighted memory for every task it finishes (success or failure),
+ * accumulates token/cost totals, and emits a snapshot on every change for the
+ * agents screen to render. `runAgent` is injected so the engine is unit-testable
+ * without touching the gateway.
+ */
+import { EventEmitter } from "node:events";
+import type { ProjectContext } from "../project-context.js";
+import type { AgentDefinition } from "../../agents/types.js";
+import type { FleetMemory } from "./memory.js";
+import type { PlanStore } from "./store.js";
+import type { Isolation } from "./git-isolation.js";
+import { type FleetSnapshot, type Plan } from "./types.js";
+/** The subset of {@link runAgent} the fleet depends on (injectable for tests). */
+export type AgentRunner = (opts: {
+    prompt: string;
+    cwd: string;
+    model?: string;
+    projectContext?: ProjectContext;
+    agent?: AgentDefinition;
+    readOnly?: boolean;
+    signal?: AbortSignal;
+    onText?: (delta: string) => void;
+    onToolCall?: (name: string, input: unknown) => void;
+}) => Promise<{
+    text: string;
+    steps: number;
+    usage: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+}>;
+export interface FleetOptions {
+    cwd: string;
+    /** Max subagents running at once (default 4). */
+    concurrency?: number;
+    memory?: FleetMemory | null;
+    store?: PlanStore | null;
+    projectContext?: ProjectContext;
+    /** Named agent registry; a task's `agent` is looked up here at dispatch. */
+    agents?: Map<string, AgentDefinition>;
+    /** Inject a fake runner in tests; defaults to the real {@link runAgent}. */
+    runner?: AgentRunner;
+    /** Read-only subagents (explain, don't edit). */
+    readOnly?: boolean;
+    /**
+     * Per-task git isolation. When set, each agent runs in its own worktree and
+     * its work is checkpointed + integrated via explicit merges, so parallel
+     * agents physically cannot clobber the tree. When omitted (default), all
+     * agents share `cwd` and overlapping-file tasks are serialized instead.
+     */
+    isolation?: Isolation | null;
+}
+export declare class Fleet extends EventEmitter {
+    private readonly cwd;
+    private readonly concurrency;
+    private readonly memory;
+    private readonly store;
+    private readonly projectContext;
+    private readonly agents;
+    private readonly runner;
+    private readonly readOnly;
+    private readonly isolation;
+    private readonly tasks;
+    private readonly snapshots;
+    private readonly controllers;
+    private readonly running;
+    private planId;
+    private settle;
+    private donePromise;
+    private adhocCounter;
+    constructor(opts: FleetOptions);
+    /** Register every task in a plan (does not start it). */
+    loadPlan(plan: Plan): void;
+    /** Add one ad-hoc task (e.g. typed into the agents screen). Returns its id. */
+    dispatchPrompt(prompt: string): string;
+    /** Begin scheduling. Resolves when every task has reached a terminal state. */
+    start(): Promise<void>;
+    /** Cancel one running/queued task. */
+    cancelTask(id: string): void;
+    /** Cancel everything in flight. */
+    cancelAll(): void;
+    snapshot(): FleetSnapshot;
+    /** Fill open slots with ready tasks, honouring deps and file-ownership locks. */
+    private pump;
+    /** The next queued task whose deps are all done and whose files are free. */
+    private pickReady;
+    private run;
+    private recordSuccess;
+    private recordFailure;
+    private toSnapshot;
+    private update;
+    private emitUpdate;
+    private checkDone;
+}
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/agent/fleet/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../../src/agent/fleet/orchestrator.ts"],"names":[],"mappings":"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"}