@nodii/dev 0.6.37 → 0.6.38

package/README.md

@@ -856,14 +856,53 @@ first.
 coordinator run and shows its running lanes, orphaned runs and unclaimed
 results. A live second coordinator is refused; a coordinator whose heartbeat
 watchdog has recorded it orphaned is recorded as the predecessor of the
-takeover.
+takeover. Each `--account RUNTIME:PROFILE` (for example
+`--account claude:/Users/me/.claude-work`) registers that model account on
+the machine, and the command then reports every registered account's usage.
+
+### Account capacity (MW1-38.1, MW1-38.2)
+
+Each Claude or Codex profile a machine launches lanes on is a Dev runner of
+kind `account`, owned by the machine's coordinator.
+`machine accounts register --runtime claude|codex --profile PATH` registers
+one and reports its usage at once; `machine accounts list` shows them;
+`machine usage report [--profile PATH]` re-reads and reports each one. The
+reading is read-only and never prints a token: Claude reads
+`GET https://api.anthropic.com/api/oauth/usage` with the profile's own login
+(the macOS keychain, or `PROFILE/.credentials.json`), and an expired login is
+left for Claude to renew, never refreshed here; Codex reads the newest
+rollout's `rate_limits`, which counts only while it is under 15 minutes old
+(MW1-38.1: an older reading is unknown). An idle Codex account can opt in with
+`machine accounts register --runtime codex --profile PATH --probe` (and out with
+`--no-probe`): when its
+newest reading is 10 minutes old, a `lane launch` on it or an explicit
+`machine usage report --probe` (never the watch loop, since a probe spends
+quota) runs one minimal
+`codex exec --skip-git-repo-check -s read-only "reply ok"` under that
+`CODEX_HOME` and reads the fresh rollout. Dev places a launch by the higher of the 5-hour and
+weekly windows: under 80% anything; 80–94% no new long lanes; 95–99% only
+`no-build` work (a one-file fix, a publish or verify relaunch, an
+evidence-only step); 100% nothing. A reading older than 15 minutes counts as
+unknown. `lane launch` refreshes its own account's reading first, and the
+watchdog sweep re-reports every account every 5 minutes (install it with
+`watchdog install` under the coordinator's identity).
+
+`coordinator start` also launches a detached heartbeater
+(`coordinator heartbeat`, its PID saved in
+`coordinator-NAME.heartbeat.pid` next to the config) tied to the coordinator
+session's process. It heartbeats the run at half its expected interval while
+the session lives, ends the run (`done`) when the session exits, and stops
+without touching a run that a later `coordinator start` replaced.
 
 `lane launch KEY` replaces the manual worktree/start/process sequence. It
 requires the issue (whose title supplies both lane title and objective), done
-check, build kind and side, runtime profile and model, subagent quota, and
+check, build kind and side, runtime profile and model, subagent quota, the
+lane's class (`--class long|short|no-build`, MW1-38.3), and
 repeated `--repo NAME=/SOURCE` plus
 `--branch NAME=BRANCH` pairs. The Hub preflight checks the coordinator waiter,
-target agent and machine, fresh account-capacity telemetry, repository grants,
+target agent and machine, the account's fresh usage band against the lane's
+class (refusing with `ACCOUNT_LIMIT_UNAVAILABLE` or `ACCOUNT_BAND_REFUSED` and
+the command that fixes it), repository grants,
 lane limit, open issues and (when `--figma` is present) the authenticated Figma
 account. Only after that passes does the CLI create one worktree per repository,
 atomically register the lane and watched run, and launch the runtime with the

package/dist/accounts.js

@@ -0,0 +1,342 @@
+// Model-account capacity (MW1-38.1, AGENT-HARNESS-43). Each Claude or Codex
+// profile a machine launches lanes on is a Dev runner of kind `account`; its
+// subscription usage ceiling carries the account's measured 5-hour and weekly
+// windows, and `lane launch` refuses an account with no reading under 15
+// minutes old. Readings are read-only: a token is never printed or refreshed.
+import { execFile as execFileCallback } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { dirname, isAbsolute, join, normalize } from "node:path";
+import { promisify } from "node:util";
+import { CliError, configPath, devRequest, encode, readConfig } from "./core.js";
+
+const execFile = promisify(execFileCallback);
+export const RUNTIMES = ["claude", "codex"];
+export const CLAUDE_USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+// The watchdog sweeps every minute; it re-reports at this cadence so a launch
+// always finds a reading well inside Dev's 15-minute window.
+export const USAGE_REFRESH_MS = 5 * 60_000;
+
+/**
+ * MW1-38.2 bands, placed by the higher of the windows: under 80% ok (normal
+ * placement), 80-94% warning (no new long lanes), 95-99% short_only (a
+ * one-file fix, a publish or verify relaunch, an evidence-only step), 100%
+ * exhausted (nothing new).
+ */
+export function usageBand(windows) {
+  const peak = Math.max(...Object.values(windows).map((window) => window?.utilization ?? 0), 0);
+  return peak >= 100 ? "exhausted" : peak >= 95 ? "short_only" : peak >= 80 ? "warning" : "ok";
+}
+
+/**
+ * The ceiling's stored state (ok | warning | exhausted). Dev places a launch
+ * by the band it computes from the percentages in counters, so 95-99% is
+ * stored as warning without losing the stricter band.
+ */
+export function usageState(windows) {
+  const band = usageBand(windows);
+  return band === "short_only" ? "warning" : band;
+}
+
+/** One spelling per profile directory: Dev matches an account's profile exactly. */
+export const profilePath = (value) => (typeof value === "string" && value.length > 1 ? value.replace(/\/+$/, "") : value);
+
+function checkAccount({ runtime, profile }) {
+  if (!RUNTIMES.includes(runtime)) throw new CliError("USAGE", "--runtime must be claude or codex.", 2);
+  if (!profile || !isAbsolute(profile) || normalize(profile) !== profile)
+    throw new CliError("USAGE", "--profile must be an absolute, normalized runtime profile path.", 2);
+}
+
+/**
+ * The keychain services that may hold a profile's Claude login, in order.
+ * With CLAUDE_CONFIG_DIR set (as lane launch always sets it), Claude Code
+ * suffixes the service with the directory's hash; only the default
+ * ~/.claude also has the plain service, from sessions started without it.
+ */
+export function claudeKeychainServices(profile, home = homedir()) {
+  const hashed = `Claude Code-credentials-${createHash("sha256").update(profile).digest("hex").slice(0, 8)}`;
+  return profile === join(home, ".claude") ? [hashed, "Claude Code-credentials"] : [hashed];
+}
+
+async function claudeCredential(profile, { platform = process.platform, run = execFile, read = readFile } = {}) {
+  if (platform !== "darwin") return JSON.parse(await read(join(profile, ".credentials.json"), "utf8"))?.claudeAiOauth ?? null;
+  for (const service of claudeKeychainServices(profile)) {
+    try { return JSON.parse((await run("security", ["find-generic-password", "-s", service, "-w"], { encoding: "utf8" })).stdout)?.claudeAiOauth ?? null; }
+    catch {}
+  }
+  return null;
+}
+
+const isoOrNull = (value) => {
+  if (value === null || value === undefined || value === "") return null;
+  const date = typeof value === "number" ? new Date(value * 1000) : new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString();
+};
+
+/** The account's own windows from Anthropic's read-only usage endpoint. */
+export async function readClaudeUsage(profile, { credential = claudeCredential, fetchImpl = fetch, now = () => new Date() } = {}) {
+  let oauth;
+  try { oauth = await credential(profile); }
+  catch { throw new CliError("ACCOUNT_CREDENTIAL_UNAVAILABLE", `No Claude login found for ${profile}.`, 1); }
+  if (!oauth?.accessToken) throw new CliError("ACCOUNT_CREDENTIAL_UNAVAILABLE", `No Claude login found for ${profile}.`, 1);
+  // Lanes share this login: refreshing it here could sign them out, so an
+  // expired token is reported as unreadable and left for the runtime to renew.
+  if (oauth.expiresAt && Number(oauth.expiresAt) <= now().getTime())
+    throw new CliError("ACCOUNT_TOKEN_EXPIRED", `The Claude login for ${profile} has expired. Lanes share it, so it is not refreshed here: start Claude once on that profile (CLAUDE_CONFIG_DIR=${profile}) to renew it, then report again.`, 1);
+  let response;
+  try {
+    response = await fetchImpl(CLAUDE_USAGE_URL, {
+      headers: { authorization: `Bearer ${oauth.accessToken}`, "anthropic-beta": "oauth-2025-04-20" },
+      signal: AbortSignal.timeout(15_000),
+    });
+  } catch (error) {
+    throw new CliError("ACCOUNT_USAGE_UNAVAILABLE", `Anthropic's usage endpoint was unreachable for ${profile} (${error?.cause?.code ?? error?.name ?? "network error"}).`, 1);
+  }
+  if (!response.ok) throw new CliError("ACCOUNT_USAGE_UNAVAILABLE", `Anthropic's usage endpoint answered ${response.status} for ${profile}.`, 1);
+  const body = await response.json();
+  const window = (value) => value && typeof value.utilization === "number"
+    ? { utilization: value.utilization, resetsAt: isoOrNull(value.resets_at) }
+    : null;
+  // Model-scoped weekly windows (seven_day_opus, seven_day_sonnet, …) bind
+  // too when present, so they count toward the band.
+  const scoped = Object.entries(body)
+    .filter(([name, value]) => /^seven_day_/.test(name) && window(value))
+    .map(([name, value]) => [name.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase()), window(value)]);
+  return {
+    source: "anthropic-oauth-usage",
+    measuredAt: now().toISOString(),
+    windows: { fiveHour: window(body.five_hour), sevenDay: window(body.seven_day), ...Object.fromEntries(scoped) },
+  };
+}
+
+/** The newest rollouts first, walking sessions/YYYY/MM/DD newest-first and stopping at `limit`. */
+async function newestRollouts(profile, limit = 20) {
+  const files = [];
+  const names = async (dir) => {
+    try { return (await readdir(dir, { withFileTypes: true })).sort((a, b) => b.name.localeCompare(a.name)); }
+    catch { return []; }
+  };
+  async function walk(dir) {
+    for (const entry of await names(dir)) {
+      if (files.length >= limit) return;
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) await walk(path);
+      else if (/^rollout-.*\.jsonl$/.test(entry.name)) files.push(path);
+    }
+  }
+  await walk(join(profile, "sessions"));
+  return files;
+}
+
+function lastRateLimits(text) {
+  const lines = text.trimEnd().split("\n");
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    if (!lines[index].includes('"rate_limits"')) continue;
+    let record;
+    try { record = JSON.parse(lines[index]); } catch { continue; }
+    const limits = record?.payload?.rate_limits ?? record?.rate_limits;
+    if (limits && (limits.primary || limits.secondary)) return { limits, at: record.timestamp };
+  }
+  return null;
+}
+
+// MW1-38.1: a reading older than 15 minutes is unknown, never free. A Codex
+// rollout is only as fresh as the last Codex run on that profile.
+export const MAX_READING_AGE_MS = 15 * 60_000;
+// A probing account takes a fresh reading before its newest one gets close
+// to that limit when a launch or an explicit report asks for one.
+export const PROBE_AFTER_MS = 10 * 60_000;
+
+/** The newest rate-limit reading in the profile's rollouts, or null. */
+async function newestCodexReading(profile, { rollouts, read, now }) {
+  for (const path of await rollouts(profile)) {
+    const found = lastRateLimits(await read(path, "utf8"));
+    if (!found) continue;
+    const windows = { fiveHour: null, sevenDay: null };
+    for (const limit of [found.limits.primary, found.limits.secondary]) {
+      if (!limit || typeof limit.used_percent !== "number") continue;
+      const resetsAt = isoOrNull(limit.resets_at);
+      // A window that has reset since the rollout was written is empty now.
+      const utilization = resetsAt && Date.parse(resetsAt) <= now().getTime() ? 0 : limit.used_percent;
+      const name = limit.window_minutes === 300 ? "fiveHour" : limit.window_minutes === 10_080 ? "sevenDay" : `window${limit.window_minutes}m`;
+      windows[name] = { utilization, resetsAt };
+    }
+    return { source: "codex-rollout", measuredAt: isoOrNull(found.at), windows };
+  }
+  return null;
+}
+
+/**
+ * One minimal Codex turn under the profile's CODEX_HOME, so Codex writes a
+ * fresh rollout with the account's current rate limits (opt-in per account).
+ */
+export async function probeCodex(profile, { codexBin = "codex", run = execFile } = {}) {
+  // The probe must run on the profile's own ChatGPT login, never an API key.
+  const { OPENAI_API_KEY: _key, OPENAI_BASE_URL: _base, ...env } = process.env;
+  try {
+    await run(codexBin, ["exec", "--skip-git-repo-check", "-s", "read-only", "reply ok"], {
+      cwd: tmpdir(), env: { ...env, CODEX_HOME: profile }, timeout: 120_000, encoding: "utf8",
+    });
+  } catch (error) {
+    throw new CliError("ACCOUNT_PROBE_FAILED", `The Codex probe on ${profile} failed (${error?.code ?? error?.signal ?? "error"}).`, 1);
+  }
+}
+
+/** The account's windows from the newest Codex rollout that recorded them, under 15 minutes old. */
+export async function readCodexUsage(profile, { probe = null, rollouts = newestRollouts, read = readFile, now = () => new Date(), runProbe = probeCodex } = {}) {
+  const age = (reading) => (reading?.measuredAt ? now().getTime() - Date.parse(reading.measuredAt) : Number.POSITIVE_INFINITY);
+  let reading = await newestCodexReading(profile, { rollouts, read, now });
+  if (probe && age(reading) >= PROBE_AFTER_MS) {
+    try {
+      await runProbe(profile, probe);
+      reading = await newestCodexReading(profile, { rollouts, read, now });
+    } catch (error) {
+      // A failed probe never discards a reading that still counts.
+      if (age(reading) > MAX_READING_AGE_MS) throw error;
+    }
+  }
+  if (!reading)
+    throw new CliError("ACCOUNT_USAGE_UNAVAILABLE", `No Codex rollout under ${profile}/sessions records rate limits yet.`, 1);
+  if (age(reading) > MAX_READING_AGE_MS)
+    throw new CliError("ACCOUNT_USAGE_STALE", `The newest Codex reading on ${profile} is ${Math.round(age(reading) / 60_000)} min old, and MW1-38.1 counts it as unknown. Let it probe with \`nodii-dev machine accounts register --runtime codex --profile ${profile} --probe\`, or run Codex on it.`, 1);
+  return reading;
+}
+
+// Probing is opt-in per account and runs on this machine, so the choice and
+// the Codex binary (launchd's PATH has no user bin directories) live here.
+const probesPath = () => join(dirname(configPath()), "account-probes.json");
+export async function readProbes(read = readFile) {
+  try { return JSON.parse(await read(probesPath(), "utf8")); } catch { return {}; }
+}
+async function saveProbe(profile, codexBin) {
+  const probes = await readProbes();
+  if (codexBin) probes[profile] = { codexBin };
+  else delete probes[profile];
+  await mkdir(dirname(probesPath()), { recursive: true, mode: 0o700 });
+  const temporary = `${probesPath()}.tmp-${process.pid}`;
+  await writeFile(temporary, `${JSON.stringify(probes, null, 2)}\n`, { mode: 0o600 });
+  await rename(temporary, probesPath());
+}
+async function resolveCodexBin(run = execFile) {
+  if (process.env.NODII_DEV_CODEX_BIN) return process.env.NODII_DEV_CODEX_BIN;
+  try { return (await run("/usr/bin/which", ["codex"], { encoding: "utf8" })).stdout.trim() || null; }
+  catch { return null; }
+}
+
+const READERS = { claude: readClaudeUsage, codex: readCodexUsage };
+
+/** The usage ceiling body Dev stores for one reading. */
+export function usageReport(reading) {
+  const state = usageState(reading.windows);
+  const binding = Object.values(reading.windows)
+    .filter(Boolean)
+    .sort((a, b) => (b.utilization ?? 0) - (a.utilization ?? 0))[0];
+  return {
+    ceiling: "subscription",
+    state,
+    resetsAt: state === "ok" ? null : binding?.resetsAt ?? null,
+    counters: { source: reading.source, measuredAt: reading.measuredAt, ...reading.windows },
+  };
+}
+
+/** The coordinator's machine: from its saved coordinator run, else its agent record. */
+export async function coordinatorMachineId({ request = devRequest, config = readConfig } = {}) {
+  const c = await config();
+  const agent = (await request("GET", `/api/v1/agents/${encode(c.agentId)}`)).data;
+  if (agent?.role !== "coordinator" || !agent.machineId)
+    throw new CliError("MACHINE_COORDINATOR_REQUIRED", "Account capacity is reported by the machine's coordinator; run this with the coordinator's Dev identity.", 1);
+  return agent.machineId;
+}
+
+export async function listAccounts(machineId, { request = devRequest } = {}) {
+  const runners = (await request("GET", "/api/v1/runners?kind=account")).data ?? [];
+  return runners.filter((runner) => runner.machineId === machineId);
+}
+
+export async function registerAccount(machineId, { runtime, profile: given }, { request = devRequest } = {}) {
+  const profile = profilePath(given);
+  checkAccount({ runtime, profile });
+  return (await request("POST", "/api/v1/runners", { kind: "account", machineId, runtime, profile, status: "online" })).data;
+}
+
+/**
+ * Read and report each account's windows; one failure never hides the rest.
+ * `probe` lets an opted-in Codex account take a fresh reading. Only an
+ * explicit report or a launch probes, never the watch loop: a probe spends
+ * the account's quota (hub-58, 30 Oct).
+ */
+export async function reportUsage(accounts, { request = devRequest, readers = READERS, probes = readProbes, probe = false } = {}) {
+  const results = [];
+  const probing = probe && accounts.some((account) => account.runtime === "codex") ? await probes() : {};
+  for (const account of accounts) {
+    try {
+      const reading = await readers[account.runtime](account.profile, probing[account.profile] ? { probe: probing[account.profile] } : {});
+      const body = usageReport(reading);
+      await request("POST", `/api/v1/runners/${encode(account.id)}/usage`, body);
+      // Bump liveness only: a status someone set (offline) is theirs to change.
+      await request("POST", `/api/v1/runners/${encode(account.id)}/heartbeat`, {});
+      results.push({ runnerId: account.id, runtime: account.runtime, profile: account.profile, state: body.state, band: usageBand(reading.windows), resetsAt: body.resetsAt, ...reading.windows });
+    } catch (error) {
+      results.push({ runnerId: account.id, runtime: account.runtime, profile: account.profile, error: { code: error?.code ?? "ACCOUNT_USAGE_UNAVAILABLE", message: error?.message ?? String(error) } });
+    }
+  }
+  return results;
+}
+
+const percent = (window) => window ? `${Math.round(window.utilization)}%` : "n/a";
+export const usageLine = (result) => result.error
+  ? `${result.runtime} ${result.profile}: not reported (${result.error.code}: ${result.error.message})`
+  : `${result.runtime} ${result.profile}: ${result.band ?? result.state} (5h ${percent(result.fiveHour)}, week ${percent(result.sevenDay)})`;
+
+function parseAccountFlag(value) {
+  const match = /^(claude|codex):(.+)$/.exec(String(value));
+  if (!match) throw new CliError("USAGE", "--account must be RUNTIME:PROFILE, for example claude:/Users/me/.claude-work.", 2);
+  const account = { runtime: match[1], profile: profilePath(match[2]) };
+  checkAccount(account);
+  return account;
+}
+export const accountFlags = (value) => (value === undefined ? [] : Array.isArray(value) ? value : [value]).map(parseAccountFlag);
+
+/** The coordinator run `coordinator start --machine NAME` saved, if any. */
+async function savedCoordinatorRun(machine) {
+  try { return JSON.parse(await readFile(join(dirname(configPath()), `coordinator-${encodeURIComponent(machine)}.json`), "utf8")); }
+  catch { return null; }
+}
+
+/** `machine accounts register|list` and `machine usage report`. */
+export async function machineCapacityCommand(area, action, flags, { request = devRequest, config = readConfig, readers = READERS, savedRun = savedCoordinatorRun } = {}) {
+  const machineId = flags["machine-id"] ?? await coordinatorMachineId({ request, config });
+  // A coordinator coordinates one machine; --machine NAME must be that one.
+  const saved = flags.machine ? await savedRun(flags.machine) : null;
+  if (saved?.machineId && saved.machineId !== machineId)
+    throw new CliError("MACHINE_COORDINATOR_REQUIRED", `This Dev identity coordinates a different machine than ${flags.machine}.`, 1);
+  if (area === "accounts" && action === "register") {
+    if ((flags.probe || flags["no-probe"]) && flags.runtime !== "codex") throw new CliError("USAGE", "--probe and --no-probe apply to a codex account only.", 2);
+    const account = await registerAccount(machineId, { runtime: flags.runtime, profile: flags.profile }, { request });
+    if (flags.probe) {
+      const codexBin = await resolveCodexBin();
+      if (!codexBin) throw new CliError("CODEX_NOT_FOUND", "--probe needs the codex binary: put it on PATH or set NODII_DEV_CODEX_BIN.", 1);
+      await saveProbe(account.profile, codexBin);
+    }
+    if (flags["no-probe"]) await saveProbe(account.profile, null);
+    const [result] = await reportUsage([account], { request, readers });
+    return { payload: { data: { account, usage: result } }, human: `Registered ${account.runtime} account ${account.profile} (${account.id}).\n${usageLine(result)}` };
+  }
+  if (area === "accounts" && action === "list") {
+    const accounts = await listAccounts(machineId, { request });
+    return { payload: { data: accounts }, human: accounts.map((a) => `${a.id}\t${a.runtime}\t${a.profile}\t${a.status}`).join("\n") || "No accounts registered on this machine." };
+  }
+  if (area === "usage" && action === "report") {
+    const all = await listAccounts(machineId, { request });
+    const accounts = flags.profile ? all.filter((a) => a.profile === profilePath(flags.profile)) : all;
+    if (!accounts.length)
+      throw new CliError("ACCOUNT_NOT_REGISTERED", `No account${flags.profile ? ` ${flags.profile}` : "s"} registered on this machine. Run nodii-dev machine accounts register --runtime claude|codex --profile PATH first.`, 1);
+    const results = await reportUsage(accounts, { request, readers, probe: Boolean(flags.probe) });
+    const failed = results.filter((r) => r.error);
+    if (failed.length === results.length)
+      throw new CliError(failed[0].error.code, results.map(usageLine).join("\n"), 1);
+    return { payload: { data: results }, human: results.map(usageLine).join("\n") };
+  }
+  throw new CliError("USAGE", "machine accounts register --runtime claude|codex --profile PATH | machine accounts list | machine usage report [--profile PATH]", 2);
+}

