cruo-agent 0.1.0 → 0.1.2

package/README.md

@@ -60,6 +60,28 @@ Run it from the repository the agent should work on. If that repository needs
 installing before its tests will run, add `--prepare 'npm ci'` or whatever your
 equivalent is — a fresh checkout has your source and none of your dependencies.
 
+Checkouts go under `~/.cruo-work/<agent>`, one directory per agent, so **running
+several agents at once needs no extra flags**. `--worktree-root` overrides it if
+you want them somewhere else; pointing two agents at one root is safe too, since
+the sweep that clears abandoned checkouts at startup only removes ones too old
+for any run to still be inside.
+
+## When it stops doing anything
+
+A supervisor sitting idle costs nothing — it is a database query on a timer. If
+the *harness* refuses to work, though, the supervisor says so and slows down:
+
+```
+! the harness is refusing to work: the account's spend limit is reached
+  No card is charged for this, and polling backs off until it changes.
+```
+
+That distinction matters more than it looks. A refusal is a fact about your
+account, not about the card, so those runs are **not** counted against the
+card's `--max-attempts` — otherwise one billing problem would quietly set aside
+every issue the agent was holding, and you would come back to a board that had
+given up on work nobody abandoned.
+
 ## Common options
 
 | flag | |
@@ -74,7 +96,7 @@ equivalent is — a fresh checkout has your source and none of your dependencies
 | `--harness-timeout <seconds>` | kill a run that wedges (default 600) |
 | `--max-attempts <n>` | give up on a card after n unproductive runs (default 3) |
 
-The full list, and what each is for: <https://cruo.space/agents>
+The full list, and what each is for: <https://cruo.space/docs#agents>
 
 ## Running it somewhere that is not your laptop
 

package/dist/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.2

package/dist/cli.js

