nomarmy 0.1.0-alpha.0

package/lib/slots.mjs

@@ -0,0 +1,112 @@
+// Machine-wide job leases and agent slots.
+//
+// Every coordinator session runs its own MCP server process, and each used
+// to count only its own jobs -- seen live: six server processes, so an
+// agent's `max_concurrent: 1` held per session, not per machine. These live
+// in files under nomArmy's shared state directory instead, so every session
+// sees every job:
+//
+//   leases/<jobId>.json       one per running job: lane, agent, owning pid
+//   slots/<agent>.<n>.lock    one per occupied max_concurrent slot, taken
+//                             with exclusive create (O_EXCL), so two sessions
+//                             can't both take the last one
+//
+// A lease or slot whose owning process is gone is stale: it doesn't count,
+// and the next reader removes it, so a crashed session never wedges a slot.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+/** True when `pid` is a running process (EPERM: it exists, owned by someone else). */
+export function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code === "EPERM"; }
+}
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; }
+}
+
+/** A lease/slot file is stale when its owner is gone, or it's unreadable and not brand new. */
+function isStale(file, { alive = pidAlive } = {}) {
+  const held = readJson(file);
+  if (held) return !alive(held.pid);
+  try { return Date.now() - fs.statSync(file).mtimeMs > 60000; } catch { return true; }
+}
+
+const safeKey = (key) => String(key).replace(/[^A-Za-z0-9._-]/g, "_");
+
+// --- job leases -------------------------------------------------------------
+
+export function writeLease(leasesDir, jobId, { lane, agent = null, runId = null, role = null, model = null, repo = null }) {
+  fs.mkdirSync(leasesDir, { recursive: true });
+  fs.writeFileSync(path.join(leasesDir, `${safeKey(jobId)}.json`), JSON.stringify({ jobId, lane, agent, runId, role, model, repo, pid: process.pid, startedAt: new Date().toISOString() }));
+}
+
+export function removeLease(leasesDir, jobId) {
+  try { fs.unlinkSync(path.join(leasesDir, `${safeKey(jobId)}.json`)); } catch { /* already gone */ }
+}
+
+/** Live leases across every session on this machine, optionally filtered. Removes stale ones. */
+export function liveLeases(leasesDir, { lane = null, agent = null, runId = null, alive = pidAlive } = {}) {
+  let files;
+  try { files = fs.readdirSync(leasesDir).filter((f) => f.endsWith(".json")); } catch { return []; }
+  const out = [];
+  for (const f of files) {
+    const file = path.join(leasesDir, f);
+    if (isStale(file, { alive })) { try { fs.unlinkSync(file); } catch { /* raced another reader */ } continue; }
+    const lease = readJson(file);
+    if (!lease) continue;
+    if (lane && lease.lane !== lane) continue;
+    if (agent && lease.agent !== agent) continue;
+    if (runId && lease.runId !== runId) continue;
+    out.push(lease);
+  }
+  return out;
+}
+
+// --- agent slots ------------------------------------------------------------
+
+/** How many of `key`'s slots are held right now, across the machine. */
+export function liveSlots(slotsDir, key, { alive = pidAlive } = {}) {
+  const prefix = `${safeKey(key)}.`;
+  let files;
+  try { files = fs.readdirSync(slotsDir).filter((f) => f.startsWith(prefix) && f.endsWith(".lock")); } catch { return 0; }
+  return files.filter((f) => !isStale(path.join(slotsDir, f), { alive })).length;
+}
+
+/**
+ * Take one of `key`'s `max` slots, atomically. Returns { release } or null
+ * when all are held. With `waitMs`, polls until one frees up or time runs
+ * out (for a batch, where the next job should queue, not fail).
+ */
+export async function acquireSlot(slotsDir, key, max, { jobId = null, waitMs = 0, pollMs = 2000, alive = pidAlive } = {}) {
+  fs.mkdirSync(slotsDir, { recursive: true });
+  const token = crypto.randomBytes(6).toString("hex");
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    for (let i = 0, retried = false; i < max; i++) {
+      const file = path.join(slotsDir, `${safeKey(key)}.${i}.lock`);
+      try {
+        const fd = fs.openSync(file, "wx");
+        fs.writeSync(fd, JSON.stringify({ pid: process.pid, token, jobId, key, takenAt: new Date().toISOString() }));
+        fs.closeSync(fd);
+        return {
+          file,
+          release() {
+            const held = readJson(file);
+            if (held?.token === token) { try { fs.unlinkSync(file); } catch { /* already gone */ } }
+          },
+        };
+      } catch (error) {
+        if (error.code !== "EEXIST") throw error;
+        // A stale slot is cleared and retried once; never loop on it.
+        if (!retried && isStale(file, { alive })) { try { fs.unlinkSync(file); } catch { /* raced */ } retried = true; i--; continue; }
+        retried = false;
+      }
+    }
+    if (Date.now() >= deadline) return null;
+    await new Promise((r) => setTimeout(r, Math.min(pollMs, Math.max(1, deadline - Date.now()))));
+  }
+}

