@outerlayer/cli 0.19.1 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @outerlayer/cli
 
+## 0.20.0
+
+### Minor Changes
+
+- 89270e0: `outerlayer emit criteria` reads an acceptance file ending in `.md`, so a person can record or replace an item's criteria from the file a build committed.
+- bf0bf30: `outerlayer work stop --item <n>` asks the host building an item to stop. The runner reports what it is doing, so an item can say why nothing is building it.
+
 ## 0.19.1
 
 ### Patch Changes

package/README.md

@@ -91,8 +91,10 @@ content:
   work item's general thread or a criterion thread — the detected session id
   rides along the same way it does for `emit`, only ever narrowing what the
   comment may do; `outerlayer work threads` reads them back. `outerlayer work logs`
-  reads the runner's log for a host attempt. A runner key
-  needs `git.read` and `work.read` to
+  reads the runner's log for a host attempt. `outerlayer work stop` sends
+  `POST /v1/work-items/<n>/claim/stop` with the optional note, and the
+  gateway records the request against the item's live host build. A runner
+  key needs `git.read` and `work.read` to
   list and read items, and `work.claim` to claim, renew or release — `work.claim`
   is not granted to a dashboard role by default, since a claim is a host's
   lease, not a person's.
@@ -118,6 +120,12 @@ content:
   off for want of disk it adds the free and needed bytes. While a check of
   its own stops it claiming, it adds one sentence saying why, which can
   include the host's usable memory and Docker's own error text, unscrubbed.
+  Every heartbeat also says what the runner is doing about new work (taking
+  work, draining, restarting, holding for an update, blocked or low on
+  disk), the queues and repository patterns it takes, and, while draining,
+  the numbers of the items it waits on. The reply can name a build that
+  someone stopped with `outerlayer work stop`; the runner then ends that
+  build and releases it as stopped, with the name of whoever stopped it.
   When a build's command exits 0, it reads that work item once more, for its
   evidence verdict, before releasing it: it sends nothing but the request.
   Just before that read, the runner runs the repository's host checks. A host
@@ -408,6 +416,7 @@ before it gives up.
 | `outerlayer emit artifact <file> --caption <text> [--for <criterion-id>] [--pr <n>]` | Upload a proof artifact — screenshot, recording, report, or log — with its caption. Inside a recorded session it spools locally and ships on the next `sync`; otherwise it uploads immediately, anchored to a pull request or the current checkout. `--replaces` retires artifacts an earlier run uploaded. A JUnit XML file bound with `--for` proves a criterion that declares `test` proof; `--test <name[=path:line]>` binds only the named tests. |
 | `outerlayer emit <name> --result <pass\|fail> [--link <url>] [--body <text>\|--body-file <path>] --item <number>` | Record one named check's outcome on a work item. A check that ran carries the run URL as its proof (`--link`); a judgment you are making yourself carries one sentence (`--body`, or `--body-file` to read it from a file — `-` reads standard input). A `fail` needs at least one of the two; a `pass` needs neither. `--item` names the work item by the number printed when the item was created — always required, in or out of a recorded session; a session records checks on its own item like any other, stored as the session's, but cannot clear a person's fail. Prints the recorded check's id. Who recorded it comes from your API key, never from what you send. |
 | `outerlayer work comment --item <n> [--criterion <id>] --body <text> [--artifact <id>] [--pass\|--fail\|--attach\|--ready]` | Post one comment on a work item's general thread, or on one acceptance criterion's own thread with `--criterion`. `--pass`/`--fail` need a person's own credential and apply to the whole item, so they work on the general thread only and the gateway refuses them with `--criterion`; `--attach` makes the named artifact that criterion's current proof; `--ready` hands a thread back to a person. The detected session id rides along automatically, only ever narrowing what the comment may do. |