@@ -45,6 +45,64 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/options.ts
+function stripTokenFlag(argv2) {
+  const at = argv2.indexOf("--token");
+  if (at < 0) return [...argv2];
+  return [...argv2.slice(0, at), ...argv2.slice(at + 2)];
+}
+function numericIn(argv2, name, spec = {}) {
+  const i = argv2.indexOf(`--${name}`);
+  if (i < 0) return spec.fallback;
+  const raw = argv2[i + 1];
+  if (raw === void 0 || raw.startsWith("--")) {
+    throw new OptionError(
+      `--${name} expects a ${spec.integer ? "whole " : ""}number${spec.unit ? ` of ${spec.unit}` : ""}, but no value followed it.`
+    );
+  }
+  const value = raw.trim() === "" ? NaN : Number(raw);
+  const what = `--${name} ${JSON.stringify(raw)}`;
+  if (!Number.isFinite(value)) {
+    throw new OptionError(
+      `${what} is not a number.` + // Reached only by something like `-abc`. A plain `-5` is a finite
+      // negative and falls to the range check below, which is the accurate
+      // refusal for it — this hint is for the case where the leading dash is
+      // the reason it did not parse at all.
+      (raw.startsWith("-") ? " A leading `-` reads as a flag, not a sign." : "")
+    );
+  }
+  if (value <= 0) {
+    throw new OptionError(`${what} must be greater than zero${spec.unit ? ` ${spec.unit}` : ""}.`);
+  }
+  if (spec.integer && !Number.isInteger(value)) {
+    throw new OptionError(`${what} must be a whole number.`);
+  }
+  return value;
+}
+function requiredNumericIn(argv2, name, fallback, spec = {}) {
+  return numericIn(argv2, name, { ...spec, fallback });
+}
+function secondsIn(argv2, name, fallbackSeconds) {
+  return requiredNumericIn(argv2, name, fallbackSeconds, { unit: "seconds" }) * 1e3;
+}
+var OptionError, flagIn, optIn;
+var init_options = __esm({
+  "src/options.ts"() {
+    "use strict";
+    OptionError = class extends Error {
+      constructor(message) {
+        super(message);
+        this.name = "OptionError";
+      }
+    };
+    flagIn = (argv2, name) => argv2.includes(`--${name}`);
+    optIn = (argv2, name, fallback) => {
+      const i = argv2.indexOf(`--${name}`);
+      return i >= 0 && argv2[i + 1] && !argv2[i + 1].startsWith("--") ? argv2[i + 1] : fallback;
+    };
+  }
+});
+
 // ../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/core/core.js
 // @__NO_SIDE_EFFECTS__
 function $constructor(name, initializer3, params) {
@@ -15238,10 +15296,13 @@ var init_plans = __esm({
 });
 
 // ../../packages/core/dist/mcp-connect.js
-var CRUO_CLOUD;
+var DOCS_URL, AGENT_DOCS_URL, MCP_DOCS_URL, CRUO_CLOUD;
 var init_mcp_connect = __esm({
   "../../packages/core/dist/mcp-connect.js"() {
     "use strict";
+    DOCS_URL = "https://cruo.space/docs";
+    AGENT_DOCS_URL = `${DOCS_URL}#agents`;
+    MCP_DOCS_URL = `${DOCS_URL}#mcp`;
     CRUO_CLOUD = {
       apiUrl: "https://szsutuujxbldkykcvdrm.supabase.co",
       publishableKey: "sb_publishable_hpnQFQ8IV0JXTch51XAstA_-S8H1eaD",
@@ -45940,62 +46001,34 @@ var init_auth = __esm({
   }
 });
 
-// src/options.ts
-function numericIn(argv2, name, spec = {}) {
-  const i = argv2.indexOf(`--${name}`);
-  if (i < 0) return spec.fallback;
-  const raw = argv2[i + 1];
-  if (raw === void 0 || raw.startsWith("--")) {
-    throw new OptionError(
-      `--${name} expects a ${spec.integer ? "whole " : ""}number${spec.unit ? ` of ${spec.unit}` : ""}, but no value followed it.`
-    );
+// src/harness-signal.ts
+function refusalIn(stdout) {
+  if (!stdout.trim()) return null;
+  for (const [pattern, reason] of REFUSALS) {
+    if (pattern.test(stdout)) return reason;
   }
-  const value = raw.trim() === "" ? NaN : Number(raw);
-  const what = `--${name} ${JSON.stringify(raw)}`;
-  if (!Number.isFinite(value)) {
-    throw new OptionError(
-      `${what} is not a number.` + // Reached only by something like `-abc`. A plain `-5` is a finite
-      // negative and falls to the range check below, which is the accurate
-      // refusal for it — this hint is for the case where the leading dash is
-      // the reason it did not parse at all.
-      (raw.startsWith("-") ? " A leading `-` reads as a flag, not a sign." : "")
-    );
-  }
-  if (value <= 0) {
-    throw new OptionError(`${what} must be greater than zero${spec.unit ? ` ${spec.unit}` : ""}.`);
-  }
-  if (spec.integer && !Number.isInteger(value)) {
-    throw new OptionError(`${what} must be a whole number.`);
-  }
-  return value;
-}
-function requiredNumericIn(argv2, name, fallback, spec = {}) {
-  return numericIn(argv2, name, { ...spec, fallback });
+  return null;
 }
-function secondsIn(argv2, name, fallbackSeconds) {
-  return requiredNumericIn(argv2, name, fallbackSeconds, { unit: "seconds" }) * 1e3;
+function neverRan(run) {
+  return run.refusal !== null || run.stdoutBytes === 0;
 }
-var OptionError, flagIn, optIn;
-var init_options = __esm({
-  "src/options.ts"() {
+var REFUSALS;
+var init_harness_signal = __esm({
+  "src/harness-signal.ts"() {
     "use strict";
-    OptionError = class extends Error {
-      constructor(message) {
-        super(message);
-        this.name = "OptionError";
-      }
-    };
-    flagIn = (argv2, name) => argv2.includes(`--${name}`);
-    optIn = (argv2, name, fallback) => {
-      const i = argv2.indexOf(`--${name}`);
-      return i >= 0 && argv2[i + 1] && !argv2[i + 1].startsWith("--") ? argv2[i + 1] : fallback;
-    };
+    REFUSALS = [
+      [/hit your (monthly |weekly |daily )?(spend|usage) limit/i, "the account's spend limit is reached"],
+      [/insufficient credit|out of credit|credit balance is too low/i, "the account is out of credit"],
+      [/upgrade to (a paid plan|claude pro)/i, "the plan does not cover this"],
+      [/invalid api key|authentication[_ ]error|please run \/login/i, "the harness is not signed in"],
+      [/rate limit(ed| exceeded|s? reached)\b.*\btry again/i, "the account is rate limited"]
+    ];
   }
 });
 
 // src/worktree.ts
 import { execFile } from "node:child_process";
-import { mkdir, readdir, rm } from "node:fs/promises";
+import { mkdir, readdir, rm, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { promisify } from "node:util";
 async function git(repo, args) {
@@ -46078,7 +46111,7 @@ async function createWorktree(ref, config3) {
     }
   };
 }
-async function sweep(config3) {
+async function sweep(config3, maxRunMs = 0) {
   await git(config3.repo, ["worktree", "prune"]);
   let entries;
   try {
@@ -46086,9 +46119,17 @@ async function sweep(config3) {
   } catch {
     return [];
   }
+  const cutoff = Date.now() - Math.max(maxRunMs + 5 * 6e4, 60 * 6e4);
   const removed = [];
   for (const name of entries) {
     const path = join(config3.root, name);
+    let touched;
+    try {
+      touched = (await stat(path)).mtimeMs;
+    } catch {
+      continue;
+    }
+    if (touched >= cutoff) continue;
     await git(config3.repo, ["worktree", "remove", "--force", path]).catch(async () => {
       await rm(path, { recursive: true, force: true });
     });
@@ -46109,7 +46150,7 @@ var init_worktree = __esm({
 var supervisor_exports = {};
 import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
-import { mkdtemp, readdir as readdir2, readFile, rm as rm2, stat, writeFile } from "node:fs/promises";
+import { mkdtemp, readdir as readdir2, readFile, rm as rm2, stat as stat2, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import { join as join2 } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -46132,6 +46173,12 @@ async function identify(ctx) {
     capabilities: member.capabilities
   };
 }
+function resolveWorktreeRoot(identity) {
+  if (options.worktreeRoot) return options.worktreeRoot;
+  const slug = (value) => value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40);
+  const name = slug(identity.name) || slug(identity.email.split("@")[0] ?? "") || "agent";
+  return join2(homedir(), ".cruo-work", name);
+}
 async function pollAssigned(ctx) {
   const { data: issues, error: error51 } = await ctx.client.from("issues").select("*").eq("assignee_id", ctx.userId).order("created_at", { ascending: true });
   if (error51) throw new Error(`Assignment poll failed: ${error51.message}`);
@@ -46247,17 +46294,25 @@ async function pollMentions(ctx, identity) {
   );
 }
 async function claim(ctx, hit) {
-  const expiresAt = new Date(Date.now() + options.harnessTimeoutMs + 3e4);
-  const { error: error51 } = await ctx.client.schema("pm").from("issue_claims").upsert(
-    {
-      issue_id: hit.issue.id,
-      claimed_by: ctx.userId,
-      claimed_at: (/* @__PURE__ */ new Date()).toISOString(),
-      expires_at: expiresAt.toISOString()
-    },
-    { onConflict: "issue_id" }
-  );
-  if (error51) log(`  could not claim ${hit.ref}: ${error51.message}`);
+  const ttlMs = options.harnessTimeoutMs + 3e4;
+  const { data, error: error51 } = await ctx.client.schema("public").rpc("claim_issue", {
+    issue: hit.issue.id,
+    ttl_ms: ttlMs
+  });
+  if (error51) {
+    log(`  could not claim ${hit.ref}: ${error51.message} \u2014 leaving it`);
+    return false;
+  }
+  return data === true;
+}
+async function claimedElsewhere(ctx, hits) {
+  if (hits.length === 0) return /* @__PURE__ */ new Set();
+  const { data, error: error51 } = await ctx.client.schema("pm").from("issue_claims").select("issue_id, claimed_by").in("issue_id", hits.map((h) => h.issue.id)).gt("expires_at", (/* @__PURE__ */ new Date()).toISOString()).neq("claimed_by", ctx.userId);
+  if (error51) {
+    log(`  could not read claims: ${error51.message} \u2014 relying on the claim itself`);
+    return /* @__PURE__ */ new Set();
+  }
+  return new Set((data ?? []).map((r) => r.issue_id));
 }
 async function release(ctx, hit) {
   const { error: error51 } = await ctx.client.schema("pm").from("issue_claims").delete().eq("issue_id", hit.issue.id).eq("claimed_by", ctx.userId);
@@ -46317,7 +46372,7 @@ async function sweepStaleConfigs() {
     if (!name.startsWith(CONFIG_DIR_PREFIX)) continue;
     const path = join2(dir, name);
     try {
-      const info = await stat(path);
+      const info = await stat2(path);
       if (info.mtimeMs >= cutoff) continue;
       await rm2(path, { recursive: true, force: true });
       removed += 1;
@@ -46447,9 +46502,6 @@ function userPrompt(hit) {
     `which your function owns. Pick it up and do your part.`
   ].join(" ");
 }
-function neverRan(run) {
-  return run.code !== 0 && run.stdoutBytes === 0;
-}
 async function invokeHarness(ctx, identity, hit, worktree) {
   const cwd = worktree?.path ?? options.cwd;
   const { path: mcpConfig, cleanup } = await writeMcpConfig();
@@ -46479,8 +46531,10 @@ async function invokeHarness(ctx, identity, hit, worktree) {
         env: harnessEnv()
       });
       let stdoutBytes = 0;
+      let head2 = "";
       child.stdout?.on("data", (c) => {
         stdoutBytes += c.length;
+        if (head2.length < 2048) head2 += c.toString("utf8").slice(0, 2048 - head2.length);
         process.stdout.write(c);
       });
       child.stderr?.on("data", (c) => process.stderr.write(c));
@@ -46492,11 +46546,11 @@ async function invokeHarness(ctx, identity, hit, worktree) {
       child.on("error", (e) => {
         clearTimeout(timer);
         log(`  harness failed to start: ${e.message}`);
-        resolve2({ code: 127, stdoutBytes });
+        resolve2({ code: 127, stdoutBytes, refusal: refusalIn(head2) });
       });
       child.on("close", (code) => {
         clearTimeout(timer);
-        resolve2({ code: code ?? 1, stdoutBytes });
+        resolve2({ code: code ?? 1, stdoutBytes, refusal: refusalIn(head2) });
       });
     });
   } finally {
@@ -46588,11 +46642,17 @@ async function tick(ctx, identity, deadTicks) {
     seen.add(h.ref);
     return true;
   });
-  const attemptsByHit = await loadAttempts(ctx, hits);
+  const heldByOthers = await claimedElsewhere(ctx, hits);
+  const free = hits.filter((h) => !heldByOthers.has(h.issue.id));
+  if (heldByOthers.size > 0) {
+    log(`${heldByOthers.size} issue(s) already being worked by someone else`);
+  }
+  const attemptsByHit = await loadAttempts(ctx, free);
   const attemptsFor = (h) => attemptsByHit.get(`${h.reason}:${h.issue.id}`) ?? 0;
-  const actionable = hits.filter((h) => attemptsFor(h) < options.maxAttempts);
+  const actionable = free.filter((h) => attemptsFor(h) < options.maxAttempts);
   if (actionable.length === 0) {
-    if (hits.length > 0) log(`${hits.length} issue(s) waiting, all set aside`);
+    if (free.length > 0) log(`${free.length} issue(s) waiting, all set aside`);
+    else if (heldByOthers.size > 0) log(`nothing free \u2014 everything waiting is claimed`);
     await beat(ctx, { holding: 0, deadTicks, intervalMs: options.intervalMs });
     return { invoked: 0, failedToRun: 0 };
   }
@@ -46621,6 +46681,10 @@ async function tick(ctx, identity, deadTicks) {
     invoked += 1;
     const before = { status: hit.issue.status_id, assignee: hit.issue.assignee_id };
     const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+    if (!await claim(ctx, hit)) {
+      log(`  ${hit.ref} is being worked by another agent \u2014 skipping`);
+      continue;
+    }
     let worktree = null;
     if (worktreeConfig) {
       try {
@@ -46628,12 +46692,12 @@ async function tick(ctx, identity, deadTicks) {
         log(`  ${hit.ref} worktree ${worktree.path} on ${worktree.branch}`);
       } catch (error51) {
         failedToRun += 1;
+        await release(ctx, hit);
         log(`  ${hit.ref} could not prepare a worktree \u2014 not counted against this issue`);
         log(`    ${error51 instanceof Error ? error51.message.split("\n")[0] : String(error51)}`);
         continue;
       }
     }
-    await claim(ctx, hit);
     let run;
     let committed = 0;
     try {
@@ -46645,9 +46709,17 @@ async function tick(ctx, identity, deadTicks) {
     const code = run.code;
     if (neverRan(run)) {
       failedToRun += 1;
-      log(
-        `  ${hit.ref} the harness exited ${code} without reaching a model \u2014 not counted against this issue`
-      );
+      if (run.refusal) {
+        if (run.refusal !== lastRefusal) {
+          log(`! the harness is refusing to work: ${run.refusal}`);
+          log(`  No card is charged for this, and polling backs off until it changes.`);
+          lastRefusal = run.refusal;
+        }
+      } else {
+        log(
+          `  ${hit.ref} the harness exited ${code} without reaching a model \u2014 not counted against this issue`
+        );
+      }
       continue;
     }
     const { data: after } = await ctx.client.from("issues").select("status_id, assignee_id").eq("id", hit.issue.id).maybeSingle();
@@ -46684,6 +46756,7 @@ async function tick(ctx, identity, deadTicks) {
       }
     }
   }
+  if (failedToRun < invoked) lastRefusal = null;
   const allDead = invoked > 0 && failedToRun === invoked;
   if (allDead) {
     log(`! nothing reached a model this tick (${invoked}/${invoked} failed to run).`);
@@ -46722,20 +46795,20 @@ async function main() {
     const base = await resolveBase(options.repo, options.base);
     worktreeConfig = {
       repo: options.repo,
-      root: options.worktreeRoot,
+      root: resolveWorktreeRoot(identity),
       base,
       prepare: options.prepare,
       prepareTimeoutMs: options.prepareTimeout,
       keepFailed: options.keepFailed
     };
-    log(`worktrees in ${options.worktreeRoot}, branching from ${base} in ${options.repo}`);
+    log(`worktrees in ${worktreeConfig.root}, branching from ${base} in ${options.repo}`);
     if (base === "HEAD") {
       log(`! no origin/main or main \u2014 branching from HEAD, so tasks inherit your working state`);
     }
     if (!options.prepare) {
       log(`  no --prepare: a fresh worktree has no dependencies and no built packages`);
     }
-    const swept = await sweep(worktreeConfig);
+    const swept = await sweep(worktreeConfig, options.harnessTimeoutMs + options.prepareTimeout);
     if (swept.length) log(`  swept ${swept.length} worktree(s) left by an earlier run: ${swept.join(", ")}`);
     if (options.push) log(`  publishing to ${options.pushRemote} after any run that commits`);
     if (options.allow === "mcp__cruo") {
@@ -46770,7 +46843,7 @@ async function main() {
     await new Promise((r) => setTimeout(r, wait));
   }
 }
-var argv, flag, opt, num, ms, readOptions, options, log, worktreeConfig, PRIORITY_RANK, CONFIG_DIR_PREFIX, CRUO_OWNED_ENV;
+var argv, flag, opt, num, ms, readOptions, options, log, worktreeConfig, lastRefusal, PRIORITY_RANK, CONFIG_DIR_PREFIX, CRUO_OWNED_ENV;
 var init_supervisor = __esm({
   "src/supervisor.ts"() {
     "use strict";
@@ -46779,6 +46852,7 @@ var init_supervisor = __esm({
     init_env2();
     init_auth();
     init_options();
+    init_harness_signal();
     init_worktree();
     argv = process.argv.slice(2);
     flag = (name) => flagIn(argv, name);
@@ -46845,7 +46919,13 @@ var init_supervisor = __esm({
        * legitimate setup, and so is a PM agent with no filesystem at all.
        */
       worktree: flag("worktree"),
-      worktreeRoot: opt("worktree-root", join2(homedir(), ".cruo-work")),
+      /**
+       * Where worktrees are created. Defaults to `~/.cruo-work/<agent>` — per
+       * AGENT, not one shared directory — which needs this agent's name and so is
+       * resolved in `main` rather than here. Two supervisors sharing a root is a
+       * setup someone has to ask for; see `resolveWorktreeRoot`.
+       */
+      worktreeRoot: opt("worktree-root"),
       /** The repo to branch from. Defaults to wherever the supervisor was started. */
       repo: opt("repo", process.cwd()),
       /** Ref new task branches are cut from. Resolved at startup; see `resolveBase`. */
@@ -46890,6 +46970,7 @@ cruo-supervisor: ${error51.message}
     })();
     log = (...parts) => console.log(`[${(/* @__PURE__ */ new Date()).toLocaleTimeString("en-GB", { hour12: false })}]`, ...parts);
     worktreeConfig = null;
+    lastRefusal = null;
     PRIORITY_RANK = {
       urgent: 0,
       high: 1,
@@ -46919,6 +47000,7 @@ cruo-supervisor: ${error51.message}
 });
 
 // src/cli.ts
+init_options();
 import { chmod, mkdir as mkdir2, readFile as readFile2, rm as rm3, writeFile as writeFile2 } from "node:fs/promises";
 import { homedir as homedir2 } from "node:os";
 import { join as join3 } from "node:path";
@@ -46942,7 +47024,7 @@ Common options
   --push                 publish the branch after a run that commits
   --interval <seconds>   how often to poll (default 20)
 
-  Full list and what each one is for: https://cruo.space/agents
+  Full list and what each one is for: https://cruo.space/docs#agents
 
 The token comes from CRUO_TOKEN, then --token, then whatever \`login\` stored.
 `;
@@ -47014,7 +47096,7 @@ Get one from Cruo \u2192 Settings \u2192 Members \u2192 Add an agent.
     process.exit(2);
   }
   process.env.CRUO_TOKEN = token;
-  const passthrough = argv2.filter((a, i) => i !== flagIndex && i !== flagIndex + 1);
+  const passthrough = stripTokenFlag(argv2);
   process.argv = [process.argv[0], process.argv[1], ...passthrough];
   await Promise.resolve().then(() => (init_supervisor(), supervisor_exports));
 }

package/dist/index.js

@@ -34986,6 +34986,9 @@ var signupSchema = external_exports.object({
 });
 
 // ../../packages/core/dist/mcp-connect.js
+var DOCS_URL = "https://cruo.space/docs";
+var AGENT_DOCS_URL = `${DOCS_URL}#agents`;
+var MCP_DOCS_URL = `${DOCS_URL}#mcp`;
 var CRUO_CLOUD = {
   apiUrl: "https://szsutuujxbldkykcvdrm.supabase.co",
   publishableKey: "sb_publishable_hpnQFQ8IV0JXTch51XAstA_-S8H1eaD",

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "cruo-agent",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Run a Cruo agent: it watches your board, picks up the cards you assign it, and works them.",
   "license": "MIT",
-  "homepage": "https://cruo.space/agents",
+  "homepage": "https://cruo.space/docs#agents",
   "keywords": [
     "cruo",
     "agent",
@@ -29,12 +29,13 @@
     "access": "public"
   },
   "scripts": {
-    "build": "node scripts/build.mjs"
+    "build": "node scripts/build.mjs",
+    "prepublishOnly": "node scripts/build.mjs"
   },
   "devDependencies": {
     "@cruo/mcp": "workspace:*"
   },
   "bugs": {
-    "url": "https://cruo.space/agents"
+    "url": "https://cruo.space/docs#agents"
   }
 }