@jr2/machines 0.3.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jr2/machines",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "The Machines the jr2 kit ships: packaged xstate Machines that leave their parts Open for a composer to bind.",
   "license": "MIT",
   "private": false,
@@ -35,20 +35,20 @@
   "peerDependencies": {
     "xstate": "^5.18.0",
     "zod": "^4.4.3",
-    "@jr2/orchestrator": "0.3.0"
+    "@jr2/orchestrator": "0.4.1"
   },
   "devDependencies": {
     "@types/node": "^26.0.1",
     "typescript": "^5.6.0",
     "xstate": "^5.18.0",
     "zod": "^4.4.3",
-    "@jr2/orchestrator": "0.3.0"
+    "@jr2/orchestrator": "0.4.1"
   },
   "files": [
     "src"
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "node --test"
+    "test": "node --test --test-global-setup=../../scripts/test-tmpdir.ts"
   }
 }

package/src/index.ts

@@ -3,8 +3,8 @@
 // Machines from this index: `import { task } from "@jr2/machines"`.
 //
 // It ships MACHINES and never Workflows. A Workflow is the name an Instance registers a Machine
-// under, and only the Instance's `workflows/` file can do that (CONTEXT.md) — so what a consumer
-// receives is a Machine object, and the line that turns it into a Workflow is theirs:
+// under, and only the Instance's `workflows/` file can do that (GLOSSARY.md, ADR-0009) — so what a
+// consumer receives is a Machine object, and the line that turns it into a Workflow is theirs:
 //
 //   import { customize } from "@jr2/orchestrator";
 //   import { task } from "@jr2/machines";
@@ -21,7 +21,7 @@
 // rejected for working by the ACCIDENT of equal versions and installing two copies silently on
 // skew (ADR-0054).
 //
-// Every Machine exported here leaves its unfillable parts OPEN (CONTEXT.md, ADR-0054): a package
+// Every Machine exported here leaves its unfillable parts OPEN (GLOSSARY.md, ADR-0054): a package
 // cannot know the repository or pay for the model, so it says so rather than guessing. `jr2 up`
 // refuses an Open part nobody bound and prints the `customize` line that binds it.
 

package/src/task.ts

@@ -2,7 +2,7 @@
 // done. It is the smallest shape that is still worth packaging — a coder in a Sandbox, a Gate a
 // human answers, and a loop between them that ends when the human ends it.
 //
-// Both of the parts a package cannot honestly fill are left OPEN (CONTEXT.md, ADR-0051/0054): the
+// Both of the parts a package cannot honestly fill are left OPEN (GLOSSARY.md, ADR-0051/0054): the
 // Repo Slots are Open as a MAP, because the package cannot know the repository — nor how many
 // checkouts the task wants beside it — and the Agent `coder` has no model, because the package
 // cannot pay for one. A consumer binds both on the line that registers this Machine as a
@@ -133,7 +133,9 @@ type BodyContext = BodyInput & {
   turns: number;
   /** The coder's own account of the last finished Turn — the Gate's `summary`. */
   summary?: string;
-  /** Why the run is parked without a summary: the reason the fault carried — the Gate's `reason`. */
+  /** Why the run is parked without a summary: the reason the fault carried — the Gate's `reason`.
+   * Kept into the re-briefed Turn that follows, which tells the coder of a memory kill (ADR-0061);
+   * the next `finish` clears it. */
   reason?: string;
   /** The human's last notes, which are the next Turn's prompt. */
   notes?: string;
@@ -246,7 +248,7 @@ export const body = jr2Setup({
         // next one starts, so a count jr2 chose would only ever interrupt them.
         request_changes: {
           target: "working",
-          actions: assign({ notes: ({ event }) => event.notes, summary: undefined, reason: undefined }),
+          actions: assign({ notes: ({ event }) => event.notes, summary: undefined }),
         },
       },
     },
@@ -321,6 +323,8 @@ function branchOf(input: TaskInput): string {
 function coderPrompt(context: BodyContext): string {
   const notes = context.notes ? `\n\nThe human reviewed your work and asks for changes:\n${context.notes}` : "";
   if (context.turns > 0) return notes.trimStart() || "Continue.";
+  const fault = memoryKill(context.reason);
+  const ended = fault ? `\n\nThe last attempt ended: ${fault}` : "";
   const { branch, repos } = context.workspace;
   const worktree = worktreeOf(context);
   const beside = Object.entries(repos)
@@ -328,13 +332,25 @@ function coderPrompt(context: BodyContext): string {
     .map(([slot, path]) => `\n- ${slot}: ${path}`)
     .join("");
   return (
-    `${context.prompt}${notes}\n\n` +
+    `${context.prompt}${ended}${notes}\n\n` +
     `Work in ${worktree.path}, on branch ${branch} — your tools are rooted there, so a relative ` +
     `path lands inside it. Commit what you do there, then call finish.` +
     (beside ? `\n\nAlso checked out beside it, for you to read:${beside}` : "")
   );
 }
 
+/**
+ * A memory kill's named line (ADR-0061, layer 5), or undefined for any other fault. The one fault
+ * the coder can act on — fewer workers, smaller steps — so the retry Turn carries it: the example
+ * for authors. The Orchestrator names it with the fixed prefix `memory limit` on the first line;
+ * the lines after it are the transport's words, not the coder's business. Any other fault (a
+ * provider down, a runaway rerolled) is the human's, and stays on the Gate alone.
+ */
+function memoryKill(reason: string | undefined): string | undefined {
+  const line = reason?.split("\n")[0]?.trim();
+  return line?.startsWith("memory limit") ? line : undefined;
+}
+
 /**
  * The checkout the coder edits: the FIRST slot the consumer wrote. This is `task`'s convention,
  * not the kit's — the handles keep the slots in declaration order and give none a meaning