bareloop 0.35.0 → 0.37.0

package/types/planrun.d.ts

@@ -397,10 +397,10 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  *   the resume-plan-red option, the fix-loop terminal) say "resume is `run-u`-only
  *   in v1" instead of naming a flag that would fail if typed.
  * @param {string|null} [opts.stopFile=null] P5 item 5 — the run's STOP REQUEST file
- *   (`stopFilePath(spine)`, src/legs.js). Read at ONE seam, the round boundary of a step worker
- *   (the `metered` callback, where the money cap binds): present = emit `stop-requested`, consume
+ *   (`stopFilePath(spine)`, src/legs.js). Read at ONE seam, the round boundary of EVERY worker
+ *   (scout, plan/replan drafter, step, close-fix: the `metered` callback, where the money cap binds): present = emit `stop-requested`, consume
  *   the file, end the Loop after that round, and end the leg `stopped` (a checkpoint outcome, filed
- *   the way a mid-step cap-halt is; resume re-enters that step). Nothing is in flight at that
+ *   the way a mid-step cap-halt is; resume re-enters that step, or continues the phase). Nothing is in flight at that
  *   point, so the spend is exact. `null` = no stop surface (the default).
  * @returns {Promise<string>} 'green' | 'already-green' | 'escalated' | 'plan-red' |
  *   'check-red' | 'close-red' | 'close-unsupported' | 'recipe-stale' | 'pricing-red' |

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;
@@ -289,6 +297,13 @@ export function frontDoorFromManifest(read: {
 }): {
     destination: string;
 } | null;
+/**
+ * The $0 refusal for a non-repo source, worded by the kind the source door recorded (`prep.manifest.kind`) — a single
+ * file is not a "folder", and Source must be the repo folder with the file named in Destination (hamr 2026-10-05).
+ * @param {string} kind `prep.manifest.kind`: 'file' | 'folder' | 'url' (a 'repo' never reaches this)
+ * @returns {string}
+ */
+export function nonRepoSourceMessage(kind: string): string;
 /**
  * a named, non-throwing stop
  */

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;

package/types/worktree.d.ts

@@ -0,0 +1,48 @@
+/** where a run's worktree lives in the person's repo @param {string} repo @param {string} id */
+export function worktreePath(repo: string, id: string): string;
+/**
+ * `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: string, dir: string): void;
+/**
+ * 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: string): number;
+/** the short sha of `repo`'s HEAD, or null @param {string} repo @returns {string|null} */
+export function shortHead(repo: string): string | 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: string): boolean;
+/**
+ * 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: string, dir: string): boolean;
+/**
+ * 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: string, message: string): {
+    committed: boolean;
+    sha: string;
+};
+/** 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/";