@gigaai/newton 0.3.0 → 0.4.0

package/README.md

@@ -66,14 +66,21 @@ script body. The body runs as an async function with these in scope:
 | `pipeline(items, ...stages)` | Each item flows through the stages independently — no barrier between stages. Stage signature: `(prev, item, index)`. |
 | `phase(title)` | Group subsequent agents in progress output. |
 | `log(message)` | Narrator line in progress output and the journal. |
+| `workflow(nameOrPath, args?)` | Run one child workflow. Bare names resolve from `.newton/workflows/<name>.js`; paths resolve relative to the calling workflow. Nesting is limited to one child level. |
 | `args` | Whatever you passed via `--args` (JSON-parsed when possible). |
 | `budget` | `{ total, spent(), remaining() }` for the `--budget` output-token ceiling. |
 
 `agent()` options: `provider` (see below), `model`, `effort` (`low`–`xhigh`),
 `access` (`read` | `write` | `full` — sandbox posture), `schema` (JSON Schema
 for structured output, validated with automatic retries), `label`, `phase`,
-`cwd`, `timeoutMs`, and `command` — an escape hatch to run any ACP agent,
-e.g. `command: ['my-agent', '--acp']`.
+`cwd`, `timeoutMs`, `isolation: 'worktree'` for disposable per-agent git
+worktrees, `mcp` (`true` for all `.mcp.json` servers, or a list of names/inline
+servers), `config` (ACP `configId` to string value), and `command` — an escape
+hatch to run any ACP agent, e.g. `command: ['my-agent', '--acp']`.
+
+Workflow scripts run in a sandboxed JavaScript realm: Node globals such as
+`process`, `fetch`, and `setTimeout` are not available, and `console.log()`
+routes through `log()` into progress output and the journal.
 
 ## Providers
 
@@ -98,7 +105,7 @@ the agent advertises over ACP (session config options) and selects it
 protocol-side. `newton models <provider>` shows what an agent exposes;
 requesting a model an agent doesn't offer fails with the available list.
 
-`Date.now()`, argless `new Date()`, and `Math.random()` throw inside
+`Date.now()`, argless `new Date()`, and `Math.random()` also throw inside
 workflows: nondeterminism would silently break `--resume` replay. Pass
 timestamps in via `--args`.
 
@@ -113,15 +120,32 @@ workspace:
   chunk, tool call, and permission decision.
 
 `newton run workflow.js --resume <runId>` replays successful agent results
-from a previous run's journal — identical calls return instantly and only new
-or changed calls hit real agents.
+from a previous run's journal. The default `--resume-mode prefix` replays by
+call position until the first changed agent call, then runs that call and
+everything after it live. `--resume-mode hash` uses the legacy hash replay:
+identical calls return instantly no matter where they appear.
+
+Long runs can be detached and controlled from another shell:
+
+- `newton run workflow.js --detach` starts in the background and prints
+  `{ runId, pid }`.
+- `newton runs [--json]` lists `.newton/runs/*` with status, agent count,
+  output tokens, and pid.
+- `newton watch <runId> [--json]` replays the journal from the beginning and
+  keeps tailing until the run ends.
+- `newton skip <runId> <agentId>` asks a queued or live agent to cancel;
+  `agent()` returns `null` and the workflow continues.
 
 ## CLI
 
 ```
 newton run <workflow.js>   --args <json> --cwd <dir> --resume <runId> --json
+                           --resume-mode <prefix|hash> --detach
                            --budget <tokens> --max-agents <n> --timeout <seconds>
                            --concurrency <n>
+newton runs [--json]             list runs under .newton/runs
+newton watch <runId> [--json]    replay/tail a run's journal
+newton skip <runId> <agentId>    cancel one agent; workflow continues
 newton validate <workflow.js>   parse + compile without spawning agents
 newton agents [--json]          supported agents: installed? signed in? (alias: doctor)
 newton models <provider>        ask an agent which models/modes it exposes

package/dist/acp.js

@@ -50,8 +50,14 @@ export class AcpAgentSession {
     toolCalls = 0;
     usage = null;
     stderrTail = [];
+    aborted;
+    abortSignal;
+    resolveAbortSignal;
     constructor(request) {
         this.request = request;
+        this.abortSignal = new Promise((resolveAbort) => {
+            this.resolveAbortSignal = resolveAbort;
+        });
     }
     async prompt() {
         try {
@@ -72,6 +78,15 @@ export class AcpAgentSession {
     }
     async promptAgain(prompt) {
         try {
+            if (this.aborted) {
+                return {
+                    text: this.text,
+                    stopReason: "cancelled",
+                    usage: this.usage,
+                    toolCalls: this.toolCalls,
+                    error: this.aborted,
+                };
+            }
             const connection = this.connection;
             const sessionId = this.sessionId;
             this.text = "";
@@ -84,7 +99,7 @@ export class AcpAgentSession {
                 sessionId,
                 prompt: [{ type: "text", text: prompt }],
             });
-            const outcome = await Promise.race([turn, timedOut]);
+            const outcome = await Promise.race([turn, timedOut, this.abortSignal]);
             clearTimeout(timer);
             if (outcome === "timeout") {
                 await connection.cancel({ sessionId }).catch(() => { });
@@ -99,6 +114,19 @@ export class AcpAgentSession {
                     error: `agent timed out after ${this.request.timeoutMs}ms`,
                 };
             }
+            if (outcome === "aborted") {
+                await connection.cancel({ sessionId }).catch(() => { });
+                // Give the agent a moment to flush final updates, then hard-stop.
+                await Promise.race([turn.catch(() => { }), new Promise((r) => setTimeout(r, 3000))]);
+                this.close();
+                return {
+                    text: this.text,
+                    stopReason: "cancelled",
+                    usage: this.usage,
+                    toolCalls: this.toolCalls,
+                    error: this.aborted,
+                };
+            }
             this.usage = outcome.usage ?? this.usage;
             return {
                 text: this.text,
@@ -111,6 +139,10 @@ export class AcpAgentSession {
             return this.failure(error);
         }
     }
+    abort(reason) {
+        this.aborted = reason;
+        this.resolveAbortSignal("aborted");
+    }
     close() {
         if (this.child && !this.child.killed)
             this.child.kill("SIGTERM");
@@ -187,13 +219,17 @@ export class AcpAgentSession {
                 session: { configOptions: {} },
             },
         });
-        const session = await connection.newSession({ cwd: resolve(cwd), mcpServers: [] });
+        const session = await connection.newSession({ cwd: resolve(cwd), mcpServers: this.request.mcpServers ?? [] });
         this.sessionId = session.sessionId;
         this.sessionInfo = session;
         trace({ type: "session", sessionId: session.sessionId, configOptions: session.configOptions ?? null });
         if (this.request.spec.model && !resolved.modelHandled) {
             await this.selectModelViaProtocol(session, this.request.spec.model);
         }
+        for (const [configId, value] of Object.entries(this.request.config ?? {})) {
+            await connection.setSessionConfigOption({ sessionId: this.sessionId, configId, value });
+            trace({ type: "config_set", configId, value });
+        }
     }
     /**
      * Providers without a CLI/env model knob may still expose model choice as an

package/dist/cli.js

@@ -1,7 +1,11 @@
 #!/usr/bin/env node
-import { accessSync, constants } from "node:fs";
+import { spawn } from "node:child_process";
+import { accessSync, closeSync, constants, mkdirSync, openSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 import { AcpAgentSession } from "./acp.js";
+import { listRuns, readStatus, requestSkip, tailJournal } from "./control.js";
 import { compileWorkflow, loadWorkflow, runWorkflow } from "./executor.js";
+import { newRunId } from "./journal.js";
 import { HumanReporter, JsonReporter } from "./progress.js";
 import { describeProviders } from "./providers.js";
 import { VERSION } from "./version.js";
@@ -9,6 +13,10 @@ const USAGE = `newton — deterministic multi-agent workflows over ACP
 
 Usage:
   newton run <workflow.js> [options]   Run a workflow in the current directory
