@nodii/dev 0.6.34 → 0.6.36

package/dist/remote.js

@@ -0,0 +1,281 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { promisify } from "node:util";
+import { CliError, devRequest, encode } from "./core.js";
+import { artifactEvidence, currentRunId, endRun, redactRunText, runKind, RUN_ID_ENV } from "./runs.js";
+
+// `nodii-dev run --remote-ssm` (AGENT-HARNESS-41): a script on an EC2
+// instance, watched like a local run. A benchmark that died silently on the
+// Dev EC2 went unheard for 8 hours (29-30 Oct); this fails it within N minutes.
+//
+// The script runs detached on the instance (its own session, so a cancel stops
+// its children), writing a log and then an exit-code file under its run
+// directory. Every poll is a short SSM command that reads the log's size and
+// tail, the exit code, and whether the process is alive. SSM keeps only the
+// first 24,000 characters of a command's output, so polling the script's own
+// invocation could neither see progress nor give the real tail.
+
+const execFileAsync = promisify(execFile);
+export const REMOTE_RUN_ROOT = "/var/tmp/nodii-dev-runs";
+const INSTANCE = /^m?i-[0-9a-f]{8,17}$/;
+const SCRIPT_MAX_BYTES = 32 * 1024;
+const TAIL_BYTES = 8 * 1024;
+const SSM_DONE = new Set(["Success", "Failed", "Cancelled", "TimedOut", "Cancelling", "Undeliverable", "Terminated", "DeliveryTimedOut", "ExecutionTimedOut", "InvalidPlatform", "AccessDenied"]);
+const sleepFor = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const quote = (value) => `'${String(value).replace(/'/g, `'\\''`)}'`;
+
+/** The AWS CLI as nodii-dev calls it: JSON out, the caller's own credentials. */
+export function awsCli({ region, exec = execFileAsync } = {}) {
+  return async (args) => {
+    let stdout;
+    try {
+      ({ stdout } = await exec("aws", [...args, "--output", "json", ...(region ? ["--region", region] : [])], { encoding: "utf8", maxBuffer: 4 * 1024 * 1024 }));
+    } catch (error) {
+      if (error?.code === "ENOENT")
+        throw new CliError("AWS_CLI_REQUIRED", "run --remote-ssm needs the AWS CLI (aws) on PATH, signed in to the instance's account.", 2);
+      const text = String(error?.stderr || error?.message || "").trim();
+      const code = /InvocationDoesNotExist/.test(text) ? "SSM_INVOCATION_PENDING" : "SSM_CALL_FAILED";
+      throw new CliError(code, `aws ${args.slice(0, 2).join(" ")} failed: ${redactRunText(text.split("\n").at(-1) ?? "")}`, 1);
+    }
+    return stdout.trim() ? JSON.parse(stdout) : {};
+  };
+}
+
+/** One short shell command on the instance; resolves with its stdout. */
+export async function ssmShell(aws, instance, commands, { comment, waitMs = 90_000, sleep = sleepFor, now = Date.now } = {}) {
+  const sent = await aws(["ssm", "send-command", "--instance-ids", instance, "--document-name", "AWS-RunShellScript",
+    "--comment", comment.slice(0, 100), "--parameters", JSON.stringify({ commands: [commands], executionTimeout: ["120"] })]);
+  const commandId = sent.Command?.CommandId;
+  if (!commandId) throw new CliError("SSM_CALL_FAILED", "aws ssm send-command returned no command id.", 1);
+  const until = now() + waitMs;
+  for (;;) {
+    let invocation = null;
+    try {
+      invocation = await aws(["ssm", "get-command-invocation", "--command-id", commandId, "--instance-id", instance]);
+    } catch (error) {
+      if (error?.code !== "SSM_INVOCATION_PENDING") throw error;
+    }
+    if (invocation && SSM_DONE.has(invocation.Status)) {
+      if (invocation.Status !== "Success")
+        throw new CliError("SSM_COMMAND_FAILED", `SSM command on ${instance} ended ${invocation.Status}${invocation.StatusDetails && invocation.StatusDetails !== invocation.Status ? ` (${invocation.StatusDetails})` : ""}${invocation.StandardErrorContent ? `: ${redactRunText(invocation.StandardErrorContent.trim().split("\n").at(-1))}` : ""}.`, 1);
+      return { commandId, stdout: invocation.StandardOutputContent ?? "" };
+    }
+    if (now() >= until)
+      throw new CliError("SSM_UNREACHABLE", `${instance} did not finish an SSM command within ${Math.round(waitMs / 1000)} s (${invocation?.Status ?? "not delivered"}).`, 1);
+    await sleep(2_000);
+  }
+}
+
+export const remoteDir = (runId) => `${REMOTE_RUN_ROOT}/${runId}`;
+
+export function startCommand(runId, script) {
+  const dir = quote(remoteDir(runId));
+  return [
+    "set -eu",
+    `d=${dir}`,
+    'mkdir -p "$d" && chmod 700 "$d" && cd "$d"',
+    `printf '%s' ${quote(Buffer.from(script, "utf8").toString("base64"))} | base64 -d > script`,
+    "chmod 700 script",
+    // Its own session (setsid): a cancel signals the whole group.
+    `setsid sh -c 'cd "$1"; ./script > log 2>&1; echo $? > exit.tmp; mv exit.tmp exit' nodii-dev-run "$d" < /dev/null > /dev/null 2>&1 &`,
+    'echo $! > pid',
+    'echo "started $(cat pid)"',
+  ].join("\n");
+}
+
+export function pollCommand(runId, tailBytes = TAIL_BYTES) {
+  return [
+    `d=${quote(remoteDir(runId))}`,
+    'if [ ! -d "$d" ]; then echo "state=missing"; exit 0; fi',
+    'echo "size=$(wc -c < "$d/log" 2>/dev/null || echo 0)"',
+    'p=$(cat "$d/pid" 2>/dev/null || true)',
+    'if [ -f "$d/exit" ]; then echo "exit=$(cat "$d/exit")"',
+    'elif [ -n "$p" ] && kill -0 "$p" 2>/dev/null; then echo "state=running"',
+    'else echo "state=vanished"; fi',
+    'echo "--- tail ---"',
+    `tail -c ${tailBytes} "$d/log" 2>/dev/null || true`,
+  ].join("\n");
+}
+
+export function cancelCommand(runId) {
+  return [
+    `d=${quote(remoteDir(runId))}`,
+    'p=$(cat "$d/pid" 2>/dev/null || true)',
+    '[ -n "$p" ] || exit 0',
+    // `kill -SIG -PGID`, never `kill -SIG -- -PGID`: dash (Ubuntu's sh) and
+    // busybox refuse the `--` form, and SSM runs this with sh.
+    'kill -TERM "-$p" 2>/dev/null || kill -TERM "$p" 2>/dev/null || true',
+    "sleep 5",
+    'kill -KILL "-$p" 2>/dev/null || true',
+    'echo cancelled',
+  ].join("\n");
+}
+
+export function artifactCommand(runId, path) {
+  return [
+    `cd ${quote(remoteDir(runId))}`,
+    `f=${quote(path)}`,
+    'if [ ! -f "$f" ]; then echo missing; exit 0; fi',
+    'echo "bytes=$(wc -c < "$f")"',
+    'base64 < "$f" | tr -d "\\n"',
+  ].join("\n");
+}
+
+export function parsePoll(stdout) {
+  const [head, ...rest] = String(stdout).split("--- tail ---\n");
+  const fields = Object.fromEntries(head.split("\n").filter((line) => line.includes("=")).map((line) => [line.slice(0, line.indexOf("=")), line.slice(line.indexOf("=") + 1).trim()]));
+  const exitCode = fields.exit === undefined ? null : Number(fields.exit);
+  return {
+    state: exitCode !== null ? "exited" : fields.state ?? "unknown",
+    size: Number(fields.size ?? 0),
+    exitCode: Number.isInteger(exitCode) ? exitCode : exitCode === null ? null : -1,
+    tail: rest.join("--- tail ---\n"),
+  };
+}
+
+const minutes = (ms) => (ms >= 60_000 ? `${Math.round(ms / 60_000)} min` : `${Math.round(ms / 1000)} s`);
+
+/**
+ * Run SCRIPT on INSTANCE through SSM as a watched run: register it with Dev
+ * (the waiter is NODII_DEV_RUN_ID), heartbeat on every poll, and end it with
+ * the exit code, the remote log tail and, on success, the artifact. It fails
+ * on a non-zero exit, a process that vanished without an exit code, or no new
+ * output (or no answer from the instance) for `quietMinutes`.
+ */
+export async function superviseRemoteRun({
+  instance,
+  script,
+  artifact,
+  quietMinutes = 10,
+  pollSeconds = 30,
+  ssmWaitMs = 90_000,
+  kind,
+  name,
+  waiterRunId = process.env[RUN_ID_ENV],
+  request = devRequest,
+  aws = awsCli(),
+  readScript = (path) => readFile(path, "utf8"),
+  sleep = sleepFor,
+  now = Date.now,
+  stdoutWrite = (value) => process.stdout.write(value),
+  stderrWrite = (value) => process.stderr.write(value),
+} = {}) {
+  const waiter = currentRunId(waiterRunId);
+  if (!waiter)
+    throw new CliError("RUN_CONTEXT_REQUIRED", `nodii-dev run needs ${RUN_ID_ENV}, supplied by the harness launcher for the current waiter run.`, 2);
+  if (typeof instance !== "string" || !INSTANCE.test(instance))
+    throw new CliError("USAGE", "run --remote-ssm needs an instance id (i-… or mi-…).", 2);
+  if (typeof script !== "string" || !script)
+    throw new CliError("USAGE", "run --remote-ssm INSTANCE SCRIPT needs a local script file.", 2);
+  for (const [flag, value] of [["quiet-minutes", quietMinutes], ["poll-seconds", pollSeconds]])
+    if (!Number.isFinite(value) || value <= 0) throw new CliError("USAGE", `run --${flag} needs a positive number.`, 2);
+  if (artifact !== undefined && (typeof artifact !== "string" || !artifact))
+    throw new CliError("USAGE", "run --artifact needs a path on the instance.", 2);
+  let body;
+  try {
+    body = await readScript(script);
+  } catch (error) {
+    throw new CliError("USAGE", `Cannot read script ${script}: ${error?.code ?? error?.message}.`, 2);
+  }
+  if (!body.trim()) throw new CliError("USAGE", `Script ${script} is empty.`, 2);
+  if (Buffer.byteLength(body) > SCRIPT_MAX_BYTES)
+    throw new CliError("SCRIPT_TOO_LARGE", `Script ${script} is over ${SCRIPT_MAX_BYTES / 1024} KB; copy larger code to the instance and run a short script that calls it.`, 2);
+  const selectedKind = runKind(kind);
+  const label = redactRunText(String(name ?? `ssm ${instance} ${basename(script)}`)).trim().slice(0, 300);
+  const quietMs = quietMinutes * 60_000;
+  const registered = await request("POST", "/api/v1/runs", {
+    kind: selectedKind,
+    name: label,
+    externalRef: `ssm:${instance}`,
+    waiterRunId: waiter,
+    // A poll is an SSM round trip; Dev's watchdog allows a few of them.
+    expectedHeartbeatSeconds: Math.ceil(pollSeconds * 3 + 120),
+    metadata: { executable: "aws ssm", instance, script: basename(script), quietMinutes, ...(artifact ? { artifact } : {}) },
+  });
+  const runId = registered.data?.id;
+  if (!runId) throw new CliError("RUN_REGISTER_INVALID", "Dev registered a run without an id.", 1);
+
+  const ssm = (commands, what) => ssmShell(aws, instance, commands, { comment: `nodii-dev run ${runId} ${what}`, waitMs: ssmWaitMs, sleep, now });
+  const commandIds = [];
+  let tail = "";
+  const evidence = (exitCode, extra = []) => [
+    { kind: "command", ref: `ssm:${instance} ${basename(script)}` },
+    { kind: "remote", ref: `${instance}:${remoteDir(runId)}`, ...(commandIds.length ? { note: `SSM command ${commandIds[0]}` } : {}) },
+    { kind: "exit_code", ref: String(exitCode ?? -1) },
+    { kind: "log_tail", ref: "remote combined stdout/stderr", note: redactRunText(tail) || "(no output)" },
+    ...extra,
+  ];
+  const finish = async (status, exitCode, reason, extra = []) => {
+    await endRun(request, runId, status === "done"
+      ? { status, evidence: evidence(exitCode, extra) }
+      : { status, reason, evidence: evidence(exitCode, extra) });
+    if (reason) stderrWrite(`nodii-dev run: ${reason}\n`);
+    return { runId, exitCode: status === "done" ? 0 : exitCode || 1, reason: reason ?? null, tail: redactRunText(tail) };
+  };
+
+  try {
+    commandIds.push((await ssm(startCommand(runId, body), "start")).commandId);
+  } catch (error) {
+    return finish("failed", 1, `Remote script could not start on ${instance}: ${redactRunText(error?.message ?? error)}`);
+  }
+  stderrWrite(`nodii-dev run ${runId}: started on ${instance} (${remoteDir(runId)}); polling every ${pollSeconds} s, failing after ${minutes(quietMs)} without new output.\n`);
+
+  let size = 0;
+  let lastProgress = now();
+  let lastError = null;
+  let exited = null;
+  while (!exited) {
+    await sleep(pollSeconds * 1000);
+    let poll = null;
+    try {
+      poll = parsePoll((await ssm(pollCommand(runId), "poll")).stdout);
+      lastError = null;
+    } catch (error) {
+      lastError = redactRunText(error?.message ?? error);
+    }
+    if (poll) {
+      if (poll.size !== size) {
+        const added = poll.size - size;
+        const fresh = added > 0 && added <= Buffer.byteLength(poll.tail) ? Buffer.from(poll.tail).subarray(-added).toString("utf8") : poll.tail;
+        if (fresh) stdoutWrite(fresh);
+        size = poll.size;
+        lastProgress = now();
+      }
+      tail = poll.tail;
+      if (poll.state === "exited") {
+        exited = poll;
+        break;
+      }
+      if (poll.state === "vanished" || poll.state === "missing")
+        return finish("failed", 1, poll.state === "missing"
+          ? `Remote run directory ${remoteDir(runId)} is gone from ${instance} (the instance was replaced or cleaned).`
+          : `Remote script on ${instance} stopped without an exit code (killed, or the instance restarted).`);
+    }
+    if (now() - lastProgress >= quietMs) {
+      await ssm(cancelCommand(runId), "cancel").catch(() => {});
+      return finish("failed", 1, `Remote script on ${instance} went quiet: no new output for ${minutes(quietMs)}${lastError ? ` (last SSM error: ${lastError})` : ""}; it was cancelled.`);
+    }
+    try {
+      await request("POST", `/api/v1/runs/${encode(runId)}/heartbeat`, { note: lastError ? `ssm ${instance}: no answer (${lastError})` : `ssm ${instance}: running, log ${size} bytes` });
+    } catch (error) {
+      stderrWrite(`nodii-dev run heartbeat failed (${redactRunText(error?.code ?? error?.message ?? "error")}); retrying.\n`);
+    }
+    if (poll === null && lastError) stderrWrite(`nodii-dev run: no answer from ${instance} (${lastError}); retrying.\n`);
+  }
+
+  const { exitCode } = exited;
+  if (exitCode !== 0) return finish("failed", exitCode, `Remote script exited with code ${exitCode}.`);
+  if (!artifact) return finish("done", 0);
+  try {
+    const { stdout } = await ssm(artifactCommand(runId, artifact), "artifact");
+    if (stdout.trim() === "missing") throw new CliError("ARTIFACT_MISSING", `${artifact} does not exist on ${instance}.`, 1);
+    const [bytesLine, ...encoded] = stdout.split("\n");
+    const content = Buffer.from(encoded.join("").trim(), "base64").toString("utf8");
+    if (Buffer.byteLength(content) !== Number(bytesLine.replace("bytes=", "")))
+      throw new CliError("ARTIFACT_TRUNCATED", `${artifact} (${bytesLine.replace("bytes=", "")} bytes) arrived incomplete: SSM returns at most 24,000 characters of base64, and a Result carries at most 10,000 characters.`, 1);
+    return finish("done", 0, undefined, [artifactEvidence(artifact, content)]);
+  } catch (error) {
+    return finish("failed", 1, `Artifact not attached: ${redactRunText(error?.message ?? error)}`);
+  }
+}

package/dist/runs.js

@@ -1,4 +1,6 @@
 import { spawn as nodeSpawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
 import { basename } from "node:path";
 import { CliError, devRequest, encode } from "./core.js";
 
@@ -36,7 +38,7 @@ function writeSafe(write, value) {
   }
 }
 
-function currentRunId(runId = process.env[RUN_ID_ENV]) {
+export function currentRunId(runId = process.env[RUN_ID_ENV]) {
   if (runId === undefined || runId === "") return null;
   if (!UUID.test(runId))
     throw new CliError(
@@ -113,7 +115,7 @@ function commandLabel(command) {
   return basename(command[0] ?? "command").slice(0, 240) || "command";
 }
 
-function runKind(value) {
+export function runKind(value) {
   const kind = value ?? "build";
   if (!RUN_KINDS.has(kind))
     throw new CliError(
@@ -138,7 +140,7 @@ function runEvidence(command, exitCode, signal, tail) {
   return evidence;
 }
 
-async function endRun(request, runId, body, attempts = 3) {
+export async function endRun(request, runId, body, attempts = 3) {
   let error;
   for (let attempt = 0; attempt < attempts; attempt++) {
     try {
@@ -152,6 +154,25 @@ async function endRun(request, runId, body, attempts = 3) {
   throw error;
 }
 
+// The Result artifact contract (AGENT-HARNESS-41): a run that succeeds can
+// attach one text artifact (e.g. a benchmark table as JSON). It rides in the
+// Result as an `artifact` evidence item, delivered whole to the waiter: the
+// note is the content, the ref names it with its size and sha256. Dev holds at
+// most 10,000 characters in a note, so a larger artifact fails the run rather
+// than arriving cut.
+export const ARTIFACT_MAX_CHARS = 10_000;
+
+export function artifactEvidence(name, content) {
+  const text = redactRunText(content);
+  if (!text.trim()) throw new CliError("ARTIFACT_EMPTY", `Artifact ${basename(name)} is empty.`, 1);
+  if (text.length > ARTIFACT_MAX_CHARS)
+    throw new CliError("ARTIFACT_TOO_LARGE", `Artifact ${basename(name)} is ${text.length} characters; a Result carries at most ${ARTIFACT_MAX_CHARS}.`, 1);
+  const sha256 = createHash("sha256").update(text).digest("hex");
+  return { kind: "artifact", ref: `${basename(name)} · ${Buffer.byteLength(text)} bytes · sha256:${sha256}`, note: text };
+}
+
+const artifactFailure = (error) => `Artifact not attached: ${redactRunText(error?.code === "ENOENT" ? "the file does not exist" : error?.message ?? error)}`;
+
 export async function superviseRun({
   command,
   waiterRunId = process.env[RUN_ID_ENV],
@@ -160,6 +181,8 @@ export async function superviseRun({
   expectedHeartbeatSeconds = 60,
   heartbeatIntervalMs = DEFAULT_HEARTBEAT_MS,
   tailBytes = DEFAULT_TAIL_BYTES,
+  artifact,
+  readArtifact = (path) => readFile(path, "utf8"),
   request = devRequest,
   spawn = nodeSpawn,
   stdoutWrite = (value) => process.stdout.write(value),
@@ -268,12 +291,21 @@ export async function superviseRun({
       outcome.signal,
       tail,
     );
-    const succeeded = outcome.exitCode === 0 && !outcome.signal && !spawnError;
-    const reason = spawnError
+    let succeeded = outcome.exitCode === 0 && !outcome.signal && !spawnError;
+    let artifactError = null;
+    if (succeeded && artifact) {
+      try {
+        evidence.push(artifactEvidence(artifact, await readArtifact(artifact)));
+      } catch (error) {
+        succeeded = false;
+        artifactError = artifactFailure(error);
+      }
+    }
+    const reason = artifactError ?? (spawnError
       ? `Command could not start: ${redactRunText(spawnError.code ?? spawnError.message)}`
       : outcome.signal
         ? `Command ended by signal ${outcome.signal}`
-        : `Command exited with code ${outcome.exitCode ?? -1}`;
+        : `Command exited with code ${outcome.exitCode ?? -1}`);
     await endRun(
       request,
       runId,
@@ -283,7 +315,7 @@ export async function superviseRun({
     );
     return {
       runId,
-      exitCode: succeeded ? 0 : (outcome.exitCode ?? 1),
+      exitCode: succeeded ? 0 : (outcome.exitCode || 1),
       signal: outcome.signal,
       tail: redactRunText(tail.toString("utf8")),
     };
@@ -302,6 +334,7 @@ export async function launchRunSupervisor(
     env = process.env,
     kind,
     name,
+    artifact,
   } = {},
 ) {
   if (!entrypoint)
@@ -309,6 +342,7 @@ export async function launchRunSupervisor(
   const args = [entrypoint, "__run-supervisor"];
   if (kind) args.push("--kind", kind);
   if (name) args.push("--name", name);
+  if (artifact) args.push("--artifact", artifact);
   args.push("--", ...command);
   const supervisor = spawn(process.execPath, args, {
     detached: true,

package/dist/starting.js

@@ -5,7 +5,7 @@ import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { CliError, configPath, devRequest, encode, query, readConfig, requireFlag } from "./core.js";
 import { assertKnownSets, checkComponentSetKey, checkFileKey, loadDsCatalog, mergeScopes, scopesFromRoutes } from "./figma-scope.js";
-import { GATHER_TIMEOUT_MS } from "./gather.js";
+import { GATHER_TIMEOUT_MS, gatherDeadline } from "./gather.js";
 import { laneCommand, nextCommand } from "./lanes.js";
 
 const execFile = promisify(execFileCallback);
@@ -346,6 +346,19 @@ export async function launchLaneCommand(key, flags, {
   } catch (error) {
     throw new CliError(error?.code ?? "LANE_REGISTER_FAILED", `${error?.message ?? error}. Worktrees were created and were not removed; reconcile them before retrying.`, 1);
   }
+  // An agent is dispatched only onto a lane whose start Dev recorded: building,
+  // with its first steps current (LANE-RECORD-GAP-APPLY-VERDICTS-1).
+  const status = payload.data?.lane?.status;
+  if (status !== "building") {
+    const reason = `Dev registered lane ${key} as ${status ?? "unknown"}, not started (no lane start recorded)`;
+    let reported = "Dev recorded it for lane resume";
+    try {
+      await request("POST", `/api/v1/lanes/${encode(payload.data.lane.id)}/resume/${encode(payload.data.run.id)}/launch-failed`, { reason, ...via });
+    } catch (reportError) {
+      reported = `Dev could not record the launch failure (${reportError.message})`;
+    }
+    throw new CliError("LANE_NOT_STARTED", `${reason}, so its agent was not dispatched; ${reported}. Worktrees were created and were not removed.`, 1);
+  }
   await markers(repositories, { laneKey: key, laneId: payload.data.lane.id, runId: payload.data.run.id });
   try {
     await launcher({
@@ -415,31 +428,31 @@ export async function amendmentGuard(argv, { request = devRequest, marker = curr
 // Gather's human output is a renderer of its payload; Delta gather prints the
 // Clause map too, never only "Gather complete.".
 
-const runGather = (key, flags, { request, signal }) => laneCommand("gather", [key], flags, { request, gatherSignal: signal });
+const runGather = (key, flags, { request, deadline }) => laneCommand("gather", [key], flags, { request, deadline });
 
 // Gather's human text is its Clause map (a function of the payload).
 const gatheredText = (gathered) => typeof gathered.human === "function" ? gathered.human(gathered.payload) : gathered.human ?? "Gather complete.";
 
 export async function gatherLaneCommand(key, flags, { request = devRequest, marker = currentMarker, gather = runGather, acknowledge = nextCommand, gatherTimeoutMs = GATHER_TIMEOUT_MS } = {}) {
-  const controller = new AbortController();
-  const deadline = setTimeout(() => controller.abort(), gatherTimeoutMs);
-  const signal = controller.signal;
+  // The lane's local pick holds this deadline while it runs on its own budget.
+  const deadline = gatherDeadline(gatherTimeoutMs);
+  const signal = deadline.signal;
   const timedRequest = (method, path, body, options = {}) => withSignal(request(method, path, body, { ...options, signal }), signal);
   try {
     const lane = await withSignal(marker(), signal);
     key ??= lane?.laneKey;
     if (!key) throw new CliError("USAGE", "lane gather needs <key> outside a launched lane worktree.", 2);
-    if (!flags.delta) return await withSignal(gather(key, flags, { request: timedRequest, signal }), signal);
+    if (!flags.delta) return await withSignal(gather(key, flags, { request: timedRequest, deadline }), signal);
     if (lane && lane.laneKey !== key) throw new CliError("LANE_RUN_REQUIRED", "Delta gather for another lane cannot run inside this lane's registered worktree.", 1);
-    if (!lane) return await withSignal(gather(key, flags, { request: timedRequest, signal }), signal);
+    if (!lane) return await withSignal(gather(key, flags, { request: timedRequest, deadline }), signal);
     const pending = await timedRequest("GET", `/api/v1/lanes/${encode(key)}/amendments${query({ runId: lane.runId })}`);
     if (!pending.data.length) {
-      const gathered = await withSignal(gather(key, flags, { request: timedRequest, signal }), signal);
+      const gathered = await withSignal(gather(key, flags, { request: timedRequest, deadline }), signal);
       if (gathered.payload?.data?.recorded === false) return gathered;
       return { ...gathered, human: `${gatheredText(gathered)}\nNo pending amendments.` };
     }
     const version = Math.max(...pending.data.map((item) => item.version));
-    const gathered = await withSignal(gather(key, flags, { request: timedRequest, signal }), signal);
+    const gathered = await withSignal(gather(key, flags, { request: timedRequest, deadline }), signal);
     // An agent picker's shortlist step records nothing, so it acknowledges nothing.
     if (gathered.payload?.data?.recorded === false) return gathered;
     const acknowledgement = await withSignal(acknowledge(key, {
@@ -454,9 +467,9 @@ export async function gatherLaneCommand(key, flags, { request = devRequest, mark
       human: `${pending.data.map((item) => `v${item.version} ${item.reason}: ${JSON.stringify(item.change)}`).join("\n")}\n${gatheredText(gathered)}\nAcknowledged amendment version ${version}.`,
     };
   } catch (error) {
-    if (signal.aborted) throw new CliError("GATHER_TIMEOUT", `Gather exceeded its ${Math.round(gatherTimeoutMs / 1000)}-second deadline; nothing was retried.`, 1);
+    if (signal.aborted) throw new CliError("GATHER_TIMEOUT", `Gather's Dev requests exceeded their ${Math.round(gatherTimeoutMs / 1000)}-second deadline (the local pick runs on its own budget); nothing was retried.`, 1);
     throw error;
   } finally {
-    clearTimeout(deadline);
+    deadline.clear();
   }
 }

