@dynamicagents/plugins 0.11.0 → 0.12.0

package/dist/computer/install.d.ts

@@ -52,9 +52,8 @@ export interface InstallProbe {
  * `npm ci`.
  *
  * `JobState` intersects `TExtra` into its `running`/`done`/`failed` variants
- * instead of nesting it under `meta`, so this alias is byte-identical to the
- * hand-written union it replaced. Every reader still spells `status.command` at
- * the top level and no call site moved.
+ * rather than nesting it under `meta`, so a reader spells `status.command` at
+ * the top level.
  */
 export type InstallState = JobState<{
     command: string;
@@ -137,8 +136,7 @@ export declare function resolveInstallCommand(fs: InstallProbe, dir: string, pla
  *
  * Content, not mtime: a `git fetch && reset --hard` onto a new commit rewrites
  * these files whether or not their dependencies changed, and re-installing on
- * every commit would throw away the thing that makes a warm container worth
- * having.
+ * every commit would throw away a tree that is already correct.
  *
  * ## Both files, not just the lockfile
  *
@@ -171,8 +169,8 @@ export declare function resolveInstallCommand(fs: InstallProbe, dir: string, pla
  * {@link INSTALL_CONFIG_FILES} is hashed too, for the same reason `package.json`
  * is: a lockfile says which versions, and `.npmrc` says how they are laid out.
  * Flipping pnpm's `node-linker` to `hoisted` produces a different
- * `node_modules` from a byte-identical lockfile, and a warm container would
- * otherwise skip the reinstall that change requires.
+ * `node_modules` from a byte-identical lockfile, and a matching fingerprint
+ * would otherwise skip the reinstall that change requires.
  *
  * The residual is worth stating because it cannot be closed here: an override
  * that *builds* — `npm ci && npm run build`, the documented example — is not
@@ -184,10 +182,8 @@ export declare function resolveInstallCommand(fs: InstallProbe, dir: string, pla
  * ## This is only half of the skip condition
  *
  * A matching fingerprint means "the same install would produce the same tree".
- * It does **not** mean the tree is there. `node_modules` lives in the container
- * and dies with it, while this fingerprint is stored in the Durable Object and
- * does not — so on a cold container the two disagree, and a caller that skips on
- * the fingerprint alone skips the install that the empty tree needs most. The
- * caller must also confirm `node_modules` is actually present.
+ * It does **not** mean the tree is there: it is on the container's disk, and
+ * goes with the container. The caller also needs a record that this container
+ * finished it — see `./host/install-job.ts`.
  */
 export declare function installFingerprint(fs: InstallProbe, dir: string, resolution: InstallResolution): Promise<string | null>;

package/dist/computer/install.js

@@ -211,8 +211,7 @@ async function firstPresent(fs, dir, names) {
  *
  * Content, not mtime: a `git fetch && reset --hard` onto a new commit rewrites
  * these files whether or not their dependencies changed, and re-installing on
- * every commit would throw away the thing that makes a warm container worth
- * having.
+ * every commit would throw away a tree that is already correct.
  *
  * ## Both files, not just the lockfile
  *
@@ -245,8 +244,8 @@ async function firstPresent(fs, dir, names) {
  * {@link INSTALL_CONFIG_FILES} is hashed too, for the same reason `package.json`
  * is: a lockfile says which versions, and `.npmrc` says how they are laid out.
  * Flipping pnpm's `node-linker` to `hoisted` produces a different
- * `node_modules` from a byte-identical lockfile, and a warm container would
- * otherwise skip the reinstall that change requires.
+ * `node_modules` from a byte-identical lockfile, and a matching fingerprint
+ * would otherwise skip the reinstall that change requires.
  *
  * The residual is worth stating because it cannot be closed here: an override
  * that *builds* — `npm ci && npm run build`, the documented example — is not
@@ -258,11 +257,9 @@ async function firstPresent(fs, dir, names) {
  * ## This is only half of the skip condition
  *
  * A matching fingerprint means "the same install would produce the same tree".
- * It does **not** mean the tree is there. `node_modules` lives in the container
- * and dies with it, while this fingerprint is stored in the Durable Object and
- * does not — so on a cold container the two disagree, and a caller that skips on
- * the fingerprint alone skips the install that the empty tree needs most. The
- * caller must also confirm `node_modules` is actually present.
+ * It does **not** mean the tree is there: it is on the container's disk, and
+ * goes with the container. The caller also needs a record that this container
+ * finished it — see `./host/install-job.ts`.
  */
 export async function installFingerprint(fs, dir, resolution) {
     if (resolution.kind !== "run")

package/dist/computer/paths.d.ts

@@ -1,16 +1,15 @@
 /**
  * Which paths these tools act on, and the sentence a refused one gets.
  *
- * Two lists that look alike and mean opposite things. `node_modules` is *absent*
- * — physics, decided by `computerd` — so its note explains a file that is really
- * there and names the tool that can reach it. `.git` is present, readable, and
- * refused anyway — policy, decided here — so its note names where repository work
- * belongs. Two reasons want two sentences, which is why they are not one list.
+ * Both refused directories are also skipped by every walk. `.git` is refused as
+ * policy: a model that edits `.git/HEAD` corrupts a checkout in a way that
+ * surfaces much later. `node_modules` is refused as a fact: it lives on the
+ * container's disk (see `./host/container-deps.ts`), so these tools, which read
+ * the workspace, would find it empty.
  *
  * Everything here is a string comparison: no filesystem, no `await`, which is
  * what lets {@link guardPath} run before a tool opens the workspace at all.
  */
-export declare function isContainerOnly(path: string): boolean;
 /**
  * Is this path inside git's internal state?
  *
@@ -18,27 +17,33 @@ export declare function isContainerOnly(path: string): boolean;
  * checkout in a way that surfaces much later as an inexplicable git failure.
  *
  * Exact segment rather than substring, so `.gitignore`, `.gitattributes` and
- * `.github/` are untouched — the same trap `node_modules_old` sets one function up.
+ * `.github/` are untouched.
  */
 export declare function isGitInternal(path: string): boolean;
+/**
+ * What every walk steps over. `find` prunes these in the store; `grep` takes no
+ * exclusion, so `sb_grep` filters its results instead.
+ */
+export declare const WALK_SKIPS: readonly [".git", "node_modules"];
+/** Whether a walk carrying `skips` steps over `path`. */
+export declare function isSkipped(skips: readonly string[], path: string): boolean;
+/** The skipped directories, for a sentence: "`.git` and `node_modules`". */
+export declare function skipNames(skips: readonly string[]): string;
 /**
  * The path check every file tool makes, before it opens anything.
  *
- * Returns the sentence to hand back, or `undefined` to proceed. Two string
- * comparisons — no `stat`, no round trip — which is why all six tools can afford
- * to call it before the workspace is opened.
+ * Returns the sentence to hand back, or `undefined` to proceed. One string
+ * comparison — no `stat`, no round trip — which is why every file tool can
+ * afford to call it before the workspace is opened.
  *
  * ## A redirect, not a boundary
  *
- * `node_modules` is a fact about the substrate and the note names the tool that
- * can see it; `.git` is a rule about where repository work belongs and the note
- * names the tools it belongs to. Both catch the case that actually happens — a
- * model reaching into `.git/HEAD` to fix a merge, or reading a dependency's
- * source and finding nothing there.
+ * The note names the tools repository work belongs to, because the case that
+ * actually happens is a model reaching into `.git/HEAD` to fix a merge.
  *
  * It is not containment, and this is the only place worth saying so. `sb_exec`
  * is in the same tool family, granted per family rather than per tool, so every
- * agent holding these six also holds a shell that reads and writes `.git`
+ * agent holding these file tools also holds a shell that reads and writes `.git`
  * directly.
  *
  * Symlinks are not resolved, for the same reason: a tracked

package/dist/computer/paths.js

@@ -1,35 +1,18 @@
 /**
  * Which paths these tools act on, and the sentence a refused one gets.
  *
- * Two lists that look alike and mean opposite things. `node_modules` is *absent*
- * — physics, decided by `computerd` — so its note explains a file that is really
- * there and names the tool that can reach it. `.git` is present, readable, and
- * refused anyway — policy, decided here — so its note names where repository work
- * belongs. Two reasons want two sentences, which is why they are not one list.
+ * Both refused directories are also skipped by every walk. `.git` is refused as
+ * policy: a model that edits `.git/HEAD` corrupts a checkout in a way that
+ * surfaces much later. `node_modules` is refused as a fact: it lives on the
+ * container's disk (see `./host/container-deps.ts`), so these tools, which read
+ * the workspace, would find it empty.
  *
  * Everything here is a string comparison: no filesystem, no `await`, which is
  * what lets {@link guardPath} run before a tool opens the workspace at all.
  */
-/**
- * Whether a path sits under a directory the workspace never receives.
- *
- * Only `node_modules` today, and it is not configurable here because it is not
- * our choice: `computerd` applies its own `DEFAULT_IGNORE` container-side, and
- * this list exists to *predict* that so a read can explain itself rather than
- * reporting a missing file. A dependency the model can plainly see in a `ls` but
- * cannot read is the kind of thing that sends it hunting for the wrong bug.
- */
-const CONTAINER_ONLY_SEGMENTS = ["node_modules"];
-export function isContainerOnly(path) {
-    return path
-        .split("/")
-        .some((segment) => CONTAINER_ONLY_SEGMENTS.includes(segment));
-}
-/** The sentence a container-only path gets instead of "not found". */
-function containerOnlyNote(path, verb) {
-    return (`${path} is inside node_modules, which lives only in the container and is ` +
-        `not part of the durable workspace — ${verb} cannot see it. Use \`sb_exec\` ` +
-        `(for example \`cat ${path}\`) to read it through the shell instead.`);
+/** Whether any segment of `path` is exactly `segment`. */
+function hasSegment(path, segment) {
+    return path.split("/").includes(segment);
 }
 /**
  * Is this path inside git's internal state?
@@ -38,10 +21,32 @@ function containerOnlyNote(path, verb) {
  * checkout in a way that surfaces much later as an inexplicable git failure.
  *
  * Exact segment rather than substring, so `.gitignore`, `.gitattributes` and
- * `.github/` are untouched — the same trap `node_modules_old` sets one function up.
+ * `.github/` are untouched.
  */
 export function isGitInternal(path) {
-    return path.split("/").includes(".git");
+    return hasSegment(path, ".git");
+}
+/**
+ * What every walk steps over. `find` prunes these in the store; `grep` takes no
+ * exclusion, so `sb_grep` filters its results instead.
+ */
+export const WALK_SKIPS = [".git", "node_modules"];
+/** Whether a walk carrying `skips` steps over `path`. */
+export function isSkipped(skips, path) {
+    return skips.some((segment) => hasSegment(path, segment));
+}
+/** The skipped directories, for a sentence: "`.git` and `node_modules`". */
+export function skipNames(skips) {
+    const quoted = skips.map((segment) => `\`${segment}\``);
+    return quoted.length > 1
+        ? `${quoted.slice(0, -1).join(", ")} and ${quoted[quoted.length - 1]}`
+        : (quoted[0] ?? "");
+}
+/** The sentence a `node_modules` path gets. */
+function dependencyTreeNote(path, verb) {
+    return (`${path} is inside node_modules, which lives on the container's disk rather ` +
+        `than in the workspace ${verb} works on. Use sb_exec there — ` +
+        `\`cat\`, \`ls\`, \`rg\`.`);
 }
 /**
  * The sentence a `.git` path gets.
@@ -67,21 +72,18 @@ function gitInternalNote(path, verb) {
 /**
  * The path check every file tool makes, before it opens anything.
  *
- * Returns the sentence to hand back, or `undefined` to proceed. Two string
- * comparisons — no `stat`, no round trip — which is why all six tools can afford
- * to call it before the workspace is opened.
+ * Returns the sentence to hand back, or `undefined` to proceed. One string
+ * comparison — no `stat`, no round trip — which is why every file tool can
+ * afford to call it before the workspace is opened.
  *
  * ## A redirect, not a boundary
  *
- * `node_modules` is a fact about the substrate and the note names the tool that
- * can see it; `.git` is a rule about where repository work belongs and the note
- * names the tools it belongs to. Both catch the case that actually happens — a
- * model reaching into `.git/HEAD` to fix a merge, or reading a dependency's
- * source and finding nothing there.
+ * The note names the tools repository work belongs to, because the case that
+ * actually happens is a model reaching into `.git/HEAD` to fix a merge.
  *
  * It is not containment, and this is the only place worth saying so. `sb_exec`
  * is in the same tool family, granted per family rather than per tool, so every
- * agent holding these six also holds a shell that reads and writes `.git`
+ * agent holding these file tools also holds a shell that reads and writes `.git`
  * directly.
  *
  * Symlinks are not resolved, for the same reason: a tracked
@@ -96,9 +98,9 @@ function gitInternalNote(path, verb) {
  * segment.
  */
 export function guardPath(path, verb) {
-    if (isContainerOnly(path))
-        return containerOnlyNote(path, verb);
     if (isGitInternal(path))
         return gitInternalNote(path, verb);
+    if (hasSegment(path, "node_modules"))
+        return dependencyTreeNote(path, verb);
     return undefined;
 }

package/dist/computer/read.d.ts

@@ -27,18 +27,14 @@ import type { WorkspaceClient } from "@cloudflare/computer";
  *
  * `maxChars` is a character ceiling everywhere else — see
  * {@link ComputerConfig.maxOutputChars} — and here it is spent against
- * `byteOffset`/`byteLength`, which are the only units the transport has. That is
- * deliberate and it is safe in the direction that matters: a UTF-8 byte is never
- * more than one UTF-16 code unit, so *N* bytes decode to at most *N* characters.
- * Reading the character budget as bytes therefore always honours the ceiling,
- * and errs low on a file that is mostly non-ASCII — a CJK source file is cut at
- * about a third of the characters it could have shown. The alternative is a
- * second round trip to measure what the first one returned, on every read, to
- * recover a bound the marker already announces.
- *
- * The other reason it cannot be characters is the one this function exists for:
- * bounding the *transport*. A byte range is what stops a 4 MB lockfile being
- * materialised in a 128 MB isolate before anything is thrown away.
+ * `byteOffset`/`byteLength`, which are the only units the transport has, and the
+ * only ones that bound what crosses it. Safe in the direction that matters: a
+ * UTF-8 byte is never more than one UTF-16 code unit, so *N* bytes decode to at
+ * most *N* characters. Reading the character budget as bytes therefore always
+ * honours the ceiling, and errs low on a file that is mostly non-ASCII — a CJK
+ * source file is cut at about a third of the characters it could have shown. The
+ * alternative is a second round trip on every read, to recover a bound the
+ * marker already announces.
  *
  * ## Why `stat` first
  *
@@ -73,20 +69,20 @@ export declare function readWindow(fs: WorkspaceClient["fs"], path: string, offs
  * The subtle part is why `rawIndex` exists at all. `offset` counts items at the
  * source; the caller renders a filtered, budget-trimmed subset of them. So the
  * obvious `nextOffset = offset + shown` is wrong — it silently skips or repeats
- * whenever anything was dropped, which is precisely when `.git` is involved. Keeping
- * each survivor's source index means the next page starts exactly after the last one
- * the model actually saw.
+ * whenever anything was dropped, which is precisely when a skipped directory is
+ * involved. Keeping each survivor's source index means the next page starts exactly
+ * after the last one the model actually saw.
  *
- * Retries because `.git` can outnumber a whole page on its own: at a repo root it is
- * walked *first* (`.` sorts before alphanumerics) and holds thousands of objects, so
- * one fetch can come back entirely excluded. `maxRounds` is the caller's, and the
- * asymmetry is deliberate — a `find` retry re-walks dirents, which is cheap SQLite
- * reads, while a `grep` retry re-reads and re-scans every file it already looked at.
+ * Retries because a skipped directory can outnumber a whole page on its own — a
+ * dependency tree runs to tens of thousands of files — so one fetch can come back
+ * entirely excluded. `maxRounds` is the caller's: a retry re-reads and re-scans
+ * every file the last one looked at. For a walk the store can prune instead, see
+ * `sb_ls`, which passes exclusions to `find` and needs none of this.
  *
  * Deliberately no slicing to `want`: the caller needs the extra item to know a next
  * page exists, and its index to say where.
  */
-export declare function collectVisible<T>(fetch: (offset: number, limit: number) => Promise<T[]>, pathOf: (item: T) => string, want: number, offset: number, maxRounds: number): Promise<{
+export declare function collectVisible<T>(fetch: (offset: number, limit: number) => Promise<T[]>, pathOf: (item: T) => string, skip: (path: string) => boolean, want: number, offset: number, maxRounds: number): Promise<{
     items: T[];
     /** Source offset of `items[i]`. */
     rawIndex: number[];
@@ -109,7 +105,7 @@ interface VisiblePage {
  *
  * `rawIndex[shown]` rather than `offset + shown`: the first item the model did *not*
  * see, at its source coordinate. Anything else drifts by however many entries the
- * `.git` filter removed, and drifts silently — the next page would repeat or skip
+ * skip filter removed, and drifts silently — the next page would repeat or skip
  * with nothing to indicate it had.
  *
  * Narrowing is still offered, and still first-class, because it is cheaper than

package/dist/computer/read.js

@@ -1,4 +1,3 @@
-import { isGitInternal } from "./paths.js";
 /**
  * Reading the workspace without pulling more of it across the boundary than the
  * model will be shown.
@@ -27,18 +26,14 @@ import { isGitInternal } from "./paths.js";
  *
  * `maxChars` is a character ceiling everywhere else — see
  * {@link ComputerConfig.maxOutputChars} — and here it is spent against
- * `byteOffset`/`byteLength`, which are the only units the transport has. That is
- * deliberate and it is safe in the direction that matters: a UTF-8 byte is never
- * more than one UTF-16 code unit, so *N* bytes decode to at most *N* characters.
- * Reading the character budget as bytes therefore always honours the ceiling,
- * and errs low on a file that is mostly non-ASCII — a CJK source file is cut at
- * about a third of the characters it could have shown. The alternative is a
- * second round trip to measure what the first one returned, on every read, to
- * recover a bound the marker already announces.
- *
- * The other reason it cannot be characters is the one this function exists for:
- * bounding the *transport*. A byte range is what stops a 4 MB lockfile being
- * materialised in a 128 MB isolate before anything is thrown away.
+ * `byteOffset`/`byteLength`, which are the only units the transport has, and the
+ * only ones that bound what crosses it. Safe in the direction that matters: a
+ * UTF-8 byte is never more than one UTF-16 code unit, so *N* bytes decode to at
+ * most *N* characters. Reading the character budget as bytes therefore always
+ * honours the ceiling, and errs low on a file that is mostly non-ASCII — a CJK
+ * source file is cut at about a third of the characters it could have shown. The
+ * alternative is a second round trip on every read, to recover a bound the
+ * marker already announces.
  *
  * ## Why `stat` first
  *
@@ -112,20 +107,20 @@ export async function readWindow(fs, path, offset, length, maxChars) {
  * The subtle part is why `rawIndex` exists at all. `offset` counts items at the
  * source; the caller renders a filtered, budget-trimmed subset of them. So the
  * obvious `nextOffset = offset + shown` is wrong — it silently skips or repeats
- * whenever anything was dropped, which is precisely when `.git` is involved. Keeping
- * each survivor's source index means the next page starts exactly after the last one
- * the model actually saw.
+ * whenever anything was dropped, which is precisely when a skipped directory is
+ * involved. Keeping each survivor's source index means the next page starts exactly
+ * after the last one the model actually saw.
  *
- * Retries because `.git` can outnumber a whole page on its own: at a repo root it is
- * walked *first* (`.` sorts before alphanumerics) and holds thousands of objects, so
- * one fetch can come back entirely excluded. `maxRounds` is the caller's, and the
- * asymmetry is deliberate — a `find` retry re-walks dirents, which is cheap SQLite
- * reads, while a `grep` retry re-reads and re-scans every file it already looked at.
+ * Retries because a skipped directory can outnumber a whole page on its own — a
+ * dependency tree runs to tens of thousands of files — so one fetch can come back
+ * entirely excluded. `maxRounds` is the caller's: a retry re-reads and re-scans
+ * every file the last one looked at. For a walk the store can prune instead, see
+ * `sb_ls`, which passes exclusions to `find` and needs none of this.
  *
  * Deliberately no slicing to `want`: the caller needs the extra item to know a next
  * page exists, and its index to say where.
  */
-export async function collectVisible(fetch, pathOf, want, offset, maxRounds) {
+export async function collectVisible(fetch, pathOf, skip, want, offset, maxRounds) {
     const items = [];
     const rawIndex = [];
     let cursor = offset;
@@ -136,7 +131,7 @@ export async function collectVisible(fetch, pathOf, want, offset, maxRounds) {
         rounds += 1;
         const batch = await fetch(cursor, want + 1);
         batch.forEach((item, i) => {
-            if (isGitInternal(pathOf(item)))
+            if (skip(pathOf(item)))
                 return;
             items.push(item);
             rawIndex.push(cursor + i);
@@ -160,7 +155,7 @@ export async function collectVisible(fetch, pathOf, want, offset, maxRounds) {
  *
  * `rawIndex[shown]` rather than `offset + shown`: the first item the model did *not*
  * see, at its source coordinate. Anything else drifts by however many entries the
- * `.git` filter removed, and drifts silently — the next page would repeat or skip
+ * skip filter removed, and drifts silently — the next page would repeat or skip
  * with nothing to indicate it had.
  *
  * Narrowing is still offered, and still first-class, because it is cheaper than
@@ -196,8 +191,10 @@ export function listingNote(page, shown, noun, narrower) {
  * somewhere else — is the same either way.
  */
 export async function pathExists(fs, path) {
-    const probe = fs.exists;
-    if (typeof probe === "function")
-        return probe.call(fs, path);
+    // Called as a method, never through `.call`: on an RPC stub `.call` is read as
+    // a remote method, and the stub it would pass as `this` cannot be serialised.
+    const remote = fs;
+    if (typeof remote.exists === "function")
+        return remote.exists(path);
     return fs.stat(path).then(() => true, () => false);
 }

package/dist/computer/render.d.ts

@@ -100,7 +100,35 @@ export declare function renderResult(result: {
     stdout: string;
     stderr: string;
     status?: WorkspaceRuntimeStatus;
+    sync?: {
+        status: "complete" | "pending";
+    };
 }, maxChars: number): string;
+/**
+ * The command ran; its changes have not landed in the workspace yet.
+ *
+ * Every command is bracketed by a sync, and the pull afterwards is what moves
+ * what it wrote from the container into the Durable Object. That pull can fail
+ * while the command itself succeeds — a transport that dropped, a container
+ * replaced underneath — and the runtime reports it in `sync` rather than in the
+ * exit code, because the command genuinely did run.
+ *
+ * Worth a sentence to the model because the *next* thing it does is usually read
+ * what it just wrote, and the file tools read the workspace rather than the
+ * container. Without this the file looks unchanged and the obvious conclusion is
+ * that the command did not work, which is the one conclusion that is wrong.
+ *
+ * Recovery is deliberately not the model's, and is not automatic either: the
+ * runtime schedules no retry of its own, so an outstanding pull lands when the
+ * host drives one or when a later command's own bracket carries it. What the
+ * model is told therefore stops short of "it will be there in a moment" — it is
+ * told the read may be stale, that re-running the command is the wrong fix
+ * because it would repeat the side effects, and to say so in its result if the
+ * workspace still disagrees with what it wrote.
+ */
+export declare function syncPendingNote(sync: {
+    status: "complete" | "pending";
+} | undefined): string | undefined;
 /**
  * Why a command has nothing to show for itself.
  *

package/dist/computer/render.js

@@ -177,7 +177,40 @@ export function renderResult(result, maxChars) {
     const body = truncateOutput(parts.join("\n"), maxChars);
     const state = result.status && result.status !== "completed" ? ` (${result.status})` : "";
     const verdict = `--- exit ${result.exitCode}${state} ---`;
-    return body ? `${body}\n${verdict}` : `(no output)\n${verdict}`;
+    const pending = syncPendingNote(result.sync);
+    const transcript = body ? `${body}\n${verdict}` : `(no output)\n${verdict}`;
+    return pending ? `${transcript}\n${pending}` : transcript;
+}
+/**
+ * The command ran; its changes have not landed in the workspace yet.
+ *
+ * Every command is bracketed by a sync, and the pull afterwards is what moves
+ * what it wrote from the container into the Durable Object. That pull can fail
+ * while the command itself succeeds — a transport that dropped, a container
+ * replaced underneath — and the runtime reports it in `sync` rather than in the
+ * exit code, because the command genuinely did run.
+ *
+ * Worth a sentence to the model because the *next* thing it does is usually read
+ * what it just wrote, and the file tools read the workspace rather than the
+ * container. Without this the file looks unchanged and the obvious conclusion is
+ * that the command did not work, which is the one conclusion that is wrong.
+ *
+ * Recovery is deliberately not the model's, and is not automatic either: the
+ * runtime schedules no retry of its own, so an outstanding pull lands when the
+ * host drives one or when a later command's own bracket carries it. What the
+ * model is told therefore stops short of "it will be there in a moment" — it is
+ * told the read may be stale, that re-running the command is the wrong fix
+ * because it would repeat the side effects, and to say so in its result if the
+ * workspace still disagrees with what it wrote.
+ */
+export function syncPendingNote(sync) {
+    if (sync?.status !== "pending")
+        return undefined;
+    return ("(The command finished, but what it wrote has not reached the workspace " +
+        "yet, so the file tools may still show the previous contents. Do not re-run " +
+        "the command to force it — that repeats whatever it already did. Read again " +
+        "in a moment, and if the workspace still disagrees with what the command " +
+        "wrote, say so in your result rather than working around it.)");
 }
 /**
  * Why a command has nothing to show for itself.

package/dist/computer/shell.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Run a command under {@link file://./index.ts ComputerConfig.shell} with its
+ * two output streams left as they are, or hand it back untouched when no shell
+ * is configured.
+ *
+ * This is the variant for a caller that **reads the result in code**: `stdout` is
+ * a data channel it compares or parses, and `stderr` is a separate diagnostic.
+ * {@link file://./index.ts computerExec} is that caller, on behalf of
+ * `@dynamicagents/plugins/repo`, which asks git questions like
+ * `symbolic-ref --short refs/remotes/origin/HEAD` and `rev-list --count` and
+ * needs the answer alone.
+ *
+ * Two functions rather than one with a flag, because the difference is a change
+ * to the *output contract* and a boolean hides it at the call site. Merging the
+ * streams here would give every `/repo` git command an empty `stderr` and a
+ * `stdout` that is a transcript rather than an answer — which fails silently,
+ * since the commands `/repo` parses are quiet ones and a single `warning:` is
+ * enough to skip the empty-branch guard.
+ */
+export declare function withShell(command: string, shell: string | undefined): string;
+/**
+ * Run a command under {@link file://./index.ts ComputerConfig.shell} with its
+ * two output streams merged into one transcript, in the order they were
+ * written.
+ *
+ * This is the variant for a caller whose consumer is **a model reading output**.
+ * `sb_exec` is that caller. A project's check is a chain — `wrangler types &&
+ * prettier && eslint && tsc` — and *which tool spoke last* is how you know which
+ * one failed. A stdout block and a separate stderr block destroy that ordering,
+ * and a model that wants it back re-runs the whole gate as
+ * `npm run check > /tmp/out 2>&1; cat /tmp/out`. This is that workaround, done
+ * once, for free.
+ *
+ * The redirect binds to the wrapper process, so it applies to everything the
+ * command writes however deeply nested — and there is no inner brace group or
+ * subshell to mis-parse a command that already contains `&&`, quotes or redirects
+ * of its own.
+ *
+ * With no shell configured there is no wrapper process to redirect, so the
+ * command goes to the runtime untouched and the two streams arrive separate.
+ * That is not a gap: {@link file://./render.ts renderResult} renders them as a
+ * labelled `--- stderr ---` block for exactly this case. The transcript is the
+ * better answer, not the only supported one.
+ */
+export declare function withShellTranscript(command: string, shell: string | undefined): string;

package/dist/computer/shell.js

@@ -0,0 +1,80 @@
+import { shellQuote } from "@cloudflare/computer";
+/** How a command reaches the shell, and what its two output streams do there. */
+/**
+ * The shell wrapper both variants share, minus the choice they differ on.
+ *
+ * One quoted argument, not string concatenation: the command is model-authored
+ * and routinely contains quotes of its own (`git commit -m "…"`), so anything
+ * less than `shellQuote` re-parses the model's quoting and mangles it.
+ *
+ * ## Why `-o pipefail`
+ *
+ * Without it a pipeline's exit status is its **last** stage's, so
+ * `npm run check | tail -100` reports `exit 0` for a gate that failed outright —
+ * and models pipe into `tail` constantly. A tool that reports success for a
+ * failed build is worse than one that reports nothing. It also costs a re-run
+ * every time: a model that cannot trust a piped exit code runs the whole thing
+ * again unpiped to get one.
+ *
+ * The trade is worth stating. `pipefail` surfaces SIGPIPE too, so
+ * `ls big-dir | head -1` reports 141 rather than 0 — noisy, but *visible*, where
+ * the alternative is a failing gate that looks clean. The tool description tells
+ * the model not to pipe into `head`/`tail` at all, since output is already
+ * truncated with both ends kept.
+ *
+ * Requires a shell that implements it — `bash`, `zsh`, `ksh`, not `sh`/dash. A
+ * host setting {@link file://./index.ts ComputerConfig.shell} is choosing that
+ * shell explicitly.
+ */
+function wrapped(command, shell) {
+    return `${shell} -o pipefail -c ${shellQuote(command)}`;
+}
+/**
+ * Run a command under {@link file://./index.ts ComputerConfig.shell} with its
+ * two output streams left as they are, or hand it back untouched when no shell
+ * is configured.
+ *
+ * This is the variant for a caller that **reads the result in code**: `stdout` is
+ * a data channel it compares or parses, and `stderr` is a separate diagnostic.
+ * {@link file://./index.ts computerExec} is that caller, on behalf of
+ * `@dynamicagents/plugins/repo`, which asks git questions like
+ * `symbolic-ref --short refs/remotes/origin/HEAD` and `rev-list --count` and
+ * needs the answer alone.
+ *
+ * Two functions rather than one with a flag, because the difference is a change
+ * to the *output contract* and a boolean hides it at the call site. Merging the
+ * streams here would give every `/repo` git command an empty `stderr` and a
+ * `stdout` that is a transcript rather than an answer — which fails silently,
+ * since the commands `/repo` parses are quiet ones and a single `warning:` is
+ * enough to skip the empty-branch guard.
+ */
+export function withShell(command, shell) {
+    return shell ? wrapped(command, shell) : command;
+}
+/**
+ * Run a command under {@link file://./index.ts ComputerConfig.shell} with its
+ * two output streams merged into one transcript, in the order they were
+ * written.
+ *
+ * This is the variant for a caller whose consumer is **a model reading output**.
+ * `sb_exec` is that caller. A project's check is a chain — `wrangler types &&
+ * prettier && eslint && tsc` — and *which tool spoke last* is how you know which
+ * one failed. A stdout block and a separate stderr block destroy that ordering,
+ * and a model that wants it back re-runs the whole gate as
+ * `npm run check > /tmp/out 2>&1; cat /tmp/out`. This is that workaround, done
+ * once, for free.
+ *
+ * The redirect binds to the wrapper process, so it applies to everything the
+ * command writes however deeply nested — and there is no inner brace group or
+ * subshell to mis-parse a command that already contains `&&`, quotes or redirects
+ * of its own.
+ *
+ * With no shell configured there is no wrapper process to redirect, so the
+ * command goes to the runtime untouched and the two streams arrive separate.
+ * That is not a gap: {@link file://./render.ts renderResult} renders them as a
+ * labelled `--- stderr ---` block for exactly this case. The transcript is the
+ * better answer, not the only supported one.
+ */
+export function withShellTranscript(command, shell) {
+    return shell ? `${wrapped(command, shell)} 2>&1` : command;
+}