+| `outerlayer work stop --item <n> [--note <text>]` | Ask the host that holds the item's build to end it. The host reads the request at its next heartbeat and ends the build with outcome `stopped`, so the build may run a little longer. The item is not built again until a new build request. Needs `work.update`. Exits 1 when no host build is running for the item. |
 | `outerlayer work logs --item <n> [--attempt <claim id>]` | Print the runner's log for a host attempt on a work item: the newest attempt a runner made, or the one `--attempt` names (an `id` from `claims` in `work status --json`). The log is what the runner did around the agent, with secrets removed on the host. Exits 1 for an attempt that is still running or that an older runner released without a log. |
 | `outerlayer work threads --item <n>` | Read a work item's threads back — the general thread first, then one per criterion with proof or a comment, each with its `waitingOn`. |
 | `outerlayer emit finding --id <id> --category <context\|flaky-test\|tooling\|environment\|defect\|other> --title <text> --file <path> --where <label> [--line <n>] [--item <number>] [--cause <text>] [--detail <text>] [--suggestion <text>] [--command <text>] [--error <text>] [--test <name>] [--symbol <name>] [--started-at <event> --ended-at <event>] [--problem <id> … --link-reason <text> \| --new] …` | Record one problem you hit in the factory. `--category` is one of `context` (an instruction that is wrong, broken or missing), `flaky-test`, `tooling`, `environment`, `defect` (a bug outside your own change) or `other`. A `context` finding also needs `--rule-path` and `--rule-relation` (`wrong`, `broken` or `missing`), and `--rule-quote` unless the relation is `missing`. `--cause`, `--detail`, `--suggestion`, `--command`, `--error` (the first error line), `--test` and `--symbol` carry what a fix needs. Every finding joins a factory-level problem: when a key of the finding matches a known problem it joins that problem; otherwise nothing is stored, the closest problems are printed, and the command exits with code 3. Run it again with `--problem <id> --link-reason <text>` (repeat `--problem` for each problem the finding reports) or with `--new`. Without `--started-at`, it prints the session's recent events with ids and times; name the event where you hit the problem and the one where you got past it with `--started-at` and `--ended-at`. Findings are informational; nothing reads one to pass or fail the work. `--item` names the work item; without it, inside a recorded session, the item that session was launched for is used automatically. Re-emitting the same `--id` on the item replaces that finding and keeps its problems. |

package/dist/build-info.json

@@ -1 +1 @@
-{"id":"2026-10-13T20:24:21.442Z+3c40b5d","root":"/home/runner/_work/outerlayer/outerlayer","pkg":"outerlayer"}
+{"id":"2026-10-14T00:32:09.011Z+25b1e13","root":"/home/runner/_work/outerlayer/outerlayer","pkg":"outerlayer"}

package/dist/{check-W2JGXN3B.js → check-BR5D27CX.js}

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
-import { probeCredentials } from './chunk-F2KXHIFI.js';
+import { probeCredentials } from './chunk-AD3EYI7P.js';
 import './chunk-B6SCN5NY.js';
+import './chunk-SADUQSO4.js';
 import './chunk-MTP2QEVO.js';
 import './chunk-S5PCA3SN.js';
 import './chunk-3JVYMD4G.js';
 import './chunk-YETTWTAY.js';
-import './chunk-SADUQSO4.js';
 import './chunk-I2UOAV7X.js';
-import './chunk-BWSUPRDK.js';
+import './chunk-ZX4I2MEK.js';
 import './chunk-JHGEBPLE.js';
 import './chunk-XNGMQ27R.js';
 import './chunk-R22NZSGA.js';

package/dist/{chunk-F2KXHIFI.js → chunk-AD3EYI7P.js}

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
 import { LEASE_SECONDS, releaseLease, isUnfinished, setStage, jobEnv, runHook, describeHookEnd, provisionMicroVm, deliverCommitHooks, provisionProcess, provisionEnvironment, readProvisionOut, resolveHostBuild, workdirProblem, listenOnBroker, hostEnvironment, hostCommandEnvironment, execArgv, microVmCommandLine, runCommand, execCommandLine, startSender, startHostServices, finishJob, isGroupAlive, outcomeFromExitCode, isTimedOut, readCpuUsec, isIdle, stopOrphanedMicroVms, unfinishedJobs, listAdoptableJobs, retryFailedReleases, recoverLostJobs, hookLimitsFor, AttemptLogBook, needsRenew, renewLease, RENEW_INTERVAL_SECONDS, ALREADY_RELEASED } from './chunk-B6SCN5NY.js';
+import { writeJobFile, readJobFile, readJobFileChecked } from './chunk-SADUQSO4.js';
 import { writePendingUpdate } from './chunk-MTP2QEVO.js';
 import { readHousekeepingRecord, writeHousekeepingRecord } from './chunk-S5PCA3SN.js';
 import { decideInstalledSwitch } from './chunk-3JVYMD4G.js';
 import { fetchVersionMeta, npmVersion, npmSupportsProvenance, fetchTarballDigest, fetchProvenance, installVersion, auditSignatures } from './chunk-YETTWTAY.js';
-import { writeJobFile, readJobFile, readJobFileChecked } from './chunk-SADUQSO4.js';
 import { compareVersions, satisfiesRange } from './chunk-I2UOAV7X.js';
