bareloop 0.35.0 → 0.36.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to bareloop are documented here. Format:
 [SemVer](https://semver.org/spec/v2.0.0.html). Pre-1.0: **minor** = a ladder rung or
 feature lands, **patch** = docs, fixes, scaffolding.
 
+## [0.36.0] - 2026-10-06
+
+### Added
+
+- **Repo jobs run in a git worktree in the person's own repo.** A panel drafting session makes `<repo>/.bareloop/wt/<session>` (detached at HEAD, hidden through the repo's private exclude, with a notice for uncommitted changes) instead of copying the source. `git worktree add` and the green-end commit run none of the person's git hooks. `node_modules/` is hidden the same way as `/.bareloop/`, so installed packages never read as worker writes. A GREEN run commits its work to the work branch and removes the folder (kept only while a review door is open); any other end keeps it. The Ended block gives the `git merge` / `git branch -D` text on green and names the folder otherwise; Resume is withdrawn once the folder is gone. The bundle door shares the one worktree-making module.
+- **bareloop installs npm dependencies itself.** For an npm lock file, bareloop runs `npm ci --ignore-scripts` at $0, before any token, with a secret-stripped environment. Any failure, or another lock file (yarn, pnpm), falls back to the install-needed wait. `missingDependencies` now carries `dir` and `lockFile`. The panel step reads "installing packages" while it runs and "Installed packages (npm ci)." on success.
+- **Run names `job (run-N)`.** Runs are numbered per job, oldest first (`runNo` in the run list and run detail); rows, cards, the workflow row and the header use the name. The real run id stays in the Resume and Reuse texts. Runs search also finds `run-N` and `job (run-N)`.
+- **Settings: price per key row.** The Providers table takes In $/1M and Out $/1M per key (blank = not set; a half-set price is refused; the price posts once both boxes are filled or both are empty). Columns are Key, Name, API shape, Base URL, Test, Tokens used, Balance, In $/1M, Out $/1M.
+- **Settings: Open keys folder button** (`POST /api/settings/open-keys-folder`) replaces the keys path text; the path shows only when the folder cannot be opened.
+- **Drafting part.** A panel-authored run serves its drafting as the first part on the Run map, its card and the Audit grouped view, with a per-step table (time, calls, model, cost, total) read from a per-session `draft-log.jsonl`.
+- **Runs list cards are two lines**: workflow card `job (run-N) word / check, cost, wall, date`; sub-card `(run-N) word / cost, wall, date`.
+
+### Fixed
+
+- A gate-audit move across devices no longer crashes a worktree run: `moveFile` falls back to copy and unlink on `EXDEV` (the workdir can sit on another drive than the spine dir).
+- A green worktree run always commits its work to the branch, including door-open and leak greens, and does so right after the gate-audit move, before any later readout step can throw.
+- An already-green worktree run removes its folder (and commits a resumed leg's uncommitted work) instead of leaving it behind.
+- Panel: a price box typed alone no longer flashes the half-set error; card textareas auto-grow as you type.
+- Tests no longer write settled rows into the real run list (`cli.test.js` passes `keysHome` with `runlistHome`). Test-only.
+
+### Changed
+
+- A secret already in the person's own repo no longer refuses a worktree repo source: it is masked wherever bareloop records it. A `.env` file by name is still refused.
+- The link-login item is dropped; the panel's token-in-page model is unchanged.
+- The progress step label "copying source" reads "making worktree".
+- `prepareSource`'s manifest type is `Record<string, any>` (types only).
+
 ## [0.35.0] - 2026-10-05
 
 ### Added

package/bareloop.context.md

@@ -3363,7 +3363,12 @@ key you want first (the panel picks the row by the Model menu).
   list by job for the left pane's "Workflows" view and renders it flat for "History", both
   behind one `Runs` tab toggle; there is no separate `/api/workflows` endpoint, deleted in
   the P1 Runs-tab merge); `GET /api/runs/:runid` (the full replay — parts/steps, counters,
-  summary, model/provider/judge); `GET /api/runs/:runid/audit` (the gate-audit sidecar rows,
+  summary, model/provider/judge). Every `GET /api/runs` row and the detail carry `runNo` (P6 item 7): runs of one job are numbered
+  oldest `at` first by ONE server function (`runNumbers`), and the page names a run `job (run-N)`; the run id stays in the Audit
+  tab and every command line. A run that came out of a panel drafting session also carries the DRAFTING part as the FIRST element of
+  `detail.parts` (`kind:'drafting'`, built from the session's `draft-log.jsonl`, `src/draftspend.js`): every other index a reader
+  is handed (`legDividers.beforePart`, the flat Audit rows' `partIndex`, the rounds endpoint's `part`) lives in that one shifted
+  index space, and the drafting part has no rounds table (`rounds?part=0` is a 404). `GET /api/runs/:runid/audit` (the gate-audit sidecar rows,
   ts-windowed to this run alone even when the sidecar file is shared with other runs, plus
   the matching raw-log text windowed the same way — when one resolves); `GET
   /api/runs/:runid/rounds?part=&attempt=&offset=&limit=` (one attempt's rounds, lazily
@@ -3436,7 +3441,8 @@ key you want first (the panel picks the row by the Model menu).
   completion; the page sees the key's NAME and a status word, never the value). `POST
   /api/author/:id/check-deps` is the install-gap's "Check again" (the main button's wording while waiting on an install) (`phase:'install-needed'`:
   the session waits on the person's own install, then re-runs `missingDependencies` on the
-  same copy — bareloop never installs). `POST /api/author/:id/abandon` (the Chat card's **Abandon** button, 2026-10-05) ends a
+  same worktree — the AGENT never installs; for a committed npm lock file the panel door first runs `npm ci --ignore-scripts` itself,
+  $0, before any token (`src/npminstall.js`, credential env stripped), and only a failure, a timeout or another lock file lands here). `POST /api/author/:id/abandon` (the Chat card's **Abandon** button, 2026-10-05) ends a
   LIVE, unsigned session: phase becomes the terminal `abandoned` (releasing the one-at-a-time lock), money already booked
   stays booked (`draftSpentUsd` is never zeroed; a call in flight still books its usage), no NEW model call starts;
   `400` on a session that is not live, `404` unknown id, same guard as the other author routes. After `signed` the card's
@@ -3850,12 +3856,16 @@ placeholder `no-key-needed`, never the word `null`). Each row: the env NAME (rea
 **Name** (the model id Chat uses), **API shape** (Anthropic / OpenAI-compatible / Gemini), **Base
 URL** (blank = the shape's own host), **Test**, **Tokens used** (total, display only), and Balance
 (DeepSeek fetched, Anthropic a typed note). Saves on change to `config.json`
-`keys.<ENV NAME> = { name, shape, baseUrl }`. Defaults for a key with no saved entry:
+`keys.<ENV NAME> = { name, shape, baseUrl, priceInPerM?, priceOutPerM? }`. The last two columns are the customer's own price
+(**In $/1M**, **Out $/1M**, plain boxes; blank = not set, a number >= 0 otherwise; the server refuses a half-set pair with a plain
+error and saves nothing, and the page leaves a half-typed pair out of the save until both boxes are filled or both cleared).
+**Open keys folder** (`POST /api/settings/open-keys-folder`) opens `~/.config/bareloop` in the file manager (`xdg-open` / `open`,
+argv array, never the file itself); where it cannot, the page shows the path as text. Defaults for a key with no saved entry:
 `ANTHROPIC_API_KEY` claude-sonnet-5 / Anthropic; `DEEPSEEK_API_KEY` deepseek-flash /
 OpenAI-compatible / `https://api.deepseek.com/v1`; `OPENAI_API_KEY` OpenAI-compatible;
 `GEMINI_API_KEY` Gemini; `LOCAL_API_KEY` OpenAI-compatible / `http://127.0.0.1:11434/v1` (Ollama, LM
-Studio, llama.cpp: change the URL); any other name OpenAI-compatible; Name blank until typed. **No
-price is shown anywhere** (display only — cost recording, the estimated provenance, spend sums, caps
+Studio, llama.cpp: change the URL); any other name OpenAI-compatible; Name blank until typed. **The
+only price shown is the customer's own, typed in the two price boxes** (cost recording, the estimated provenance, spend sums, caps
 and the monthly limit are unchanged; a local model has no known rate, so its rounds come out as a
 non-zero loud guess, never a real $0).
 
@@ -3895,6 +3905,23 @@ const prepared = await prepareSource({
 Or the CLI: `node scripts/prep-source.mjs --source <path-or-url> --into <dir> [--destination
 <absolute-directory>]` — prints the tree path, the seed, and the exact next command.
 
+**A REPO source on a worktree (P6 item 1, the panel's repo jobs).** Pass `worktree: '<repo>/.bareloop/wt/<id>'` to
+`prepareSource` and a repo source is NOT copied: its tree is a detached `git worktree` of the person's own repo at their current
+commit (`src/worktree.js`, the one spelling the bundle door shares). `prepared.tree` is that worktree; `into` holds only
+`source.json`, which records `worktree`, `repo` and `seed` (= the repo's HEAD — no seed commit is made, no `output/` scaffold
+is written). Uncommitted edits in the person's repo are not in it (the panel says so at drafting start: "N uncommitted
+change(s) in your repo are not in this job — it starts from commit <sha>"). `.bareloop/` and `node_modules/` (any depth, so packages installed in the worktree never read as worker writes) are hidden from the person's own
+`git status` through the repo's private `<common-git-dir>/info/exclude`, never their tracked `.gitignore`. The person's git hooks never run when bareloop makes the worktree (either door). The signed run
+(`run-u --spec`) reads `worktree` from that manifest; its spine and books stay in the session directory beside `source.json`,
+never inside the person's repo. At the end: GREEN (an already-green run too, which has nothing to commit unless it is a resumed
+leg) ALWAYS commits the run's work on its `bareloop-<job>` work branch (authored by `bareloop`, hooks off, arbiter books and
+`node_modules` left out) — including a green that opened a review door or whose spine leaked — and removes the worktree folder,
+except while a review door is open: that folder is KEPT (a door accept re-runs the mechanical stages against it). The branch stays and the
+merge stays the person's (`git merge <branch>` / `git branch -D <branch>` are shown as text). Any other ending (stopped,
+capped, died, red) leaves the folder so Resume can re-enter it; a drafting session that ends without ever running (refused,
+abandoned) removes its worktree. A panel restart mid-drafting loses the in-memory session and leaves its worktree behind
+(`git worktree list` shows it; `git worktree remove --force <folder>` clears it).
+
 > **If your source is a folder, read this first (hamr's ruling):** make a new folder, put
 > only the file(s) this job needs in it, point bareloop at that — never your original
 > folder. Everything in the folder you name is frozen, read, and paid for. `prep-source`
@@ -3996,13 +4023,14 @@ the run's own scratch tree.
 **`prepareSource` copies ONLY git-tracked files** (hamr's ruling, unchanged) — a JS/TS repo's
 prepared copy therefore never carries `node_modules`, and every close stage that needs a tool
 (`tsc`, a test runner) would instrument-stop with nothing telling the person why. bareloop
-NEVER runs an install itself — it only ever touches gated primitives, never a shell-out to
-`npm`/`pnpm`/`yarn`/`bun` on the person's behalf. `missingDependencies` is exported ($0,
+NEVER runs an install itself for the agent or the CLI doors — the agent only touches gated primitives, never a shell-out to
+`npm`/`pnpm`/`yarn`/`bun` on the person's behalf (the one exception is the panel door's own pre-token `npm ci --ignore-scripts` for an
+npm lock file, P6 item 3, `src/npminstall.js`; it is never a verb the agent holds). `missingDependencies` is exported ($0,
 JS/TS only for now — other languages return `null`, M3b's job): it takes `(treeDir,
 sourceSubdir?)` and walks from `sourceSubdir` up to `treeDir` (the same nearest-manifest rule
 `detectLanguage` uses, done independently to avoid a `source.js` ⇄ `detectlang.js` import
 cycle), and when the nearest `package.json` names a non-empty `dependencies`/`devDependencies`
-with no sibling `node_modules`, it returns `{manager, command, reason}` — the exact install
+with no sibling `node_modules`, it returns `{dir, lockFile, manager, command, reason}` (`dir` = the folder holding the manifest, `lockFile` = the committed lock file or `null`) — the exact install
 line (`npm ci`/`pnpm install --frozen-lockfile`/`yarn install --frozen-lockfile`/`bun install
 --frozen-lockfile` by lockfile, else `npm install`), `cd`-prefixed for a subfolder job. An
 invalid `package.json`, no manifest found, or `node_modules` already present all return `null`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bareloop",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "Workflows that earn their own design, with receipts — agent-authored workflows for repeated, long, verifiable jobs that improve across runs under an un-gameable gate.",
   "type": "module",
   "main": "./src/index.js",

package/src/authorrun.js

@@ -104,7 +104,7 @@ import { keysForDoor } from './keysfile.js';
 import { applyConfiguredKey, judgeRatesFor, keyNameFor, ratesFor, rowsForHome } from './providerrows.js';
 import { ConfigError } from './config.js';
 import {
-  readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync, renameSync, statSync,
+  readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync, statSync,
 } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { createInterface } from 'node:readline';
@@ -120,6 +120,7 @@ import { defaultJudgeLoop, resolveJobJudge } from './judged.js';
 import { validateJob, jobSpecHash, resolveWorkerModel } from './job.js';
 import { scanSecrets, redactSecrets } from './validate.js';
 import { detectLanguage } from './detectlang.js';
+import { moveFile } from './movefile.js';
 import { closeJudges, GATE_AUDIT_FILE } from './kinds.js';
 import { resolveProvider, buildRunnerProviders, apiKeyProblem } from './providers.js';
 import { commandFor } from './invoke.js';
@@ -288,7 +289,7 @@ export async function main(argv, deps = {}) {
     if (!existsSync(treeAudit)) return;
     const archived = join(OUT, `author-${runid}-${GATE_AUDIT_FILE}`);
     try {
-      renameSync(treeAudit, archived);
+      moveFile(treeAudit, archived);
       out(`gate audit ${archived} (moved out of the patient tree — F186)`);
     } catch (e) {
       err(`gate audit could not be archived out of the patient tree: ${/** @type {NodeJS.ErrnoException} */ (e)?.message ?? e}`);

package/src/bundlerun.js

@@ -16,12 +16,13 @@
 import { hostname } from 'node:os';
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { join, resolve } from 'node:path';
 
 import {
   readBundle, resolveBundleSpec, checkEnvelope, bless, verifyBlessing, appendHistory, checkBundleDeps,
 } from './bundle.js';
 import { jobSpecHash } from './job.js';
+import { addWorktree, worktreePath } from './worktree.js';
 import { parseJsonl } from './replayio.js';
 import { legsOf } from './legs.js';
 import { startRun, resumeRun } from './userrun.js';
@@ -165,7 +166,7 @@ export async function bundleMain(args, {
       err(`--repo ${repoArg} must be a git repository with at least one commit: ${/** @type {Error} */ (e).message}`);
       return 1;
     }
-    worktree = join(repo, '.bareloop', 'wt', runid);
+    worktree = worktreePath(repo, runid);
     if (existsSync(worktree)) { err(`worktree already exists: ${worktree}`); return 1; }
   }
 
@@ -186,12 +187,7 @@ export async function bundleMain(args, {
   // at job-end (a killed run has none) and the run list is machine-global.
   const prepareTree = () => {
     if (deadSpine === null) {
-      mkdirSync(dirname(worktree), { recursive: true });
-      try {
-        execFileSync('git', ['-C', repo, 'worktree', 'add', '--detach', worktree, 'HEAD'], { encoding: 'utf8' });
-      } catch (e) {
-        throw new Error(`git worktree add failed: ${/** @type {Error} */ (e).message}`);
-      }
+      addWorktree(repo, worktree);
     }
     mkdirSync(runDir, { recursive: true });
     writeFileSync(join(runDir, 'run.json'), `${JSON.stringify({

package/src/draftspend.js

@@ -12,11 +12,32 @@
 // Month attribution is the file's `startedAt` (the first metered call): fixed once written, so a session's
 // figure never moves between months as spend continues, the same start-date rule a run's leg uses.
 // `spendComplete: false` = "at least", never $0 (F6).
-import { existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { appendFileSync, existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
 import { readRunList, runlistHome } from './runlist.js';
 
 export const DRAFT_SPEND_FILE = 'draft-spend.json';
+/** the session's drafting LOG: an append-only JSONL beside draft-spend.json (one owner: the session, src/panel/authorsession.js). Three event kinds, see {@link DraftEvent}. */
+export const DRAFT_LOG_FILE = 'draft-log.jsonl';
+
+/**
+ * One line of the drafting log. `no` = the step's position in the session's progress list (a step id can repeat).
+ *  - `step-start`  {no, id, label, at}
+ *  - `step-end`    {no, status: 'done'|'failed', label, at}   (a re-opened step writes `step-reopen` {no, at} first)
+ *  - `call`        {no, step, label, model, costUsd (null stays null), unpricedRounds, at}: one METERED model call
+ *    (no token counts: the call path does not carry them without reworking the library, so none are recorded)
+ * @typedef {{kind: string, no: number, at: string, [k: string]: any}} DraftEvent
+ */
+
+/**
+ * Append one event to `<dir>/draft-log.jsonl`. Best-effort like draft-spend.json: a disk fault never stops the draft.
+ * @param {string} dir the session's folder
+ * @param {DraftEvent} ev
+ * @returns {void}
+ */
+export function appendDraftLog(dir, ev) {
+  try { appendFileSync(join(dir, DRAFT_LOG_FILE), `${JSON.stringify(ev)}\n`); } catch { /* money already spent stays in memory */ }
+}
 
 /**
  * @typedef {object} DraftSpend
@@ -80,3 +101,97 @@ export function readOrphanDraftSpends(opts = {}) {
   }
   return out;
 }
+
+/**
+ * The session folder a run-list row became a run in: the folder under `<home>/panel-sessions` that carries a drafting
+ * log and holds the row's `spine` or `patient` ("became a run", the same rule as {@link readOrphanDraftSpends}).
+ * A Reuse-workflow run, a CLI run and an imported run sit in no such folder.
+ * @param {{spine?: string, patient?: string|null}} row
+ * @param {{ home?: string, sessionsRoot?: string }} [opts]
+ * @returns {string|null}
+ */
+export function sessionDirForRow(row, opts = {}) {
+  const root = resolve(opts.sessionsRoot ?? join(runlistHome(opts.home), 'panel-sessions'));
+  /** @type {string[]} */
+  let names;
+  try { names = readdirSync(root); } catch { return null; }
+  for (const name of names) {
+    const dir = join(root, name);
+    if (!existsSync(join(dir, DRAFT_LOG_FILE))) continue;
+    if (inside(/** @type {string} */ (row.spine), dir) || (row.patient && inside(row.patient, dir))) return dir;
+  }
+  return null;
+}
+
+/**
+ * Fold `<dir>/draft-log.jsonl` into one record per drafting step, each with its calls. A line that cannot be parsed is
+ * skipped (a torn last line must not hide the rest).
+ * @param {string} dir
+ * @returns {{no: number, id: string, label: string, status: 'running'|'done'|'failed', startedAt: string, endedAt: string|null, wallMs: number|null,
+ *   calls: {label: string, model: string|null, costUsd: number|null, unpricedRounds: number, at: string}[]}[]}
+ */
+export function readDraftSteps(dir) {
+  /** @type {string} */
+  let text;
+  try { text = readFileSync(join(dir, DRAFT_LOG_FILE), 'utf8'); } catch { return []; }
+  /** @type {Map<number, any>} */
+  const byNo = new Map();
+  /** @type {any[]} */
+  const orphanCalls = [];
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    let ev;
+    try { ev = JSON.parse(line); } catch { continue; }
+    if (!ev || typeof ev !== 'object' || !Number.isInteger(ev.no)) continue;
+    if (ev.kind === 'step-start') {
+      byNo.set(ev.no, { no: ev.no, id: String(ev.id), label: String(ev.label), status: 'running', startedAt: ev.at, endedAt: null, wallMs: null, calls: [] });
+    } else if (ev.kind === 'step-end' && byNo.has(ev.no)) {
+      const x = byNo.get(ev.no);
+      x.status = ev.status === 'failed' ? 'failed' : 'done';
+      x.endedAt = ev.at;
+      if (typeof ev.label === 'string') x.label = ev.label;
+    } else if (ev.kind === 'step-reopen' && byNo.has(ev.no)) {
+      const x = byNo.get(ev.no);
+      x.status = 'running';
+      x.endedAt = null;
+    } else if (ev.kind === 'call') {
+      const c = { label: String(ev.label), model: typeof ev.model === 'string' ? ev.model : null, costUsd: typeof ev.costUsd === 'number' ? ev.costUsd : null, unpricedRounds: Number(ev.unpricedRounds) || 0, at: String(ev.at) };
+      (byNo.get(ev.no)?.calls ?? orphanCalls).push(c);
+    }
+  }
+  const steps = [...byNo.values()].sort((a, b) => a.no - b.no);
+  for (const x of steps) {
+    const a = Date.parse(x.startedAt);
+    const b = x.endedAt === null ? NaN : Date.parse(x.endedAt);
+    x.wallMs = Number.isFinite(a) && Number.isFinite(b) ? Math.max(0, b - a) : null;
+  }
+  return steps;
+}
+
+/**
+ * The DRAFTING PART of a run (hamr 2026-10-06, option A): the first part of the run's views, built from the session's
+ * drafting log. `null` when the run did not come out of a panel session, or the log carries no metered call (a Reuse
+ * workflow run, a CLI run, a run older than the log). The part's money is the SPINE's figure (`job-start.draftSpentUsd`,
+ * passed in) — the log's calls are shown beside it, never summed into a second total; `null` spine figure = no part.
+ * @param {{spine?: string, patient?: string|null}} row
+ * @param {{draftSpentUsd: number|null, draftSpendComplete: boolean|null}} spine the run's own drafting figures
+ * @param {{ home?: string, sessionsRoot?: string }} [opts]
+ * @returns {any|null}
+ */
+export function draftingPartFor(row, spine, opts = {}) {
+  if (spine.draftSpentUsd === null) return null;
+  const dir = sessionDirForRow(row, opts);
+  if (!dir) return null;
+  const steps = readDraftSteps(dir);
+  const calls = steps.reduce((n, x) => n + x.calls.length, 0);
+  if (calls === 0) return null;
+  const starts = steps.map((x) => Date.parse(x.startedAt)).filter(Number.isFinite);
+  const ends = steps.map((x) => (x.endedAt === null ? NaN : Date.parse(x.endedAt))).filter(Number.isFinite);
+  return {
+    kind: 'drafting', id: 'drafting', label: 'drafting', occurrence: 1, leg: 1, outcome: null, blocked: 0,
+    attempts: [], rounds: calls, toolCalls: 0, byTool: null,
+    wallMs: starts.length && ends.length ? Math.max(0, Math.max(...ends) - Math.min(...starts)) : null,
+    spentUsd: spine.draftSpentUsd, spendComplete: spine.draftSpendComplete !== false, unpricedRounds: 0,
+    draftSteps: steps,
+  };
+}

package/src/index.js

@@ -153,9 +153,9 @@ export { answerReviewDoor } from './reviewdoor.js';
 // but no longer read by any grading path), the rulebook a card SELECTS from,
 // the card gate, and the two halves themselves so a calibration harness can
 // grade the whole pipe without running a close.
-// `defaultJudgeLoop` is the one spelling of how this repo drives a judge; the
-// runner reaches it through `runPlan`'s `judgeProvider`, and it is exported so a
-// caller building its own harness does not spell a second one.
+// `defaultJudgeLoop` (src/judged.js) is the one spelling of how this repo drives a
+// judge; the runner reaches it through `runPlan`'s `judgeProvider`. It is internal:
+// the package root does not export it.
 export {
   JUDGE_MODEL, resolveJudge, JUDGE_RULES, JUDGE_RULE_IDS,
   runLocate, decide,

package/src/legs.js

@@ -160,7 +160,7 @@ export function watchdogNotePath(spineFile, leg) {
 
 /**
  * P5 item 5 (Stop) — where a run's STOP REQUEST lives: a file beside its spine. The panel's stop route writes it;
- * the engine reads it at the between-steps seam (src/planrun.js) and consumes it. One spelling, here, so the route
+ * the engine reads it at the round seam of a step worker (src/planrun.js `metered`) and consumes it. One spelling, here, so the route
  * and the engine can never name two files. A request belongs to ONE leg: the engine deletes it when it honours it,
  * when the leg ends, and again at the start of the next leg (src/userrun.js).
  * @param {string} spineFile

package/src/movefile.js

@@ -0,0 +1,22 @@
+// Move a file between two paths that may sit on DIFFERENT filesystems.
+// `renameSync` cannot cross a device (EXDEV): a worktree inside the person's own repo can be on /tmp or
+// another drive while the spine / output dir stays under ~/.config. EXDEV only falls back to copy + unlink;
+// every other error rethrows untouched. Renames inside one directory (atomic tmp -> final writes) don't need this.
+import { renameSync, copyFileSync, unlinkSync } from 'node:fs';
+
+/**
+ * @param {string} src
+ * @param {string} dst
+ * @param {{ rename?: (a: string, b: string) => void }} [deps] test seam: the rename to try first
+ * @returns {void}
+ */
+export function moveFile(src, dst, deps = {}) {
+  const rename = deps.rename ?? renameSync;
+  try {
+    rename(src, dst);
+  } catch (e) {
+    if (/** @type {NodeJS.ErrnoException} */ (e)?.code !== 'EXDEV') throw e;
+    copyFileSync(src, dst);
+    unlinkSync(src);
+  }
+}

package/src/npminstall.js

@@ -0,0 +1,55 @@
+// P6 item 3 (signed 2026-10-05): bareloop installs a JS repo's packages ITSELF, $0, before any token,
+// for the one case whose command is exact and offline-reproducible: a committed `package-lock.json` /
+// `npm-shrinkwrap.json` -> `npm ci --ignore-scripts`. It is the panel door's own step, never a verb the
+// agent is granted (the tool menu is untouched): the agent never sees, asks for, or triggers it.
+// Anything else (another lock file, no lock file, npm missing, a failure, a timeout) returns `ok:false`
+// and the caller falls back to the install-needed wait with the real command.
+
+import { existsSync } from 'node:fs';
+import { spawnClose, CLOSE_ENV_DENY } from './ralph.js';
+import { redactSecrets } from './validate.js';
+
+/** Wall-clock cap for one `npm ci`: 10 minutes. A cold install of a large repo is minutes, never an hour;
+ * past this the person is better served by the printed command in their own terminal. Operator-set. */
+export const NPM_CI_TIMEOUT_MS = 600_000;
+
+/** the lock files whose gap command is `npm ci` (the rule table in src/source.js, LOCKFILE_COMMANDS) */
+export const NPM_CI_LOCKS = Object.freeze(['package-lock.json', 'npm-shrinkwrap.json']);
+
+/**
+ * The env npm sees: the panel's own env minus every credential `CLOSE_ENV_DENY` names (never re-spelled).
+ * `npm ci` needs no provider key; a private registry token (NPM_TOKEN) is stripped too, so such a repo
+ * simply falls back to the person's own install.
+ * @param {NodeJS.ProcessEnv} base
+ * @returns {NodeJS.ProcessEnv}
+ */
+export function npmEnv(base) {
+  const env = { ...base };
+  delete env.NODE_TEST_CONTEXT;
+  for (const name of Object.keys(env)) {
+    if (CLOSE_ENV_DENY.names.includes(name)
+      || CLOSE_ENV_DENY.prefixes.some((p) => name.startsWith(p))
+      || CLOSE_ENV_DENY.shape.test(name)) delete env[name];
+  }
+  return env;
+}
+
+/**
+ * Run `npm ci --ignore-scripts` in `cwd`. Async (never blocks the panel's event loop); argv array, no shell.
+ * @param {string} cwd the directory holding package.json + the lock file
+ * @param {{timeoutMs?: number, env?: NodeJS.ProcessEnv, run?: typeof spawnClose}} [o] `run` is the test seam
+ * @returns {Promise<{ok: true}|{ok: false, reason: string}>}
+ */
+export async function runNpmCi(cwd, { timeoutMs = NPM_CI_TIMEOUT_MS, env = process.env, run = spawnClose } = {}) {
+  const r = await run('npm', ['ci', '--ignore-scripts'], { env: npmEnv(env), cwd, timeoutMs });
+  if (r.error) {
+    const code = r.error.code;
+    if (code === 'ETIMEDOUT') return { ok: false, reason: `timed out after ${Math.round(timeoutMs / 1000)}s` };
+    if (code === 'ENOENT') return existsSync(cwd) ? { ok: false, reason: 'npm was not found' } : { ok: false, reason: 'the install folder does not exist' };
+    return { ok: false, reason: redactSecrets(String(r.error.message ?? r.error)).slice(0, 200) };
+  }
+  if (r.status === 0) return { ok: true };
+  const lines = String(r.stderr || r.stdout || '').split('\n').map((l) => l.trim()).filter(Boolean);
+  const last = redactSecrets(lines[lines.length - 1] ?? '').slice(0, 200);
+  return { ok: false, reason: last || (r.status === null ? `killed by ${r.signal ?? 'a signal'}` : `exit ${r.status}`) };
+}