package/lib/statusline.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// nomArmy in Claude Code's status line.
+//
+// Claude Code runs a status-line command each time it redraws, passing the
+// session (model, working directory) as JSON on stdin, and shows the one
+// line it prints. This prints the session's model and repo, then what
+// nomArmy is doing across every session on the machine:
+//
+//   Opus 5.5 · rayson-senti │ 🍪 sr-dev codex/gpt-6-astra 9m 10f │ run 3/40 $0.41
+//   Opus 5.5 · rayson-senti │ 🍪 2: scout claude 20s · sr-dev-action-wr… codex 20s │ run 5/14 $2.16
+//   Opus 5.5 · nomarmy │ 🍪 idle · 2 in other repos
+//
+// This session's repo gets the detail; jobs in other repos are only a
+// count (showing Senti's jobs in full in every window read as noise).
+//
+// Kept short: Claude Code cuts a long status line off. Job names lose
+// their date/time/hash suffix, models show only for a single job, and
+// the whole line is capped (NOMARMY_STATUSLINE_MAX, default 90), with
+// jobs that don't fit collapsing to "+N" so the run summary survives.
+//
+// Deliberately Node built-ins only, reading nothing but the job leases,
+// their status files and this repo's open runs: it runs on every redraw.
+// `nomarmy connect claude` installs it (unless a status line is already
+// configured); `nomarmy statusline` runs the same thing.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+function readJson(file) { try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; } }
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code === "EPERM"; }
+}
+/** "scout-20260924-143127-49f447" -> "scout"; long names shortened. */
+export function shortJobName(name, max = 18) {
+  const bare = String(name ?? "job").replace(/-\d{8}-\d{6}-[0-9a-f]{4,}$/i, "");
+  return bare.length > max ? `${bare.slice(0, max - 1)}…` : bare;
+}
+
+const minutes = (ms) => (ms < 60000 ? `${Math.max(1, Math.round(ms / 1000))}s` : ms < 3600000 ? `${Math.round(ms / 60000)}m` : `${Math.floor(ms / 3600000)}h${String(Math.round((ms % 3600000) / 60000)).padStart(2, "0")}`);
+
+/**
+ * The status line's text.
+ * @param {{ session?: object, stateRoot?: string, now?: number }} input
+ */
+export function statusLineText({ session = {}, stateRoot, now = Date.now(), maxLength = Number(process.env.NOMARMY_STATUSLINE_MAX) || 90 } = {}) {
+  const root = stateRoot ?? (process.env.NOMARMY_AGENT_STATE || path.join(os.homedir(), ".local", "share", "nomarmy-local-agents"));
+  // workspace.project_dir is where Claude Code was launched -- the repo that
+  // session's nomArmy server works in; current_dir can be a subdirectory.
+  const cwd = session.workspace?.project_dir ?? session.workspace?.current_dir ?? session.cwd ?? process.cwd();
+  const repoName = path.basename(cwd);
+  const head = [session.model?.display_name, repoName.length > 16 ? `${repoName.slice(0, 15)}…` : repoName].filter(Boolean).join(" · ");
+
+  const leasesDir = path.join(root, "leases");
+  let leases = [];
+  try { leases = fs.readdirSync(leasesDir).filter((f) => f.endsWith(".json")).map((f) => readJson(path.join(leasesDir, f))).filter((l) => l && pidAlive(l.pid)); } catch { /* none */ }
+  // A lease from before leases recorded their repo can't be attributed; it
+  // counts as "elsewhere" rather than claimed by every window.
+  // A lease from a server that predates `repo`: its worktree's .git file
+  // ("gitdir: <repo>/.git/worktrees/<name>") still names the repo.
+  for (const l of leases) {
+    if (l.repo) continue;
+    try {
+      const m = /^gitdir:\s*(.+?)[\\/]\.git[\\/]worktrees[\\/]/.exec(fs.readFileSync(path.join(root, "jobs", l.jobId, "worktree", ".git"), "utf8"));
+      if (m) l.repo = m[1];
+    } catch { /* no worktree yet */ }
+  }
+  const inRepo = (l) => Boolean(l.repo) && (cwd === l.repo || cwd.startsWith(`${l.repo}${path.sep}`));
+  const elsewhere = leases.filter((l) => !inRepo(l)).length;
+  leases = leases.filter(inRepo);
+  const single = leases.length === 1;
+  const jobs = leases.map((l) => {
+    const status = readJson(path.join(root, "jobs", l.jobId, "status.json")) ?? {};
+    const name = shortJobName(l.role ?? status.workerId ?? l.jobId);
+    const who = l.agent ? `${l.agent}${single && l.model ? `/${l.model}` : ""}` : "local";
+    const started = Date.parse(status.startedAt ?? l.startedAt ?? "") || now;
+    const files = Number.isFinite(status.filesChangedLive) && status.filesChangedLive > 0 ? ` ${status.filesChangedLive}f` : "";
+    const phase = status.phase && status.phase !== "worker" ? ` ${status.phase}` : "";
+    return `${name} ${who} ${minutes(now - started)}${files}${phase}`;
+  });
+
+  let runPart = "";
+  try {
+    const runsDir = path.join(root, "runs");
+    const open = fs.readdirSync(runsDir).filter((f) => f.endsWith(".json")).map((f) => readJson(path.join(runsDir, f)))
+      .filter((r) => r?.status === "running" && r.repo === cwd).sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt));
+    const run = open[0];
+    if (run) {
+      const inFlight = leases.filter((l) => l.runId === run.id).length;
+      const spent = run.jobs.reduce((s, j) => s + (j.kind === "api" && Number.isFinite(j.costUsd) ? j.costUsd : 0), 0);
+      const warn = Object.keys(run.pausedAgents ?? {}).length ? " ⚠ agent paused" : "";
+      runPart = ` │ run ${run.jobs.length + inFlight}/${run.limits.max_jobs}${spent ? ` $${spent.toFixed(2)}` : ""}${warn}`;
+    }
+  } catch { /* no runs */ }
+  // The most serious recent health warning (lib/health.mjs), short.
+  let healthPart = "";
+  try {
+    const health = readJson(path.join(root, "health.json"));
+    if (health && now - Date.parse(health.checkedAt) < 2 * 86400000) {
+      const top = (health.issues ?? []).find((i) => i.severity !== "info" && i.short);
+      if (top) healthPart = ` │ ⚠ ${top.short}`;
+    }
+  } catch { /* no health yet */ }
+  runPart += healthPart;
+  // As many jobs as fit, then "+N": the run summary is never what gets cut.
+  const prefix = `${head ? `${head} │ ` : ""}🍪 `;
+  const count = jobs.length > 1 ? `${jobs.length}: ` : "";
+  let shown = jobs.length, army;
+  for (;;) {
+    const rest = jobs.length - shown;
+    army = (!jobs.length ? "idle" : `${count}${jobs.slice(0, shown).join(" · ")}${rest ? `${shown ? " " : ""}+${rest}` : ""}`)
+      + (elsewhere ? ` · ${elsewhere} in other repo${elsewhere === 1 ? "" : "s"}` : "");
+    if (shown === 0 || [...`${prefix}${army}${runPart}`].length <= maxLength) break;
+    shown--;
+  }
+  return `${prefix}${army}${runPart}`;
+}
+
+const isMain = (() => { try { return path.resolve(process.argv[1] ?? "") === fileURLToPath(import.meta.url); } catch { return false; } })();
+if (isMain) {
+  let session = {};
+  if (!process.stdin.isTTY) { try { session = JSON.parse(fs.readFileSync(0, "utf8") || "{}"); } catch { /* no session JSON */ } }
+  process.stdout.write(`${statusLineText({ session })}\n`);
+}

