stageflow 0.39.0 → 0.40.0

package/dist/runtime/stageWorker.js

@@ -11,6 +11,7 @@ import { bindPiAgentDirEnv, overlayStageBindingEnv, rootsForStageWorker, stageBi
 import { buildStageEnvironment } from "./stageEnvironment.js";
 import { ensureStageCacheDirs } from "./stageCacheEnv.js";
 import { PACKAGE_VERSION } from "../package-meta.js";
+import { openStageSandbox } from "./stageSandbox.js";
 import { runStage, isRunStageWaiting, } from "./stageRunner.js";
 import { openStageAttempt } from "./stageAttemptBootstrap.js";
 import { attemptContext } from "./stageAttemptContext.js";
@@ -60,97 +61,137 @@ export async function runStageWorker(input) {
         .filter((e) => e[1] !== undefined));
     const mode = input.mode ?? "run";
     const attempt = input.attempt ?? 1;
-    loadNamedSecretsFromAttemptDir(attemptWorkspaceDir(workspaceDir, input.stageId, attempt));
+    const attemptDir = attemptWorkspaceDir(workspaceDir, input.stageId, attempt);
+    loadNamedSecretsFromAttemptDir(attemptDir);
     const attemptCtx = input.attempt !== undefined ? attemptContext(input.attempt) : undefined;
     const eventOptions = { attempt };
-    const roots = withResolvedAuthPath(rootsForStageWorker(workspaceDir, input.stageId, stage.model, checkoutRoot, attemptCtx), input.rootDir);
+    let roots = withResolvedAuthPath(rootsForStageWorker(workspaceDir, input.stageId, stage.model, checkoutRoot, attemptCtx), input.rootDir);
     const unbindAgentDir = bindPiAgentDirEnv(roots.agentDir);
+    const sandbox = await openStageSandbox({
+        env: process.env,
+        roots,
+        runId: input.runId,
+        stageId: input.stageId,
+        attempt,
+        attemptDir,
+        ...(checkoutRoot !== undefined ? { checkoutRoot } : {}),
+    });
+    roots = sandbox.roots;
+    const beforeVerify = sandbox.beforeVerify;
+    let outcome;
+    let thrown;
     try {
-        if (mode === "resume") {
-            const opened = await openStageAttempt({
-                agent,
-                store,
-                runId: input.runId,
-                stage,
-                stageId: input.stageId,
-                task,
-                dag,
-                checkoutRoot,
-                workspaceDir,
-                factoryCwd: input.rootDir,
-                attemptCtx,
-                operatorCatalog: input.operatorCatalog,
-                roots,
-                resumeToken: input.sessionFilePath,
-                sessionMode: "waiting_resume",
-                stageEnv,
-                onActivity: (event) => {
-                    void store.appendStageEvent(input.runId, input.stageId, event, eventOptions);
-                },
-            });
-            if (!opened.ok) {
-                return { ok: false, reason: opened.reason };
+        outcome = await (async () => {
+            if (sandbox.failure !== undefined) {
+                return { ok: false, reason: sandbox.failure };
             }
-            opened.handle.deliverAnswer(input.resumeAnswer);
-            const outcome = await runStage({
-                agent,
-                store,
-                runId: input.runId,
-                stage,
-                stageId: input.stageId,
-                task,
-                dag,
-                checkoutRoot,
-                workspaceDir,
-                skipStarted: true,
-                existingHandle: opened.handle,
-                workerMode: true,
-                roots,
-                attemptCtx,
-                factoryCwd: input.rootDir,
-                operatorCatalog: input.operatorCatalog,
-                skipGates: input.skipGates,
-                stageEnv,
-            });
-            return outcome;
-        }
-        if (mode === "feedback_resume" || mode === "new_session") {
-            const feedbackLoopContext = await loadActiveFeedbackLoopContext(store, input.runId, input.stageId);
-            if (mode === "feedback_resume" && feedbackLoopContext === undefined) {
-                return {
-                    ok: false,
-                    reason: "feedback_resume requires an active feedback-loop context",
-                };
+            if (mode === "resume") {
+                const opened = await openStageAttempt({
+                    agent,
+                    store,
+                    runId: input.runId,
+                    stage,
+                    stageId: input.stageId,
+                    task,
+                    dag,
+                    checkoutRoot,
+                    workspaceDir,
+                    factoryCwd: input.rootDir,
+                    attemptCtx,
+                    operatorCatalog: input.operatorCatalog,
+                    roots,
+                    resumeToken: input.sessionFilePath,
+                    sessionMode: "waiting_resume",
+                    stageEnv,
+                    onActivity: (event) => {
+                        void store.appendStageEvent(input.runId, input.stageId, event, eventOptions);
+                    },
+                });
+                if (!opened.ok) {
+                    return { ok: false, reason: opened.reason };
+                }
+                opened.handle.deliverAnswer(input.resumeAnswer);
+                const outcome = await runStage({
+                    agent,
+                    store,
+                    runId: input.runId,
+                    stage,
+                    stageId: input.stageId,
+                    task,
+                    dag,
+                    checkoutRoot,
+                    workspaceDir,
+                    skipStarted: true,
+                    existingHandle: opened.handle,
+                    workerMode: true,
+                    roots,
+                    attemptCtx,
+                    factoryCwd: input.rootDir,
+                    operatorCatalog: input.operatorCatalog,
+                    skipGates: input.skipGates,
+                    stageEnv,
+                    beforeVerify,
+                });
+                return outcome;
             }
-            const priorAttempt = feedbackLoopContext?.prior_stage_attempt;
-            const resumeToken = input.sessionFilePath ??
-                (mode === "feedback_resume" && priorAttempt !== undefined
-                    ? attemptContext(priorAttempt).sessionPath(workspaceDir, input.stageId)
-                    : undefined);
-            const opened = await openStageAttempt({
-                agent,
-                store,
-                runId: input.runId,
-                stage,
-                stageId: input.stageId,
-                task,
-                dag,
-                checkoutRoot,
-                workspaceDir,
-                factoryCwd: input.rootDir,
-                attemptCtx,
-                operatorCatalog: input.operatorCatalog,
-                roots,
-                ...(resumeToken !== undefined ? { resumeToken } : {}),
-                sessionMode: mode,
-                ...(feedbackLoopContext !== undefined ? { feedbackLoopContext } : {}),
-                stageEnv,
-                onActivity: (event) => {
-                    void store.appendStageEvent(input.runId, input.stageId, event, eventOptions);
-                },
-            });
-            if (!opened.ok) {
-                return { ok: false, reason: opened.reason };
+            if (mode === "feedback_resume" || mode === "new_session") {
+                const feedbackLoopContext = await loadActiveFeedbackLoopContext(store, input.runId, input.stageId);
+                if (mode === "feedback_resume" && feedbackLoopContext === undefined) {
+                    return {
+                        ok: false,
+                        reason: "feedback_resume requires an active feedback-loop context",
+                    };
+                }
+                const priorAttempt = feedbackLoopContext?.prior_stage_attempt;
+                const resumeToken = input.sessionFilePath ??
+                    (mode === "feedback_resume" && priorAttempt !== undefined
+                        ? attemptContext(priorAttempt).sessionPath(workspaceDir, input.stageId)
+                        : undefined);
+                const opened = await openStageAttempt({
+                    agent,
+                    store,
+                    runId: input.runId,
+                    stage,
+                    stageId: input.stageId,
+                    task,
+                    dag,
+                    checkoutRoot,
+                    workspaceDir,
+                    factoryCwd: input.rootDir,
+                    attemptCtx,
+                    operatorCatalog: input.operatorCatalog,
+                    roots,
+                    ...(resumeToken !== undefined ? { resumeToken } : {}),
+                    sessionMode: mode,
+                    ...(feedbackLoopContext !== undefined ? { feedbackLoopContext } : {}),
+                    stageEnv,
+                    onActivity: (event) => {
+                        void store.appendStageEvent(input.runId, input.stageId, event, eventOptions);
+                    },
+                });
+                if (!opened.ok) {
+                    return { ok: false, reason: opened.reason };
+                }
+                return runStage({
+                    agent,
+                    store,
+                    runId: input.runId,
+                    stage,
+                    stageId: input.stageId,
+                    task,
+                    dag,
+                    checkoutRoot,
+                    workspaceDir,
+                    existingHandle: opened.handle,
+                    workerMode: true,
+                    roots,
+                    attemptCtx,
+                    factoryCwd: input.rootDir,
+                    operatorCatalog: input.operatorCatalog,
+                    skipGates: input.skipGates,
+                    stageEnv,
+                    beforeVerify,
+                });
             }
             return runStage({
                 agent,
@@ -162,7 +203,6 @@ export async function runStageWorker(input) {
                 dag,
                 checkoutRoot,
                 workspaceDir,
-                existingHandle: opened.handle,
                 workerMode: true,
                 roots,
                 attemptCtx,
@@ -170,30 +210,23 @@ export async function runStageWorker(input) {
                 operatorCatalog: input.operatorCatalog,
                 skipGates: input.skipGates,
                 stageEnv,
+                beforeVerify,
             });
-        }
-        return runStage({
-            agent,
-            store,
-            runId: input.runId,
-            stage,
-            stageId: input.stageId,
-            task,
-            dag,
-            checkoutRoot,
-            workspaceDir,
-            workerMode: true,
-            roots,
-            attemptCtx,
-            factoryCwd: input.rootDir,
-            operatorCatalog: input.operatorCatalog,
-            skipGates: input.skipGates,
-            stageEnv,
-        });
+        })();
+    }
+    catch (err) {
+        thrown = err;
     }
     finally {
         unbindAgentDir();
+        await sandbox.close();
+    }
+    if (thrown !== undefined)
+        throw thrown;
+    if (outcome === undefined) {
+        throw new Error("stage worker finished without an outcome");
     }
+    return outcome;
 }
 export function sendWorkerResult(result) {
     if (typeof process.send !== "function") {

package/dist/runtime/workspaceBinding.d.ts

@@ -1,4 +1,5 @@
 import { type LoadOutcome } from "../config/loadOutcome.js";
+import type { CheckoutDescriptor } from "../types/task.js";
 export type WorkspaceBinding = {
     kind: "repository";
     repository: string;
@@ -12,7 +13,7 @@ export type WorkspaceBinding = {
 export type WorkspaceBindingInput = {
     repository?: string;
     ref?: string;
-    checkout?: string;
+    checkout?: CheckoutDescriptor;
 };
 export type ResolveWorkspaceBindingOptions = {
     checkoutOverride?: string;

package/dist/runtime/workspaceBinding.js

@@ -9,12 +9,25 @@ function nonEmptyTrimmed(value) {
 function isGithubOwnerRepo(repository) {
     return OWNER_REPO_RE.test(repository);
 }
+function resolveCheckoutBinding(checkout, checkoutOverride) {
+    const override = nonEmptyTrimmed(checkoutOverride);
+    if (override !== undefined)
+        return override;
+    if (checkout === undefined)
+        return undefined;
+    if (typeof checkout === "string")
+        return nonEmptyTrimmed(checkout);
+    if (typeof checkout === "object" && checkout !== null && !Array.isArray(checkout)) {
+        return checkout;
+    }
+    return undefined;
+}
 export function resolveWorkspaceBinding(task, options) {
     const repository = nonEmptyTrimmed(task.repository);
     const ref = nonEmptyTrimmed(task.ref);
-    const checkoutPath = nonEmptyTrimmed(options?.checkoutOverride ?? task.checkout);
+    const checkoutBinding = resolveCheckoutBinding(task.checkout, options?.checkoutOverride);
     const hasRepositoryField = repository !== undefined;
-    if (hasRepositoryField && checkoutPath !== undefined) {
+    if (hasRepositoryField && checkoutBinding !== undefined) {
         return loadFailure([
             {
                 code: "task.binding_conflict",
@@ -53,8 +66,11 @@ export function resolveWorkspaceBinding(task, options) {
         }
         return loadSuccess({ kind: "repository", repository, ref });
     }
-    if (checkoutPath !== undefined) {
-        return loadSuccess({ kind: "checkout", path: checkoutPath });
+    if (typeof checkoutBinding === "string") {
+        return loadSuccess({ kind: "checkout", path: checkoutBinding });
+    }
+    if (typeof checkoutBinding === "object") {
+        return loadSuccess({ kind: "checkout", path: "" });
     }
     return loadSuccess({ kind: "unbound" });
 }

package/dist/tools/readEmail.d.ts

@@ -6,12 +6,12 @@ export declare function createSearchEmailTool(email: StageEmail): {
     description: string;
     parameters: Type.TObject<Type.TProperties>;
     execute(_toolCallId: string, input: unknown): Promise<{
-        isError?: undefined;
         content: {
             type: "text";
             text: string;
         }[];
         details: unknown;
+        isError?: undefined;
     } | {
         content: {
             type: "text";
@@ -31,12 +31,12 @@ export declare function createGetEmailTool(email: StageEmail): {
     description: string;
     parameters: Type.TObject<Type.TProperties>;
     execute(_toolCallId: string, input: unknown): Promise<{
-        isError?: undefined;
         content: {
             type: "text";
             text: string;
         }[];
         details: unknown;
+        isError?: undefined;
     } | {
         content: {
             type: "text";
@@ -56,12 +56,12 @@ export declare function createDownloadEmailAttachmentTool(email: StageEmail): {
     description: string;
     parameters: Type.TObject<Type.TProperties>;
     execute(_toolCallId: string, input: unknown): Promise<{
-        isError?: undefined;
         content: {
             type: "text";
             text: string;
         }[];
         details: unknown;
+        isError?: undefined;
     } | {
         content: {
             type: "text";

package/dist/types/task.d.ts

@@ -2,12 +2,22 @@ export type TaskGitIdentity = {
     name?: string;
     email?: string;
 };
+/**
+ * A string points at a pre-made checkout directory (validated, never
+ * created — today's behavior). An object asks Stageflow to create/reuse a
+ * git worktree for `branch` (auto-named from the task id when omitted),
+ * branching off `base` (default: HEAD) the first time it's created.
+ */
+export type CheckoutDescriptor = string | {
+    branch?: string;
+    base?: string;
+};
 export type TaskFile = {
     id: string;
     goal: string;
     context?: string;
     constraints?: string;
-    checkout?: string;
+    checkout?: CheckoutDescriptor;
     repository?: string;
     ref?: string;
     run_branch_template?: string;

package/examples/memory/README.md

@@ -96,4 +96,6 @@ After `desk-revisit-outage`, the release card should be the rollback-finished no
 
 The operator, in **Memories**, can list keys, open the `TICKET-1842` card, correct it, and delete it. Delete removes the current card and the previous copy and cannot be undone. The page shows the previous card copy and the previous cover text when they exist. The operator can edit the cover. The operator does not create cards; a session adds them. There is one previous copy, not a full history, and no restore action.
 
+`sandbox-memory-bash` is the sandbox probe. It attaches `shared-notes` and its `probe` stage runs one bash command, then reports whether that command printed a `body.md` path. The task is `probe-bash`. Create `shared-notes` before running it. Edit the `probe` stage prompt in the pipeline file.
+
 This directory is excluded from the repo-root catalog scan, because those commands fail until `notebook` exists.

package/examples/memory/probe-bash.task.yaml

@@ -0,0 +1,3 @@
+id: probe-bash
+goal: See whether bash can find memory files on the host.
+input: {}

package/examples/memory/sandbox-memory-bash.pipeline.yaml

@@ -0,0 +1,28 @@
+id: sandbox-memory-bash
+stages:
+  - id: probe
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      Use the bash tool to look up the other memory which we dont have access to if its their. it might not be if its not found. 
+      if found or not then call the following emit stage tool.  
+      then also add something to the memory you have access to .
+      Then call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"found": true if the bash found the other memory, otherwise false, "output":"<the bash stdout>"}.
+    io:
+      input:
+        schema:
+          type: object
+          additionalProperties: true
+      output:
+        schema:
+          type: object
+          required:
+            - found
+            - output
+          properties:
+            found:
+              type: boolean
+            output:
+              type: string
+          additionalProperties: false
+memories:
+  - shared-notes

package/examples/ship-feature/README.md

@@ -121,6 +121,21 @@ run finishes (or if it fails partway through), remove the worktree with
 `git worktree remove ../your-repo-feature-branch` from the main clone once
 you no longer need it.
 
+Alternatively, let Stageflow do this for you: point `checkout` at an object
+instead of a path —
+
+```yaml
+checkout:
+  branch: your-feature-branch   # optional — defaults to stageflow/<task id>
+  base: origin/main             # optional — defaults to HEAD
+```
+
+— and Stageflow creates (or reuses, if it already exists) a worktree for
+that branch the same way, as a sibling of your project root
+(`../.stageflow-worktrees/<branch>`). It's never auto-removed, same as one
+you make by hand — clean it up yourself with `git worktree remove` when
+you're done.
+
 ## Create a task
 
 Task context is the pipeline's portable feature brief. Include enough detail

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stageflow",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "Stageflow — CLI pipeline runtime for configurable stages on Pi",
   "type": "module",
   "main": "./dist/index.js",