stageflow 0.25.0 → 0.30.0

package/dist/runtime/completionCheckRunner.d.ts

@@ -16,6 +16,7 @@ export type CommandExecutionInput = {
     command: string;
     cwd: string;
     timeout_ms?: number;
+    env?: NodeJS.ProcessEnv;
 };
 export type CommandExecutor = {
     run(input: CommandExecutionInput): Promise<CommandExecution>;
@@ -61,6 +62,8 @@ export type CompletionCheckRunnerInput = {
     artifactsDir: string;
     /** Base directory used for a command check without its own cwd. */
     commandWorkingDirectory?: string;
+    /** Curated env for command checks; omit to inherit the caller's process env. */
+    commandEnv?: NodeJS.ProcessEnv;
     commandExecutor?: CommandExecutor;
     gates?: GateDecisionProvider;
     /** Captured before the agent attempt began. */
@@ -69,6 +72,12 @@ export type CompletionCheckRunnerInput = {
     /** Why the runtime could not establish the required pre-stage baseline. */
     checkoutError?: string;
     checklistAttestations?: readonly ChecklistAttestation[];
+    /** Re-runs the Host login check against the stage's own browser session. */
+    browserLogin?: () => Promise<{
+        state: "logged_in" | "logged_out" | "unknown";
+        logged_in: boolean | null;
+        url: string;
+    }>;
     onCheckStart?: (check: CompletionCheck) => Promise<void> | void;
     onCheckComplete?: (result: CompletionCheckResult) => Promise<void> | void;
 };
@@ -115,7 +124,12 @@ export type ChecklistCheckEvidence = {
     missing_items: string[];
     unexpected_items: string[];
 };
-export type CompletionCheckEvidence = CommandCheckEvidence | ArtifactCheckEvidence | PayloadSchemaCheckEvidence | GateCheckEvidence | CheckoutChangesCheckEvidence | ChecklistCheckEvidence;
+export type BrowserLoginCheckEvidence = {
+    kind: "browser_login";
+    state?: "logged_in" | "logged_out" | "unknown";
+    url?: string;
+};
+export type CompletionCheckEvidence = BrowserLoginCheckEvidence | CommandCheckEvidence | ArtifactCheckEvidence | PayloadSchemaCheckEvidence | GateCheckEvidence | CheckoutChangesCheckEvidence | ChecklistCheckEvidence;
 export type CompletionCheckResult = {
     check_id: string;
     check_type: CompletionCheck["type"];

package/dist/runtime/completionCheckRunner.js

@@ -3,7 +3,12 @@ import { spawn } from "node:child_process";
 import { lstat, readFile } from "node:fs/promises";
 import path from "node:path";
 import { assertEnvelopePayload } from "../envelope/payloadSchema.js";
+import { resolveBashPath } from "../preflight/bash.js";
+import { redactString } from "../logging/redact.js";
+import { getNamedSecrets } from "../logging/namedSecrets.js";
+import { signalProcessGroup } from "./stageProcessLauncher.js";
 const MAX_COMMAND_OUTPUT_BYTES = 64 * 1024;
+const COMMAND_KILL_ESCALATE_MS = 2000;
 function captureOutput(chunks, chunk, currentSize) {
     const remaining = MAX_COMMAND_OUTPUT_BYTES - currentSize;
     if (remaining <= 0)
@@ -23,19 +28,26 @@ export const nodeCommandExecutor = {
             let timedOut = false;
             let settled = false;
             let timeout;
+            let escalateTimer;
             const finish = (result) => {
                 if (settled)
                     return;
                 settled = true;
                 if (timeout)
                     clearTimeout(timeout);
+                // When timed out, keep escalateTimer so SIGKILL still runs after the
+                // grace window even if the parent already exited cooperatively.
+                if (escalateTimer && !timedOut)
+                    clearTimeout(escalateTimer);
                 resolve(result);
             };
             let child;
             try {
-                child = spawn(input.command, {
+                const bash = resolveBashPath(input.env ?? process.env);
+                child = spawn(bash, ["-c", input.command], {
                     cwd: input.cwd,
-                    shell: true,
+                    env: input.env,
+                    detached: true,
                     stdio: ["ignore", "pipe", "pipe"],
                 });
             }
@@ -55,6 +67,12 @@ export const nodeCommandExecutor = {
             child.stderr?.on("data", (data) => {
                 stderrSize = captureOutput(stderr, Buffer.from(data), stderrSize);
             });
+            child.once("exit", () => {
+                if (timedOut) {
+                    // Parent may exit on SIGTERM while SIGTERM-proof grandchildren remain.
+                    signalProcessGroup(child.pid, "SIGKILL");
+                }
+            });
             child.once("error", (error) => {
                 finish({
                     exit_code: null,
@@ -75,7 +93,12 @@ export const nodeCommandExecutor = {
             if (input.timeout_ms !== undefined) {
                 timeout = setTimeout(() => {
                     timedOut = true;
-                    child.kill("SIGTERM");
+                    const pid = child.pid;
+                    signalProcessGroup(pid, "SIGTERM");
+                    escalateTimer = setTimeout(() => {
+                        // Always escalate after the grace window regardless of exited.
+                        signalProcessGroup(pid, "SIGKILL");
+                    }, COMMAND_KILL_ESCALATE_MS);
                 }, input.timeout_ms);
             }
         });
@@ -101,16 +124,31 @@ async function runCommandCheck(check, input) {
     const cwd = resolveCommandCwd(check, base);
     const executor = input.commandExecutor ?? nodeCommandExecutor;
     try {
-        const execution = await executor.run({ command: check.run, cwd, timeout_ms: check.timeout_ms });
+        const execution = await executor.run({
+            command: check.run,
+            cwd,
+            timeout_ms: check.timeout_ms,
+            ...(input.commandEnv !== undefined ? { env: input.commandEnv } : {}),
+        });
         const evidence = {
             kind: "command",
             command: check.run,
             cwd,
             exit_code: execution.exit_code,
-            stdout: execution.stdout,
-            stderr: execution.stderr,
+            stdout: redactString(execution.stdout, {
+                namedSecrets: getNamedSecrets(),
+            }),
+            stderr: redactString(execution.stderr, {
+                namedSecrets: getNamedSecrets(),
+            }),
             timed_out: execution.timed_out,
-            ...(execution.error !== undefined ? { error: execution.error } : {}),
+            ...(execution.error !== undefined
+                ? {
+                    error: redactString(execution.error, {
+                        namedSecrets: getNamedSecrets(),
+                    }),
+                }
+                : {}),
         };
         if (execution.timed_out)
             return result(check, "failed", evidence, "command timed out");
@@ -326,6 +364,26 @@ function runChecklistCheck(check, input) {
     }
     return result(check, "passed", evidence);
 }
+async function runBrowserLoginCheck(check, input) {
+    const empty = { kind: "browser_login" };
+    if (input.browserLogin === undefined) {
+        return result(check, "error", empty, "browser_login check requires a browser session");
+    }
+    try {
+        const observed = await input.browserLogin();
+        const evidence = {
+            kind: "browser_login",
+            state: observed.state,
+            url: observed.url,
+        };
+        return observed.logged_in === true
+            ? result(check, "passed", evidence)
+            : result(check, "failed", evidence, `the Host login check still sees a ${observed.state === "unknown" ? "session it cannot confirm" : "logged-out session"}`);
+    }
+    catch (error) {
+        return result(check, "error", empty, error instanceof Error ? error.message : String(error));
+    }
+}
 async function runCheck(check, input) {
     switch (check.type) {
         case "command":
@@ -340,6 +398,8 @@ async function runCheck(check, input) {
             return runCheckoutChangesCheck(check, input);
         case "checklist":
             return runChecklistCheck(check, input);
+        case "browser_login":
+            return runBrowserLoginCheck(check, input);
     }
 }
 /**

package/dist/runtime/containerLimits.d.ts

@@ -0,0 +1,16 @@
+import os from "node:os";
+export type ContainerLimits = {
+    memoryLimitBytes: number | undefined;
+    maxActiveStageProcesses: number;
+    maxOldSpaceSizeMb: number;
+    source: "cgroup-v2" | "cgroup-v1" | "fallback";
+};
+export declare function readContainerMemoryLimit(roots?: readonly string[]): {
+    bytes: number | undefined;
+    source: ContainerLimits["source"];
+};
+export declare function deriveContainerLimits(memoryLimitBytes: number | undefined, source?: ContainerLimits["source"]): ContainerLimits;
+export declare function getContainerLimits(): ContainerLimits;
+export declare function resetContainerLimitsForTests(): void;
+/** Test hook: prove sizing never consults os.totalmem. */
+export declare function assertNoOsTotalmemInSizing(): typeof os.totalmem;

package/dist/runtime/containerLimits.js

@@ -0,0 +1,84 @@
+import { readFileSync, existsSync } from "node:fs";
+import os from "node:os";
+const HOST_RESERVE_MIB = 512;
+const WORKER_BUDGET_MIB = 512;
+const MAX_CAP = 8;
+const FALLBACK_CAP = 4;
+const FALLBACK_HEAP_MIB = 512;
+const V1_SENTINEL = 9223372036854771712n;
+function parseCgroupMemory(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === "" || trimmed === "max")
+        return undefined;
+    let n;
+    try {
+        n = BigInt(trimmed);
+    }
+    catch {
+        return undefined;
+    }
+    if (n <= 0n || n >= V1_SENTINEL)
+        return undefined;
+    if (n > BigInt(Number.MAX_SAFE_INTEGER))
+        return undefined;
+    return Number(n);
+}
+export function readContainerMemoryLimit(roots = ["/sys/fs/cgroup"]) {
+    for (const root of roots) {
+        const v2 = `${root}/memory.max`;
+        if (existsSync(v2)) {
+            try {
+                const bytes = parseCgroupMemory(readFileSync(v2, "utf8"));
+                return { bytes, source: bytes === undefined ? "fallback" : "cgroup-v2" };
+            }
+            catch {
+                // continue
+            }
+        }
+        const v1 = `${root}/memory/memory.limit_in_bytes`;
+        if (existsSync(v1)) {
+            try {
+                const bytes = parseCgroupMemory(readFileSync(v1, "utf8"));
+                return { bytes, source: bytes === undefined ? "fallback" : "cgroup-v1" };
+            }
+            catch {
+                // continue
+            }
+        }
+    }
+    return { bytes: undefined, source: "fallback" };
+}
+export function deriveContainerLimits(memoryLimitBytes, source = "fallback") {
+    if (memoryLimitBytes === undefined) {
+        return {
+            memoryLimitBytes: undefined,
+            maxActiveStageProcesses: FALLBACK_CAP,
+            maxOldSpaceSizeMb: FALLBACK_HEAP_MIB,
+            source: "fallback",
+        };
+    }
+    const limitMib = Math.floor(memoryLimitBytes / (1024 * 1024));
+    const workerBudget = Math.max(1, limitMib - HOST_RESERVE_MIB);
+    const cap = Math.min(MAX_CAP, Math.max(1, Math.floor(workerBudget / WORKER_BUDGET_MIB)));
+    return {
+        memoryLimitBytes,
+        maxActiveStageProcesses: cap,
+        maxOldSpaceSizeMb: WORKER_BUDGET_MIB,
+        source,
+    };
+}
+let cached;
+export function getContainerLimits() {
+    if (cached === undefined) {
+        const { bytes, source } = readContainerMemoryLimit();
+        cached = deriveContainerLimits(bytes, source);
+    }
+    return cached;
+}
+export function resetContainerLimitsForTests() {
+    cached = undefined;
+}
+/** Test hook: prove sizing never consults os.totalmem. */
+export function assertNoOsTotalmemInSizing() {
+    return os.totalmem;
+}

package/dist/runtime/credentialBinding.d.ts

@@ -11,6 +11,8 @@ export type ResolveCredentialBindingOptions = {
 };
 export declare function sfOwnedAgentDir(): string;
 export declare function sfOwnedAuthPath(): string;
+export declare const PI_HOME_AUTH_PATH_ENV = "STAGEFLOW_PI_HOME_AUTH_PATH";
+/** A stage worker's HOME is an empty attempt dir, so the Host passes its own Pi auth path through the environment. */
 export declare function piHomeAuthPath(override?: string): string;
 export declare function isUsableAuthFile(authPath: string): boolean;
 export declare function ensureSfOwnedAuthStore(): string;

package/dist/runtime/credentialBinding.js

@@ -11,8 +11,11 @@ export function sfOwnedAgentDir() {
 export function sfOwnedAuthPath() {
     return path.join(sfOwnedAgentDir(), "auth.json");
 }
+export const PI_HOME_AUTH_PATH_ENV = "STAGEFLOW_PI_HOME_AUTH_PATH";
+/** A stage worker's HOME is an empty attempt dir, so the Host passes its own Pi auth path through the environment. */
 export function piHomeAuthPath(override) {
     return (override ??
+        (process.env[PI_HOME_AUTH_PATH_ENV] || undefined) ??
         path.join(os.homedir(), ".pi", "agent", "auth.json"));
 }
 export function isUsableAuthFile(authPath) {

package/dist/runtime/credentialMaterialisation.d.ts

@@ -0,0 +1,28 @@
+export type MaterialiseCopyResult = {
+    destPath: string;
+    mode: number;
+};
+export declare class CredentialMaterialisationError extends Error {
+    readonly code: "symlink_rejected" | "escape_rejected" | "source_missing" | "not_a_file";
+    constructor(message: string, code: CredentialMaterialisationError["code"]);
+}
+export declare function attemptCredentialsDir(attemptDir: string, secretName: string): string;
+/** Copy a Host source file into attempt credentials with mode 0400. */
+export declare function materialiseCredentialFile(options: {
+    sourcePath: string;
+    destDir: string;
+    destBasename?: string;
+    allowedRoot?: string;
+}): MaterialiseCopyResult;
+export declare function materialiseSecretBytes(options: {
+    contents: string | Buffer;
+    destDir: string;
+    destBasename: string;
+}): MaterialiseCopyResult;
+export declare function cleanupCredentialsDir(attemptDir: string): void;
+export declare function stageAskpassHelperPath(home?: string): string;
+export declare function ensureStageAskpassHelper(home?: string): string;
+export declare function readFileCredentialRegistry(home?: string): Record<string, {
+    source: string;
+    pointerVar: string;
+}>;

package/dist/runtime/credentialMaterialisation.js

@@ -0,0 +1,128 @@
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { ensureGlobalHome, globalStageflowHome } from "../project/globalHome.js";
+export class CredentialMaterialisationError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "CredentialMaterialisationError";
+        this.code = code;
+    }
+}
+export function attemptCredentialsDir(attemptDir, secretName) {
+    return path.join(attemptDir, "credentials", secretName);
+}
+/** Copy a Host source file into attempt credentials with mode 0400. */
+export function materialiseCredentialFile(options) {
+    const sourcePath = path.resolve(options.sourcePath);
+    let stat;
+    try {
+        stat = lstatSync(sourcePath);
+    }
+    catch {
+        throw new CredentialMaterialisationError(`credential source missing: ${sourcePath}`, "source_missing");
+    }
+    if (stat.isSymbolicLink()) {
+        throw new CredentialMaterialisationError(`credential source must not be a symlink: ${sourcePath}`, "symlink_rejected");
+    }
+    if (!stat.isFile()) {
+        throw new CredentialMaterialisationError(`credential source must be a regular file: ${sourcePath}`, "not_a_file");
+    }
+    const realSource = realpathSync(sourcePath);
+    if (options.allowedRoot !== undefined) {
+        let root = path.resolve(options.allowedRoot);
+        try {
+            root = realpathSync(root);
+        }
+        catch {
+            // allowed root may not exist yet; keep resolved path
+        }
+        if (realSource !== root && !realSource.startsWith(root + path.sep)) {
+            throw new CredentialMaterialisationError(`credential source escapes allowed root: ${sourcePath}`, "escape_rejected");
+        }
+    }
+    mkdirSync(options.destDir, { recursive: true, mode: 0o700 });
+    const destPath = path.join(options.destDir, options.destBasename ?? path.basename(realSource));
+    copyFileSync(realSource, destPath);
+    try {
+        chmodSync(destPath, 0o400);
+    }
+    catch {
+        // best-effort on non-POSIX
+    }
+    return { destPath, mode: 0o400 };
+}
+export function materialiseSecretBytes(options) {
+    mkdirSync(options.destDir, { recursive: true, mode: 0o700 });
+    const destPath = path.join(options.destDir, options.destBasename);
+    writeFileSync(destPath, options.contents, { mode: 0o400 });
+    try {
+        chmodSync(destPath, 0o400);
+    }
+    catch {
+        // best-effort
+    }
+    return { destPath, mode: 0o400 };
+}
+export function cleanupCredentialsDir(attemptDir) {
+    const root = path.join(attemptDir, "credentials");
+    if (!existsSync(root))
+        return;
+    rmSync(root, { recursive: true, force: true });
+}
+const STAGE_ASKPASS_BASENAME = "git-askpass-stage";
+const STAGE_ASKPASS_SCRIPT = `#!/bin/sh
+prompt=\${1-}
+case "\$prompt" in
+  *Username*|*username*)
+    printf '%s\\n' 'x-access-token'
+    ;;
+  *)
+    token=
+    if [ -n "\${STAGEFLOW_GIT_ASKPASS_TOKEN_FILE-}" ] && [ -f "\$STAGEFLOW_GIT_ASKPASS_TOKEN_FILE" ]; then
+      token=\$(cat "\$STAGEFLOW_GIT_ASKPASS_TOKEN_FILE")
+    fi
+    printf '%s\\n' "\$token"
+    ;;
+esac
+`;
+export function stageAskpassHelperPath(home = globalStageflowHome()) {
+    return path.join(home, STAGE_ASKPASS_BASENAME);
+}
+export function ensureStageAskpassHelper(home) {
+    const resolvedHome = home ?? ensureGlobalHome();
+    mkdirSync(resolvedHome, { recursive: true });
+    const askpass = stageAskpassHelperPath(resolvedHome);
+    writeFileSync(askpass, STAGE_ASKPASS_SCRIPT, { encoding: "utf8", mode: 0o700 });
+    try {
+        chmodSync(askpass, 0o700);
+    }
+    catch {
+        // best-effort
+    }
+    return askpass;
+}
+export function readFileCredentialRegistry(home = globalStageflowHome()) {
+    const registryPath = path.join(home, "secrets", "file-credentials.json");
+    if (!existsSync(registryPath))
+        return {};
+    try {
+        const raw = JSON.parse(readFileSync(registryPath, "utf8"));
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            return {};
+        const out = {};
+        for (const [name, entry] of Object.entries(raw)) {
+            if (!entry || typeof entry !== "object" || Array.isArray(entry))
+                continue;
+            const e = entry;
+            if (typeof e.source !== "string" || typeof e.pointerVar !== "string") {
+                continue;
+            }
+            out[name] = { source: e.source, pointerVar: e.pointerVar };
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}

package/dist/runtime/emailSource.d.ts

@@ -0,0 +1,72 @@
+import type { RunStore } from "../runstore/port.js";
+import type { TriggerFireEvent, TriggerSourcePort } from "./triggerPort.js";
+export declare const DEFAULT_EMAIL_RECONNECT_BASE_DELAY_MS = 1000;
+export declare const DEFAULT_EMAIL_RECONNECT_MAX_DELAY_MS = 30000;
+export declare const EMAIL_TEXT_EXCERPT_MAX_CHARS = 2000;
+export type NormalizedEmailMessage = {
+    uid: number;
+    from: string;
+    subject: string;
+    date: string;
+    text: string;
+};
+export type EmailClientConfig = {
+    host: string;
+    port: number;
+    user: string;
+    password: string;
+};
+/**
+ * Narrow, test-friendly seam over "one IMAP/IDLE mailbox connection". The
+ * default implementation adapts `imapflow`'s `ImapFlow`; tests inject a fake
+ * so no real mailbox is ever contacted.
+ */
+export type EmailImapClient = {
+    connect(): Promise<{
+        uidNext: number;
+    }>;
+    idle(): void;
+    fetchNewMessages(sinceUid: number): Promise<NormalizedEmailMessage[]>;
+    close(): Promise<void>;
+    onExists(listener: () => void): void;
+    onClose(listener: () => void): void;
+    onError(listener: (err: Error) => void): void;
+};
+export type EmailSourceOptions = {
+    store: RunStore;
+    cwd?: string;
+    logError?: (message: string) => void;
+    env?: NodeJS.ProcessEnv;
+    /** Injectable client factory so tests never hit a real mailbox. */
+    createEmailClient?: (config: EmailClientConfig) => EmailImapClient;
+    reconnectBaseDelayMs?: number;
+    reconnectMaxDelayMs?: number;
+};
+/**
+ * `TriggerSourcePort` adapter for `event`-kind triggers whose `event.source`
+ * starts with `email.`. Unlike the poll-based adapters this one is push-based:
+ * on `start()` it groups triggers by distinct mailbox (`host`+`port`+`user`),
+ * opens exactly one real IMAP/IDLE connection per mailbox regardless of how
+ * many triggers watch it, and reacts to the server's new-message
+ * notification instead of ticking on an interval. A dropped connection
+ * reconnects with bounded exponential backoff rather than going dark.
+ */
+export declare class EmailSource implements TriggerSourcePort {
+    private readonly store;
+    private readonly cwd;
+    private readonly logError;
+    private readonly env;
+    private readonly createEmailClient;
+    private readonly reconnectBaseDelayMs;
+    private readonly reconnectMaxDelayMs;
+    private readonly connections;
+    private stopped;
+    constructor(options: EmailSourceOptions);
+    start(onFire: (event: TriggerFireEvent) => Promise<void>): Promise<void>;
+    stop(): Promise<void>;
+    private discover;
+    private connectMailbox;
+    private scheduleReconnect;
+    private processNewMail;
+    private fireSafely;
+}