package/lib/subscription-config.mjs

@@ -0,0 +1,68 @@
+// Subscription agents at dispatch time: exact-name lookup (never a pick),
+// and the one-credential-per-provider conflict check. The agents
+// themselves are defined in agents.yml (lib/agents.mjs), which hands these
+// functions the `{ config: { workers } }` shape they were written for.
+
+import { openclawProviderId } from "./dispatch-schema.mjs";
+
+/**
+ * Look up a named worker in a loaded subscription config, or throw a clear
+ * error naming which ones DO exist -- a typo must never silently fall back
+ * to anything else. There is no picker
+ * function alongside this one, by design: dispatch to this mode always
+ * names an entry, never selects one.
+ */
+export function resolveSubscriptionWorker(subscriptionConfig, name) {
+  const workers = subscriptionConfig?.config?.workers;
+  // hasOwnProperty, not a truthy lookup -- same reasoning as
+  // lib/dispatch-config.mjs's resolvePool: `workers?.["__proto__"]` on a
+  // plain object returns Object.prototype itself, a real truthy value even
+  // though lib/agents.mjs already refuses a file that declares one.
+  const entry = workers && Object.prototype.hasOwnProperty.call(workers, name) ? workers[name] : undefined;
+  if (!entry) {
+    const known = Object.keys(subscriptionConfig?.config?.workers || {});
+    throw new Error(
+      known.length
+        ? `unknown subscription agent "${name}" -- your subscription agents are: ${known.join(", ")}`
+        : `unknown subscription agent "${name}" -- none are defined yet (run \`nomarmy agents add subscription\`)`,
+    );
+  }
+  return { id: name, ...entry };
+}
+
+/**
+ * OpenClaw providers that BOTH an api agent (as its one-entry pool) and a
+ * subscription agent use. Some vendors (OpenAI, Meta, xAI) put their
+ * subscription credential and their pay-as-you-go API key under the same
+ * OpenClaw provider id -- so a pool entry for that provider could silently
+ * run on the subscription credential (or a subscription agent on the
+ * metered key), which is exactly the pooling subscriptions must never be. Only Claude (claude-cli vs anthropic) uses distinct ids and
+ * never collides. Callers refuse to dispatch either side of
+ * a conflict rather than guess which credential OpenClaw will pick.
+ * @returns {{ provider: string, poolEntries: string[], workers: string[] }[]}
+ */
+export function findProviderConflicts(pools = {}, workers = {}) {
+  const poolByProvider = new Map();
+  for (const [pool, entries] of Object.entries(pools || {})) {
+    for (const entry of entries || []) {
+      const provider = openclawProviderId(entry);
+      if (!poolByProvider.has(provider)) poolByProvider.set(provider, []);
+      poolByProvider.get(provider).push(`${pool}/${entry.id}`);
+    }
+  }
+  const conflicts = new Map();
+  for (const [name, entry] of Object.entries(workers || {})) {
+    const poolEntries = poolByProvider.get(entry.provider);
+    if (!poolEntries) continue;
+    if (!conflicts.has(entry.provider)) conflicts.set(entry.provider, { provider: entry.provider, poolEntries, workers: [] });
+    conflicts.get(entry.provider).workers.push(name);
+  }
+  return [...conflicts.values()];
+}
+
+/** One readable refusal line for a conflict, shared by dispatch and the CLI. */
+export function describeProviderConflict(conflict) {
+  const apiAgents = conflict.poolEntries.map((e) => e.split("/").pop());
+  return `OpenClaw provider "${conflict.provider}" is used by both api agent${apiAgents.length === 1 ? "" : "s"} ${apiAgents.join(", ")} and subscription agent${conflict.workers.length === 1 ? "" : "s"} ${conflict.workers.join(", ")} -- OpenClaw holds one credential per provider, so the api agent could run on the subscription (or the subscription on the metered key). Keep only one of them.`;
+}
+

