bareloop 0.35.0 → 0.36.0

package/src/userrun.js

@@ -24,11 +24,13 @@
 // green ONE job end to end. That green GRADUATES the bridge: the plan the agent
 // authored is preserved from the spine as a reusable artifact, and the next run of
 // this shape reuses and fine-tunes it rather than starting cold.
-import { readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync, renameSync, rmSync, readdirSync, openSync, readSync, closeSync, fstatSync, unlinkSync } from 'node:fs';
+import { readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync, rmSync, readdirSync, openSync, readSync, closeSync, fstatSync, unlinkSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { execFileSync, spawn } from 'node:child_process';
 import { join, resolve, dirname, basename } from 'node:path';
+import { commitWork, removeWorktree } from './worktree.js';
+import { moveFile } from './movefile.js';
 import { runJob } from './run.js';
 import { moneyWithDraft } from './replay.js';
 import { jobSpecHash, resolveWorkerModel, validateJob } from './job.js';
@@ -268,6 +270,9 @@ class ExitSignal extends Error {
  * @property {string} [workdir] the patient's tree
  * @property {string} [seed] the patient's frozen seed commit
  * @property {string} [spineName] the spine directory name, beside `workdir`
+ * @property {string} [into] the source door's own directory (`source.json`, and the spine directory beside it).
+ *   Default `dirname(workdir)` — the copied-tree layout, where the tree is `<into>/tree`. A repo job on a WORKTREE
+ *   (P6 item 1) has its tree inside the person's repo, so its `into` is passed explicitly.
  * @property {string|null} [model] the raw `--model` tier name (`sonnet`/`haiku`), or null for the default
  * @property {string|null} [readShim] the raw `--read-shim` arm name, or null for the default
  * @property {string|null} [scout] the raw `--scout` value (`on`/`off`), or null for the default
@@ -299,6 +304,7 @@ class ExitSignal extends Error {
  * @property {string} workdir
  * @property {string} seed
  * @property {string} spineName
+ * @property {string} [into] see `RunOpts.into`
  * @property {string|null} model
  * @property {string|null} readShim
  * @property {string|null} scout
@@ -660,7 +666,10 @@ async function execute(ctx) {
    * both the RESUME reader below and the live run further down need them. Two spellings of
    * one path is how `--resume` comes to read a different directory than the run writes. */
   const wd = resolve(WORKDIR);
-  const spineDir = ctx.bundle ? ctx.bundle.runDir : join(wd, '..', target.spine);
+  /** the source door's own directory: where `source.json` sits and the spine directory goes. The copied-tree layout
+   * has the tree at `<into>/tree`, so `dirname(wd)`; a worktree run passes it (its tree is inside the person's repo). */
+  const into = ctx.into !== undefined ? resolve(ctx.into) : dirname(wd);
+  const spineDir = ctx.bundle ? ctx.bundle.runDir : join(into, target.spine);
   /** `--resume` takes the runid (the conventional `<spine dir>/u-<runid>.jsonl`) or an
    * explicit path — the path form is what makes these gates testable without touching
    * an operator's real spine directory. */
@@ -1767,7 +1776,7 @@ async function execute(ctx) {
   // manifest — that absence IS "repo jobs untouched", never an invented
   // destination for a job that declared none. A manifest that EXISTS but
   // cannot be read or parsed is a named $0 stop, never a silent skip.
-  const sourceManifest = await readSourceManifest(dirname(wd));
+  const sourceManifest = await readSourceManifest(into);
   if (sourceManifest.stop !== null) {
     emit('destination-refused', { code: sourceManifest.code, detail: sourceManifest.stop });
     emit('run-end', { outcome: 'escalated' });
@@ -1786,7 +1795,7 @@ async function execute(ctx) {
     // against `wd` alone let a destination at `<into>/profile.md` (inside the
     // run's own scratch area, outside the frozen tree, but still bareloop's
     // own scratch plumbing no destination should land in) slip through clean.
-    const dp = await proveDestination(frontDoor.destination, { into: dirname(wd) });
+    const dp = await proveDestination(frontDoor.destination, { into });
     if (dp.stop !== null) {
       emit('destination-refused', { code: dp.code, detail: dp.stop });
       emit('run-end', { outcome: 'escalated' });
@@ -2028,7 +2037,36 @@ async function execute(ctx) {
       const prior = readFileSync(auditFile, 'utf8');
       appendFileSync(auditFile, `${prior.length > 0 && !prior.endsWith('\n') ? '\n' : ''}${legAuditText}`);
       unlinkSync(auditSrc);
-    } else renameSync(auditSrc, auditFile);
+    } else moveFile(auditSrc, auditFile);
+  }
+  // ── P6 item 1: a repo job on a WORKTREE in the person's own repo. GREEN: the run's work is committed on its work
+  // branch and the worktree folder removed (an already-green is a green: a cold one has nothing to commit, a resumed one may hold uncommitted work) — the branch stays, and the merge stays the person's. Anything else
+  // (stopped, capped, died, red): the folder stays so Resume works, and the Ended block names it. A green that opened a
+  // review door is committed too (the branch always holds the work) but keeps its folder: an accept at the door re-runs
+  // the mechanical stages against that tree.
+  // It runs HERE, right after the gate-audit move, so a later readout step that throws can never skip the commit.
+  const doorHere = events.findLast((e) => e.type === 'review-door') ?? null;
+  /** @type {string | null} */
+  let worktreeLine = null;
+  const wtManifest = sourceManifest.present ? sourceManifest.manifest : null;
+  if (typeof wtManifest?.worktree === 'string' && typeof wtManifest?.repo === 'string') {
+    if (outcome === 'green' || outcome === 'already-green') {
+      const wb = events.findLast((e) => e.type === 'work-branch' && typeof e.branch === 'string') ?? null;
+      try {
+        // the branch ALWAYS holds a green's work (the panel tells the person to merge it); only the FOLDER waits on a door
+        const fin = commitWork(wd, `bareloop: ${spec.job} (run ${runid})`);
+        // an already-green COLD run never made a work branch (the close passed before any work): nothing to name
+        const done = fin.committed ? `final commit ${fin.sha}` : (wb ? 'nothing left to commit' : 'nothing was changed (the close already passed)');
+        const onBranch = wb?.branch ?? 'the work branch';
+        if (doorHere) worktreeLine = `\nWORKTREE  ${done}${wb || fin.committed ? ` on ${onBranch}` : ''}; the worktree folder is KEPT for the review door — ${wd}`;
+        else {
+          const gone = removeWorktree(wtManifest.repo, wd);
+          worktreeLine = `\nWORKTREE  ${done}${wb || fin.committed ? ` on ${onBranch}` : ''}; ${gone ? 'the worktree folder is removed' : `the worktree folder could not be removed — ${wd}`}`;
+        }
+      } catch (e) {
+        worktreeLine = `\nWORKTREE  the final commit failed, so the folder is KEPT: ${wd} (${redactSecrets(String(/** @type {Error} */ (e).message).split('\n')[0])})`;
+      }
+    }
   }
   const writes = audit.filter((e) => e.decision === 'allow' && (e.action?.type === 'write' || e.action?.type === 'edit'));
 
@@ -2178,7 +2216,7 @@ async function execute(ctx) {
     // as "contained". D3 rework: `destination` is a DIRECTORY now, and a job
     // may produce more than one file — `copyOut` delivers every non-empty file
     // under `output/`, each under its own dated name, and returns the list.
-    const co = await copyOut({ tree: wd, into: dirname(wd), destination: frontDoor.destination });
+    const co = await copyOut({ tree: wd, into, destination: frontDoor.destination });
     if (co.stop === null) {
       // `f.path`, never `frontDoor.destination` — each file lands under its
       // OWN dated name (M2b fix 4: `profile-2026-09-12.md`, `-2` the same
@@ -2264,7 +2302,6 @@ async function execute(ctx) {
   // ENDED and its verdict is minted — this readout offers the three doors over it and
   // changes nothing about the outcome printed above. Read off the run's own record
   // (never off a flag), so a green that opened no door prints exactly what it always did.
-  const doorHere = events.findLast((e) => e.type === 'review-door') ?? null;
   if (doorHere) {
     out('');
     for (const l of reviewDoorPackage({
@@ -2364,6 +2401,7 @@ async function execute(ctx) {
       out('MEMORY-CACHE  no record (run ended before its summary)');
     }
   }
+  if (worktreeLine !== null) out(worktreeLine);
   out(`\nspine     ${spineFile}`);
   out(`patient   left AS THE RUN LEFT IT (read it before the next run resets to the seed)`);
 
@@ -2393,6 +2431,7 @@ function buildCtx(mode, opts) {
     workdir: /** @type {string} */ (opts.workdir),
     seed: /** @type {string} */ (opts.seed),
     spineName: /** @type {string} */ (opts.spineName),
+    ...(opts.into === undefined ? {} : { into: opts.into }),
     model: opts.model ?? null,
     readShim: opts.readShim ?? null,
     scout: opts.scout ?? null,
@@ -2489,7 +2528,7 @@ export async function main(argv, deps = {}) {
       die(`give one of --job <key> (one of: ${Object.keys(JOBS).join(', ')}) or --spec <path to resolved-spec.json> `
         + '— a run has to name a job one of the two ways.');
     }
-    /** @type {{spec: string, workdir: string, spine: string, seed: string}} */
+    /** @type {{spec: string, workdir: string, spine: string, seed: string, into?: string}} */
     let target;
     /** the spec's own path, wherever it was found — a `jobs/` file for `--job`,
      * an arbitrary `resolved-spec.json` for `--spec`. */
@@ -2588,9 +2627,14 @@ export async function main(argv, deps = {}) {
       if (typeof seed !== 'string' || !seed) {
         die(`--spec ${specPath}: ${into}/source.json carries no seed commit — not a prepared copy this runner can trust`);
       }
-      const specWorkdir = join(into, 'tree');
+      // P6 item 1: a repo job's tree is a WORKTREE in the person's own repo, recorded in the manifest; every other prepared
+      // copy keeps its tree at `<into>/tree`
+      const worktreeRun = typeof manifestRead.manifest.worktree === 'string' && manifestRead.manifest.worktree !== '';
+      const specWorkdir = worktreeRun ? manifestRead.manifest.worktree : join(into, 'tree');
       if (!existsSync(specWorkdir) || !existsSync(join(specWorkdir, '.git'))) {
-        die(`--spec ${specPath}: the prepared copy's tree is gone (${specWorkdir} has no .git) — nothing to run against; re-prepare the source`);
+        die(worktreeRun
+          ? `--spec ${specPath}: the job's worktree is gone (${specWorkdir} has no .git) — nothing to run against; start the job again from the page`
+          : `--spec ${specPath}: the prepared copy's tree is gone (${specWorkdir} has no .git) — nothing to run against; re-prepare the source`);
       }
       target = {
         // display-only in --spec mode (SPEC_DESC below is what actually prints)
@@ -2601,6 +2645,7 @@ export async function main(argv, deps = {}) {
         // is, just computed instead of typed by a developer.
         spine: `${spec.job}-bareloop`,
         seed,
+        into,
       };
       SELECTOR = `--spec ${specPath}`;
       SPEC_DESC = specPath;
@@ -2614,6 +2659,7 @@ export async function main(argv, deps = {}) {
       workdir: target.workdir,
       seed: target.seed,
       spineName: target.spine,
+      ...(target.into === undefined ? {} : { into: target.into }),
       model: argFlag('model'),
       readShim: argFlag('read-shim'),
       scout: argFlag('scout'),

package/src/worktree.js

@@ -0,0 +1,120 @@
+// The ONE spelling of "a run's tree is a git worktree inside the person's own repo"
+// (`<repo>/.bareloop/wt/<id>`, detached at the repo's HEAD). Two doors make that tree: the bundle runner
+// (`src/bundlerun.js`) and the panel's drafting session (`src/panel/authorsession.js`, through the source
+// door's `worktree` option). Neither carries its own copy of the `git worktree add` call.
+//
+// Plain git, no dependency. Every helper takes the repo ROOT (the directory whose `.git` is the real
+// repository), never a subfolder.
+
+import { execFileSync } from 'node:child_process';
+import {
+  appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+/** the line that hides bareloop's own folder from the person's `git status` (anchored at the repo root) */
+export const EXCLUDE_LINE = '/.bareloop/';
+
+/** the line that hides installed packages at any depth */
+export const NODE_MODULES_LINE = 'node_modules/';
+
+/** the person's git hooks never run for anything bareloop does in their repo: one spelling, used by `addWorktree` and `commitWork` */
+const NO_HOOKS = ['-c', 'core.hooksPath=/dev/null/bareloop-no-hooks'];
+
+/** where a run's worktree lives in the person's repo @param {string} repo @param {string} id */
+export function worktreePath(repo, id) {
+  return join(repo, '.bareloop', 'wt', id);
+}
+
+/**
+ * `git worktree add --detach <dir> HEAD` in `repo` (none of the person's hooks run), creating `dir`'s parent first. Throws
+ * `Error('git worktree add failed: …')` — a caller decides whether that is a stop or a refusal.
+ * @param {string} repo @param {string} dir
+ */
+export function addWorktree(repo, dir) {
+  mkdirSync(dirname(dir), { recursive: true });
+  try {
+    execFileSync('git', [...NO_HOOKS, '-C', repo, 'worktree', 'add', '--detach', dir, 'HEAD'], { encoding: 'utf8' });
+  } catch (e) {
+    throw new Error(`git worktree add failed: ${/** @type {Error} */ (e).message}`);
+  }
+}
+
+/**
+ * How many paths `git status --porcelain` lists in `repo` (tracked edits AND untracked files); 0 for a clean
+ * tree. A repo git cannot read counts as 0 — this feeds a notice, never a refusal.
+ * @param {string} repo @returns {number}
+ */
+export function uncommittedCount(repo) {
+  try {
+    const out = execFileSync('git', ['-C', repo, 'status', '--porcelain'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    return out.split('\n').filter((l) => l.trim() !== '').length;
+  } catch { return 0; }
+}
+
+/** the short sha of `repo`'s HEAD, or null @param {string} repo @returns {string|null} */
+export function shortHead(repo) {
+  try {
+    return execFileSync('git', ['-C', repo, 'rev-parse', '--short', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+  } catch { return null; }
+}
+
+/**
+ * Hide `.bareloop/` and `node_modules/` (packages installed in a worktree must not read as worker writes) from the person's own `git status` through the repo's PRIVATE exclude file
+ * (`<common-git-dir>/info/exclude`), never their tracked `.gitignore`. The common dir, not `.git`: in a linked
+ * worktree `.git` is a file and the shared `info/exclude` lives in the main repository's git dir. Idempotent —
+ * each line is checked separately and never written twice.
+ * @param {string} repo
+ * @returns {boolean} true when the line was added now
+ */
+export function hideBareloopDir(repo) {
+  const common = execFileSync('git', ['-C', repo, 'rev-parse', '--git-common-dir'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  const exclude = join(resolve(repo, common), 'info', 'exclude');
+  mkdirSync(dirname(exclude), { recursive: true });
+  const text = existsSync(exclude) ? readFileSync(exclude, 'utf8') : '';
+  const have = new Set(text.split('\n').map((l) => l.trim()));
+  const missing = [EXCLUDE_LINE, NODE_MODULES_LINE].filter((l) => !have.has(l));
+  if (missing.length === 0) return false;
+  const add = `${missing.join('\n')}\n`;
+  if (text === '') writeFileSync(exclude, add);
+  else appendFileSync(exclude, `${text.endsWith('\n') ? '' : '\n'}${add}`);
+  return true;
+}
+
+/**
+ * Remove a run's worktree folder from `repo` (`git worktree remove --force`: the folder may hold untracked
+ * scratch — a `.litectx/` index, the gate-audit file — and what matters is on the branch by now). Never throws.
+ * @param {string} repo @param {string} dir
+ * @returns {boolean} true when the folder is gone afterwards
+ */
+export function removeWorktree(repo, dir) {
+  try {
+    execFileSync('git', ['-C', repo, 'worktree', 'remove', '--force', dir], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch { /* fall through: report what is on disk */ }
+  return !existsSync(dir);
+}
+
+/** a commit bareloop makes in the person's repo is authored by bareloop (never their global config), signs nothing, runs none of their hooks */
+const COMMIT_CONFIG = [
+  '-c', 'user.name=bareloop', '-c', 'user.email=bareloop@localhost', '-c', 'commit.gpgsign=false',
+  ...NO_HOOKS,
+];
+
+/** what never goes into the work commit: the arbiter's own books and installed packages */
+const NOT_WORK = [':(exclude).smoke', ':(exclude).litectx', ':(exclude)gate-audit.jsonl', ':(exclude,glob)**/node_modules/**'];
+
+/**
+ * The run's final commit, on whatever branch the worktree stands on: everything the run changed except the
+ * arbiter's books and `node_modules`. Nothing changed = no commit (a green with nothing to commit is still a green).
+ * Throws on a git failure — the caller must not remove a worktree whose work is not safely on the branch.
+ * @param {string} dir the worktree
+ * @param {string} message
+ * @returns {{committed: boolean, sha: string}}
+ */
+export function commitWork(dir, message) {
+  const run = (/** @type {string[]} */ args) => execFileSync('git', ['-C', dir, ...COMMIT_CONFIG, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  run(['add', '-A', '--', '.', ...NOT_WORK]);
+  const staged = run(['diff', '--cached', '--name-only']).trim();
+  if (staged !== '') run(['commit', '-q', '-m', message]);
+  return { committed: staged !== '', sha: run(['rev-parse', '--short', 'HEAD']).trim() };
+}

package/types/draftspend.d.ts

@@ -1,3 +1,18 @@
+/**
+ * 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: string, ev: DraftEvent): void;
 /**
  * @typedef {object} DraftSpend
  * @property {string} sessionId
@@ -25,7 +40,80 @@ export function readOrphanDraftSpends(opts?: {
     home?: string;
     sessionsRoot?: string;
 }): DraftSpend[];
+/**
+ * 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: {
+    spine?: string;
+    patient?: string | null;
+}, opts?: {
+    home?: string;
+    sessionsRoot?: string;
+}): string | 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: string): {
+    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;
+    }[];
+}[];
+/**
+ * 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?: string;
+    patient?: string | null;
+}, spine: {
+    draftSpentUsd: number | null;
+    draftSpendComplete: boolean | null;
+}, opts?: {
+    home?: string;
+    sessionsRoot?: string;
+}): any | null;
 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)
+ */
+export type DraftEvent = {
+    kind: string;
+    no: number;
+    at: string;
+    [k: string]: any;
+};
 export type DraftSpend = {
     sessionId: string;
     /**

package/types/legs.d.ts

@@ -49,7 +49,7 @@ export function parseSpineText(raw: string): {
 export function watchdogNotePath(spineFile: string, leg: number): string;
 /**
  * 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/types/movefile.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @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: string, dst: string, deps?: {
+    rename?: (a: string, b: string) => void;
+}): void;

package/types/npminstall.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * 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 function runNpmCi(cwd: string, { timeoutMs, env, run }?: {
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    run?: typeof spawnClose;
+}): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/** 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: 600000;
+/** the lock files whose gap command is `npm ci` (the rule table in src/source.js, LOCKFILE_COMMANDS) */
+export const NPM_CI_LOCKS: readonly string[];
+import { spawnClose } from './ralph.js';

package/types/panel/authorsession.d.ts

@@ -108,7 +108,7 @@ export function validateJobCard(card: any, opts?: {
  * @param {any} card the validated job card (see {@link validateJobCard})
  * @param {{env?: Record<string,string|undefined>, sessionsRoot?: string, home?: string, timeoutMs?: number,
  *   scout?: any, generate?: Function, confirmGenerate?: Function, authorFn?: Function,
- *   prepareSigningFn?: Function, reuse?: {spec: any, workflowKey: string}}} [deps] `scout`..`prepareSigningFn` are
+ *   prepareSigningFn?: Function, npmCiFn?: Function, reuse?: {spec: any, workflowKey: string}}} [deps] `scout`..`prepareSigningFn` are
  *   TEST SEAMS ONLY — see the note just above where each is read, below. `reuse` (Reuse workflow) is NOT a seam: the
  *   caller (`/api/author/start`) sets it only when the server's own same-job rule held.
  * @returns {any} the session object
@@ -123,6 +123,7 @@ export function createSession(card: any, deps?: {
     confirmGenerate?: Function;
     authorFn?: Function;
     prepareSigningFn?: Function;
+    npmCiFn?: Function;
     reuse?: {
         spec: any;
         workflowKey: string;

package/types/panel/server.d.ts

@@ -119,7 +119,9 @@ export function legDividersFor(spineRecords: any[], parts: any[]): {
  * (replaces P5 item 3, 2026-10-03) is offered on green rows only, and starts a NEW run.
  * @param {{outcome: string|null, stopReason: string|null, spentUsd: number|null, budgetUsd: number|null, lastEscalation?: any}} summary
  * @param {{died: boolean, lastThing: string|null}} death
- * @param {{resume?: {ok: boolean, why?: string}|null, destinationRefused?: string|null, moneyHalt?: boolean}} [o]
+ * @param {{resume?: {ok: boolean, why?: string}|null, destinationRefused?: string|null, moneyHalt?: boolean,
+ *   worktree?: {folder: string, repo: string, branch: string|null, exists: boolean}|null}} [o]
+ *   `worktree` (P6 item 1): the run's worktree in the person's repo, from {@link worktreeOfRun}; absent for every other run
  * @returns {{reason: string, next: string, line: string, actions: {id: string, label: string}[]}|null}
  */
 export function endedFor(summary: {
@@ -138,6 +140,12 @@ export function endedFor(summary: {
     } | null;
     destinationRefused?: string | null;
     moneyHalt?: boolean;
+    worktree?: {
+        folder: string;
+        repo: string;
+        branch: string | null;
+        exists: boolean;
+    } | null;
 }): {
     reason: string;
     next: string;
@@ -487,7 +495,8 @@ export function handleRequest(req: import("node:http").IncomingMessage, res: imp
  * this package's own `bin/bareloop.mjs`).
  * @param {{ port?: number, home?: string, env?: Record<string,string|undefined>,
  *   sessionsRoot?: string, spawnFn?: (...a: any[]) => any, bareloopBin?: string,
- *   fetchImpl?: typeof fetch, settleMs?: number, userHome?: string }} [opts]
+ *   fetchImpl?: typeof fetch, settleMs?: number, userHome?: string,
+ *   openFolderSpawn?: (cmd: string, args: string[], o: object) => any, platform?: string }} [opts]
  * @returns {Promise<{ server: import('node:http').Server, port: number, token: string, close: () => Promise<void> }>}
  */
 export function createPanelServer(opts?: {
@@ -500,6 +509,8 @@ export function createPanelServer(opts?: {
     fetchImpl?: typeof fetch;
     settleMs?: number;
     userHome?: string;
+    openFolderSpawn?: (cmd: string, args: string[], o: object) => any;
+    platform?: string;
 }): Promise<{
     server: import("node:http").Server;
     port: number;

package/types/panel/settingsroutes.d.ts

@@ -1,6 +1,9 @@
 /**
+ * `openFolderSpawn` / `platform` are test seams for the Open keys folder button (a real caller passes
+ * neither: `child_process.spawn` and `process.platform`).
  * @param {{ port: number, token: string, home?: string, env?: Record<string,string|undefined>,
- *   fetchImpl?: typeof fetch, now?: () => number }} opts
+ *   fetchImpl?: typeof fetch, now?: () => number, openFolderSpawn?: (cmd: string, args: string[], o: object) => any,
+ *   platform?: string }} opts
  */
 export function createSettingsRoutes(opts: {
     port: number;
@@ -9,6 +12,8 @@ export function createSettingsRoutes(opts: {
     env?: Record<string, string | undefined>;
     fetchImpl?: typeof fetch;
     now?: () => number;
+    openFolderSpawn?: (cmd: string, args: string[], o: object) => any;
+    platform?: string;
 }): {
     handle: (req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse, pathname: string, body: any) => boolean;
 };

package/types/ralph.d.ts

@@ -1,3 +1,22 @@
+/**
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{env: NodeJS.ProcessEnv, cwd?: string, timeoutMs?: number}} o
+ * @returns {Promise<{error: (Error & {code?: string})|null, status: number|null, signal: string|null, stdout: string, stderr: string}>}
+ */
+export function spawnClose(cmd: string, args: string[], { env, cwd, timeoutMs }: {
+    env: NodeJS.ProcessEnv;
+    cwd?: string;
+    timeoutMs?: number;
+}): Promise<{
+    error: (Error & {
+        code?: string;
+    }) | null;
+    status: number | null;
+    signal: string | null;
+    stdout: string;
+    stderr: string;
+}>;
 /**
  * Run a close command; its exit code is the verdict (hard green, PRD §4).
  * `expect` → satisfied; any other exit → needs_revision (gap fed back).

package/types/source.d.ts

@@ -71,19 +71,25 @@ export function looksLikeRepoSource(source: string): boolean;
  * as declared, unvalidated by `proveDestination`, and `frontDoorFromManifest`
  * never hands a repo source's destination to `copyOut` — wiring it into
  * `writeScope` is M3/M4's job, not this one.
- * @param {{source: string, into: string, destination?: string,
+ * `worktree` (P6 item 1, repo sources ONLY — ignored for every other kind): instead of COPYING the repo, make the
+ * run's tree a detached git worktree of the person's own repo at that directory (the shared
+ * `src/worktree.js`, the bundle door's own spelling), hide `.bareloop/` from their `git status`, and record the
+ * worktree and the repo root in the manifest. `into` then holds only `source.json`; the tree is `worktree`, at the
+ * repo's current commit (uncommitted edits are NOT in it). No seed commit is made — the seed IS the repo's HEAD.
+ * @param {{source: string, into: string, destination?: string, worktree?: string,
  *   fetchTimeoutMs?: number, afterScan?: () => (void|Promise<void>)}} args
  *   `fetchTimeoutMs` is test-only — production callers omit it and get
  *   `PROVIDER_TIMEOUT_MS`. `afterScan` is a test seam too: called exactly once,
  *   after the secret scan finished and before the freeze loop re-reads any
  *   file's bytes, so a test can swap a file inside that window
  *   deterministically. Production never sets it; absent, behaviour is unchanged.
- * @returns {Promise<{stop: null, into: string, tree: string, manifestPath: string, manifest: object}|SourceRefusal>}
+ * @returns {Promise<{stop: null, into: string, tree: string, manifestPath: string, manifest: Record<string, any>}|SourceRefusal>}
  */
-export function prepareSource({ source, into, destination, fetchTimeoutMs, afterScan }: {
+export function prepareSource({ source, into, destination, worktree, fetchTimeoutMs, afterScan }: {
     source: string;
     into: string;
     destination?: string;
+    worktree?: string;
     fetchTimeoutMs?: number;
     afterScan?: () => (void | Promise<void>);
 }): Promise<{
@@ -91,7 +97,7 @@ export function prepareSource({ source, into, destination, fetchTimeoutMs, after
     into: string;
     tree: string;
     manifestPath: string;
-    manifest: object;
+    manifest: Record<string, any>;
 } | SourceRefusal>;
 /**
  * THE INSTALL-GAP DETECTOR (PRD item 33 close-out, `docs/product/PRD.md:450-452`,
@@ -127,13 +133,15 @@ export function prepareSource({ source, into, destination, fetchTimeoutMs, after
  *   manifest)
  * @param {string} [sourceSubdir] the manifest's own `sourceSubdir` ('' or
  *   undefined when Source IS the repo root)
- * @returns {{manager: string, command: string, reason: string}|null} `null`
+ * @returns {{dir: string, lockFile: string|null, manager: string, command: string, reason: string}|null} `null`
  *   when there is nothing to report: no JS/TS manifest found walking up from
  *   `sourceSubdir` to `treeDir`, the nearest one found has no dependencies,
  *   `node_modules` is already there, or the manifest cannot even be read as
  *   JSON (an invalid `package.json` is "cannot tell", never a false alarm).
  */
 export function missingDependencies(treeDir: string, sourceSubdir?: string): {
+    dir: string;
+    lockFile: string | null;
     manager: string;
     command: string;
     reason: string;

package/types/userrun.d.ts

@@ -129,6 +129,12 @@ export type RunOpts = {
      * the spine directory name, beside `workdir`
      */
     spineName?: string | undefined;
+    /**
+     * the source door's own directory (`source.json`, and the spine directory beside it).
+     * Default `dirname(workdir)` — the copied-tree layout, where the tree is `<into>/tree`. A repo job on a WORKTREE
+     * (P6 item 1) has its tree inside the person's repo, so its `into` is passed explicitly.
+     */
+    into?: string | undefined;
     /**
      * the raw `--model` tier name (`sonnet`/`haiku`), or null for the default
      */
@@ -194,6 +200,10 @@ export type RunCtx = {
     workdir: string;
     seed: string;
     spineName: string;
+    /**
+     * see `RunOpts.into`
+     */
+    into?: string | undefined;
     model: string | null;
     readShim: string | null;
     scout: string | null;