package/dist/upload.js

@@ -169,9 +169,12 @@ const uploadBody = (docs, cls, flags, decision) => ({
     ...(flags["meaning-unchanged"] && cls === "editorial" ? { meaningUnchangedReason: String(flags["meaning-unchanged"]) } : {}),
   })),
   ...(decision ? { decision } : {}),
-  ...(flags.pending ? { pending: true } : {}),
 });
 
+// Dev locks a ruling's decision as its change lands (DEV-DEC-AS-COMMIT-1,
+// hub #406); there is no pending decision to draft any more.
+export const PENDING_NO_OP = "--pending does nothing now: decisions lock on upload.";
+
 export async function docsCommand(action, args, flags, { request = devRequest, log = console.error, cwd = process.cwd(), waitInterval } = {}) {
   const json = Boolean(flags.json);
   if (action === "check") {
@@ -193,6 +196,7 @@ export async function docsCommand(action, args, flags, { request = devRequest, l
       throw new CliError("USAGE", "--pending is valid only with docs upload.", 2);
     if (flags.pending && cls !== "ruling")
       throw new CliError("USAGE", "--pending requires --class ruling and --decision FILE.", 2);
+    if (flags.pending) log(PENDING_NO_OP);
     const decision = await readJsonFile(flags.decision, "decision");
     if (cls === "ruling" && !decision) throw new CliError("RULING_NEEDS_DECISION", "A ruling write needs its decision: --decision DECISION.json (title, context, options, ruling, consequences, provenance, amends).", 2);
     if (cls !== "ruling" && decision) throw new CliError("DECISION_NEEDS_RULING", "--decision goes with --class ruling only.", 2);
@@ -317,6 +321,15 @@ export async function rulesCommand(action, args, flags, { request = devRequest }
     const payload = await request("GET", `/api/v1/rules/find${query({ question, limit })}`);
     return { payload, human: rulesFindText };
   }
+  if (action === "show") {
+    const id = args[0]?.trim();
+    if (!id) throw new CliError("USAGE", "rules show needs a clause id, for example: nodii-dev rules show S04-7", 2);
+    const payload = await request("GET", `/api/v1/rules/clauses/${encode(id)}`);
+    return {
+      payload,
+      human: (p) => p.data.map((c) => `${c.clauseId}${c.counterInstinct ? " ⚑" : ""} · ${c.documentCode}@${c.documentVersion} › ${c.section}\n${c.text}`).join("\n\n"),
+    };
+  }
   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");
@@ -347,5 +360,5 @@ export async function rulesCommand(action, args, flags, { request = devRequest }
     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 find "QUESTION" [--limit N] | rules core | rules report [--section rulebook|services|all] [--lane KEY] | rules cap TOKENS', 2);
+  throw new CliError("USAGE", 'rules find "QUESTION" [--limit N] | rules show CLAUSE_ID | 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.34",
+  "version": "0.6.36",
   "description": "Agent CLI for Nodii Dev, reached through the platform edge",
   "type": "module",
   "bin": {