package/lib/subscription-setup.mjs

@@ -0,0 +1,217 @@
+// Pure pieces of `nomarmy subscriptions setup <vendor>` -- the guided path
+// that wraps every OpenClaw step behind one command so an operator never has
+// to know OpenClaw is involved for the common case. bin/nomarmy.mjs owns the
+// actual subprocess calls and prompts; everything here is parse/decide logic
+// so it can be tested without a real TTY, a real login, or a real network.
+//
+// Every value in SUBSCRIPTION_VENDORS was confirmed live against a real
+// install, not taken from docs: "claude-cli" (not "anthropic-cli", a wrong
+// guess that cost real time), Codex needing OpenAI's own @openai/codex CLI
+// installed separately, @openclaw/codex needing OpenClaw >= 2026.9.5, and a
+// ChatGPT plan running under OpenClaw's `openai` provider, not `codex` (the
+// codex login is imported as an `openai/oauth` profile; `codex/<model>`
+// answers "Unknown model" while `openai/gpt-6-astra` completes).
+// KNOWN TO DRIFT: if OpenClaw or a vendor renames any of this, the table goes
+// stale before nomArmy's own code does.
+//
+// `credential.kind` is how the subscription credential actually reaches
+// OpenClaw, and it genuinely differs per vendor (each confirmed live):
+//   cli-session    OpenClaw reuses the vendor CLI's own logged-in session
+//                  directly; nothing to link (Claude).
+//   openclaw-login OpenClaw's plugin wants its own `models auth login` on
+//                  top of the vendor CLI's login (Codex). `loginProvider`
+//                  is the id that login takes when it differs from the
+//                  provider the models run under.
+//   minted-key     The vendor CLI's login mints a Model API key into the OS
+//                  keychain, and OpenClaw's plugin only accepts an API key
+//                  (Meta: @openclaw/meta-provider declares authMethods
+//                  ["api-key"] only). Meta's own subscription docs say the
+//                  flat rate covers "the Muse Code API key that is
+//                  automatically connected in the Muse Code CLI onboarding
+//                  process" -- that minted key, not one you create by hand
+//                  (those bill pay-as-you-go). It is copied into OpenClaw by
+//                  stdin on every setup run, since it can rotate.
+
+import { modelRejection } from "./openclaw-errors.mjs";
+
+export const SUBSCRIPTION_VENDORS = Object.freeze({
+  claude: Object.freeze({
+    label: "Anthropic Claude (Pro/Max/Team seat)",
+    provider: "claude-cli",
+    cli: Object.freeze({
+      bin: "claude",
+      npmPackage: null,
+      installHint: "Install Claude Code first: https://claude.com/claude-code",
+      statusArgs: ["auth", "status"],
+      loginArgs: ["auth", "login"],
+    }),
+    plugin: null,
+    credential: Object.freeze({ kind: "cli-session" }),
+    defaultModel: null,
+  }),
+  codex: Object.freeze({
+    label: "OpenAI Codex (ChatGPT plan)",
+    provider: "openai",
+    cli: Object.freeze({
+      bin: "codex",
+      npmPackage: "@openai/codex",
+      installHint: "npm install -g @openai/codex",
+      statusArgs: ["login", "status"],
+      loginArgs: ["login"],
+    }),
+    plugin: Object.freeze({ id: "codex", spec: "clawhub:@openclaw/codex", minOpenclaw: "2026.9.5" }),
+    credential: Object.freeze({ kind: "openclaw-login", loginProvider: "codex" }),
+    // The top entry in Codex's own ~/.codex/models_cache.json.
+    defaultModel: "gpt-6-astra",
+  }),
+  meta: Object.freeze({
+    label: "Meta Muse Code (subscription)",
+    provider: "meta",
+    cli: Object.freeze({
+      bin: "muse",
+      npmPackage: null,
+      installHint: "Install Muse Code first (Meta's developer site, dev.meta.ai)",
+      // No status subcommand exists; `muse login` records a non-secret
+      // descriptor here (mechanism/storage/obtained_via -- confirmed live),
+      // and the credential itself goes to the OS keychain.
+      statusArgs: null,
+      statusFile: "~/.config/muse/auth.json",
+      loginArgs: ["login"],
+    }),
+    // providerConfig: the plugin's own step that writes Meta's entry into
+    // openclaw.json (lib/openclaw-config.mjs). Without it every Muse model is
+    // listed but fails "Unknown model" (confirmed live).
+    plugin: Object.freeze({ id: "meta", spec: "clawhub:@openclaw/meta-provider", minOpenclaw: "2026.9.3",
+      providerConfig: Object.freeze({ module: "dist/onboard.js", exportName: "applyMetaConfig" }) }),
+    credential: Object.freeze({
+      kind: "minted-key",
+      keychain: Object.freeze({ service: "ai.meta.dev.credentials", account: "meta", field: "api_key" }),
+      profileId: "meta:subscription",
+    }),
+    // The plugin manifest's own defaultModel; Meta models don't appear in
+    // OpenClaw's catalog until a credential is linked.
+    defaultModel: "muse-spark-1.3",
+  }),
+});
+
+/** "OpenClaw 2026.9.5 (ec9c1a1)" -> [2026, 9, 5], or null if unparseable. */
+export function parseOpenclawVersion(text) {
+  const match = /(\d+)\.(\d+)\.(\d+)/.exec(String(text ?? ""));
+  return match ? match.slice(1, 4).map(Number) : null;
+}
+
+/** True when `have` ([a,b,c]) is at least the dotted `min` string. */
+export function versionAtLeast(have, min) {
+  const want = parseOpenclawVersion(min);
+  if (!have || !want) return false;
+  for (let i = 0; i < 3; i++) {
+    if (have[i] > want[i]) return true;
+    if (have[i] < want[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * Model ids for one provider from `openclaw models list --refresh` output,
+ * which prints one `<provider>/<model>  <capabilities> ...` row per model.
+ * Returned without the provider prefix, in catalog order, de-duplicated.
+ */
+export function parseCatalogModels(listOutput, provider) {
+  const prefix = `${provider}/`;
+  const models = [];
+  for (const line of String(listOutput ?? "").split(/\r?\n/)) {
+    const first = line.trim().split(/\s+/)[0] ?? "";
+    if (first.startsWith(prefix) && first.length > prefix.length) models.push(first.slice(prefix.length));
+  }
+  return [...new Set(models)];
+}
+
+/**
+ * Whether a vendor CLI's own status command says it's logged in, plus the
+ * account email when the CLI reports one (used as the default owner, so the
+ * operator doesn't retype who they are). Claude prints JSON
+ * (`{"loggedIn":true,"email":...}`); Codex prints a line like
+ * "Logged in using ChatGPT". Anything unrecognized is "not logged in" --
+ * running the login again is harmless, silently skipping a needed one isn't.
+ */
+export function parseCliLoginStatus(vendorKey, output) {
+  const text = String(output ?? "");
+  if (vendorKey === "claude") {
+    try {
+      // stdout and stderr arrive merged (see bin/nomarmy.mjs's runQuiet), so
+      // parse just the JSON object, not the whole blob.
+      const parsed = JSON.parse(text.slice(text.indexOf("{"), text.lastIndexOf("}") + 1));
+      return { loggedIn: parsed.loggedIn === true, email: typeof parsed.email === "string" ? parsed.email : null, subscriptionType: parsed.subscriptionType ?? null };
+    } catch {
+      return { loggedIn: false, email: null, subscriptionType: null };
+    }
+  }
+  if (vendorKey === "codex") {
+    return { loggedIn: /^\s*logged in\b/im.test(text) && !/not logged in/i.test(text), email: null, subscriptionType: /chatgpt/i.test(text) ? "chatgpt" : null };
+  }
+  return { loggedIn: false, email: null, subscriptionType: null };
+}
+
+/**
+ * The one-token probe envelope `openclaw agent exec --json` returns; true
+ * only on a real completion. Tolerates log lines around the envelope (it
+ * is parsed from its first "{" line to its last "}"), since OpenClaw
+ * writes a colored run log to stderr and callers may have merged the two.
+ */
+export function probeSucceeded(stdout) {
+  const text = String(stdout ?? "");
+  const start = text.search(/^\{/m), end = text.lastIndexOf("}");
+  if (start === -1 || end < start) return false;
+  try {
+    const parsed = JSON.parse(text.slice(start, end + 1));
+    return parsed?.ok === true && typeof parsed.final === "string" && parsed.final.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * A test call's outcome, from both streams: { ok, reason }.
+ *
+ * It must read the way a job does. A model the provider refuses fails
+ * with a model_not_found reason in the run log; a run that answered and
+ * then hit OpenClaw's known cleanup error (Codex: "Agent runtime cleanup did
+ * not settle", after stopReason=stop) worked, and jobs salvage it too.
+ */
+export function probeOutcome({ stdout = "", stderr = "" } = {}) {
+  if (probeSucceeded(stdout)) return { ok: true, reason: null };
+  const rejected = modelRejection(`${stderr}\n${stdout}`);
+  if (rejected) return { ok: false, reason: rejected.message };
+  if (/ended with stopReason=stop\b/.test(stderr) && /cleanup/i.test(`${stdout}\n${stderr}`)) return { ok: true, reason: null };
+  const message = /"message"\s*:\s*"((?:[^"\\]|\\.)*)"/.exec(stdout)?.[1];
+  return { ok: false, reason: message ? message.replace(/\\"/g, '"').slice(0, 300) : null };
+}
+
+/**
+ * Muse Code's non-secret login descriptor (~/.config/muse/auth.json) ->
+ * { loggedIn, email }. Reads only descriptor fields; the credential itself
+ * is never in this file (storage: "keychain").
+ */
+export function parseMuseAuthDescriptor(text) {
+  try {
+    const meta = JSON.parse(String(text ?? ""))?.providers?.meta;
+    return { loggedIn: Boolean(meta?.mechanism), email: typeof meta?.user_email === "string" ? meta.user_email : null, subscriptionType: meta?.mechanism ? "muse-code" : null };
+  } catch {
+    return { loggedIn: false, email: null, subscriptionType: null };
+  }
+}
+
+/**
+ * The minted API key out of a keychain JSON blob, or null. Muse's blob holds
+ * both an `api_key` ("LLM|<id>|<secret>") and an OAuth `access_token`; only
+ * the api_key works as a bearer against api.meta.ai, so anything that isn't
+ * that exact three-part shape is refused rather than passed on.
+ */
+export function extractMintedKey(blob, field) {
+  try {
+    const value = JSON.parse(String(blob ?? ""))?.[field];
+    return typeof value === "string" && /^LLM\|[^|\s]+\|[^|\s]+$/.test(value) ? value : null;
+  } catch {
+    return null;
+  }
+}