@prohost/cli 0.8.2 → 0.9.0

package/dist/agent/worktrees.js

@@ -0,0 +1,317 @@
+/**
+ * A private checkout of each `--repos` repository, per conversation.
+ *
+ * A coding agent that opens pull requests does it in a git checkout, and until
+ * `--concurrency` there was only ever one run touching it. Two runs sharing one
+ * checkout switch each other's branch mid-edit and commit each other's
+ * half-finished files — the reason runs were serialized in the first place. So
+ * when the operator names the repositories the agent works on, each
+ * conversation gets its own `git worktree` of every one of them:
+ *
+ *     $PROHOST_HOME/worktrees/<conversation>/<repo-name>
+ *
+ * Per *conversation*, not per run, for the same reason sessions are: a
+ * follow-up in the thread ("address the review comments") resumes the session
+ * that made the branch, and must find that branch where it left it. Runs of one
+ * conversation never overlap (see `scheduler.ts`), so one checkout per
+ * conversation is exactly as isolated as one per run and far cheaper.
+ *
+ * The harness makes the worktree; the agent never needs `git worktree add`.
+ * The agent command's working directory does not change — it stays the
+ * workspace, because that is where its `.claude/` configuration lives and what
+ * its sessions are keyed on. The checkouts are named in the prompt and in
+ * `$PROHOST_RUN_REPOS`.
+ *
+ * Worktrees share the source repository's object store, so a branch committed
+ * in one survives the worktree being removed. That is what makes pruning safe:
+ * `git worktree remove` (never `--force`) refuses a checkout with uncommitted
+ * or untracked files, and those are the only things a worktree holds alone.
+ */
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, rmdirSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { prohostHome } from './credentials.js';
+/** Child-process env var naming the directory that holds this run's checkouts. */
+export const RUN_REPOS_ENV_VAR = 'PROHOST_RUN_REPOS';
+/** Touched on every run of a conversation; its mtime is "last used". */
+const MARKER_FILENAME = '.last-used';
+/** A conversation's checkouts idle this long are removed, if clean. */
+export const WORKTREE_RETENTION_MS = 14 * 24 * 3_600_000;
+/** Pruning walks every conversation directory, so it is not done per run. */
+const PRUNE_INTERVAL_MS = 24 * 3_600_000;
+/** Checking out a large repository takes a while; a wedged git must still end. */
+const GIT_TIMEOUT_MS = 10 * 60_000;
+export class ReposFlagError extends Error {
+}
+export function worktreesRoot(env = process.env) {
+    return path.join(prohostHome(env), 'worktrees');
+}
+/**
+ * Directory name for a lane (see `sessionKeyFor`).
+ *
+ * Readable enough to recognise in `ls`, and suffixed with a digest of the whole
+ * key because the readable part is lossy: two keys that differ only in
+ * punctuation, or in the agent they belong to, must not share a checkout.
+ */
+export function laneDirName(lane) {
+    const surface = lane.includes('/') ? lane.slice(lane.indexOf('/') + 1) : lane;
+    const readable = surface.replace(/[^A-Za-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60);
+    const digest = createHash('sha256').update(lane).digest('hex').slice(0, 8);
+    return readable ? `${readable}-${digest}` : digest;
+}
+function git(args, env) {
+    return new Promise((resolve) => {
+        execFile('git', args, { env: { ...process.env, ...env }, timeout: GIT_TIMEOUT_MS, maxBuffer: 4 * 1024 * 1024 }, (error, stdout, stderr) => {
+            resolve({ ok: error === null, stdout: String(stdout), stderr: String(stderr) || (error?.message ?? '') });
+        });
+    });
+}
+function lastLine(text) {
+    const lines = text.trim().split('\n');
+    return (lines[lines.length - 1] ?? '').trim();
+}
+/**
+ * Read `--repos a,b` into absolute paths, refusing what can never work.
+ *
+ * An empty list and two checkouts with one directory name are always errors.
+ * A path that is not a git checkout is an error only when `requireCheckouts`
+ * is set — which `install-daemon` does and `agent run` does not. At install
+ * time a mistyped path should stop the install; at run time the same check
+ * would make a daemon whose repository was moved, deleted or is on an
+ * unmounted volume exit before connecting, and the service manager restart it
+ * forever. A running harness instead reports the checkout it could not make on
+ * each run, and keeps answering.
+ *
+ * @throws ReposFlagError naming the entry that is wrong.
+ */
+export function parseReposFlag(raw, options = {}) {
+    const entries = raw
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    if (entries.length === 0)
+        throw new ReposFlagError('--repos needs at least one path to a git checkout.');
+    const repos = [];
+    const names = new Map();
+    for (const entry of entries) {
+        const repo = path.resolve(entry);
+        if (options.requireCheckouts && !isCheckout(repo)) {
+            throw new ReposFlagError(`--repos: ${repo} is not the top of a git checkout (no .git there).`);
+        }
+        const name = path.basename(repo);
+        const clash = names.get(name);
+        if (clash && clash !== repo) {
+            throw new ReposFlagError(`--repos: ${clash} and ${repo} are both named "${name}"; their checkouts would land in the same directory.`);
+        }
+        if (!clash)
+            repos.push(repo);
+        names.set(name, repo);
+    }
+    return repos;
+}
+/** Whether `repo` is the top of a git checkout (a clone, or a worktree of one). */
+export function isCheckout(repo) {
+    return existsSync(path.join(repo, '.git'));
+}
+/**
+ * Makes, reuses and prunes per-conversation worktrees for one harness.
+ *
+ * Every git mutation goes through one in-process queue. Lanes run side by
+ * side, and two `git worktree add` calls against the same repository race for
+ * the same administrative name; pruning, meanwhile, must never remove the
+ * directory a run arriving this instant is about to use.
+ */
+export class WorktreeManager {
+    repos;
+    env;
+    log;
+    now;
+    retentionMs;
+    chain = Promise.resolve();
+    lastPrunedAt = 0;
+    constructor(options) {
+        this.repos = options.repos;
+        this.env = options.env ?? process.env;
+        this.log = options.log ?? (() => { });
+        this.now = options.now ?? Date.now;
+        this.retentionMs = options.retentionMs ?? WORKTREE_RETENTION_MS;
+    }
+    get enabled() {
+        return this.repos.length > 0;
+    }
+    exclusive(work) {
+        const next = this.chain.then(work, work);
+        this.chain = next.catch(() => { });
+        return next;
+    }
+    /**
+     * Ensure this lane has a worktree of every repository, and say where.
+     *
+     * Never rejects and never fails the run: most runs are questions that touch
+     * no repository at all, so a checkout that could not be made is reported in
+     * {@link PreparedCheckouts.failures} for the prompt to tell the agent about.
+     */
+    prepare(lane) {
+        return this.exclusive(async () => {
+            const dir = path.join(worktreesRoot(this.env), laneDirName(lane));
+            const prepared = { dir, checkouts: [], failures: [] };
+            try {
+                mkdirSync(dir, { recursive: true, mode: 0o700 });
+                this.touch(dir);
+            }
+            catch (err) {
+                const reason = err instanceof Error ? err.message : String(err);
+                prepared.failures = this.repos.map((source) => ({ source, reason }));
+                return prepared;
+            }
+            for (const source of this.repos) {
+                const name = path.basename(source);
+                const target = path.join(dir, name);
+                let failure;
+                try {
+                    failure = isCheckout(target) ? await this.reuse(source, target) : await this.add(source, target);
+                }
+                catch (err) {
+                    failure = err instanceof Error ? err.message : String(err);
+                }
+                if (failure)
+                    prepared.failures.push({ source, reason: failure });
+                else
+                    prepared.checkouts.push({ name, path: target, source });
+            }
+            // Housekeeping for other conversations must not cost this one its run.
+            await this.pruneIfDue(dir).catch((err) => {
+                this.log(`    ! could not prune idle checkouts (${err instanceof Error ? err.message : String(err)})`);
+            });
+            return prepared;
+        });
+    }
+    /** The repository a checkout's history lives in, as one comparable path. */
+    async commonDir(checkout) {
+        const result = await git(['-C', checkout, 'rev-parse', '--path-format=absolute', '--git-common-dir'], this.env);
+        const dir = result.stdout.trim();
+        return result.ok && dir ? dir : undefined;
+    }
+    /**
+     * Keep an existing checkout — once it is proven to be a worktree of `source`.
+     *
+     * The directory is named after the repository's basename, so pointing
+     * `--repos` from `/old/app` to `/new/app` leaves every conversation with an
+     * `app` checkout of the *old* repository. Handing that to the agent as a
+     * checkout of the new one would have it commit to the wrong repository.
+     */
+    async reuse(source, target) {
+        const [mine, theirs] = await Promise.all([this.commonDir(target), this.commonDir(source)]);
+        if (theirs === undefined)
+            return `${source} is not a git checkout`;
+        if (mine === theirs)
+            return undefined;
+        // Not ours to throw away: without `--force`, git removes it only if it
+        // holds nothing uncommitted.
+        const removed = mine === undefined
+            ? { ok: false, stderr: 'it is not a usable git checkout' }
+            : await git(['--git-dir', mine, 'worktree', 'remove', target], this.env);
+        if (!removed.ok) {
+            return (`${target} is a checkout of a different repository and could not be replaced ` +
+                `(${lastLine(removed.stderr) || 'git would not remove it'})`);
+        }
+        this.log(`    ⚙ replaced ${target}: it was a checkout of ${mine}, not of ${source}`);
+        return this.add(source, target);
+    }
+    /** Returns why the worktree could not be made, or `undefined` when it was. */
+    async add(source, target) {
+        // A worktree whose directory was deleted by hand is still registered, and
+        // git refuses to add another at that path until the record is pruned.
+        await git(['-C', source, 'worktree', 'prune'], this.env);
+        // Detached at the remote's default branch: the agent cuts its own branch,
+        // and a detached HEAD cannot collide with a branch checked out elsewhere.
+        let base = 'HEAD';
+        for (const candidate of ['origin/HEAD', 'origin/main', 'origin/master']) {
+            const known = await git(['-C', source, 'rev-parse', '--verify', '--quiet', `${candidate}^{commit}`], this.env);
+            if (known.ok) {
+                base = candidate;
+                break;
+            }
+        }
+        const added = await git(['-C', source, 'worktree', 'add', '--detach', target, base], this.env);
+        if (added.ok) {
+            this.log(`    ⚙ checkout ready: ${target} (worktree of ${source} at ${base})`);
+            return undefined;
+        }
+        // A half-made directory would be mistaken for a checkout on the next run.
+        rmSync(target, { recursive: true, force: true });
+        return lastLine(added.stderr) || 'git worktree add failed';
+    }
+    touch(dir) {
+        const marker = path.join(dir, MARKER_FILENAME);
+        const stamp = new Date(this.now());
+        if (existsSync(marker))
+            utimesSync(marker, stamp, stamp);
+        else {
+            writeFileSync(marker, '');
+            utimesSync(marker, stamp, stamp);
+        }
+    }
+    async pruneIfDue(keep) {
+        if (this.now() - this.lastPrunedAt < PRUNE_INTERVAL_MS)
+            return;
+        this.lastPrunedAt = this.now();
+        await this.prune(keep);
+    }
+    /** Remove idle conversations' checkouts, never the one about to be used. */
+    async prune(keep) {
+        const root = worktreesRoot(this.env);
+        let lanes;
+        try {
+            lanes = readdirSync(root);
+        }
+        catch {
+            return; // nothing has ever been checked out
+        }
+        for (const lane of lanes) {
+            const dir = path.join(root, lane);
+            if (dir === keep)
+                continue;
+            try {
+                if (!statSync(dir).isDirectory())
+                    continue;
+                const marker = path.join(dir, MARKER_FILENAME);
+                const usedAt = (existsSync(marker) ? statSync(marker) : statSync(dir)).mtimeMs;
+                if (this.now() - usedAt < this.retentionMs)
+                    continue;
+                await this.removeLane(dir);
+            }
+            catch (err) {
+                this.log(`    ! could not prune ${dir} (${err instanceof Error ? err.message : String(err)})`);
+            }
+        }
+    }
+    async removeLane(dir) {
+        let kept = 0;
+        for (const name of readdirSync(dir)) {
+            if (name === MARKER_FILENAME)
+                continue;
+            const target = path.join(dir, name);
+            if (!existsSync(path.join(target, '.git'))) {
+                kept += 1;
+                continue;
+            }
+            // Asked of the worktree itself, so pruning still works for a repository
+            // the operator has since dropped from `--repos`.
+            const common = await git(['-C', target, 'rev-parse', '--path-format=absolute', '--git-common-dir'], this.env);
+            const removed = common.ok
+                ? await git(['--git-dir', common.stdout.trim(), 'worktree', 'remove', target], this.env)
+                : common;
+            if (!removed.ok) {
+                kept += 1;
+                this.log(`    ! kept idle checkout ${target} — ${lastLine(removed.stderr) || 'git would not remove it'}`);
+            }
+        }
+        if (kept === 0) {
+            rmSync(path.join(dir, MARKER_FILENAME), { force: true });
+            rmdirSync(dir);
+            this.log(`    ⚙ removed idle checkouts in ${dir}`);
+        }
+    }
+}

package/dist/index.js

@@ -25,7 +25,8 @@ function printHelp() {
         'Usage:',
         '  prohost listen --forward-to <local-url> [--api-key <key>] [--url <ws-url>] [--machine <name>] [--subscription-id <id>]',
         '  prohost agent pair --code <pairing-code> [--account <label>] [--webhook-url <https-url>] [--base-url <url>]',
-        "  prohost agent run --exec '<command>' [--idle-timeout <seconds>] [--timeout <seconds>] [--dry-run] [--workdir <dir>]",
+        "  prohost agent run --exec '<command>' [--concurrency <n>] [--repos <checkout,…>] [--idle-timeout <seconds>]",
+        '                    [--timeout <seconds>] [--dry-run] [--workdir <dir>]',
         "  prohost agent install-daemon --exec '<command>' [--workdir <dir>] [--account <label>]   Keep the agent running",
         '  prohost agent uninstall-daemon',
         '  prohost agent account add <label> --runtime claude|codex [--billing subscription|api_key]',
@@ -53,6 +54,14 @@ function printHelp() {
         '  --timeout        Seconds one run may take before it is killed, however busy it is.',
         '                   Defaults to 0 — no wall-clock limit, because a long run is not a stuck',
         '                   one. Set it if you want a hard ceiling as well as the stall watchdog.',
+        '  --concurrency    How many runs may execute at once, 1 to 16. Defaults to 1. Runs in the same',
+        '                   conversation always take turns, so only different conversations overlap.',
+        '                   Every run spends the same login\'s quota, and they share this machine —',
+        '                   pair it with --repos if the agent edits code.',
+        '  --repos          Comma-separated git checkouts the agent works on. Each conversation gets',
+        '                   its own `git worktree` of every one under $PROHOST_HOME/worktrees, kept for',
+        '                   the life of the thread and removed after 14 idle days if it is clean. The',
+        '                   agent is told to work there and to leave the originals alone.',
         '  --dry-run        Print the reply that would be posted; write nothing.',
         '  --workdir        Working directory for the agent command. Defaults to $PROHOST_HOME/workspace.',
         '                   Avoid pointing it at a code checkout: agents read CLAUDE.md, .claude/settings.json',
@@ -92,7 +101,8 @@ function printHelp() {
         '',
         'agent install-daemon flags:  (macOS: launchd; Linux: prints a systemd-user unit)',
         '  --exec           The same command you would pass to `agent run` (required).',
-        '  --workdir, --idle-timeout, --timeout, --machine, --url, --allow-unverified, --safe-tools',
+        '  --workdir, --concurrency, --repos, --idle-timeout, --timeout, --machine, --url,',
+        '  --allow-unverified, --safe-tools',
         '                   — passed to `agent run`.',
         '',
         'Global flags:',

package/dist/version.d.ts

@@ -7,6 +7,6 @@
  * `package.json`, so a release bump that forgets this file fails the suite
  * instead of shipping a `User-Agent` that lies about which build is calling.
  */
-export declare const CLI_VERSION = "0.8.2";
+export declare const CLI_VERSION = "0.9.0";
 /** Sent on every HTTP request the CLI makes back into ProhostAI. */
-export declare const USER_AGENT = "prohost-cli/0.8.2";
+export declare const USER_AGENT = "prohost-cli/0.9.0";

package/dist/version.js

@@ -7,6 +7,6 @@
  * `package.json`, so a release bump that forgets this file fails the suite
  * instead of shipping a `User-Agent` that lies about which build is calling.
  */
-export const CLI_VERSION = '0.8.2';
+export const CLI_VERSION = '0.9.0';
 /** Sent on every HTTP request the CLI makes back into ProhostAI. */
 export const USER_AGENT = `prohost-cli/${CLI_VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prohost/cli",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Run your own AI agent as a ProhostAI teammate, and stream your account's webhooks to your laptop.",
   "type": "module",
   "license": "MIT",