@nodii/dev 0.6.9 → 0.6.11

package/dist/docs.js

@@ -93,12 +93,34 @@ function fencedLines(lines) {
   });
 }
 
+/**
+ * The document's own clause id at the start of a line in a definition
+ * position (Dev issue 80), as Dev reads it: a bullet, text inside the bold,
+ * a bold paragraph, a heading, a bold table row or a numbered item. Ranges and
+ * lists (`**A-1 to A-4:**`, `**A-1, A-2:**`) are references. Null otherwise.
+ */
+export function sourceIdAt(line, code) {
+  const m = /^\s*(?:([-*+])\s+|(\d+)\.\s+|(#{1,6})\s+|(\|)\s*)?(\*\*)?(.*)$/.exec(line);
+  if (!m) return null;
+  const [, bullet, numbered, heading, pipe, bold, rest = ""] = m;
+  if (!bold && !heading) return null;
+  const id = new RegExp(`^(${CLAUSE_ID})(?![\\d.]*\\d)`).exec(rest)?.[1];
+  // The document's own id: `TELE-3`, not the sibling code's `TELE-POR-3`.
+  if (!id || !new RegExp(`^${code.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}-S?\\d`).test(id)) return null;
+  const after = rest.slice(id.length);
+  // A list or range (`, X-2`, ` to X-4`, `–4`) is a reference, in or just after the bold; a dash before prose is not.
+  if (new RegExp(`^(?:\\*\\*)?\\s*(?:,|to\\s|and\\s|or\\s|[\u2013\u2014-])\\s*(?:\\*\\*)?(?:${CLAUSE_ID}|\\d)`).test(after)) return null;
+  const form = bullet && bold ? (/^\*\*(?=\s|$)/.test(after) ? "bullet" : "bullet-malformed") : heading ? "heading" : pipe ? "table-row" : numbered ? "numbered" : "bold-paragraph";
+  return { id, form };
+}
+
 /** Sections, clause definitions and parked items, skipping fenced code, with 1-based lines of the whole file. */
-export function parseBody(content, bodyStartLine = 1) {
+export function parseBody(content, bodyStartLine = 1, code = "") {
   const lines = content.split("\n");
   const sections = [];
   const clauses = [];
   const parked = [];
+  const sourceIds = [];
   const fenced = fencedLines(lines);
   let section = "";
   for (let i = bodyStartLine - 1; i < lines.length; i++) {
@@ -106,17 +128,43 @@ export function parseBody(content, bodyStartLine = 1) {
     if (fenced[i]) continue;
     const h2 = /^##\s+(.+?)\s*#*\s*$/.exec(line);
     if (h2 && !line.startsWith("###")) {
+      const heading = code ? sourceIdAt(line, code) : null;
+      if (heading) sourceIds.push({ ...heading, line: i + 1 });
       section = sectionTitle(h2[1]);
       sections.push({ title: section, line: i + 1 });
       continue;
     }
     // `- **TELE-32** Undecided: …` parks that clause; it is not a second definition of it.
     const p = parkedItem(line);
-    if (p !== null) { parked.push({ text: p, line: i + 1 }); continue; }
+    if (p !== null) { parked.push({ text: p, line: i + 1, clauseId: PARKED.exec(line)?.[1] ?? null }); continue; }
+    const source = code ? sourceIdAt(line, code) : null;
+    if (source) sourceIds.push({ ...source, line: i + 1 });
     const clause = CLAUSE_DEF.exec(line);
     if (clause) clauses.push({ id: clause[1], section, line: i + 1 });
   }
-  return { sections, clauses, parked };
+  return { sections, clauses, parked, sourceIds };
+}
+
+/** Dev issue 80: refuse every non-bullet clause form, then state the count invariant. */
+export function clauseFormErrors(body) {
+  const defined = new Set(body.clauses.map((c) => c.id));
+  // A parked line names its clause; a `### X-12` group heading is defined by its sub-clauses.
+  // Only a heading groups sub-clauses: `**X-12** … MUST …` over `- **X-12.1**` is a clause of its own.
+  const known = (id, form) => defined.has(id) || body.parked.some((p) => p.clauseId === id) || (form === "heading" && body.clauses.some((c) => c.id.startsWith(`${id}.`)));
+  const missing = new Map();
+  const errors = [];
+  for (const s of body.sourceIds) {
+    if (known(s.id, s.form) || missing.has(s.id)) continue;
+    missing.set(s.id, s.line);
+    errors.push(s.form === "bullet-malformed"
+      ? { code: "CLAUSE_MALFORMED", message: `clause \`${s.id}\` has text inside its bold; write \`- **${s.id}** …\` with any tag such as \`[INTENDED]\` after the bold (Dev issue 80)`, line: s.line }
+      : { code: "CLAUSE_NOT_A_BULLET", message: `clause \`${s.id}\` is written as a ${s.form.replace("-", " ")}; Dev reads a clause only as a bullet, \`- **${s.id}** …\` (Dev issue 80)`, line: s.line });
+  }
+  if (missing.size) {
+    const source = defined.size + missing.size;
+    errors.push({ code: "CLAUSE_COUNT_MISMATCH", message: `Dev would store ${defined.size} clauses but the source defines ${source}; missing: ${[...missing.keys()].join(", ")} (Dev issue 80)` });
+  }
+  return errors;
 }
 
 /**
@@ -188,9 +236,10 @@ export function validateDocument(content) {
   else if (groundedAt && !GROUNDED_AT.test(groundedAt))
     errors.push({ code: "FRONT_MATTER_FIELD_MISSING", message: `grounded_at \`${groundedAt}\` must be \`<repo>@<sha>\``, line: 1 });
 
-  const body = parseBody(text, bodyStartLine);
+  const body = parseBody(text, bodyStartLine, code);
   if (kind) errors.push(...sectionErrors(body.sections, kind));
   if (code) {
+    errors.push(...clauseFormErrors(body));
     const seen = new Map();
     for (const c of body.clauses) {
       if (!c.id.startsWith(`${code}-`)) { errors.push({ code: "CLAUSE_CODE_MISMATCH", message: `clause \`${c.id}\` does not start with the document code \`${code}-\` (M05-6)`, line: c.line }); continue; }

package/dist/lanes.js

@@ -167,12 +167,50 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
   throw new CliError("USAGE", `Unknown lane action: ${action}`, 2);
 }
 
-export async function nextCommand(ref, flags, { request = devRequest } = {}) {
+/**
+ * The files a lane touches, for path-tagged rules (M05-32): its branch and
+ * working-tree changes against origin/main, plus untracked files, read from
+ * its recorded worktree. Null when that worktree cannot be read here; Dev then
+ * serves every path-tagged clause rather than miss one.
+ */
+export async function laneChangedPaths(lane) {
+  try {
+    const run = async (...args) => (await execFileAsync("git", ["-C", lane.worktree, ...args], { encoding: "utf8", maxBuffer: 16 * 1024 * 1024 })).stdout;
+    const base = (await run("merge-base", "origin/main", "HEAD")).trim();
+    const changed = (await run("diff", "--name-only", base)).split("\n");
+    const untracked = (await run("ls-files", "--others", "--exclude-standard")).split("\n");
+    return [...new Set([...changed, ...untracked].map((x) => x.trim()).filter(Boolean))].slice(0, 5000);
+  } catch {
+    return null;
+  }
+}
+
+const rulesLines = (rules, key) => {
+  if (rules.error) return [`Rules: not served (${rules.error}). Until Dev serves them, read the clauses your brief cites; review delivers the rest (M05-35).`];
+  if (!rules.clauseCount) return [`Rules for this step: none served (no clause tagged for it yet, M05-37). Core: nodii-dev rules core`];
+  return [
+    `Rules for this step: ${rules.clauseCount} clause${rules.clauseCount === 1 ? "" : "s"}, ~${rules.tokens} tokens (DEC-0020). Full text: nodii-dev next ${key} --json`,
+    ...rules.clauses.map((c) => `  ${c.id}  ${c.gist}${c.toolGap ? `  [TOOL GAP ${c.toolGap}]` : ""}\n    -> ${c.pointer}`),
+  ];
+};
+
+export async function nextCommand(ref, flags, { request = devRequest, changedPaths = laneChangedPaths } = {}) {
   const lane = (await request("GET", `/api/v1/lanes/${encode(ref)}`)).data;
   const pending = lane.steps.filter((x) => ["waiting", "current", "blocked"].includes(x.state)).sort((a, b) => a.position - b.position);
   const steps = ["backend", "frontend"].map((side) => pending.find((x) => x.side === side)).filter(Boolean);
   const data = steps.map((step) => ({ side: step.side, step: step.stepKey, label: step.label, state: step.state, command: `nodii-dev lane step ${lane.key} --side ${step.side} --${step.state === "current" ? "done" : "start"} ${step.stepKey}` }));
-  return { payload: { data }, human: data.length ? data.map((x) => `${x.side}: ${x.label}\n  ${x.command}`).join("\n") : `All workflow steps are complete. Run: nodii-dev lane land ${lane.key}` };
+  // M05-32: the clauses Dev serves for this step. A failure here never hides the next step.
+  let rules = null;
+  if (data.length) {
+    const paths = flags.paths ? list(flags.paths) : await changedPaths(lane);
+    const body = { ...(paths ? { paths } : {}), ...(flags.components ? { components: list(flags.components) } : {}), ...(flags.role ? { role: String(flags.role) } : {}) };
+    try { rules = (await request("POST", `/api/v1/lanes/${encode(lane.key)}/rules`, body)).data; }
+    catch (error) { rules = { error: error.code ?? error.message }; }
+  }
+  const human = data.length
+    ? [...data.map((x) => `${x.side}: ${x.label}\n  ${x.command}`), ...rulesLines(rules, lane.key)].join("\n")
+    : `All workflow steps are complete. Run: nodii-dev lane land ${lane.key}`;
+  return { payload: { data, ...(rules ? { rules } : {}) }, human };
 }
 
 export async function builtCommand(action, args, flags, { request = devRequest } = {}) {

package/dist/oauth.js

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { mkdir, open, readFile, rm, stat, utimes } from "node:fs/promises";
 import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
@@ -45,73 +45,159 @@ function run(command, args, { input } = {}) {
   });
 }
 
-async function keychainStore(name, secret, os) {
+// `security -i` reads each command line into a 4096-byte buffer. A longer line
+// is cut there: the item is stored TRUNCATED and the rest of the line runs as a
+// second, failing command (Dev issue 88: the access-token cache, once the
+// JWT outgrew 4 KB, was stored cut short, every process read it as empty, and
+// every command rotated the shared refresh token). Lines stay well under it.
+export const SECURITY_LINE_MAX = 4000;
+// A secret longer than one line is stored in parts, then a header naming the
+// part count and the digest of the whole; a reader that sees a torn or partial
+// set (a writer mid-way) gets nothing rather than a wrong secret.
+const MAX_PARTS = 64;
+const CHUNKED = "chunked:v1:";
+const TOKEN_ALPHABET = /^[A-Za-z0-9._~+/=-]+$/;
+const part = (name, i) => `${name}:part:${i}`;
+const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+const addLine = (name, svc, secret) => `add-generic-password -U -a ${name} -s ${svc} -w ${secret}`;
+// Whether `security -i` takes the secret whole on one stdin line.
+const fitsOneLine = (name, svc, secret) => TOKEN_ALPHABET.test(secret) && addLine(name, svc, secret).length <= SECURITY_LINE_MAX;
+const checkName = (name) => {
+  if (!/^[A-Za-z0-9_.:-]+$/.test(name)) throw new CliError("KEYCHAIN_UNAVAILABLE", "The OAuth client id has characters the Keychain helper cannot take; nothing was stored.", 2);
+};
+
+async function keychainPut(name, secret, os, { exec, svc }) {
   if (os === "darwin") {
-    if (!/^[A-Za-z0-9_.:-]+$/.test(name)) throw new CliError("KEYCHAIN_UNAVAILABLE", "The OAuth client id has characters the Keychain helper cannot take; nothing was stored.", 2);
+    checkName(name);
     // Through `security -i` on stdin, so the secret never appears in argv
     // (visible to `ps`). The interactive parser splits on whitespace and reads
     // quotes, so a secret outside a token's own alphabet falls back to argv
     // rather than being dropped (it may be a refresh token just rotated).
-    if (/^[A-Za-z0-9._~+/=-]+$/.test(secret)) await run("security", ["-i"], { input: `add-generic-password -U -a ${name} -s ${service} -w ${secret}\n` });
-    else await run("security", ["add-generic-password", "-U", "-a", name, "-s", service, "-w", secret]);
+    if (fitsOneLine(name, svc, secret)) await exec("security", ["-i"], { input: `${addLine(name, svc, secret)}\n` });
+    else await exec("security", ["add-generic-password", "-U", "-a", name, "-s", svc, "-w", secret]);
     return "macOS Keychain";
   }
   if (os === "linux") {
     try {
-      await run("secret-tool", ["store", "--label=nodii-dev OAuth", "service", service, "account", name], { input: secret });
+      await exec("secret-tool", ["store", "--label=nodii-dev OAuth", "service", svc, "account", name], { input: secret });
       return "Secret Service";
     } catch {}
   }
   throw new CliError("KEYCHAIN_UNAVAILABLE", "OAuth refresh tokens require macOS Keychain or Linux Secret Service. No credential was stored; re-run login when a keychain is available.", 2);
 }
 
-async function keychainLoad(name, os) {
-  if (os === "darwin") return (await run("security", ["find-generic-password", "-a", name, "-s", service, "-w"])).trim();
-  if (os === "linux") return (await run("secret-tool", ["lookup", "service", service, "account", name])).trim();
+async function keychainGet(name, os, { exec, svc }) {
+  if (os === "darwin") return (await exec("security", ["find-generic-password", "-a", name, "-s", svc, "-w"])).trim();
+  if (os === "linux") return (await exec("secret-tool", ["lookup", "service", svc, "account", name])).trim();
   throw new Error("no keychain");
 }
 
-async function keychainDelete(name, os) {
+async function removeItem(name, os, { exec, svc }) {
   try {
-    if (os === "darwin") await run("security", ["delete-generic-password", "-a", name, "-s", service]);
-    else if (os === "linux") await run("secret-tool", ["clear", "service", service, "account", name]);
-  } catch {}
+    if (os === "darwin") await exec("security", ["delete-generic-password", "-a", name, "-s", svc]);
+    else if (os === "linux") await exec("secret-tool", ["clear", "service", svc, "account", name]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Parts are numbered from 1 without gaps, so the first one missing ends the
+// sweep, whatever header (or none) the parts were written under.
+async function removeParts(name, from, os, kc) {
+  if (os !== "darwin") return;
+  for (let i = from; i <= MAX_PARTS && (await removeItem(part(name, i), os, kc)); i++);
+}
+
+export async function keychainStore(name, secret, os = platform(), { exec = run, svc = service } = {}) {
+  const kc = { exec, svc };
+  if (os !== "darwin" || !TOKEN_ALPHABET.test(secret) || fitsOneLine(name, svc, secret)) {
+    const stored = await keychainPut(name, secret, os, kc);
+    await removeParts(name, 1, os, kc);
+    return stored;
+  }
+  checkName(name);
+  const size = SECURITY_LINE_MAX - addLine(part(name, MAX_PARTS), svc, "").length;
+  const parts = [];
+  if (size >= 256) for (let i = 0; i < secret.length && parts.length <= MAX_PARTS; i += size) parts.push(secret.slice(i, i + size));
+  if (!parts.length || parts.length > MAX_PARTS) throw new CliError("KEYCHAIN_UNAVAILABLE", "The secret is too long for the Keychain helper; nothing was stored.", 2);
+  // The parts in one `security` run, then, only once they are all in, the
+  // header that names them (`security -i` goes on past a failed line).
+  await exec("security", ["-i"], { input: `${parts.map((chunk, i) => addLine(part(name, i + 1), svc, chunk)).join("\n")}\n` });
+  await exec("security", ["-i"], { input: `${addLine(name, svc, `${CHUNKED}${parts.length}:${sha256(secret)}`)}\n` });
+  await removeParts(name, parts.length + 1, os, kc);
+  return "macOS Keychain";
 }
 
-export async function storeRefreshToken(clientId, token, os = platform()) {
-  return keychainStore(account(clientId), token, os);
+export async function keychainLoad(name, os = platform(), { exec = run, svc = service } = {}) {
+  const value = await keychainGet(name, os, { exec, svc });
+  if (!value.startsWith(CHUNKED)) return value;
+  const [count, digest] = value.slice(CHUNKED.length).split(":");
+  const n = Number.parseInt(count, 10);
+  if (!Number.isInteger(n) || n < 1 || n > MAX_PARTS) throw new Error("bad chunk header");
+  let secret = "";
+  for (let i = 1; i <= n; i++) secret += await keychainGet(part(name, i), os, { exec, svc });
+  if (sha256(secret) !== digest) throw new Error("chunks do not match their header");
+  return secret;
 }
 
-export async function loadRefreshToken(clientId, os = platform()) {
+export async function keychainDelete(name, os = platform(), { exec = run, svc = service } = {}) {
+  const kc = { exec, svc };
+  await removeItem(name, os, kc);
+  await removeParts(name, 1, os, kc);
+}
+
+// Read back after writing: a store that "succeeds" but keeps something else (a
+// truncated write) loses the rotated token, and the next refresh replays the
+// old one, which revokes the whole chain.
+export async function storeRefreshToken(clientId, token, os = platform(), keychain = {}) {
+  const stored = await keychainStore(account(clientId), token, os, keychain);
+  if ((await keychainLoad(account(clientId), os, keychain).catch(() => null)) !== token)
+    throw new CliError("KEYCHAIN_WRITE_FAILED", "The refresh token read back from the keychain differs from the one written.", 1);
+  return stored;
+}
+
+export async function loadRefreshToken(clientId, os = platform(), keychain = {}) {
   try {
-    const token = await keychainLoad(account(clientId), os);
+    const token = await keychainLoad(account(clientId), os, keychain);
     if (token) return token;
   } catch {}
   throw new CliError("OAUTH_LOGIN_REQUIRED", "OAuth credentials are unavailable; run `nodii-dev login` again.", 2);
 }
 
-export async function deleteRefreshToken(clientId, os = platform()) {
-  await keychainDelete(account(clientId), os);
+export async function deleteRefreshToken(clientId, os = platform(), keychain = {}) {
+  await keychainDelete(account(clientId), os, keychain);
 }
 
 // The access token is cached beside the refresh token so that every nodii-dev
 // process on the machine shares one: without it each command rotated the
 // refresh token, and N lanes rotated it N times as often.
-export async function loadAccessToken(clientId, os = platform()) {
+export async function loadAccessToken(clientId, os = platform(), keychain = {}) {
   try {
-    const cached = JSON.parse(Buffer.from(await keychainLoad(accessAccount(clientId), os), "base64url").toString("utf8"));
+    const cached = JSON.parse(Buffer.from(await keychainLoad(accessAccount(clientId), os, keychain), "base64url").toString("utf8"));
     return typeof cached?.token === "string" && Number.isFinite(cached.expiresAt) ? cached : null;
   } catch {
     return null;
   }
 }
 
-export async function storeAccessToken(clientId, cached, os = platform()) {
-  try { await keychainStore(accessAccount(clientId), Buffer.from(JSON.stringify(cached)).toString("base64url"), os); } catch {}
+let cacheWarned = false;
+
+// A cache that cannot be written is not fatal to this command, but every other
+// process would then refresh too, so it is said once, on stderr.
+export async function storeAccessToken(clientId, cached, os = platform(), keychain = {}) {
+  const value = Buffer.from(JSON.stringify(cached)).toString("base64url");
+  try {
+    await keychainStore(accessAccount(clientId), value, os, keychain);
+    if ((await keychainLoad(accessAccount(clientId), os, keychain)) === value) return;
+  } catch {}
+  if (cacheWarned) return;
+  cacheWarned = true;
+  process.stderr.write("nodii-dev: warning: the access token could not be cached in the keychain, so every nodii-dev process will refresh the sign-in.\n");
 }
 
-export async function deleteAccessToken(clientId, os = platform()) {
-  await keychainDelete(accessAccount(clientId), os);
+export async function deleteAccessToken(clientId, os = platform(), keychain = {}) {
+  await keychainDelete(accessAccount(clientId), os, keychain);
 }
 
 async function oauthPost(authUrl, path, fields, fetchImpl = fetch, timeoutMs = REFRESH_TIMEOUT_MS) {
@@ -326,7 +412,10 @@ export async function withRefreshLock(fn, { clientId, path = refreshLockPath(cli
 // grant, so the credential is kept.
 const DEAD_GRANT_ERRORS = new Set(["invalid_grant", "expired_token", "token_revoked"]);
 const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
-export const REFRESH_TIMEOUT_MS = 10_000;
+// A refresh is never cut off early: once the request is sent, nodii-auth may
+// rotate the token whether or not the answer arrives, so aborting it at 10 s
+// lost the successor and the next run replayed the old token (Dev issue 88).
+export const REFRESH_TIMEOUT_MS = 20_000;
 const REFRESH_ATTEMPTS = 4;
 const RETRY_AFTER_CAP_MS = 5_000;
 // The whole refresh, retries included, fits well inside the lock's wait
@@ -353,7 +442,10 @@ async function postRefresh(authUrl, clientId, refreshToken, fetchImpl, timeoutMs
       signal: AbortSignal.timeout(timeoutMs),
     });
   } catch (error) {
-    return { ok: false, status: 0, body: {}, json: false, reason: error?.name === "TimeoutError" ? "timeout" : "unreachable" };
+    // Only a connection that never opened is known not to have reached the
+    // server; a timeout or a dropped connection may follow a rotation.
+    const reason = error?.name === "TimeoutError" ? "timeout" : UNSENT_CODES.has(error?.cause?.code ?? error?.code) ? "unsent" : "unreachable";
+    return { ok: false, status: 0, body: {}, json: false, reason };
   }
   let raw = "";
   try { raw = await response.text(); } catch {}
@@ -364,12 +456,44 @@ async function postRefresh(authUrl, clientId, refreshToken, fetchImpl, timeoutMs
   return { ok: response.ok, status: response.status, body, json, retryAfterMs: Number.isFinite(retryAfter) ? retryAfter * 1000 : undefined };
 }
 
+// Node's (undici) and Bun's codes for a connection that never opened.
+const UNSENT_CODES = new Set(["ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN", "EHOSTUNREACH", "ENETUNREACH", "UND_ERR_CONNECT_TIMEOUT", "ConnectionRefused", "FailedToOpenSocket"]);
+// The answers that show the token was not used, so it may be sent again: the
+// edge's rate limit, nodii-auth failing before it commits (500, 503), and a
+// non-JSON 4xx (a proxy or WAF refusing before nodii-auth; it answers JSON).
+// Anything else that is not an answer (a gateway timeout, a 2xx without
+// tokens, an HTML page) may follow a rotation, and is not sent again here.
+const RESEND_STATUS = new Set([429, 500, 503]);
+const mayResend = (result) => (result.status === 0 ? result.reason === "unsent" : RESEND_STATUS.has(result.status) || (result.status >= 400 && result.status < 500 && !result.json));
+
+// From the moment a refresh token is presented until its successor is stored,
+// the process must not die: nodii-auth has already marked the old token used,
+// so losing the new one means the next refresh replays the old one and the
+// server revokes the whole chain, signing out every process on the machine.
+// SIGINT, SIGTERM and SIGHUP are held over that window and re-raised on
+// release, which comes after the refresh lock is let go. SIGHUP is re-raised
+// only with a terminal attached: under nohup (no terminal) it was meant to be
+// ignored, and re-raising it would kill what nohup kept alive.
+export function holdSignals() {
+  const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+  let caught = null;
+  const hold = (signal) => { caught ??= signal; };
+  for (const signal of signals) process.on(signal, hold);
+  return {
+    release() {
+      for (const signal of signals) process.off(signal, hold);
+      if (caught && (caught !== "SIGHUP" || process.stdin.isTTY || process.stdout.isTTY)) process.kill(process.pid, caught);
+    },
+  };
+}
+
 const describe = (result) => result.status === 0 ? (result.reason === "timeout" ? "timed out" : "nodii-auth unreachable") : `HTTP ${result.status}${result.json && typeof result.body.error === "string" ? ` ${result.body.error}` : ""}`;
 
 export class OAuthAuthProvider {
   #accessToken;
   #expiresAt = 0;
   #refreshPromise;
+  #signals;
   constructor({ fetchImpl = fetch, loadToken = loadRefreshToken, storeToken = storeRefreshToken, deleteToken = deleteRefreshToken, lock = withRefreshLock,
     loadAccess, storeAccess, deleteAccess, sleep = wait, timeoutMs = REFRESH_TIMEOUT_MS, budgetMs = REFRESH_BUDGET_MS } = {}) {
     // Injected token storage (tests) gets no shared access cache unless one is
@@ -397,7 +521,7 @@ export class OAuthAuthProvider {
         // rotated the refresh token and cached the access token it got.
         if (this.#usable(await this.loadAccess(config.clientId))) return this.#accessToken;
         return this.#refresh(config, held ?? (async () => true));
-      }, { clientId: config.clientId });
+      }, { clientId: config.clientId }).finally(() => this.#release());
     })().finally(() => { this.#refreshPromise = undefined; });
     return this.#refreshPromise;
   }
@@ -409,9 +533,15 @@ export class OAuthAuthProvider {
       // Never present the refresh token without the lock: a second holder
       // would present the same one, and the server revokes the chain on reuse.
       if (!(await held())) throw new CliError("OAUTH_REFRESH_BUSY", "Lost the refresh lock to another nodii-dev process; the saved sign-in was kept. Retry the command.", 1);
+      // Signals wait while a token is in flight; on success, until it is stored.
+      this.#signals ??= holdSignals();
       result = await postRefresh(config.authUrl, config.clientId, refresh, this.fetchImpl, Math.max(floor, Math.min(this.timeoutMs, deadline - Date.now())));
       const kind = classifyRefresh(result);
+      if (kind !== "ok") this.#release();
       if (kind !== "retry" || attempt >= REFRESH_ATTEMPTS) return { kind, result, attempts: attempt };
+      // A request that may have reached the server is not sent again with the
+      // same token: if it was rotated, that is a replay and revokes the chain.
+      if (!mayResend(result)) return { kind, result, attempts: attempt };
       const backoff = 500 * 2 ** (attempt - 1) + Math.floor(Math.random() * 250);
       const pause = Math.min(Math.max(backoff, result.retryAfterMs ?? 0), RETRY_AFTER_CAP_MS);
       if (Date.now() + pause + floor > deadline) return { kind, result, attempts: attempt };
@@ -461,6 +591,11 @@ export class OAuthAuthProvider {
     await this.storeAccess(config.clientId, { token: this.#accessToken, expiresAt: this.#expiresAt });
     return this.#accessToken;
   }
+  #release() {
+    const signals = this.#signals;
+    this.#signals = undefined;
+    signals?.release();
+  }
   async headers() {
     const config = await readConfig();
     return { authorization: `Bearer ${await this.accessToken()}`, ...(config.agentId ? { "x-agent-id": config.agentId } : {}) };

package/dist/upload.js

@@ -273,7 +273,8 @@ export async function rulebookCommand(action, args, flags, { request = devReques
     if (flags[name] === true) throw new CliError("USAGE", `--${name} needs a version, e.g. --${name} 1.0`, 2);
   if (action === "list") {
     const payload = await request("GET", `/api/v1/documents${query({ section: flags.section ?? (flags.all ? undefined : "rulebook"), kind: flags.kind, serviceId: flags.service, domain: flags.domain, status: flags.status, q: flags.q, limit: flags.limit ?? 500, offset: flags.offset })}`);
-    return { payload, human: (p) => p.data.map((x) => `${x.code}\t${x.currentVersion}\t${x.status}\t${x.kind}\t${x.title}${x.parkedCount ? `\tparked=${x.parkedCount}` : ""}`).join("\n") || "No documents." };
+    // Dev issue 80: the clause count, so a document Dev reads as 0/44 shows at a glance.
+    return { payload, human: (p) => p.data.map((x) => `${x.code}\t${x.currentVersion}\t${x.status}\t${x.kind}\t${x.clauseCount ?? "?"} clause${x.clauseCount === 1 ? "" : "s"}\t${x.title}${x.parkedCount ? `\tparked=${x.parkedCount}` : ""}`).join("\n") || "No documents." };
   }
   if (action === "show") {
     const code = args[0];
@@ -289,3 +290,43 @@ export async function rulebookCommand(action, args, flags, { request = devReques
   }
   throw new CliError("USAGE", "rulebook list|show|diff", 2);
 }
+
+const pad = (v, n) => String(v).padStart(n);
+
+/**
+ * `nodii-dev rules core|report|cap` (DEC-0020; M05-33, M05-36): the generated
+ * core, the delivery report, and the operator's core token cap.
+ */
+export async function rulesCommand(action, args, flags, { request = devRequest } = {}) {
+  if (action === "core") {
+    // Dev refuses a core over the cap with CORE_OVER_CAP; that error is the output.
+    const payload = await request("GET", "/api/v1/rules/core");
+    return { payload, human: (p) => `${p.data.markdown.trimEnd()}\n\n${p.data.clauseCount} core clause${p.data.clauseCount === 1 ? "" : "s"}, ~${p.data.tokens} of ${p.data.cap} tokens.` };
+  }
+  if (action === "report") {
+    const payload = await request("GET", `/api/v1/rules/report${query({ section: flags.section, lane: flags.lane })}`);
+    return {
+      payload,
+      human: (p) => {
+        const d = p.data;
+        const row = (code, t) => `${code.padEnd(10)}${pad(t.clauses, 6)}${pad(t.must, 6)}${pad(t.enforced, 9)}${pad(t.served, 7)}${pad(t.core, 5)}${pad(t.untagged, 9)}${pad(t.untaggedMust, 14)}${pad(t.toolGap, 9)}`;
+        const lines = [
+          `${"document".padEnd(10)}${pad("all", 6)}${pad("MUST", 6)}${pad("enforced", 9)}${pad("served", 7)}${pad("core", 5)}${pad("untagged", 9)}${pad("untagged MUST", 14)}${pad("tool gap", 9)}`,
+          ...(flags.lane ? [] : d.documents.map((x) => row(x.code, x))),
+          row("TOTAL", d.totals),
+          `Core: ${d.core.clauseCount} clauses, ~${d.core.tokens} of ${d.core.cap} tokens${d.core.overCap ? " (OVER THE CAP)" : ""}.`,
+          ...(d.lanes.length ? ["Served per lane:"] : ["No lane has been served rules yet."]),
+          ...d.lanes.flatMap((l) => [`  ${l.key} (${l.status}): ${l.clauseCount} clauses, ~${l.tokens} tokens`, ...l.steps.map((s) => `    ${s.side}/${s.step}: ${s.clauseCount} clauses, ~${s.tokens} tokens, served ${s.servedCount}x`)]),
+        ];
+        return lines.join("\n");
+      },
+    };
+  }
+  if (action === "cap") {
+    const cap = Number(args[0]);
+    if (!Number.isInteger(cap) || cap < 100 || cap > 100000) throw new CliError("USAGE", "rules cap needs a whole number of tokens, 100 to 100000 (M05-33)", 2);
+    const payload = await request("PUT", "/api/v1/rules/core/cap", { cap });
+    return { payload, human: (p) => `Core cap: ${p.data.previous} -> ${p.data.cap} tokens.` };
+  }
+  throw new CliError("USAGE", "rules core | rules report [--section rulebook|services|all] [--lane KEY] | rules cap TOKENS", 2);
+}

package/package.json

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