+  newton run <workflow.js> --detach     Start in the background; prints { runId, pid }
+  newton runs [--json]                List runs under .newton/runs with status
+  newton watch <runId> [--json]       Tail a run's journal as live progress
+  newton skip <runId> <agentId>       Cancel one agent; agent() returns null, run continues
   newton validate <workflow.js>       Parse + compile a workflow without running agents
   newton agents [--json]              Supported agents: installed? signed in? (alias: doctor)
   newton models <provider> [--json]   Ask an agent which models it exposes
@@ -17,6 +25,8 @@ Run options:
   --args <json>        Value exposed to the script as \`args\`
   --cwd <dir>          Workspace agents operate in (default: current directory)
   --resume <runId>     Replay cached agent results from a previous run
+  --resume-mode <prefix|hash>  Resume matching: positional prefix (default) or hash replay
+  --detach             Start the run in the background
   --json               NDJSON events on stdout instead of human output
   --budget <tokens>    Output-token ceiling; agent() throws once exhausted
   --max-agents <n>     Agent-call cap (default 200)
@@ -28,7 +38,11 @@ followed by a script body using agent()/parallel()/pipeline()/phase()/log(),
 with \`args\` and \`budget\` in scope. agent() opts: provider (codex | claude |
 gemini | qwen | cursor | opencode | goose | copilot), model, effort, access
 (read | write | full), schema, label, phase, cwd, command (any ACP agent,
-e.g. ["my-agent", "--acp"]).
+e.g. ["my-agent", "--acp"]), isolation ('worktree'), mcp (true | names/servers
+from .mcp.json), config ({configId: value}).
+Workflows may call workflow(nameOrPath, args) one level deep; bare names resolve
+from .newton/workflows/<name>.js.
+Scripts run sandboxed: no process/fetch/setTimeout; console.log routes to log().
 
 Runs are recorded under .newton/runs/<runId>/ — journal.jsonl plus a full
 per-agent ACP trace.`;
@@ -66,10 +80,47 @@ function intFlag(flags, name) {
         fail(`--${name} requires a positive integer`);
     return value;
 }