-import { RUNNER_PROTOCOL } from './chunk-BWSUPRDK.js';
+import { RUNNER_PROTOCOL } from './chunk-ZX4I2MEK.js';
 import { currentSkillCommand, formerSkillProblem, placeholderQueues, placeholderProblem } from './chunk-GEMQLBMW.js';
 import { freeBytes, formatBytes } from './chunk-YYYRBYWG.js';
 import { writeMarker, readMarker, currentVersion, removeMarker, entryIn, versionDir, startedThroughCurrent, switchCurrent, cleanVersions, isInLayout, stagingDir } from './chunk-AMFWYESY.js';
@@ -85,6 +85,9 @@ var HEARTBEAT_TIMEOUT_MS = 1e4;
 var ERROR_CODE_MAX = 100;
 var ERROR_MESSAGE_MAX = 500;
 var BLOCKED_REASON_MAX = 500;
+var TAKES_PATTERNS_MAX = 50;
+var TAKES_PATTERN_CHARS_MAX = 200;
+var WAITING_ITEMS_MAX = 200;
 var UNREACHABLE_MESSAGE = "the request did not reach the platform";
 function noPlatformMessage(status) {
   return `the request got HTTP ${status} with no error message from the platform`;
@@ -112,6 +115,35 @@ function workRequestFromFailure(err) {
 function workRequestFromRetryFailure(outcome) {
   return shapeWorkRequestFailure(outcome.code, outcome.status, outcome.message);
 }
+function stopsOf(data) {
+  const raw = data?.stops;
+  if (!Array.isArray(raw)) return [];
+  const stops = [];
+  for (const entry of raw) {
+    const stop = entry;
+    if (stop === null || typeof stop !== "object" || typeof stop.claimId !== "string") continue;
+    stops.push({
+      claimId: stop.claimId,
+      requestedByName: typeof stop.requestedByName === "string" ? stop.requestedByName : "",
+      note: typeof stop.note === "string" && stop.note !== "" ? stop.note : null
+    });
+  }
+  return stops;
+}
+function takesBody(takes) {
+  let truncated = false;
+  const list = (patterns) => {
+    const all = (patterns ?? []).filter((pattern) => typeof pattern === "string");
+    if (all.length > TAKES_PATTERNS_MAX) truncated = true;
+    return all.slice(0, TAKES_PATTERNS_MAX).map((pattern) => {
+      if (pattern.length > TAKES_PATTERN_CHARS_MAX) truncated = true;
+      return cutForGateway(pattern, TAKES_PATTERN_CHARS_MAX);
+    }).filter((pattern) => pattern !== "");
+  };
+  const include = list(takes.repos.include);
+  const exclude = list(takes.repos.exclude);
+  return { queues: takes.queues, repos: { include, exclude }, truncated };
+}
 async function sendHeartbeat(args, fetchImpl) {
   const body = {
     host: args.host,
@@ -132,7 +164,10 @@ async function sendHeartbeat(args, fetchImpl) {
     // Free disk on the runner's file system, in bytes. Sent only while held, so a host with room sends nothing about its disk.
     lowDisk: args.lowDisk === void 0 ? void 0 : { free: args.lowDisk.free, needed: args.lowDisk.needed },
     // Why the runner claims nothing. Sent only while it holds, so a runner that takes work says nothing about it.
-    blocked: args.blocked === void 0 ? void 0 : { reason: cutForGateway(args.blocked.reason, BLOCKED_REASON_MAX) }
+    blocked: args.blocked === void 0 ? void 0 : { reason: cutForGateway(args.blocked.reason, BLOCKED_REASON_MAX) },
+    state: args.state,
+    waitingItems: args.waitingItems === void 0 ? void 0 : args.waitingItems.slice(0, WAITING_ITEMS_MAX),
+    takes: args.takes === void 0 ? void 0 : takesBody(args.takes)
   };
   try {
     const response = await postJson(
@@ -146,11 +181,22 @@ async function sendHeartbeat(args, fetchImpl) {
       await signerFor(args.configPath)
     );
     const runnerVersion = response.data?.runnerVersion;
-    return typeof runnerVersion === "string" ? { ok: true, runnerVersion } : { ok: true };
+    const stops = stopsOf(response.data);
+    return typeof runnerVersion === "string" ? { ok: true, runnerVersion, stops } : { ok: true, stops };
   } catch (err) {
     return { ok: false, reason: describeCallFailure(err) };
   }
 }
+
+// src/runner/host-state.ts
+function hostState(flags) {
+  if (flags.draining) return "draining";
+  if (flags.restarting) return "restarting";
+  if (flags.holdingForUpdate) return "holding-for-update";
+  if (flags.blocked) return "blocked";
+  if (flags.lowDisk) return "low-disk";
+  return "taking-work";
+}
 var OUTCOMES = ["updated", "rolled_back", "verification_failed", "not_published", "retrying"];
 function lastUpdatePath(configPath) {
   return join(runnerDir(configPath), "last-update.json");
@@ -1042,6 +1088,7 @@ async function sendTickHeartbeat(state, workRequest) {
     let next = workRequest;
     for (; ; ) {
       reportRepeating(state, "the heartbeat's previous call", void 0, "line");
+      const waitingItems = state.draining === true ? runningItems(state) : [];
       const result = await sendHeartbeat(
         {
           configPath: state.config.configPath,
@@ -1056,12 +1103,25 @@ async function sendTickHeartbeat(state, workRequest) {
           workRequest: next,
           lastUpdate: readLastUpdate(state.config.configPath),
           lowDisk: state.lowDisk,
-          blocked: state.blocked
+          blocked: state.blocked,
+          state: hostState({
+            draining: state.draining === true,
+            restarting: state.restarting === true,
+            holdingForUpdate: state.holdingForUpdate === true,
+            blocked: state.blocked !== void 0,
+            lowDisk: state.lowDisk !== void 0
+          }),
+          // Left out unless a draining runner has builds to wait on, so the gateway stores null.
+          waitingItems: waitingItems.length > 0 ? waitingItems : void 0,
+          takes: { queues: state.config.queues, repos: { include: state.config.repos?.include, exclude: state.config.repos?.exclude } }
         },
         state.deps.fetchImpl
       );
       reportRepeating(state, "the heartbeat", result.ok ? void 0 : `heartbeat failed: ${result.reason}`);
-      if (result.ok) considerNamedVersion(state, result.runnerVersion);
+      if (result.ok) {
+        considerNamedVersion(state, result.runnerVersion);
+        applyStops(state, result.stops);
+      }
       next = state.queuedWorkRequest;
       state.queuedWorkRequest = void 0;
       if (next === void 0) break;
@@ -1070,6 +1130,27 @@ async function sendTickHeartbeat(state, workRequest) {
     state.heartbeating = false;
   }
 }
+function applyStops(state, stops) {
+  for (const stop of stops) {
+    const held = [...state.jobs.values()].find((entry) => entry.job.claimId === stop.claimId);
+    const active = held !== void 0 && !held.ending ? held : void 0;
+    if (active === void 0) {
+      reportRepeating(
+        state,
+        `stop of claim ${stop.claimId}`,
+        held === void 0 ? `ignoring a stop for claim ${stop.claimId}: this runner holds no build under that claim` : `#${held.job.item} a stop was asked for; the build is already ending`,
+        "line"
+      );
+      continue;
+    }
+    const who = `stopped by ${stop.requestedByName === "" ? "someone" : stop.requestedByName} through OuterLayer`;
+    const reason = stop.note === null ? who : `${who}: ${stop.note}`;
+    logOf(state).line(`#${active.job.item} ${reason} \xB7 ending the build`);
+    void endJob(state, active, "stopped", { reason }).catch((err) => {
+      logOf(state).error(`#${active.job.item} could not be stopped: ${describeCallFailure(err)}`);
+    });
+  }
+}
 function ownVersionOf(deps) {
   return (deps.cliVersion ?? resolveVersion()).split(" ")[0] ?? "";
 }
@@ -1405,9 +1486,17 @@ async function housekeepingPass(state) {
   }
 }
 async function runTick(state) {
+  state.restarting = false;
+  state.holdingForUpdate = false;
   reloadConfig(state);
-  if (restartOntoInstalled(state)) return;
-  if (await updateWhenIdle(state)) return;
+  if (restartOntoInstalled(state)) {
+    state.restarting = true;
+    return;
+  }
+  if (await updateWhenIdle(state)) {
+    state.holdingForUpdate = true;
+    return;
+  }
   if (holdWhenBlocked(state)) return;
   if (holdOffForDisk(state)) return;
   const log = logOf(state);
@@ -2226,7 +2315,7 @@ async function start(configPath, deps = { fetchImpl: fetch }) {
     const outcome = await onStartUnderMarker({
       configPath,
       own: ownVersionOf(deps),
-      check: update.check ? () => update.check(configPath) : async () => (await import('./check-W2JGXN3B.js')).runRunnerCheck(configPath, { fetchImpl: deps.fetchImpl }),
+      check: update.check ? () => update.check(configPath) : async () => (await import('./check-BR5D27CX.js')).runRunnerCheck(configPath, { fetchImpl: deps.fetchImpl }),
       now: () => (deps.now ?? (() => /* @__PURE__ */ new Date()))().getTime(),
       log
     });
@@ -2312,12 +2401,11 @@ async function start(configPath, deps = { fetchImpl: fetch }) {
   }
   let intakeClosed = false;
   let closed = false;
-  let draining = false;
   let stopping = false;
   let exited = false;
   let interrupts = 0;
   state.pollTimerSeconds = state.config.pollSeconds;
-  const pollTimer = setInterval(() => void tick(state), state.pollTimerSeconds * 1e3);
+  let pollTimer = setInterval(() => void tick(state), state.pollTimerSeconds * 1e3);
   const hooksKind = builtinKind(config.hooks.provision);
   const housekeepingTimer = hooksKind === "container" || hooksKind === "vm" ? (() => {
     const everyMs = deps.housekeeping?.intervalMs ?? HOUSEKEEPING_INTERVAL_MS;
@@ -2357,6 +2445,7 @@ async function start(configPath, deps = { fetchImpl: fetch }) {
     if (intakeClosed) return;
     intakeClosed = true;
     clearInterval(pollTimer);
+    pollTimer = setInterval(() => void sendTickHeartbeat(state, void 0), (state.pollTimerSeconds ?? state.config.pollSeconds) * 1e3);
     clearInterval(housekeepingTimer);
   };
   const close = () => {
@@ -2364,6 +2453,7 @@ async function start(configPath, deps = { fetchImpl: fetch }) {
     detachSignals();
     if (closed) return;
     closed = true;
+    clearInterval(pollTimer);
     clearInterval(watchTimer);
   };
   const finish2 = () => {
@@ -2374,8 +2464,8 @@ async function start(configPath, deps = { fetchImpl: fetch }) {
     log.line("runner exited");
   };
   const drain = async (onWaiting) => {
-    if (draining) return;
-    draining = true;
+    if (state.draining === true) return;
+    state.draining = true;
     stopIntake();
     let passes = 0;
     while (state.jobs.size > 0 && !exited) {
@@ -2397,6 +2487,7 @@ async function start(configPath, deps = { fetchImpl: fetch }) {
     if (stopping) return;
     stopping = true;
     stopIntake();
+    clearInterval(pollTimer);
     clearInterval(watchTimer);
     log.line(`stopping: ending ${state.jobs.size} running job(s) now`);
     await Promise.all([...state.jobs.values()].map((active) => endJob(state, active, "stopped")));

package/dist/{chunk-BWSUPRDK.js → chunk-ZX4I2MEK.js}

@@ -4,6 +4,6 @@ import { createRequire } from 'node:module';
 createRequire(import.meta.url);
 
 // src/runner/protocol.ts
-var RUNNER_PROTOCOL = 20;
+var RUNNER_PROTOCOL = 21;
 
 export { RUNNER_PROTOCOL };

package/dist/{cli-EXX2R73G.js → cli-MKF7TU7X.js}

@@ -4432,7 +4432,7 @@ the step, the command prints why and exits 1.
       throw err;
     }
   });
-  emitCmd.command("criteria <file>").description("Record a work item's acceptance criteria from a JSON file (- for stdin)").option("--item <number>", "work item to record on directly, by its number in this factory").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
+  emitCmd.command("criteria <file>").description("Record a work item's acceptance criteria from a JSON or acceptance .md file").option("--item <number>", "work item to record on directly, by its number in this factory").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
     "after",
     `
   ${cliInvocation()} emit criteria criteria.json --item 412
@@ -4450,9 +4450,14 @@ Once an item has a list, only a person can replace it: run the command outside a
 agent session, with your own login. A key bound to no member cannot replace it either.
 --item names the work item; without it, inside a recorded session, the item that
 session was launched for is used automatically.
+
+A file ending in .md is read as an acceptance file, such as acceptance/412-login.md:
+each list item that opens with an id in backticks is a criterion, its text is the rest
+of the item, and a (proof: <kind>) annotation names its proof.
+  ${cliInvocation()} emit criteria acceptance/412-login.md --item 412
 `
   ).action(async (file, opts) => {
-    const { runEmitCriteria, EmitCriteriaError } = await import('./emit-criteria-cmd-CRTYEF7D.js');
+    const { runEmitCriteria, EmitCriteriaError } = await import('./emit-criteria-cmd-UNMWHOUY.js');
     try {
       const result = await runEmitCriteria({
         file,
@@ -4625,6 +4630,30 @@ command exits 1.
       throw err;
     }
   });
+  workCmd.command("stop").description("Stop the host build running on a work item").requiredOption("--item <number>", "the item's number inside this factory").option("--note <text>", "why the build is stopped (up to 500 characters); kept with the attempt").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
+    "after",
+    `
+  ${cliInvocation()} work stop --item 7
+  ${cliInvocation()} work stop --item 7 --note "wrong branch"
+
+Asks the host that holds the item's build to end it. The host reads the
+request at its next heartbeat, so the build may run a little longer. The
+item is not built again until a new build request. Exits 1 when no host
+build is running for the item.
+`
+  ).action(async (opts) => {
+    const { runWorkStop, WorkStopCommandError } = await import('./work-stop-cmd-CRDHXQVW.js');
+    const { WorkCommandError } = await import('./work-cmd-5I3J2XQQ.js');
+    try {
+      await runWorkStop(opts);
+    } catch (err) {
+      if (err instanceof WorkStopCommandError || err instanceof WorkCommandError) {
+        fail(err.message);
+        return;
+      }
+      throw err;
+    }
+  });
   workCmd.command("remove").description("Withdraw a source's addition \u2014 never deletes the item").option("--item <number>", "the item's number inside this factory").option("--issue <number>", "issue number or Linear/Jira key (default: named by --item instead)").option(TRACKER_OPTION_FLAG, "tracker for a keyed --issue, when both hold the key").option("--repo <owner/name>", "repository for an issue number (default: the checkout's remote)").requiredOption("--reason <text>", "why this source is no longer working on it").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
     "after",
     `
@@ -4680,7 +4709,7 @@ by a different key is refused; claiming again with the same key extends
 it. --host is a label only.
 `
   ).action(async (opts) => {
-    const { runWorkClaim, WorkCommandError } = await import('./work-claim-cmd-ZRPSHMPT.js');
+    const { runWorkClaim, WorkCommandError } = await import('./work-claim-cmd-DRQCHCOK.js');
     try {
       await runWorkClaim(opts);
     } catch (err) {
@@ -4700,7 +4729,7 @@ Extends the live lease this API key holds. Refused with a 410 if the
 lease has expired, or a 403 if a different key holds it.
 `
   ).action(async (opts) => {
-    const { runWorkRenew, WorkCommandError } = await import('./work-claim-cmd-ZRPSHMPT.js');
+    const { runWorkRenew, WorkCommandError } = await import('./work-claim-cmd-DRQCHCOK.js');
     try {
       await runWorkRenew(opts);
     } catch (err) {
@@ -4732,7 +4761,7 @@ applies to a host's lease only. A later tool call in the session
 takes the lease again.
 `
   ).action(async (opts) => {
-    const { runWorkRelease, WorkCommandError } = await import('./work-claim-cmd-ZRPSHMPT.js');
+    const { runWorkRelease, WorkCommandError } = await import('./work-claim-cmd-DRQCHCOK.js');
     try {
       await runWorkRelease(opts);
     } catch (err) {
@@ -4802,7 +4831,7 @@ function registerRunnerCommands(program2) {
   const configOption = "the cloud config file to run against (default: ~/.outerlayer/config.json)";
   runnerCmd.command("start").description("Run the loop: claim work, run it, report, clean up, repeat").option("--config <path>", configOption).action(async (opts) => {
     const { defaultRunnerConfigPath, RunnerConfigError } = await import('./config-CLSGABD5.js');
-    const { start, RunnerStartError } = await import('./loop-TPUYUMSY.js');
+    const { start, RunnerStartError } = await import('./loop-EAZQMAE2.js');
     const { RunnerAlreadyRunningError } = await import('./pidfile-3DM4OBKO.js');
     const configPath = opts.config ?? defaultRunnerConfigPath();
     try {
@@ -4818,7 +4847,7 @@ function registerRunnerCommands(program2) {
   });
   runnerCmd.command("check").description("Validate the config, the hooks and the key, and print the effective settings").option("--config <path>", configOption).action(async (opts) => {
     const { defaultRunnerConfigPath } = await import('./config-CLSGABD5.js');
-    const { runRunnerCheck } = await import('./check-W2JGXN3B.js');
+    const { runRunnerCheck } = await import('./check-BR5D27CX.js');
     const configPath = opts.config ?? defaultRunnerConfigPath();
     const result = await runRunnerCheck(configPath);
     if (!result.ok) {
@@ -5209,14 +5238,14 @@ Next:
   });
   runnerCmd.command("stop").description("Take no more work; wait for running jobs to finish, then exit").option("--config <path>", "the cloud config file naming the runner to stop").option("--now", "end running jobs immediately, with outcome stopped").action(async (opts) => {
     const { defaultRunnerConfigPath } = await import('./config-CLSGABD5.js');
-    const { requestStop } = await import('./loop-TPUYUMSY.js');
+    const { requestStop } = await import('./loop-EAZQMAE2.js');
     const configPath = opts.config ?? defaultRunnerConfigPath();
     await requestStop(configPath, Boolean(opts.now));
   });
   runnerCmd.command("status").description("List running jobs; with --recent, finished ones too").option("--config <path>", "the cloud config file naming the runner to inspect").option("--recent", "also list finished jobs, newest first, capped at 20").option("--json", "machine-readable JSON output").action(async (opts) => {
     const { defaultRunnerConfigPath, loadRunnerConfig } = await import('./config-CLSGABD5.js');
     const { jobsDir, runnerDir } = await import('./paths-7XP63OAX.js');
-    const { listJobFiles, runnerProcessState } = await import('./loop-TPUYUMSY.js');
+    const { listJobFiles, runnerProcessState } = await import('./loop-EAZQMAE2.js');
     const { renderStatus } = await import('./status-BINH7MBG.js');
     const { readHousekeepingRecord } = await import('./record-3WP6V2K5.js');
     const path2 = await import('path');
@@ -5273,7 +5302,7 @@ Next:
   });
   runnerCmd.command("logs").argument("<item>", "the work item's number in the factory").description("Print the newest attempt's log for one item").option("--config <path>", "the cloud config file naming the runner to inspect").option("-f, --follow", "keep printing as the log grows").action(async (itemArg, opts) => {
     const { defaultRunnerConfigPath } = await import('./config-CLSGABD5.js');
-    const { listJobFiles } = await import('./loop-TPUYUMSY.js');
+    const { listJobFiles } = await import('./loop-EAZQMAE2.js');
     const { newestAttempt, logPathFor, tail, RunnerLogsError } = await import('./logs-AMLKC3VP.js');
     const configPath = opts.config ?? defaultRunnerConfigPath();
     const item = parseTrackerNumber(itemArg);

package/dist/{emit-criteria-cmd-CRTYEF7D.js → emit-criteria-cmd-UNMWHOUY.js}

@@ -24,6 +24,33 @@ import './chunk-Z5GEFMRW.js';
 import { readFileSync } from 'fs';
 
 createRequire(import.meta.url);
+
+// src/acceptance-file.ts
+var CRITERION_LINE = /^\s*\d+\.\s+`(AC-(?:\d{3,}|[A-Z][A-Z0-9]*-\d+)-\d{2})`\s*(.*)$/;
+var PROOF_ANNOTATION = /\(proof:\s*([A-Za-z]+)\)/;
+var LIST_ITEM = /^\s*(?:\d+\.|[-*])\s/;
+var CONTINUATION = /^\s+\S/;
+function criteriaFromAcceptanceFile(markdown) {
+  const criteria = [];
+  let current = null;
+  for (const line of markdown.split(/\r?\n/)) {
+    const match = CRITERION_LINE.exec(line);
+    if (match) {
+      current = { id: match[1], text: match[2].trim(), proof: null };
+      criteria.push(current);
+    } else if (current !== null && CONTINUATION.test(line) && !LIST_ITEM.test(line)) {
+      current.text = `${current.text} ${line.trim()}`;
+    } else {
+      current = null;
+    }
+  }
+  for (const criterion of criteria) {
+    criterion.proof = PROOF_ANNOTATION.exec(criterion.text.replace(/`[^`]*`/g, ""))?.[1] ?? null;
+  }
+  return criteria;
+}
+
+// src/emit-criteria-cmd.ts
 var EmitCriteriaError = class extends Error {
 };
 var REPLACE_REFUSED_MESSAGE = "this item already has a recorded list, and a person must replace it. Run the command yourself, outside the session, with your own login. A repository's .outerlayer/policy.yaml can let sessions replace it with `criteria: { replace: anyone }`.";
@@ -111,10 +138,18 @@ async function runEmitCriteria(opts) {
     }
   }
   let raw;
-  try {
-    raw = JSON.parse(text);
-  } catch (err) {
-    throw new EmitCriteriaError(`"${opts.file}" is not valid JSON: ${String(err)}`);
+  if (opts.file.endsWith(".md")) {
+    const criteria = criteriaFromAcceptanceFile(text);
+    if (criteria.length === 0) {
+      throw new EmitCriteriaError(`"${opts.file}" lists no criteria: none of its list items opens with an id such as \`AC-123-01\``);
+    }
+    raw = { criteria };
+  } else {
+    try {
+      raw = JSON.parse(text);
+    } catch (err) {
+      throw new EmitCriteriaError(`"${opts.file}" is not valid JSON: ${String(err)}`);
+    }
   }
   const list = parseFile(raw);
   const identity = resolveRepoIdentity(cwd);

package/dist/index.js

@@ -26,5 +26,5 @@ if (argv[0] === "claude") {
   process.exit(await runClaudeLauncher(argv.slice(1)));
 }
 (await import('./hook-fast-RL5E5OXE.js')).recordLinkExitFailure(argv);
-var { runCli } = await import('./cli-EXX2R73G.js');
+var { runCli } = await import('./cli-MKF7TU7X.js');
 await runCli(process.argv);

package/dist/{loop-TPUYUMSY.js → loop-EAZQMAE2.js}

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
-export { RunnerStartError, listJobFiles, probeCredentials, requestStop, runnerProcessState, start, tick, watchTick } from './chunk-F2KXHIFI.js';
+export { RunnerStartError, listJobFiles, probeCredentials, requestStop, runnerProcessState, start, tick, watchTick } from './chunk-AD3EYI7P.js';
 import './chunk-B6SCN5NY.js';
+import './chunk-SADUQSO4.js';
 import './chunk-MTP2QEVO.js';
 import './chunk-S5PCA3SN.js';
 import './chunk-3JVYMD4G.js';
 import './chunk-YETTWTAY.js';
-import './chunk-SADUQSO4.js';
 import './chunk-I2UOAV7X.js';
-import './chunk-BWSUPRDK.js';
+import './chunk-ZX4I2MEK.js';
 import './chunk-JHGEBPLE.js';
 import './chunk-XNGMQ27R.js';
 import './chunk-R22NZSGA.js';

package/dist/{work-claim-cmd-ZRPSHMPT.js → work-claim-cmd-DRQCHCOK.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
-import { RUNNER_PROTOCOL } from './chunk-BWSUPRDK.js';
+import { RUNNER_PROTOCOL } from './chunk-ZX4I2MEK.js';
 import { resolveCredentials, WorkCommandError, parsePositiveInt, postJson, environmentFacts, findLiveItemForIssue } from './chunk-FBTGMSQF.js';
 export { WorkCommandError } from './chunk-FBTGMSQF.js';
 import './chunk-IF2OSI5T.js';

package/dist/work-stop-cmd-CRDHXQVW.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+import { resolveCredentials, postJson, WorkCommandError } from './chunk-FBTGMSQF.js';
+import './chunk-IF2OSI5T.js';
+import './chunk-CG36IONK.js';
+import './chunk-G3IJ3N6F.js';
+import './chunk-BM63HB2M.js';
+import './chunk-QNLX477Q.js';
+import './chunk-GOSFARMS.js';
+import './chunk-ANPNT6PM.js';
+import { parseTrackerNumber, trackerNumberError } from './chunk-WZBHBH3J.js';
+import { defaultFetch } from './chunk-FVMYKL6L.js';
+import './chunk-NTRCK4NH.js';
+import './chunk-BJ3KTMDH.js';
+import './chunk-EABW6AJQ.js';
+import './chunk-CRB3POP4.js';
+import './chunk-7VUK5RFS.js';
+import './chunk-VNVZDWO3.js';
+import './chunk-M2ZWWTWZ.js';
+import './chunk-N2PXGQRL.js';
+import './chunk-BQXFBI7T.js';
+import './chunk-Z5GEFMRW.js';
+
+createRequire(import.meta.url);
+
+// src/work-stop-cmd.ts
+var WorkStopCommandError = class extends Error {
+};
+async function runWorkStop(opts) {
+  const itemNumber = parseTrackerNumber(opts.item);
+  if (itemNumber === void 0) {
+    throw new WorkStopCommandError(trackerNumberError("--item", opts.item ?? ""));
+  }
+  const creds = resolveCredentials(opts);
+  const fetchImpl = opts.fetchImpl ?? defaultFetch;
+  const body = opts.note === void 0 || opts.note === "" ? {} : { note: opts.note };
+  let data;
+  try {
+    ({ data } = await postJson(creds.url, `/v1/work-items/${itemNumber}/claim/stop`, creds.apiKey, creds.appId, body, fetchImpl));
+  } catch (err) {
+    if (err instanceof WorkCommandError && err.code === "no_build_running") {
+      throw new WorkStopCommandError(`no host build is running for #${itemNumber}, so there is nothing to stop`);
+    }
+    throw err;
+  }
+  const claim = data;
+  const output = opts.json ? JSON.stringify(data) : `Stop requested for #${itemNumber}: ${claim.host ?? "the host"} ends the build at its next heartbeat. The stop stays pending until the build ends.`;
+  if (!opts.quiet) process.stdout.write(output + "\n");
+  return { data, output };
+}
+
+export { WorkStopCommandError, runWorkStop };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outerlayer/cli",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "OuterLayer CLI — commands: init, claude, connect, doctor, login, logout, sync, daemon (alias: watch), emit, work, spec, runner, hooks, mcp, import, context. Capture and sync coding-agent sessions, and record proof of factory work.",
   "license": "Apache-2.0",
   "author": "Magu Studios, Inc.",