stageflow 0.33.0 → 0.36.0

package/dist/preflight/pipelinePreflight.js

@@ -2,6 +2,7 @@ import { collectEffectiveRequires, } from "../config/toolRequires.js";
 import { resolveStageMcpServers, StageMcpError, } from "../config/resolveStageMcpServers.js";
 import { assertSecretPresent, loadSecretRegistry, SecretUnavailableError, } from "../runtime/stageSecrets.js";
 import { isForeverDeniedSecret } from "../runtime/stageEnvironment.js";
+import { checkStageChannels } from "./channelChecks.js";
 import { checkToolchainRequirements, curatedStageEnv, } from "./toolchain.js";
 function toolchainItems(checks) {
     return checks.map((c) => ({
@@ -165,14 +166,21 @@ export async function runPipelinePreflight(loaded, options) {
         projectRoot: options.projectRoot,
         hostEnv,
     });
+    const channelChecks = await checkStageChannels(loaded, {
+        projectRoot: options.projectRoot,
+        hostEnv,
+        ...options.channels,
+    });
     const checks = [
         ...toolchainItems(toolchain.checks),
         ...secretChecks,
         ...mcpChecks,
+        ...channelChecks,
     ];
     const ok = toolchain.ok &&
         !secretChecks.some((c) => c.status !== "ok") &&
-        !mcpChecks.some((c) => c.status !== "ok");
+        !mcpChecks.some((c) => c.status !== "ok") &&
+        !channelChecks.some((c) => c.status !== "ok");
     return { ok, checks, requirements, toolchain };
 }
 export function preflightFailureCode(result, options = {}) {

package/dist/project/ensureProjectRootsFromEnv.d.ts

@@ -0,0 +1,3 @@
+import type { RunStore } from "../runstore/port.js";
+export declare function parseEnsureProjectRootsEnv(env: NodeJS.ProcessEnv): string[];
+export declare function ensureProjectRootsFromEnv(env: NodeJS.ProcessEnv, store: RunStore): Promise<void>;

package/dist/project/ensureProjectRootsFromEnv.js

@@ -0,0 +1,22 @@
+import path from "node:path";
+export function parseEnsureProjectRootsEnv(env) {
+    const raw = env.STAGEFLOW_ENSURE_PROJECT_ROOTS?.trim();
+    if (!raw)
+        return [];
+    return raw
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
+export async function ensureProjectRootsFromEnv(env, store) {
+    for (const entry of parseEnsureProjectRootsEnv(env)) {
+        const abs = path.resolve(entry);
+        try {
+            await store.ensureProject(abs);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`stageflow: could not register project_root ${abs}: ${message}`);
+        }
+    }
+}

package/dist/project/globalHome.d.ts

@@ -5,5 +5,6 @@ export declare class StageflowHomeError extends Error {
 }
 export declare function resetGlobalStageflowHomeForTests(): void;
 export declare function globalStageflowHome(): string;
+export declare function globalCredentialRoot(): string;
 export declare function assertStageflowHomeWritable(): void;
 export declare function ensureGlobalHome(): string;

package/dist/project/globalHome.js

@@ -10,8 +10,10 @@ export class StageflowHomeError extends Error {
     }
 }
 let memoizedHome;
+let memoizedCredentialRoot;
 export function resetGlobalStageflowHomeForTests() {
     memoizedHome = undefined;
+    memoizedCredentialRoot = undefined;
 }
 function resolveStageflowHomeFromEnv() {
     const raw = process.env.STAGEFLOW_HOME?.trim();
@@ -30,6 +32,22 @@ export function globalStageflowHome() {
     }
     return memoizedHome;
 }
+function resolveCredentialRootFromEnv() {
+    const raw = process.env.STAGEFLOW_CREDENTIAL_HOME?.trim();
+    if (raw) {
+        if (path.isAbsolute(raw)) {
+            return path.resolve(raw);
+        }
+        return path.resolve(process.cwd(), raw);
+    }
+    return path.join(os.homedir(), ".stageflow");
+}
+export function globalCredentialRoot() {
+    if (memoizedCredentialRoot === undefined) {
+        memoizedCredentialRoot = resolveCredentialRootFromEnv();
+    }
+    return memoizedCredentialRoot;
+}
 function stageflowHomeNotWritableMessage(resolvedPath) {
     const uid = process.getuid?.() ?? 0;
     const gid = process.getgid?.() ?? 0;

package/dist/project/workspaceCatalog.d.ts

@@ -0,0 +1,10 @@
+export declare const WORKSPACE_CATALOG_ID = "workspace";
+export type WorkspaceProvisionResult = {
+    path: string;
+    ok: boolean;
+    reason?: string;
+};
+export declare function resetWorkspaceProvisionForTests(): void;
+export declare function lastWorkspaceProvisionResult(): WorkspaceProvisionResult | undefined;
+export declare function workspaceCatalogPath(home?: string): string;
+export declare function ensureWorkspaceCatalog(home?: string): WorkspaceProvisionResult;

package/dist/project/workspaceCatalog.js

@@ -0,0 +1,91 @@
+import { accessSync, constants, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { globalStageflowHome } from "./globalHome.js";
+export const WORKSPACE_CATALOG_ID = "workspace";
+let lastProvisionResult;
+export function resetWorkspaceProvisionForTests() {
+    lastProvisionResult = undefined;
+}
+export function lastWorkspaceProvisionResult() {
+    return lastProvisionResult;
+}
+export function workspaceCatalogPath(home) {
+    return path.join(home ?? globalStageflowHome(), "workspace");
+}
+function workspaceManifestYaml() {
+    return `version: 1
+catalog:
+  pipelines:
+    - .
+  tasks:
+    - .
+  triggers:
+    - .
+  patterns:
+    pipeline: "*.pipeline.yaml"
+    task: "*.task.yaml"
+    trigger: "*.trigger.yaml"
+`;
+}
+function workspaceNotWritableReason(resolvedPath) {
+    const uid = process.getuid?.() ?? 0;
+    const gid = process.getgid?.() ?? 0;
+    return `Workspace catalog is not writable (${resolvedPath}). Running as uid=${uid} gid=${gid}. Try: sudo chown -R ${uid}:${gid} ${path.dirname(resolvedPath)}`;
+}
+function isWritableDir(dir) {
+    try {
+        accessSync(dir, constants.W_OK);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                return false;
+            try {
+                accessSync(parent, constants.W_OK);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        return false;
+    }
+}
+export function ensureWorkspaceCatalog(home) {
+    const wsPath = workspaceCatalogPath(home);
+    if (!isWritableDir(wsPath)) {
+        const result = {
+            path: wsPath,
+            ok: false,
+            reason: workspaceNotWritableReason(wsPath),
+        };
+        lastProvisionResult = result;
+        return result;
+    }
+    try {
+        mkdirSync(wsPath, { recursive: true });
+        const manifestPath = path.join(wsPath, "stageflow.yaml");
+        try {
+            accessSync(manifestPath, constants.F_OK);
+        }
+        catch {
+            writeFileSync(manifestPath, workspaceManifestYaml(), "utf8");
+        }
+        const result = { path: wsPath, ok: true };
+        lastProvisionResult = result;
+        return result;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const result = {
+            path: wsPath,
+            ok: false,
+            reason: `${workspaceNotWritableReason(wsPath)} (${message})`,
+        };
+        lastProvisionResult = result;
+        return result;
+    }
+}

package/dist/runstore/backup.js

@@ -8,7 +8,8 @@ import { pipeline } from "node:stream/promises";
 import { createWriteStream } from "node:fs";
 import Database from "better-sqlite3";
 import { PACKAGE_VERSION } from "../package-meta.js";
-import { globalStageflowHome } from "../project/globalHome.js";
+import { globalCredentialRoot, globalStageflowHome } from "../project/globalHome.js";
+import { isUsableAuthFile } from "../runtime/credentialBinding.js";
 import { readFilesystemSize } from "./diskUsage.js";
 import { isInsideDir } from "./workspaceLayout.js";
 export class BackupError extends Error {
@@ -45,6 +46,14 @@ export function assertBackupOutPathAllowed(outPath, homeDir = globalStageflowHom
     }
     return resolved;
 }
+function isCredentialRootDir(dir) {
+    return path.resolve(dir) === path.resolve(globalCredentialRoot());
+}
+function packAuthMember(homeDir, authPath, noCredentials) {
+    return (!noCredentials &&
+        isCredentialRootDir(homeDir) &&
+        isUsableAuthFile(authPath));
+}
 function fingerprint(filePath) {
     if (!existsSync(filePath))
         return null;
@@ -203,7 +212,8 @@ export async function createBackup(options) {
             });
             contents.push("settings.json");
         }
-        if (!noCredentials && existsSync(authPath)) {
+        const includeAuth = packAuthMember(homeDir, authPath, noCredentials);
+        if (includeAuth) {
             const stagedAuth = path.join(staging, "auth.json");
             copyFileSync(authPath, stagedAuth);
             chmodSync(stagedAuth, 0o600);
@@ -226,14 +236,14 @@ export async function createBackup(options) {
             schema_version: userVersion,
             contents,
             db_only: false,
-            credentials_included: !noCredentials && existsSync(authPath),
+            credentials_included: includeAuth,
             a2a_artifacts_included: includeA2a,
             settings_fingerprint_before: settingsBefore,
             settings_fingerprint_after: settingsAfter,
             auth_fingerprint_before: authBefore,
             auth_fingerprint_after: authAfter,
             fingerprint_skew: fingerprintSkew,
-            secret_warning: SECRET_WARNING,
+            secret_warning: includeAuth ? SECRET_WARNING : "",
         };
         const manifestPath = path.join(staging, "manifest.json");
         writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, {

package/dist/runstore/port.d.ts

@@ -99,6 +99,7 @@ export type StageSnapshot = {
     attempt_count: number;
     /** Total $ spent on this stage across every attempt; omitted when no attempt reported usage. */
     cost_usd?: number;
+    usage?: StageUsage;
 };
 export type StageExecution = {
     run_id: string;
@@ -470,12 +471,21 @@ export interface RunStore {
     upsertTrigger(input: UpsertTriggerInput): Promise<TriggerRecord>;
     getTrigger(id: string): Promise<TriggerRecord | null>;
     listTriggers(): Promise<TriggerRecord[]>;
-    /** Record a fire: stamps last_fired_at/last_run_id. Throws if the trigger is missing. */
+    /** Record a fire: stamps last_fired_at/last_run_id and appends trigger_fires. Throws if the trigger is missing. */
     recordTriggerFired(id: string, runId: string): Promise<void>;
+    /** Newest first. */
+    listTriggerFires(triggerId: string, limit: number): Promise<Array<{
+        fired_at: string;
+        run_id: string;
+    }>>;
     /** Persist the next computed fire time for a schedule-kind trigger. Throws if the trigger is missing. */
     setTriggerNextRun(id: string, nextRunAt: string): Promise<void>;
     /** Read a single adapter-owned state value for a trigger, or null if unset. */
     getTriggerAdapterState(triggerId: string, key: string): Promise<string | null>;
+    getTriggerAdapterStateMeta(triggerId: string, key: string): Promise<{
+        value: string;
+        updated_at: string;
+    } | null>;
     /** Upsert a single adapter-owned state value for a trigger. */
     setTriggerAdapterState(triggerId: string, key: string, value: string): Promise<void>;
     readRun(runId: string): Promise<RunDetail>;

package/dist/runstore/restore.js

@@ -7,7 +7,8 @@ import { pipeline } from "node:stream/promises";
 import { createWriteStream } from "node:fs";
 import Database from "better-sqlite3";
 import { PACKAGE_VERSION } from "../package-meta.js";
-import { globalStageflowHome } from "../project/globalHome.js";
+import { globalCredentialRoot, globalStageflowHome } from "../project/globalHome.js";
+import { isUsableAuthFile } from "../runtime/credentialBinding.js";
 import { CURRENT_SCHEMA_VERSION } from "./sqlite/migrations/index.js";
 import { StoreSchemaError } from "./sqlite/storeSchemaError.js";
 import { assertStoreQuickCheck } from "./sqlite/applyStorePragmas.js";
@@ -234,7 +235,9 @@ export async function applyRestoreArchive(options) {
                 if (existsSync(settingsSrc)) {
                     copyFileSync(settingsSrc, path.join(homeDir, "settings.json"));
                 }
-                if (existsSync(authSrc)) {
+                const restoreAuth = path.resolve(homeDir) === path.resolve(globalCredentialRoot()) &&
+                    isUsableAuthFile(authSrc);
+                if (restoreAuth) {
                     const agentDir = path.join(homeDir, "agent");
                     mkdirSync(agentDir, { recursive: true });
                     try {

package/dist/runstore/sqlite/SqliteRunStore.d.ts

@@ -82,8 +82,16 @@ export declare class SqliteRunStore implements RunStore {
     getTrigger(id: string): Promise<TriggerRecord | null>;
     listTriggers(): Promise<TriggerRecord[]>;
     recordTriggerFired(id: string, runId: string): Promise<void>;
+    listTriggerFires(triggerId: string, limit: number): Promise<Array<{
+        fired_at: string;
+        run_id: string;
+    }>>;
     setTriggerNextRun(id: string, nextRunAt: string): Promise<void>;
     getTriggerAdapterState(triggerId: string, key: string): Promise<string | null>;
+    getTriggerAdapterStateMeta(triggerId: string, key: string): Promise<{
+        value: string;
+        updated_at: string;
+    } | null>;
     setTriggerAdapterState(triggerId: string, key: string, value: string): Promise<void>;
     readRun(runId: string): Promise<RunDetail>;
     createFeedbackLoop(runId: string, input: CreateFeedbackLoopInput): Promise<FeedbackLoopRecord>;

package/dist/runstore/sqlite/SqliteRunStore.js

@@ -942,13 +942,29 @@ export class SqliteRunStore {
     async recordTriggerFired(id, runId) {
         await this.ready();
         const now = new Date().toISOString();
-        const result = this.db
-            .prepare(`UPDATE triggers SET last_fired_at = @last_fired_at, last_run_id = @last_run_id, updated_at = @updated_at
-         WHERE id = @id`)
-            .run({ id, last_fired_at: now, last_run_id: runId, updated_at: now });
-        if (result.changes === 0) {
-            throw new Error(`Trigger not found: ${id}`);
-        }
+        const apply = this.db.transaction(() => {
+            const result = this.db
+                .prepare(`UPDATE triggers SET last_fired_at = @last_fired_at, last_run_id = @last_run_id, updated_at = @updated_at
+           WHERE id = @id`)
+                .run({ id, last_fired_at: now, last_run_id: runId, updated_at: now });
+            if (result.changes === 0) {
+                throw new Error(`Trigger not found: ${id}`);
+            }
+            this.db
+                .prepare(`INSERT INTO trigger_fires (trigger_id, run_id, fired_at)
+           VALUES (@trigger_id, @run_id, @fired_at)`)
+                .run({ trigger_id: id, run_id: runId, fired_at: now });
+        });
+        apply();
+    }
+    async listTriggerFires(triggerId, limit) {
+        await this.ready();
+        return this.db
+            .prepare(`SELECT fired_at, run_id FROM trigger_fires
+         WHERE trigger_id = ?
+         ORDER BY fired_at DESC, id DESC
+         LIMIT ?`)
+            .all(triggerId, limit);
     }
     async setTriggerNextRun(id, nextRunAt) {
         await this.ready();
@@ -962,11 +978,15 @@ export class SqliteRunStore {
         }
     }
     async getTriggerAdapterState(triggerId, key) {
+        const row = await this.getTriggerAdapterStateMeta(triggerId, key);
+        return row?.value ?? null;
+    }
+    async getTriggerAdapterStateMeta(triggerId, key) {
         await this.ready();
         const row = this.db
-            .prepare(`SELECT value FROM trigger_adapter_state WHERE trigger_id = ? AND key = ?`)
+            .prepare(`SELECT value, updated_at FROM trigger_adapter_state WHERE trigger_id = ? AND key = ?`)
             .get(triggerId, key);
-        return row ? row.value : null;
+        return row ?? null;
     }
     async setTriggerAdapterState(triggerId, key, value) {
         await this.ready();

package/dist/runstore/sqlite/migrations/012-trigger-fires.d.ts

@@ -0,0 +1,7 @@
+import type Database from "better-sqlite3";
+export declare const MIGRATION_012: {
+    version: number;
+    name: string;
+    minStageflowVersion: string;
+    up(db: Database.Database): void;
+};

package/dist/runstore/sqlite/migrations/012-trigger-fires.js

@@ -0,0 +1,18 @@
+import { PACKAGE_VERSION } from "../../../package-meta.js";
+export const MIGRATION_012 = {
+    version: 12,
+    name: "012_trigger_fires",
+    minStageflowVersion: PACKAGE_VERSION,
+    up(db) {
+        db.exec(`
+CREATE TABLE IF NOT EXISTS trigger_fires (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  trigger_id TEXT NOT NULL,
+  run_id TEXT NOT NULL,
+  fired_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS trigger_fires_trigger_fired
+  ON trigger_fires (trigger_id, fired_at DESC);
+`);
+    },
+};

package/dist/runstore/sqlite/migrations/index.js

@@ -10,6 +10,7 @@ import { MIGRATION_008 } from "./008-triggers-table.js";
 import { MIGRATION_009 } from "./009-trigger-next-run.js";
 import { MIGRATION_010 } from "./010-trigger-adapter-state.js";
 import { MIGRATION_011 } from "./011-email-dispatch-key.js";
+import { MIGRATION_012 } from "./012-trigger-fires.js";
 const DEFAULT_MIGRATIONS = [
     MIGRATION_001,
     MIGRATION_002,
@@ -22,6 +23,7 @@ const DEFAULT_MIGRATIONS = [
     MIGRATION_009,
     MIGRATION_010,
     MIGRATION_011,
+    MIGRATION_012,
 ];
 export const CURRENT_SCHEMA_VERSION = DEFAULT_MIGRATIONS[DEFAULT_MIGRATIONS.length - 1].version;
 function throwStoreSchemaTooNew(db, version, maxKnown) {

package/dist/runstore/stageSnapshot.d.ts

@@ -1,2 +1,4 @@
-import type { RunStore, StageSnapshot } from "./port.js";
+import { type StageUsage } from "../types/usage.js";
+import type { RunStore, StageExecution, StageSnapshot } from "./port.js";
 export declare function buildStageSnapshotFromStore(store: RunStore, runId: string, stageId: string, workspaceDir: string): Promise<StageSnapshot>;
+export declare function mergeStageExecutionUsage(executions: StageExecution[]): StageUsage | undefined;

package/dist/runstore/stageSnapshot.js

@@ -1,3 +1,4 @@
+import { addModelUsage, emptyStageUsage } from "../types/usage.js";
 import { derivePendingPrompt } from "../hitl/qaTrail.js";
 import { stageStatusFromEvents } from "./port.js";
 import { listArtifactNames } from "./workspaceLayout.js";
@@ -19,6 +20,7 @@ export async function buildStageSnapshotFromStore(store, runId, stageId, workspa
     let envelope;
     let attempt_count;
     let cost_usd;
+    let usage;
     if (latest !== null) {
         events = await store.listStageEvents(runId, stageId, latest.attempt);
         status = stageStatusFromEvents(events);
@@ -26,6 +28,7 @@ export async function buildStageSnapshotFromStore(store, runId, stageId, workspa
         attempt_count = await store.countStageAttempts(runId, stageId);
         const executions = await store.listStageExecutions(runId, stageId);
         cost_usd = sumStageExecutionCost(executions);
+        usage = mergeStageExecutionUsage(executions);
     }
     else {
         events = await store.listStageEvents(runId, stageId);
@@ -46,8 +49,24 @@ export async function buildStageSnapshotFromStore(store, runId, stageId, workspa
         attempt_count,
         ...(pending ? { pending_prompt: pending } : {}),
         ...(cost_usd !== undefined ? { cost_usd } : {}),
+        ...(usage !== undefined ? { usage } : {}),
     };
 }
+export function mergeStageExecutionUsage(executions) {
+    const usages = executions
+        .map((e) => e.usage)
+        .filter((u) => u !== undefined);
+    if (usages.length === 0)
+        return undefined;
+    const merged = emptyStageUsage();
+    for (const u of usages) {
+        for (const [model, breakdown] of Object.entries(u.models)) {
+            addModelUsage(merged, model, breakdown);
+        }
+    }
+    merged.costUsd = usages.reduce((sum, u) => sum + u.costUsd, 0);
+    return merged;
+}
 /** Sum cost across every attempt — retries are real spend too, so a stage's total isn't just its latest attempt. */
 function sumStageExecutionCost(executions) {
     const costs = executions.map((e) => e.cost_usd).filter((c) => c !== undefined);

package/dist/runstore/workspaceLayout.js

@@ -1,5 +1,8 @@
 import { access, lstat, mkdir, readdir, realpath } from "node:fs/promises";
 import path from "node:path";
+import { globalCredentialRoot } from "../project/globalHome.js";
+import { STAGEFLOW_AGENT_AUTH_PATH_ENV } from "../runtime/credentialBinding.js";
+import { SF_STAGE_WORKER } from "../runtime/stageWorkerProtocol.js";
 export { stageDir } from "./paths.js";
 export function guardStageId(stageId) {
     if (stageId.includes("..") ||
@@ -101,6 +104,15 @@ export async function resolveEffectiveRealPath(candidatePath) {
         }
     }
 }
+function credentialRootForFileToolDenial() {
+    if (process.env[SF_STAGE_WORKER] === "1") {
+        const stamped = process.env[STAGEFLOW_AGENT_AUTH_PATH_ENV]?.trim();
+        if (!stamped)
+            return undefined;
+        return path.resolve(path.dirname(stamped), "..");
+    }
+    return globalCredentialRoot();
+}
 export async function durableRootFileToolDenial(candidatePath, runWorkspaceDir, durableRoot, allowlistedRoots) {
     const fileReal = await resolveEffectiveRealPath(candidatePath);
     if (fileReal === undefined) {
@@ -137,6 +149,21 @@ export async function durableRootFileToolDenial(candidatePath, runWorkspaceDir,
     if (isInsideDir(fileReal, durableReal)) {
         return STAGEFLOW_PATH_DENIED;
     }
+    const credentialRoot = credentialRootForFileToolDenial();
+    if (credentialRoot !== undefined) {
+        let credentialReal;
+        try {
+            credentialReal = await realpath(credentialRoot);
+        }
+        catch {
+            credentialReal = path.resolve(credentialRoot);
+        }
+        if (credentialReal !== durableReal &&
+            !isInsideDir(credentialReal, durableReal) &&
+            isInsideDir(fileReal, credentialReal)) {
+            return STAGEFLOW_PATH_DENIED;
+        }
+    }
     return undefined;
 }
 export function resolveArtifactTarget(runWorkspaceDir, stageId, attempt, relativePath) {

package/dist/runstore/writeContainedArtifact.d.ts

@@ -0,0 +1 @@
+export declare function writeContainedArtifact(runWorkspaceDir: string, artifactsDirectory: string, absolutePath: string, content: string): Promise<void>;

package/dist/runstore/writeContainedArtifact.js

@@ -0,0 +1,52 @@
+/**
+ * Atomic write of one file under a stage attempt's artifacts directory.
+ * Refuses symlinked or hard-linked targets and any path that resolves outside
+ * the artifacts directory.
+ */
+import { randomBytes } from "node:crypto";
+import { lstat, realpath, rename, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { ensureRealArtifactsDir, isInsideDir, resolveContainedParent, } from "./workspaceLayout.js";
+async function assertSafeWriteTarget(targetPath) {
+    try {
+        const st = await lstat(targetPath);
+        if (st.isSymbolicLink()) {
+            throw new Error("path escapes the stage artifacts directory");
+        }
+        if (st.nlink > 1) {
+            throw new Error("refusing to overwrite hard-linked file");
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw err;
+        }
+    }
+}
+export async function writeContainedArtifact(runWorkspaceDir, artifactsDirectory, absolutePath, content) {
+    const { realArtifacts } = await ensureRealArtifactsDir(runWorkspaceDir, artifactsDirectory);
+    const relativeToArtifacts = path.relative(artifactsDirectory, absolutePath);
+    const parent = await resolveContainedParent(realArtifacts, relativeToArtifacts);
+    const baseName = path.basename(absolutePath);
+    const targetPath = path.join(parent, baseName);
+    await assertSafeWriteTarget(targetPath);
+    const tmpName = `.sf-artifact-${randomBytes(8).toString("hex")}.tmp`;
+    const tmpPath = path.join(parent, tmpName);
+    try {
+        await writeFile(tmpPath, content, "utf8");
+        await rename(tmpPath, targetPath);
+    }
+    catch (err) {
+        try {
+            await unlink(tmpPath);
+        }
+        catch {
+            // best-effort cleanup
+        }
+        throw err;
+    }
+    const realWritten = await realpath(targetPath);
+    if (!isInsideDir(realWritten, realArtifacts)) {
+        throw new Error("path escapes the stage artifacts directory");
+    }
+}

package/dist/runtime/credentialBinding.js

@@ -1,12 +1,12 @@
-import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { AsyncLocalStorage } from "node:async_hooks";
 import path from "node:path";
-import { ensureGlobalHome } from "../project/globalHome.js";
+import { ensureGlobalHome, globalCredentialRoot } from "../project/globalHome.js";
 import { resolveProjectContext, } from "../project/resolveProjectContext.js";
 import { parseCredentialSource, readCredentialSourceFromContext, writeCredentialSourceToContext, } from "./settingsFile.js";
 export { parseCredentialSource, readCredentialSourceFromContext, writeCredentialSourceToContext, };
 export function sfOwnedAgentDir() {
-    return path.join(ensureGlobalHome(), "agent");
+    return path.join(globalCredentialRoot(), "agent");
 }
 export function sfOwnedAuthPath() {
     return path.join(sfOwnedAgentDir(), "auth.json");
@@ -42,7 +42,15 @@ export function isUsableAuthFile(authPath) {
 }
 export function ensureSfOwnedAuthStore() {
     ensureGlobalHome();
-    const authPath = sfOwnedAuthPath();
+    const agentDir = sfOwnedAgentDir();
+    mkdirSync(agentDir, { recursive: true });
+    try {
+        chmodSync(agentDir, 0o700);
+    }
+    catch {
+        // best-effort on non-POSIX
+    }
+    const authPath = path.join(agentDir, "auth.json");
     if (!existsSync(authPath)) {
         writeFileSync(authPath, "{}\n", { encoding: "utf8", mode: 0o600 });
     }
@@ -63,12 +71,12 @@ export function currentExplicitAuthPath() {
     return explicitAuthPath.getStore();
 }
 export function resolveCredentialBinding(ctx, _options = {}) {
+    const explicit = currentExplicitAuthPath();
     const projectCtx = typeof ctx === "string" ? resolveProjectContext(ctx) : ctx;
     const persisted = readCredentialSourceFromContext(projectCtx);
-    const authPath = ensureSfOwnedAuthStore();
     return {
         source: "sf_owned",
-        authPath,
+        authPath: explicit ?? sfOwnedAuthPath(),
         provisional: persisted === undefined,
     };
 }