+function resumeModeFlag(flags) {
+    const raw = flags["resume-mode"];
+    if (raw === undefined)
+        return undefined;
+    if (raw === "prefix" || raw === "hash")
+        return raw;
+    fail("--resume-mode requires prefix or hash");
+}
+function commandRunDetached(file, flags) {
+    const cwd = typeof flags.cwd === "string" ? resolve(flags.cwd) : process.cwd();
+    const runId = newRunId();
+    const runDir = join(cwd, ".newton", "runs", runId);
+    mkdirSync(runDir, { recursive: true });
+    const fd = openSync(join(runDir, "detach.log"), "a");
+    const argv = [process.argv[1], "run", resolve(file), "--json", "--run-id", runId, "--cwd", cwd];
+    for (const name of ["args", "resume", "resume-mode", "budget", "max-agents", "timeout", "concurrency"]) {
+        const value = flags[name];
+        if (typeof value === "string")
+            argv.push(`--${name}`, value);
+    }
+    let child;
+    try {
+        child = spawn(process.execPath, argv, { detached: true, stdio: ["ignore", fd, fd] });
+    }
+    finally {
+        closeSync(fd);
+    }
+    if (!child)
+        fail("failed to start detached run");
+    child.unref();
+    process.stdout.write(`${JSON.stringify({ runId, pid: child.pid }, null, 2)}\n`);
+    process.exit(0);
+}
 async function commandRun(positional, flags) {
     const file = positional[0];
     if (!file)
         fail("newton run requires a workflow file");
+    const resumeMode = resumeModeFlag(flags);
+    if (flags.detach === true) {
+        commandRunDetached(file, flags);
+    }
     let args;
     if (typeof flags.args === "string") {
         try {
@@ -87,6 +138,9 @@ async function commandRun(positional, flags) {
         args,
         cwd: typeof flags.cwd === "string" ? flags.cwd : process.cwd(),
         resumeRunId: typeof flags.resume === "string" ? flags.resume : undefined,
+        resumeMode,
+        runId: typeof flags["run-id"] === "string" ? flags["run-id"] : undefined,
+        detached: typeof flags["run-id"] === "string",
         budgetTokens: intFlag(flags, "budget"),
         maxAgents: intFlag(flags, "max-agents"),
         agentTimeoutMs: timeoutSeconds ? timeoutSeconds * 1000 : undefined,
@@ -99,6 +153,126 @@ async function commandRun(positional, flags) {
     }
     process.exit(result.status === "ok" ? 0 : 1);
 }
+function commandRuns(flags) {
+    const workspace = process.cwd();
+    const rows = listRuns(workspace);
+    if (flags.json === true) {
+        process.stdout.write(`${JSON.stringify(rows.map(({ runId, stale, status }) => ({ runId, stale, ...(status ?? {}) })), null, 2)}\n`);
+        return;
+    }
+    if (rows.length === 0) {
+        process.stdout.write("no runs under .newton/runs\n");
+        return;
+    }
+    const table = [
+        ["runId", "status", "agents", "out-tok", "pid", "name"],
+        ...rows.map(({ runId, stale, status }) => [
+            runId,
+            stale ? "stale" : (status?.status ?? "—"),
+            status ? String(status.agents) : "",
+            status ? String(status.outputTokens) : "",
+            status ? String(status.pid) : "",
+            status?.name ?? "",
+        ]),
+    ];
+    const widths = table[0].map((_, index) => Math.max(...table.map((row) => row[index].length)));
+    for (const row of table) {
+        process.stdout.write(`${row.map((value, index) => value.padEnd(widths[index])).join("  ")}\n`);
+    }
+}
+async function commandWatch(positional, flags) {
+    const runId = positional[0];
+    if (!runId)
+        fail("newton watch requires a run id");
+    const runDir = join(process.cwd(), ".newton", "runs", runId);
+    try {
+        accessSync(runDir, constants.F_OK);
+    }
+    catch {
+        fail(`no run "${runId}"`);
+    }
+    const journalPath = join(runDir, "journal.jsonl");
+    const json = flags.json === true;
+    const reporter = new HumanReporter();
+    let startT;
+    let exitCode = 0;
+    const keepAlive = setInterval(() => { }, 1 << 30);
+    let handle;
+    handle = tailJournal(journalPath, (entry) => {
+        if (json) {
+            process.stdout.write(`${JSON.stringify(entry)}\n`);
+        }
+        else {
+            switch (entry.type) {
+                case "workflow_start":
+                    startT = Date.parse(String(entry.t));
+                    reporter.start({ name: String(entry.name), description: "" }, String(entry.runId), dirname(journalPath));
+                    break;
+                case "phase":
+                    reporter.phase(String(entry.title));
+                    break;
+                case "log":
+                    reporter.log(String(entry.message));
+                    break;
+                case "agent_start":
+                    reporter.agentStart(Number(entry.id), String(entry.label), entry.spec, entry.phase, false);
+                    break;
+                case "agent_end": {
+                    if (entry.cached === true) {
+                        reporter.agentStart(Number(entry.id), String(entry.label), {}, entry.phase, true);
+                    }
+                    const ok = entry.status === "ok";
+                    reporter.agentEnd(Number(entry.id), ok, Number(entry.seconds ?? 0), ok ? (entry.cached ? "cached" : `${entry.toolCalls ?? 0} tools`) : String(entry.error ?? "error"));
+                    break;
+                }
+                case "workflow_child_start":
+                    reporter.log(`▸ workflow ${entry.name}`);
+                    break;
+                case "workflow_child_end":
+                    reporter.log(`${entry.status === "ok" ? "✔" : "✖"} workflow ${entry.name}`);
+                    break;
+            }
+        }
+        if (entry.type === "workflow_end") {
+            const endT = Date.parse(String(entry.t));
+            exitCode = entry.status === "ok" ? 0 : 1;
+            if (!json) {
+                reporter.done({
+                    runId,
+                    status: entry.status,
+                    result: entry.result,
+                    error: entry.error,
+                    agents: Number(entry.agents ?? 0),
+                    outputTokens: Number(entry.outputTokens ?? 0),
+                    durationMs: startT ? Math.max(0, endT - startT) : 0,
+                });
+            }
+            clearInterval(keepAlive);
+            handle.stop();
+            process.exit(exitCode);
+        }
+    });
+}
+function commandSkip(positional) {
+    const runId = positional[0];
+    const rawAgentId = positional[1];
+    if (!runId || !rawAgentId)
+        fail("newton skip requires a run id and agent id");
+    const agentId = Number(rawAgentId);
+    if (!Number.isInteger(agentId) || agentId <= 0)
+        fail("agentId requires a positive integer");
+    try {
+        requestSkip(process.cwd(), runId, agentId);
+    }
+    catch (error) {
+        fail(error.message);
+    }
+    process.stdout.write(`skip requested: run ${runId} agent #${agentId}\n`);
+    const status = readStatus(join(process.cwd(), ".newton", "runs", runId));
+    if (status?.status !== "running") {
+        process.stderr.write(`warning: run ${runId} status is ${status?.status ?? "unknown"}; skip may have no effect\n`);
+    }
+}
 function commandValidate(positional) {
     const file = positional[0];
     if (!file)
@@ -184,6 +358,15 @@ async function main() {
         case "run":
             await commandRun(positional, flags);
             break;
+        case "runs":
+            commandRuns(flags);
+            break;
+        case "watch":
+            await commandWatch(positional, flags);
+            break;
+        case "skip":
+            commandSkip(positional);
+            break;
         case "validate":
             try {
                 commandValidate(positional);

package/dist/control.js

@@ -0,0 +1,169 @@
+import { closeSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, statSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+export function writeStatus(runDir, status) {
+    const tmpPath = join(runDir, "status.json.tmp");
+    const statusPath = join(runDir, "status.json");
+    writeFileSync(tmpPath, `${JSON.stringify(status, null, 2)}\n`, "utf8");
+    renameSync(tmpPath, statusPath);
+}
+export function readStatus(runDir) {
+    try {
+        return JSON.parse(readFileSync(join(runDir, "status.json"), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return errorCode(error) === "EPERM";
+    }
+}
+export function listRuns(workspace) {
+    const runsDir = join(workspace, ".newton", "runs");
+    let runIds;
+    try {
+        runIds = readdirSync(runsDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort()
+            .reverse();
+    }
+    catch {
+        return [];
+    }
+    return runIds.map((runId) => {
+        const status = readStatus(join(runsDir, runId));
+        return {
+            runId,
+            status,
+            stale: status?.status === "running" && !pidAlive(status.pid),
+        };
+    });
+}
+export function requestSkip(workspace, runId, agentId) {
+    const runDir = join(workspace, ".newton", "runs", runId);
+    try {
+        if (!statSync(runDir).isDirectory()) {
+            throw new Error("not a directory");
+        }
+    }
+    catch {
+        throw new Error(`no run "${runId}" under .newton/runs`);
+    }
+    const controlDir = join(runDir, "control");
+    mkdirSync(controlDir, { recursive: true });
+    writeFileSync(join(controlDir, `skip-${agentId}`), "", "utf8");
+}
+export function readSkipRequests(runDir) {
+    const ids = new Set();
+    let entries;
+    try {
+        entries = readdirSync(join(runDir, "control"));
+    }
+    catch {
+        return ids;
+    }
+    for (const entry of entries) {
+        const match = /^skip-(\d+)$/.exec(entry);
+        if (!match)
+            continue;
+        const id = Number(match[1]);
+        if (Number.isInteger(id))
+            ids.add(id);
+    }
+    return ids;
+}
+export function tailJournal(journalPath, onEntry, pollMs = 300) {
+    let offset = 0;
+    let partial = Buffer.alloc(0);
+    let stopped = false;
+    function emitLine(line) {
+        const text = line.toString("utf8");
+        if (!text.trim())
+            return;
+        let entry;
+        try {
+            entry = JSON.parse(text);
+        }
+        catch {
+            // Ignore incomplete/corrupt journal lines; later valid lines still stream.
+            return;
+        }
+        if (entry !== null && typeof entry === "object" && !Array.isArray(entry)) {
+            onEntry(entry);
+        }
+    }
+    function consume(chunk) {
+        const data = partial.length === 0 ? chunk : Buffer.concat([partial, chunk]);
+        let lineStart = 0;
+        for (let i = 0; i < data.length; i++) {
+            if (data[i] !== 10)
+                continue;
+            emitLine(data.subarray(lineStart, i));
+            lineStart = i + 1;
+        }
+        partial = lineStart < data.length ? data.subarray(lineStart) : Buffer.alloc(0);
+    }
+    function tick() {
+        if (stopped)
+            return;
+        let size;
+        try {
+            const stat = statSync(journalPath);
+            if (!stat.isFile())
+                return;
+            size = stat.size;
+        }
+        catch {
+            return;
+        }
+        if (size < offset) {
+            offset = 0;
+            partial = Buffer.alloc(0);
+        }
+        if (size === offset)
+            return;
+        let fd;
+        try {
+            fd = openSync(journalPath, "r");
+            const length = size - offset;
+            const chunk = Buffer.alloc(length);
+            const bytesRead = readSync(fd, chunk, 0, length, offset);
+            if (bytesRead <= 0)
+                return;
+            offset += bytesRead;
+            consume(bytesRead === chunk.length ? chunk : chunk.subarray(0, bytesRead));
+        }
+        catch {
+            return;
+        }
+        finally {
+            if (fd !== undefined) {
+                try {
+                    closeSync(fd);
+                }
+                catch {
+                    // A close failure should not stop journal polling.
+                }
+            }
+        }
+    }
+    const timer = setInterval(tick, pollMs);
+    timer.unref();
+    return {
+        stop() {
+            stopped = true;
+            clearInterval(timer);
+        },
+    };
+}
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? error.code
+        : undefined;
+}

package/dist/executor.js

@@ -1,11 +1,36 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { cpus } from "node:os";
-import { resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { AcpAgentSession } from "./acp.js";
-import { agentCallKey, loadResumeCache, RunJournal } from "./journal.js";
+import { readSkipRequests, writeStatus } from "./control.js";
+import { agentCallKey, loadResumeCache, loadResumeCalls, RunJournal } from "./journal.js";
+import { resolveMcpServers } from "./mcp.js";
+import { checkCompile, createRealm } from "./sandbox.js";
 import { balancedSlice, extractJson, INVALID, structuredOutputInstruction, structuredOutputRetryPrompt, validateAgainstSchema, } from "./schema.js";
-const AsyncFunction = Object.getPrototypeOf(async function () { }).constructor;
-const SCRIPT_PARAMS = ["agent", "parallel", "pipeline", "phase", "log", "args", "budget", "Date", "Math"];
+import { createWorktree, finishWorktree } from "./worktree.js";
+const SCRIPT_PARAMS = ["agent", "parallel", "pipeline", "phase", "log", "args", "budget", "workflow"];
+function errorMessage(error) {
+    return typeof error === "object" &&
+        error !== null &&
+        "message" in error &&
+        typeof error.message === "string"
+        ? error.message
+        : String(error);
+}
+function isPlainObject(value) {
+    if (Object.prototype.toString.call(value) !== "[object Object]")
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === null || Object.getPrototypeOf(proto) === null;
+}
+function validateConfig(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isPlainObject(value) || Object.values(value).some((entry) => typeof entry !== "string")) {
+        throw new Error("agent() config takes an object of configId → string value");
+    }
+    return value;
+}
 export function loadWorkflow(file) {
     const absolute = resolve(file);
     const source = readFileSync(absolute, "utf8");
@@ -33,33 +58,8 @@ export function loadWorkflow(file) {
 }
 /** Compile without running — catches syntax errors and non-literal meta. */
 export function compileWorkflow(workflow) {
-    new AsyncFunction(...SCRIPT_PARAMS, workflow.body);
+    checkCompile(SCRIPT_PARAMS, workflow.body);
 }
-// Wall-clock and randomness would silently break resume replay, so scripts get
-// guarded shims instead of the real globals. Pass timestamps in via --args.
-const guardedDate = new Proxy(Date, {
-    get(target, prop, receiver) {
-        if (prop === "now") {
-            return () => {
-                throw new Error("Date.now() is unavailable in workflows (breaks resume); pass timestamps via --args");
-            };
-        }
-        return Reflect.get(target, prop, receiver);
-    },
-    construct(target, argArray) {
-        if (argArray.length === 0) {
-            throw new Error("new Date() without arguments is unavailable in workflows (breaks resume)");
-        }
-        return Reflect.construct(target, argArray);
-    },
-});
-const guardedMath = Object.create(Math, {
-    random: {
-        value: () => {
-            throw new Error("Math.random() is unavailable in workflows (breaks resume); vary prompts by index instead");
-        },
-    },
-});
 class Semaphore {
     queue = [];
     available;
@@ -89,11 +89,13 @@ const AGENT_PREAMBLE = [
 ].join("\n");
 export async function runWorkflow(options) {
     const startedAt = Date.now();
+    const statusStartedAt = new Date().toISOString();
     const workflow = loadWorkflow(options.file);
-    const scriptFn = new AsyncFunction(...SCRIPT_PARAMS, workflow.body);
     const workspace = resolve(options.cwd);
-    const journal = new RunJournal(workspace);
-    const resumeCache = options.resumeRunId ? loadResumeCache(workspace, options.resumeRunId) : undefined;
+    const journal = new RunJournal(workspace, options.runId);
+    const resumeMode = options.resumeMode ?? "prefix";
+    const resumeCache = options.resumeRunId && resumeMode === "hash" ? loadResumeCache(workspace, options.resumeRunId) : undefined;
+    const priorCalls = options.resumeRunId && resumeMode !== "hash" ? loadResumeCalls(workspace, options.resumeRunId) : undefined;
     const reporter = options.reporter;
     const maxAgents = options.maxAgents ?? 200;
     const agentTimeoutMs = options.agentTimeoutMs ?? 20 * 60 * 1000;
@@ -103,6 +105,33 @@ export async function runWorkflow(options) {
     let agentCounter = 0;
     let outputTokens = 0;
     let currentPhase;
+    let prefixIntact = true;
+    const liveSessions = new Map();
+    const skipped = new Set();
+    const controlTimer = setInterval(() => {
+        for (const id of readSkipRequests(journal.runDir)) {
+            if (skipped.has(id))
+                continue;
+            skipped.add(id);
+            liveSessions.get(id)?.abort("skipped via newton skip");
+        }
+    }, 500);
+    controlTimer.unref();
+    function syncStatus(status, extra = {}) {
+        writeStatus(journal.runDir, {
+            runId: journal.runId,
+            pid: process.pid,
+            file: workflow.file,
+            name: workflow.meta.name,
+            detached: options.detached ?? false,
+            startedAt: statusStartedAt,
+            updatedAt: new Date().toISOString(),
+            status,
+            agents: agentCounter,
+            outputTokens,
+            ...extra,
+        });
+    }
     journal.append({
         type: "workflow_start",
         runId: journal.runId,
@@ -110,8 +139,10 @@ export async function runWorkflow(options) {
         name: workflow.meta.name,
         args: options.args ?? null,
         resumedFrom: options.resumeRunId ?? null,
+        resumeMode: options.resumeRunId ? resumeMode : null,
     });
     reporter.start(workflow.meta, journal.runId, journal.runDir);
+    syncStatus("running");
     const budget = {
         total: budgetTotal,
         spent: () => outputTokens,
@@ -135,31 +166,107 @@ export async function runWorkflow(options) {
         if (budgetTotal !== null && outputTokens >= budgetTotal) {
             throw new Error(`token budget exhausted (${outputTokens}/${budgetTotal} output tokens)`);
         }
-        const key = agentCallKey(prompt, spec, callOptions.schema ?? null);
+        const config = validateConfig(callOptions.config);
+        const key = agentCallKey(prompt, { ...spec, isolation: callOptions.isolation, mcp: callOptions.mcp, config }, callOptions.schema ?? null);
         const label = callOptions.label ?? prompt.replace(/\s+/g, " ").trim().slice(0, 64);
         const phase = callOptions.phase ?? currentPhase;
+        if (priorCalls && prefixIntact) {
+            const prior = priorCalls.get(id);
+            if (!prior || prior.key !== key) {
+                prefixIntact = false;
+            }
+            else if (prior.ok) {
+                journal.append({ type: "agent_end", id, key, label, phase, status: "ok", cached: true, result: prior.result });
+                syncStatus("running");
+                reporter.agentStart(id, label, spec, phase, true);
+                reporter.agentEnd(id, true, 0, "cached");
+                return prior.result;
+            }
+        }
         const cachedQueue = resumeCache?.get(key);
         if (cachedQueue && cachedQueue.length > 0) {
             const result = cachedQueue.shift();
             journal.append({ type: "agent_end", id, key, label, phase, status: "ok", cached: true, result });
+            syncStatus("running");
             reporter.agentStart(id, label, spec, phase, true);
             reporter.agentEnd(id, true, 0, "cached");
             return result;
         }
+        const mcpServers = callOptions.mcp !== undefined ? resolveMcpServers(workspace, callOptions.mcp) : undefined;
         await semaphore.acquire();
         const agentStartedAt = Date.now();
-        reporter.agentStart(id, label, spec, phase, false);
-        journal.append({ type: "agent_start", id, key, label, phase, spec, prompt });
-        const trace = journal.traceWriter(id);
+        let session;
+        let wt;
+        let worktreeFinished = false;
+        // Idempotent so the finally can guarantee cleanup on a throw without
+        // double-finalizing the worktree that the normal path already removed.
+        const finishCreatedWorktree = async () => {
+            if (!wt || worktreeFinished)
+                return undefined;
+            worktreeFinished = true;
+            const wtInfo = await finishWorktree(workspace, wt);
+            const worktree = { path: wt.path, dirty: wtInfo.dirty, removed: wtInfo.removed };
+            if (wtInfo.dirty)
+                reporter.log(`worktree kept: ${wt.path}`);
+            return worktree;
+        };
         try {
+            reporter.agentStart(id, label, spec, phase, false);
+            journal.append({ type: "agent_start", id, key, label, phase, spec, prompt });
+            const trace = journal.traceWriter(id);
+            if (skipped.has(id)) {
+                journal.append({ type: "agent_end", id, key, label, phase, status: "error", error: "skipped via newton skip", seconds: 0 });
+                syncStatus("running");
+                reporter.agentEnd(id, false, 0, "skipped");
+                return null;
+            }
+            if (callOptions.isolation === "worktree") {
+                try {
+                    wt = await createWorktree(workspace, journal.runId, id);
+                }
+                catch (error) {
+                    const message = errorMessage(error);
+                    journal.append({ type: "agent_end", id, key, label, phase, status: "error", error: message, seconds: 0 });
+                    syncStatus("running");
+                    reporter.agentEnd(id, false, 0, message);
+                    return null;
+                }
+            }
+            if (skipped.has(id)) {
+                const worktree = await finishCreatedWorktree();
+                journal.append({
+                    type: "agent_end",
+                    id,
+                    key,
+                    label,
+                    phase,
+                    status: "error",
+                    error: "skipped via newton skip",
+                    seconds: 0,
+                    ...(worktree ? { worktree } : {}),
+                });
+                syncStatus("running");
+                reporter.agentEnd(id, false, 0, "skipped");
+                return null;
+            }
             const fullPrompt = AGENT_PREAMBLE + prompt + (callOptions.schema ? structuredOutputInstruction(callOptions.schema) : "");
-            const session = new AcpAgentSession({
+            const cwd = wt
+                ? callOptions.cwd
+                    ? resolve(wt.path, callOptions.cwd)
+                    : wt.path
+                : callOptions.cwd
+                    ? resolve(workspace, callOptions.cwd)
+                    : workspace;
+            session = new AcpAgentSession({
                 spec,
                 prompt: fullPrompt,
-                cwd: callOptions.cwd ? resolve(workspace, callOptions.cwd) : workspace,
+                cwd,
                 timeoutMs: callOptions.timeoutMs ?? agentTimeoutMs,
+                mcpServers,
+                config,
                 trace,
             });
+            liveSessions.set(id, session);
             let turn = await session.prompt();
             let result = turn.text;
             let failure = turn.error;
@@ -185,11 +292,23 @@ export async function runWorkflow(options) {
                 }
             }
             session.close();
+            const worktree = await finishCreatedWorktree();
             const seconds = Math.round((Date.now() - agentStartedAt) / 1000);
             const turnTokens = turn.usage?.outputTokens ?? 0;
             outputTokens += turnTokens;
             if (failure) {
-                journal.append({ type: "agent_end", id, key, label, phase, status: "error", error: failure, seconds });
+                journal.append({
+                    type: "agent_end",
+                    id,
+                    key,
+                    label,
+                    phase,
+                    status: "error",
+                    error: failure,
+                    seconds,
+                    ...(worktree ? { worktree } : {}),
+                });
+                syncStatus("running");
                 reporter.agentEnd(id, false, seconds, failure);
                 return null;
             }
@@ -204,11 +323,19 @@ export async function runWorkflow(options) {
                 toolCalls: turn.toolCalls,
                 usage: turn.usage,
                 result,
+                ...(worktree ? { worktree } : {}),
             });
+            syncStatus("running");
             reporter.agentEnd(id, true, seconds, turn.usage ? `${turn.toolCalls} tools · ${turnTokens} out-tok` : `${turn.toolCalls} tools`);
             return result;
         }
         finally {
+            if (session) {
+                liveSessions.delete(id);
+                session.close();
+            }
+            // No-op unless a throw skipped the normal finalize (guard above).
+            await finishCreatedWorktree().catch(() => { });
             semaphore.release();
         }
     }
@@ -219,7 +346,7 @@ export async function runWorkflow(options) {
         return Promise.all(thunks.map((thunk) => Promise.resolve()
             .then(thunk)
             .catch((error) => {
-            const message = error instanceof Error ? error.message : String(error);
+            const message = errorMessage(error);
             journal.append({ type: "log", message: `parallel task failed: ${message}` });
             reporter.log(`parallel task failed: ${message}`);
             return null;
@@ -238,7 +365,7 @@ export async function runWorkflow(options) {
                     previous = await stage(previous, item, index);
                 }
                 catch (error) {
-                    const message = error instanceof Error ? error.message : String(error);
+                    const message = errorMessage(error);
                     journal.append({ type: "log", message: `pipeline item ${index} dropped: ${message}` });
                     reporter.log(`pipeline item ${index} dropped: ${message}`);
                     return null;
@@ -253,14 +380,64 @@ export async function runWorkflow(options) {
         currentPhase = title;
         journal.append({ type: "phase", title });
         reporter.phase(title);
+        syncStatus("running");
     }
     function logFn(message) {
         const text = typeof message === "string" ? message : JSON.stringify(message);
         journal.append({ type: "log", message: text });
         reporter.log(text);
     }
+    const realm = createRealm((message) => logFn(message));
+    async function executeScript(loaded, scriptArgs, depth) {
+        const scriptFn = realm.compile(SCRIPT_PARAMS, loaded.body, loaded.file);
+        return scriptFn(agentFn, parallelFn, pipelineFn, phaseFn, logFn, scriptArgs, budget, makeWorkflowFn(loaded.file, depth));
+    }
+    function makeWorkflowFn(callerFile, depth) {
+        return async (nameOrPath, childArgs) => {
+            if (depth >= 1)
+                throw new Error("workflow() nesting is limited to one level");
+            if (typeof nameOrPath !== "string")
+                throw new Error("workflow() takes a workflow name or path string");
+            const registryDir = join(workspace, ".newton", "workflows");
+            const file = /\.(js|mjs)$/.test(nameOrPath) || nameOrPath.includes("/")
+                ? resolve(dirname(callerFile), nameOrPath)
+                : join(registryDir, `${nameOrPath}.js`);
+            if (!existsSync(file)) {
+                let names = [];
+                try {
+                    names = readdirSync(registryDir, { withFileTypes: true })
+                        .filter((entry) => entry.isFile() && /\.(js|mjs)$/.test(entry.name))
+                        .map((entry) => entry.name.replace(/\.(?:js|mjs)$/, ""))
+                        .sort();
+                }
+                catch {
+                    names = [];
+                }
+                throw new Error(`workflow "${nameOrPath}" not found at ${file}; registered workflows: ${names.length > 0 ? names.join(", ") : "(none)"}`);
+            }
+            const child = loadWorkflow(file);
+            journal.append({ type: "workflow_child_start", name: child.meta.name, file: child.file, args: childArgs ?? null });
+            reporter.log(`▸ workflow ${child.meta.name}`);
+            const savedPhase = currentPhase;
+            try {
+                const result = await executeScript(child, childArgs, depth + 1);
+                journal.append({ type: "workflow_child_end", name: child.meta.name, status: "ok" });
+                reporter.log(`✔ workflow ${child.meta.name}`);
+                return result;
+            }
+            catch (error) {
+                const message = errorMessage(error);
+                journal.append({ type: "workflow_child_end", name: child.meta.name, status: "error", error: message });
+                reporter.log(`✖ workflow ${child.meta.name}: ${message}`);
+                throw error;
+            }
+            finally {
+                currentPhase = savedPhase;
+            }
+        };
+    }
     try {
-        const result = await scriptFn(agentFn, parallelFn, pipelineFn, phaseFn, logFn, options.args, budget, guardedDate, guardedMath);
+        const result = await executeScript(workflow, options.args, 0);
         const runResult = {
             runId: journal.runId,
             status: "ok",
@@ -270,11 +447,13 @@ export async function runWorkflow(options) {
             durationMs: Date.now() - startedAt,
         };
         journal.append({ type: "workflow_end", status: "ok", result: runResult.result, agents: agentCounter, outputTokens });
+        syncStatus("ok", { result: runResult.result });
         return runResult;
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+        const message = errorMessage(error);
         journal.append({ type: "workflow_end", status: "error", error: message, agents: agentCounter, outputTokens });
+        syncStatus("error", { error: message });
         return {
             runId: journal.runId,
             status: "error",
@@ -284,4 +463,7 @@ export async function runWorkflow(options) {
             durationMs: Date.now() - startedAt,
         };
     }
+    finally {
+        clearInterval(controlTimer);
+    }
 }

package/dist/journal.js

@@ -27,7 +27,7 @@ export class RunJournal {
         };
     }
 }
-function newRunId() {
+export function newRunId() {
     const now = new Date();
     const stamp = now
         .toISOString()
@@ -43,8 +43,14 @@ export function agentCallKey(prompt, spec, schema) {
         .slice(0, 32);
 }
 /**
- * Resume cache: successful agent results from a prior run, keyed by
- * (prompt, spec, schema) hash. Duplicate keys replay in call order.
+ * Resume has two modes:
+ *   - prefix: load prior calls by positional id via loadResumeCalls.
+ *   - hash: load successful results by (prompt, spec, schema) hash here.
+ *
+ * Invariant: journal `id` is the positional sequence. Agent ids increment at
+ * every agent() call, including cached calls.
+ *
+ * Duplicate hash keys replay in call order.
  */
 export function loadResumeCache(workspace, runId) {
     const journalPath = join(workspace, ".newton", "runs", runId, "journal.jsonl");
@@ -70,3 +76,34 @@ export function loadResumeCache(workspace, runId) {
     }
     return cache;
 }
+export function loadResumeCalls(workspace, runId) {
+    const journalPath = join(workspace, ".newton", "runs", runId, "journal.jsonl");
+    if (!existsSync(journalPath)) {
+        throw new Error(`No journal found for run "${runId}" (looked at ${journalPath})`);
+    }
+    const calls = new Map();
+    for (const line of readFileSync(journalPath, "utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const id = entry.id;
+        const key = entry.key;
+        if (typeof id !== "number" || !Number.isFinite(id) || typeof key !== "string")
+            continue;
+        if (entry.type === "agent_start") {
+            if (!calls.has(id)) {
+                calls.set(id, { key, ok: false });
+            }
+        }
+        else if (entry.type === "agent_end") {
+            calls.set(id, { key, ok: entry.status === "ok", result: entry.result });
+        }
+    }
+    return calls;
+}

package/dist/mcp.js

@@ -0,0 +1,102 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function errorMessage(error) {
+    return isRecord(error) && typeof error.message === "string" ? error.message : String(error);
+}
+function readMcpConfig(workspace) {
+    const path = join(workspace, ".mcp.json");
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === "ENOENT") {
+            throw new Error(`MCP config file not found at ${path}`);
+        }
+        throw new Error(`Could not read ${path}: ${errorMessage(error)}`);
+    }
+    if (!isRecord(parsed) || !isRecord(parsed.mcpServers)) {
+        throw new Error(`${path}: expected { "mcpServers": { ... } }`);
+    }
+    return { path, servers: parsed.mcpServers };
+}
+function availableNames(servers) {
+    const names = Object.keys(servers).sort();
+    return names.length > 0 ? names.join(", ") : "(none)";
+}
+function optionalStringArray(value, field) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+        throw new Error(`${field} must be an array of strings`);
+    }
+    return value;
+}
+function nameValueEntries(value, field) {
+    if (value === undefined || value === null)
+        return [];
+    if (!isRecord(value))
+        throw new Error(`${field} must be an object`);
+    return Object.entries(value).map(([name, entryValue]) => ({ name, value: String(entryValue) }));
+}
+function toMcpServer(name, value, source) {
+    if (!isRecord(value))
+        throw new Error(`${source} must be an object`);
+    if (value.type !== undefined) {
+        if (value.type !== "http" && value.type !== "sse") {
+            throw new Error(`${source} type must be "http" or "sse"`);
+        }
+        if (typeof value.url !== "string" || !value.url) {
+            throw new Error(`${source} missing url`);
+        }
+        return {
+            type: value.type,
+            name,
+            url: value.url,
+            headers: nameValueEntries(value.headers, `${source} headers`),
+        };
+    }
+    if (typeof value.command !== "string" || !value.command) {
+        throw new Error(`${source} missing command`);
+    }
+    return {
+        name,
+        command: value.command,
+        args: optionalStringArray(value.args, `${source} args`),
+        env: nameValueEntries(value.env, `${source} env`),
+    };
+}
+export function resolveMcpServers(workspace, opt) {
+    if (opt === true) {
+        const config = readMcpConfig(workspace);
+        return Object.entries(config.servers).map(([name, server]) => toMcpServer(name, server, `MCP server "${name}"`));
+    }
+    if (!Array.isArray(opt)) {
+        throw new Error("agent() mcp option takes true or an array of names/servers");
+    }
+    let config;
+    const getConfig = () => {
+        config ??= readMcpConfig(workspace);
+        return config;
+    };
+    return opt.map((entry) => {
+        if (typeof entry === "string") {
+            const loaded = getConfig();
+            const server = loaded.servers[entry];
+            if (server === undefined) {
+                throw new Error(`MCP server "${entry}" not found in ${loaded.path}; available: ${availableNames(loaded.servers)}`);
+            }
+            return toMcpServer(entry, server, `MCP server "${entry}"`);
+        }
+        if (!isRecord(entry)) {
+            throw new Error("agent() mcp option takes true or an array of names/servers");
+        }
+        if (typeof entry.name !== "string" || !entry.name.trim()) {
+            throw new Error("inline MCP server missing name");
+        }
+        return toMcpServer(entry.name, entry, `inline MCP server "${entry.name}"`);
+    });
+}

package/dist/sandbox.js

@@ -0,0 +1,157 @@
+import * as vm from "node:vm";
+export function createRealm(consoleLog) {
+    const context = vm.createContext({}, { codeGeneration: { strings: false, wasm: false } });
+    const hostCallables = new Map();
+    let nextCallableId = 1;
+    let makeRealmCallable;
+    let makeRealmArray;
+    let makeRealmObject;
+    vm.runInContext(`
+{
+const RealmDate = Date;
+const dateNowUnavailable = () => {
+  throw new Error("Date.now() is unavailable in workflows (breaks resume); pass timestamps via --args");
+};
+const mathRandomUnavailable = () => {
+  throw new Error("Math.random() is unavailable in workflows (breaks resume); vary prompts by index instead");
+};
+
+const GuardedDate = new Proxy(RealmDate, {
+  get(target, prop, receiver) {
+    if (prop === "now") return dateNowUnavailable;
+    return Reflect.get(target, prop, receiver);
+  },
+  construct(target, argArray) {
+    if (argArray.length === 0) {
+      throw new Error("new Date() without arguments is unavailable in workflows (breaks resume)");
+    }
+    return Reflect.construct(target, argArray);
+  },
+});
+globalThis.Date = GuardedDate;
+Object.defineProperty(RealmDate.prototype, "constructor", {
+  value: GuardedDate,
+  writable: true,
+  configurable: true,
+});
+
+Math.random = mathRandomUnavailable;
+}
+`, context);
+    const bridge = (id, args) => {
+        const callable = hostCallables.get(id);
+        if (!callable)
+            throw new Error(`unknown workflow host function ${id}`);
+        return callable(...args);
+    };
+    context.__newtonBridge = bridge;
+    const helpers = vm.runInContext(`
+(() => {
+  const bridge = globalThis.__newtonBridge;
+  delete globalThis.__newtonBridge;
+
+  const importValue = (value, seen = new WeakMap()) => {
+    if (value === null || value === undefined) return value;
+    const kind = typeof value;
+    if (kind !== "object") return kind === "function" ? undefined : value;
+    const existing = seen.get(value);
+    if (existing) return existing;
+    if (Array.isArray(value)) {
+      const copy = [];
+      seen.set(value, copy);
+      for (let i = 0; i < value.length; i++) copy[i] = importValue(value[i], seen);
+      return copy;
+    }
+    const copy = {};
+    seen.set(value, copy);
+    for (const key of Object.keys(value)) copy[key] = importValue(value[key], seen);
+    return copy;
+  };
+
+  const importError = (error) =>
+    new Error(error && typeof error === "object" && typeof error.message === "string" ? error.message : String(error));
+
+  const makeCallable = (id) => (...args) => {
+    try {
+      const result = bridge(id, args);
+      if (result && typeof result === "object" && typeof result.then === "function") {
+        return Promise.resolve(result).then(
+          (value) => importValue(value),
+          (error) => {
+            throw importError(error);
+          },
+        );
+      }
+      return importValue(result);
+    } catch (error) {
+      throw importError(error);
+    }
+  };
+
+  return {
+    makeCallable,
+    makeArray: (items) => Array.from(items),
+    makeObject: (entries) => {
+      const object = {};
+      for (const [key, value] of entries) object[key] = value;
+      return object;
+    },
+  };
+})()
+`, context);
+    makeRealmCallable = helpers.makeCallable;
+    makeRealmArray = helpers.makeArray;
+    makeRealmObject = helpers.makeObject;
+    const wrapHostCallable = (callable) => {
+        const id = nextCallableId++;
+        hostCallables.set(id, callable);
+        return makeRealmCallable(id);
+    };
+    const toRealmValue = (value) => {
+        if (value === null || value === undefined)
+            return value;
+        if (typeof value === "function")
+            return wrapHostCallable(value);
+        if (typeof value !== "object")
+            return value;
+        if (Array.isArray(value))
+            return makeRealmArray(value.map((item) => toRealmValue(item)));
+        return makeRealmObject(Object.entries(value).map(([key, entry]) => [key, toRealmValue(entry)]));
+    };
+    const writeConsole = (...args) => {
+        consoleLog(args.map(formatConsoleArg).join(" "));
+    };
+    context.__newtonConsole = makeRealmObject([
+        ["log", wrapHostCallable(writeConsole)],
+        ["info", wrapHostCallable(writeConsole)],
+        ["warn", wrapHostCallable(writeConsole)],
+        ["error", wrapHostCallable(writeConsole)],
+        ["debug", wrapHostCallable(writeConsole)],
+    ]);
+    vm.runInContext(`
+globalThis.console = globalThis.__newtonConsole;
+delete globalThis.__newtonConsole;
+`, context);
+    return {
+        compile(params, body, filename) {
+            const scriptFn = vm.runInContext(`(async function(${params.join(",")}) {"use strict";\n${body}\n})`, context, {
+                filename,
+            });
+            return (...args) => scriptFn(...args.map((arg) => toRealmValue(arg)));
+        },
+    };
+}
+export function checkCompile(params, body) {
+    new vm.Script('(async function(' + params.join(",") + ') {"use strict";\n' + body + "\n})");
+}
+function formatConsoleArg(arg) {
+    if (typeof arg === "string")
+        return arg;
+    try {
+        const json = JSON.stringify(arg);
+        return json === undefined ? String(arg) : json;
+    }
+    catch {
+        return String(arg);
+    }
+}

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.3.0";
+export const VERSION = "0.4.0";

package/dist/worktree.js

@@ -0,0 +1,51 @@
+import { execFile } from "node:child_process";
+import { mkdirSync, rmdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export async function createWorktree(workspace, runId, agentId) {
+    const path = join(workspace, ".newton", "worktrees", runId, `agent-${agentId}`);
+    mkdirSync(dirname(path), { recursive: true });
+    try {
+        // Detached HEAD avoids branch-name coordination across parallel agents.
+        await git(["-C", workspace, "worktree", "add", "--detach", path, "HEAD"]);
+        const baseHead = (await git(["-C", path, "rev-parse", "HEAD"])).trim();
+        return { path, baseHead };
+    }
+    catch (error) {
+        throw new Error(`worktree setup failed: ${gitStderr(error)}`);
+    }
+}
+export async function finishWorktree(workspace, wt) {
+    try {
+        const status = await git(["-C", wt.path, "status", "--porcelain"]);
+        const head = (await git(["-C", wt.path, "rev-parse", "HEAD"])).trim();
+        const dirty = status.trim().length > 0 || head !== wt.baseHead;
+        if (dirty)
+            return { dirty: true, removed: false };
+        // Force is intentional after the clean check: this is disposable isolation.
+        await git(["-C", workspace, "worktree", "remove", "--force", wt.path]);
+        try {
+            rmdirSync(dirname(wt.path));
+        }
+        catch {
+            // Best-effort cleanup of the per-run directory.
+        }
+        return { dirty: false, removed: true };
+    }
+    catch {
+        return { dirty: true, removed: false };
+    }
+}
+async function git(args) {
+    const { stdout } = await execFileAsync("git", args);
+    return stdout.toString();
+}
+function gitStderr(error) {
+    if (typeof error === "object" && error !== null && "stderr" in error) {
+        const stderr = String(error.stderr ?? "").trim();
+        if (stderr)
+            return stderr;
+    }
+    return error instanceof Error ? error.message : String(error);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gigaai/newton",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Deterministic multi-agent workflow executor. Write workflows in plain JavaScript; Newton drives coding agents over the Agent Client Protocol.",
   "license": "Apache-2.0",
   "repository": {