package/dist/cli.js

@@ -59,6 +59,7 @@ import { docsCommand, rulebookCommand, rulesCommand } from "./upload.js";
 import { changeSetCommand, guidelineCommand } from "./guidelines.js";
 import { designCheck, designCheckText, designRoles, designRolesText } from "./design.js";
 import { watchdogCommand } from "./watchdog.js";
+import { machineCapacityCommand } from "./accounts.js";
 import {
   ALIASES,
   GROUPS,
@@ -150,7 +151,8 @@ Usage: nodii-dev <command> [options] [--json]
   harness check                         # 0 current, 1 differs from Dev, 2 not installed
   harness update --check                # the same check
   watchdog install [--interval SECONDS] # install/update the per-Mac launchd liveness sweep (default 60s)
-  watchdog sweep                        # launchd entrypoint: report dead runs, stale sockets, unpushed worktrees
+  watchdog sweep                        # launchd entrypoint: report dead runs, stale sockets, unpushed worktrees,
+                                        # and re-report account usage every 5 min
   docs check|validate|upload <path...> --class ruling|conformance|editorial
        [--base CODE=VERSION] [--decision FILE] [--conformance-ref REF]
        [--meaning-unchanged REASON] [--wait]
@@ -176,10 +178,14 @@ Usage: nodii-dev <command> [options] [--json]
   gather timings [--model M] [--last N]  # this Mac's lane Gather picks: warm-up and first-pick p50/p95
                                         # (each lane gather logs one; the first pick has 120 s once warm)
 
-  coordinator start --machine NAME       # register this machine's one watched coordinator; refuses a live second
+  coordinator start --machine NAME [--account RUNTIME:PROFILE ...]
+                                        # register this machine's one watched coordinator; refuses a live second;
+                                        # registers each --account and reports every account's usage; a background
+                                        # heartbeater keeps the run alive while this session lives, then ends it
   lane launch <key> --done-check TEXT --kind KIND --side SIDE
               --issue KEY --repo NAME=/SOURCE --branch NAME=BRANCH [--repo ... --branch ...]
               --machine NAME --runtime claude|codex --profile PATH --model MODEL --subagents N
+              --class long|short|no-build   # MW1-38.3 class, weighed against the account's MW1-38.2 band
               [--base NAME=REF] [--worktree NAME=PATH] [--owned-path NAME=PATH]
               [--route /app/... ...] [--figma FILE_KEY[=COMPONENT_SET_KEY[,KEY]]] [--notes TEXT]
               [--narrowing-note TEXT --narrowing-remainder DESTINATION]
@@ -228,6 +234,15 @@ Usage: nodii-dev <command> [options] [--json]
                                         # local document pick; prints Lane contract then Clause map
   built list | built ack <key...>
   machine list|show|set-coordinator|assign|report
+  machine accounts register --runtime claude|codex --profile PATH [--probe|--no-probe] [--machine NAME]
+                                        # coordinator: one runner per model account; reads and reports its usage;
+                                        # --probe (codex): opt in to one minimal codex turn, at launch or an explicit
+                                        # report --probe, when its reading is 10+ min old (never from the watch loop)
+  machine accounts list [--machine NAME]
+  machine usage report [--profile PATH] [--probe] [--machine NAME]
+                                        # coordinator: each account's 5-hour and weekly windows, read-only
+                                        # (Claude usage endpoint / newest Codex rollout); lane launch needs one
+                                        # under 15 min old, and the watchdog sweep re-reports every 5 min
   agent lane-limit|grant|revoke
   people reveal <id> --reason TEXT | people refresh-names
 
@@ -698,6 +713,8 @@ export async function main(argv = process.argv.slice(2)) {
   if (command === "lane") return emitCommand(await laneCommand(action, rest, f));
   if (command === "next") return emitCommand(await nextCommand(action, f));
   if (command === "built") return emitCommand(await builtCommand(action, rest, f));
+  if (command === "machine" && ["accounts", "usage"].includes(action))
+    return emitCommand(await machineCapacityCommand(action, rest[0], f));
   if (command === "machine") return emitCommand(await machineCommand(action, rest, f));
   if (command === "people" && ["reveal", "refresh-names"].includes(action))
     return emitCommand(await peopleCommand(action, rest, f));

package/dist/core.js

@@ -4,7 +4,7 @@ import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 
-export const VERSION = "0.6.37";
+export const VERSION = "0.6.38";
 export const configPath = () =>
   process.env.NODII_DEV_CONFIG_PATH ??
   join(homedir(), ".config/nodii-dev/config.json");
@@ -222,7 +222,7 @@ export async function checkLogin() {
 export const encode = (value) => encodeURIComponent(value);
 // Switches never take the next token as their value, so
 // `docs upload --wait rulebook/` keeps rulebook/ as a path.
-const SWITCHES = new Set(["json", "wait", "pending", "dry-run", "check", "all", "fleet", "help", "yes", "mine", "no-browser", "include-drafts", "drafted", "library", "async", "sync", "force", "system", "delta"]);
+const SWITCHES = new Set(["json", "wait", "pending", "dry-run", "check", "all", "fleet", "help", "yes", "mine", "no-browser", "include-drafts", "drafted", "library", "async", "sync", "force", "system", "delta", "probe", "no-probe"]);
 export function parseArgs(argv) {
   const flags = {};
   const args = [];

package/dist/setup.js

@@ -18,7 +18,7 @@ description: Drive every Nodii build lane through nodii-dev from start to verifi
 
 Use \`nodii-dev\` as the control plane. It talks only to Dev, through the platform edge, signed in with \`nodii-dev login\` as the platform tenant's OAuth app. The canonical policy is the build-workflow rulebook in Dev (\`nodii-dev rulebook list\`), §§1–8 (operator rulings A-020/A-021). Never change lane state in Dev by another route.
 
-1. The machine coordinator runs \`nodii-dev coordinator start --machine NAME\`, then \`nodii-dev lane launch KEY\` with the issue (whose title is the objective), done check, build kind/side, repeated repository/branch pairs, runtime profile/model and subagent quota. A launched agent begins with \`nodii-dev lane gather\` from its worktree.
+1. The machine coordinator runs \`nodii-dev coordinator start --machine NAME [--account RUNTIME:PROFILE ...]\` (each model account a lane may run on is registered once; its usage is reported then, before each launch and by the watchdog), then \`nodii-dev lane launch KEY\` with the issue (whose title is the objective), done check, build kind/side, repeated repository/branch pairs, runtime profile/model, subagent quota and the lane's class (\`--class long|short|no-build\`, weighed against the account's usage band). A launched agent begins with \`nodii-dev lane gather\` from its worktree.
 2. Re-run \`nodii-dev lane gather\` for the current steps and rules; start, complete, or block the reported API step with \`nodii-dev lane step\`. After an authoritative \`lane amend\`, every run is blocked until its own \`lane gather --delta\` acknowledgement.
 3. Record durable evidence with \`nodii-dev lane evidence KEY --pr|--commit|--figma|--deploy|--dev-check REF\` and heartbeat long-running work with \`nodii-dev lane heartbeat KEY --note "..."\` (notes are at most 500 characters).
 4. Record the review gate with \`nodii-dev lane review KEY\`. After merge, run \`nodii-dev lane land KEY\`. Done still means deployed and checked live on dev as the right user: \`nodii-dev lane verify KEY --dev-check REF\`.

package/dist/starting.js

@@ -7,6 +7,7 @@ import { CliError, configPath, devRequest, encode, query, readConfig, requireFla
 import { assertKnownSets, checkComponentSetKey, checkFileKey, loadDsCatalog, mergeScopes, scopesFromRoutes } from "./figma-scope.js";
 import { GATHER_TIMEOUT_MS, gatherDeadline } from "./gather.js";
 import { laneCommand, nextCommand } from "./lanes.js";
+import { accountFlags, listAccounts, profilePath, registerAccount, reportUsage, usageLine } from "./accounts.js";
 
 const execFile = promisify(execFileCallback);
 const via = { via: "nodii-dev" };
@@ -147,17 +148,99 @@ async function watchCoordinator(runId) {
   });
 }
 
-export async function coordinatorCommand(action, flags, { request = devRequest, config = readConfig, save = saveJson, watch = watchCoordinator } = {}) {
+const heartbeatPidFile = (machine) => join(dirname(configPath()), `coordinator-${encodeURIComponent(machine)}.heartbeat.pid`);
+
+/**
+ * Start the coordinator run's heartbeater: a detached `coordinator heartbeat`
+ * process tied to the coordinator session's PID (hub-58, 30 Oct). Its PID is
+ * saved next to the coordinator state so only it is ever signalled.
+ */
+async function spawnHeartbeater({ runId, machine, pid, processStartedAt, intervalSeconds }) {
+  const { spawn } = await import("node:child_process");
+  const { openSync } = await import("node:fs");
+  const log = openSync(join(dirname(configPath()), `coordinator-${encodeURIComponent(machine)}.heartbeat.log`), "a", 0o600);
+  const child = spawn(process.execPath, [
+    resolve(process.argv[1]), "coordinator", "heartbeat", "--machine", machine, "--run", runId, "--pid", String(pid),
+    ...(processStartedAt ? ["--pid-started-at", processStartedAt] : []), "--interval", String(intervalSeconds),
+  ], { detached: true, stdio: ["ignore", log, log], env: { ...process.env, NODII_DEV_CONFIG_PATH: configPath() } });
+  child.unref();
+  await writeFile(heartbeatPidFile(machine), `${child.pid}\n`, { mode: 0o600 });
+  return child.pid;
+}
+
+/**
+ * The heartbeater's loop: heartbeat the coordinator run while its session
+ * lives; when the session exits, end the run and stop. A run that a later
+ * `coordinator start` replaced, or that Dev already ended, is left alone.
+ */
+export async function coordinatorHeartbeatLoop({ machine, runId, pid, processStartedAt, intervalMs }, {
+  request = devRequest,
+  isAlive = async (target, startedAt) => (await import("./watchdog.js")).isProcessAlive(target, startedAt),
+  currentRunId = async () => (await loadJson(stateFile(machine)))?.runId,
+  sleep = (ms) => delay(ms),
+} = {}) {
+  for (;;) {
+    if ((await currentRunId()) !== runId) return { stopped: "replaced" };
+    if (!(await isAlive(pid, processStartedAt))) {
+      try {
+        await request("POST", `/api/v1/runs/${encode(runId)}/end`, {
+          status: "done",
+          evidence: [{ kind: "process", ref: `pid ${pid}`, note: "The coordinator session exited." }],
+        });
+      } catch (error) {
+        if (error?.code !== "RUN_ALREADY_TERMINAL") throw error;
+      }
+      return { stopped: "session_exited" };
+    }
+    try {
+      await request("POST", `/api/v1/runs/${encode(runId)}/heartbeat`, { note: `coordinator pid ${pid} alive` });
+    } catch (error) {
+      if (error?.code === "RUN_ALREADY_TERMINAL") return { stopped: "terminal" };
+      process.stderr.write(`coordinator heartbeat failed (${error?.code ?? error?.message ?? "error"}); retrying.\n`);
+    }
+    await sleep(intervalMs);
+  }
+}
+
+/** Register each --account, then report every account's usage (MW1-38.1). */
+async function coordinatorCapacity(machineId, flags, { request, readers }) {
+  // The run is already started: a refused registration is reported, not thrown.
+  const refused = [];
+  for (const account of accountFlags(flags.account)) {
+    try { await registerAccount(machineId, account, { request }); }
+    catch (error) { refused.push({ ...account, error: { code: error?.code ?? "ACCOUNT_REGISTER_FAILED", message: error?.message ?? String(error) } }); }
+  }
+  try {
+    const reported = await reportUsage(await listAccounts(machineId, { request }), { request, ...(readers ? { readers } : {}) });
+    return [...refused, ...reported];
+  } catch (error) {
+    return [...refused, { runtime: "accounts", profile: "(all)", error: { code: error?.code ?? "ACCOUNT_USAGE_REPORT_FAILED", message: error?.message ?? String(error) } }];
+  }
+}
+
+export async function coordinatorCommand(action, flags, { request = devRequest, config = readConfig, save = saveJson, watch = watchCoordinator, readers, heartbeater = spawnHeartbeater, heartbeatLoop = coordinatorHeartbeatLoop } = {}) {
+  if (action === "heartbeat") {
+    const result = await heartbeatLoop({
+      machine: requireFlag(flags, "machine"),
+      runId: requireFlag(flags, "run"),
+      pid: Number(requireFlag(flags, "pid")),
+      processStartedAt: flags["pid-started-at"] ?? null,
+      intervalMs: Number(flags.interval ?? 30) * 1000,
+    }, { request });
+    return { payload: { data: result }, human: `Coordinator heartbeater stopped: ${result.stopped}.` };
+  }
   if (action !== "start") throw new CliError("USAGE", `Unknown coordinator action: ${action}`, 2);
   const machine = requireFlag(flags, "machine");
+  accountFlags(flags.account);
   const payload = await request("POST", "/api/v1/coordinator-runs/start", {
     machine,
     expectedHeartbeatSeconds: flags["heartbeat-seconds"] ? Number(flags["heartbeat-seconds"]) : 60,
     ...via,
   });
   const c = await config();
+  let watched;
   try {
-    await watch(payload.data.run.id);
+    watched = await watch(payload.data.run.id);
   } catch (error) {
     try {
       await request("POST", `/api/v1/runs/${encode(payload.data.run.id)}/process-exit`, {
@@ -175,14 +258,30 @@ export async function coordinatorCommand(action, flags, { request = devRequest,
     agentId: c.agentId,
     startedAt: payload.data.run.startedAt,
   });
+  // The run expects a heartbeat every expectedHeartbeatSeconds; heartbeat at
+  // half that so one late beat never makes it quiet.
+  const expected = payload.data.run.expectedHeartbeatSeconds ?? (flags["heartbeat-seconds"] ? Number(flags["heartbeat-seconds"]) : 60);
+  let heartbeaterPid = null;
+  let heartbeaterError = null;
+  if (watched?.pid) {
+    try { heartbeaterPid = await heartbeater({ runId: payload.data.run.id, machine, pid: watched.pid, processStartedAt: watched.processStartedAt ?? null, intervalSeconds: Math.max(5, Math.floor(expected / 2)) }); }
+    catch (error) { heartbeaterError = error?.message ?? String(error); }
+  }
+  const accounts = await coordinatorCapacity(payload.data.machine.id, flags, { request, readers });
   return {
-    payload,
+    payload: { ...payload, accounts, heartbeaterPid },
     human: (p) => [
       `Coordinator ${p.data.run.id} is watching ${p.data.machine.name}.`,
       `running lanes: ${p.data.runningLanes.length}`,
       `orphans: ${p.data.orphanedRuns.length}`,
       `unclaimed results: ${p.data.unclaimedResults.length}`,
       ...(p.data.takeoverOfRunId ? [`takeover recorded from ${p.data.takeoverOfRunId}`] : []),
+      heartbeaterPid
+        ? `heartbeater ${heartbeaterPid} keeps the run alive while session ${watched.pid} lives`
+        : `heartbeater not started${heartbeaterError ? ` (${heartbeaterError})` : ""}: the run goes quiet without heartbeats`,
+      ...(accounts.length
+        ? accounts.map((result) => `account ${usageLine(result)}`)
+        : [`accounts: none registered; add one with --account claude:/path/to/profile (lane launch needs its usage)`]),
     ].join("\n"),
   };
 }
@@ -277,8 +376,16 @@ export async function figmaRateLimit(task, {
   }
 }
 
+async function refreshAccountUsage(machineId, runtime, profile, { request }) {
+  const accounts = (await listAccounts(machineId, { request })).filter((a) => a.runtime === runtime && a.profile === profile);
+  // A launch is about to spend this account anyway, so an opted-in Codex
+  // account may probe for a fresh reading here.
+  return reportUsage(accounts, { request, probe: true });
+}
+
 export async function launchLaneCommand(key, flags, {
   request = devRequest,
+  capacity = refreshAccountUsage,
   config = readConfig,
   state = loadJson,
   worktrees = createWorktrees,
@@ -310,8 +417,12 @@ export async function launchLaneCommand(key, flags, {
     throw new CliError("LANE_IDENTITY_REQUIRED", `Lane ${key} needs its provisioned Dev identity at ${devConfigPath}.`, 1);
   const scopes = await launchFigmaScopes(flags, { catalog });
   const figmaSeatVerified = scopes.length ? await figmaSeat() : false;
-  const profile = requireFlag(flags, "profile");
+  const profile = profilePath(requireFlag(flags, "profile"));
   if (!isAbsolute(profile)) throw new CliError("USAGE", "--profile must be an absolute runtime profile path.", 2);
+  // MW1-38.3: the coordinator classes the lane; Dev weighs it against the
+  // account's MW1-38.2 band.
+  const workClass = { long: "long", short: "short", "no-build": "no_build" }[requireFlag(flags, "class")];
+  if (!workClass) throw new CliError("USAGE", "--class must be long, short or no-build (a one-file fix, a publish or verify relaunch, or an evidence-only step).", 2);
   const body = {
     key,
     doneCheck: requireFlag(flags, "done-check"),
@@ -327,6 +438,7 @@ export async function launchLaneCommand(key, flags, {
     devConfigPath,
     model: requireFlag(flags, "model"),
     subagentQuota: Number(requireFlag(flags, "subagents")),
+    workClass,
     ...(flags.notes ? { notes: flags.notes } : {}),
     ...(flags["narrowing-note"] ? { narrowingNote: flags["narrowing-note"] } : {}),
     ...(flags["narrowing-remainder"] ? { narrowingRemainder: flags["narrowing-remainder"] } : {}),
@@ -337,6 +449,10 @@ export async function launchLaneCommand(key, flags, {
   };
   if (!Number.isInteger(body.subagentQuota) || body.subagentQuota < 0 || body.subagentQuota > 100)
     throw new CliError("USAGE", "--subagents must be an integer from 0 to 100.", 2);
+  // MW1-38.1: read the account's limits before every launch. A failed read is
+  // not fatal here; Dev's preflight refuses a missing or stale reading and
+  // names the command that fixes it.
+  try { await capacity(coordinator.machineId, runtime, profile, { request }); } catch {}
   await request("POST", "/api/v1/lanes/launch", { phase: "preflight", ...body });
   await worktrees(repositories);
   const lastPushedCommit = await head(repositories);

package/dist/watchdog.js

@@ -4,6 +4,7 @@ import { homedir, platform } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { CliError, configPath, devRequest, encode, readConfig } from "./core.js";
+import { USAGE_REFRESH_MS, listAccounts, reportUsage } from "./accounts.js";
 
 const execFile = promisify(execFileCallback);
 export const WATCHDOG_LABEL = "com.nodii.watchdog";
@@ -173,6 +174,29 @@ const observationBody = ({ observation, machineId, pid, observedAt, detail }) =>
   observation, machineId, ...(pid === undefined ? {} : { pid }), observedAt, ...(detail ? { detail } : {}),
 });
 
+const usageStampPath = (home = homedir()) => join(watchdogHome(home), "usage-reported-at");
+
+/**
+ * Keep the machine's account readings fresh (MW1-38.1: at least every 10
+ * minutes): re-report every USAGE_REFRESH_MS, so lane launch's 15-minute
+ * window holds without anyone remembering (AGENT-HARNESS-43).
+ */
+export async function refreshMachineUsage(machineId, {
+  request = devRequest,
+  now = () => new Date(),
+  readStamp = async () => { try { return Date.parse(await readFile(usageStampPath(), "utf8")); } catch { return Number.NaN; } },
+  writeStamp = (at) => atomicWrite(usageStampPath(), at),
+  list = listAccounts,
+  report = reportUsage,
+} = {}) {
+  const last = await readStamp();
+  if (Number.isFinite(last) && now().getTime() - last < USAGE_REFRESH_MS) return null;
+  // Never probe here: a probe spends the account's quota (hub-58, 30 Oct).
+  const results = await report(await list(machineId, { request }), { request, probe: false });
+  await writeStamp(now().toISOString());
+  return results;
+}
+
 /** One launchd sweep. The machine coordinator reports every observation through Dev's run watchdog contract. */
 export async function sweepWatchdog({
   records,
@@ -182,6 +206,7 @@ export async function sweepWatchdog({
   saveRecord = saveWatchedRun,
   machineId,
   now = () => new Date(),
+  refreshUsage = refreshMachineUsage,
 } = {}) {
   const loaded = records ? { records, errors: [] } : await loadRecords();
   const facts = await collect(loaded.records, { errors: [...loaded.errors] });
@@ -241,7 +266,18 @@ export async function sweepWatchdog({
       facts.errors.push({ kind: "run", runId: record.runId, observation: "process_dead", code: error?.code ?? "RUN_WATCHDOG_REPORT_FAILED" });
     }
   }
-  const report = { ...facts, orphanedRuns };
+  // A coordinator session has no command loop to heartbeat its run: while its
+  // process lives, the sweep does (a lane heartbeats its own run, so a stuck
+  // lane still goes quiet).
+  let accounts = null;
+  try {
+    accounts = await refreshUsage(effectiveMachineId, { request, now });
+    for (const result of accounts ?? [])
+      if (result.error) facts.errors.push({ kind: "usage", runnerId: result.runnerId, code: result.error.code });
+  } catch (error) {
+    facts.errors.push({ kind: "usage", code: error?.code ?? "ACCOUNT_USAGE_REPORT_FAILED" });
+  }
+  const report = { ...facts, orphanedRuns, accounts };
   return report;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodii/dev",
-  "version": "0.6.37",
+  "version": "0.6.38",
   "description": "Agent CLI for Nodii Dev, reached through the platform edge",
   "type": "module",
   "bin": {