stageflow 0.25.0 → 0.30.0

package/dist/config/validateCatalog.js

@@ -1,12 +1,17 @@
 import path from "node:path";
+import { globalStageflowHome } from "../project/globalHome.js";
 import { INLINE_PIPELINE_PATH, loadPipelineFromObjectOutcome, loadPipelineOutcome, resolvePipelinePath, } from "./loadPipeline.js";
 import { loadStageOutcome } from "./loadStage.js";
 import { loadTaskOutcome } from "./loadTask.js";
+import { loadTriggerOutcome } from "./loadTrigger.js";
 import { readYamlObject } from "./readYamlObject.js";
 import { resolveCatalogContext } from "./resolveCatalogContext.js";
 import { getCatalogScanPaths } from "./browseCatalog.js";
 import { manifestPathForProject } from "./loadStageflowManifest.js";
 import { MCP_CATALOG_FILENAME, StageMcpError, assertMcpAllowlistKnown, loadMcpCatalog, mcpCatalogPath, } from "./resolveStageMcpServers.js";
+import { loadSecretRegistry } from "../runtime/stageSecrets.js";
+import { isForeverDeniedSecret } from "../runtime/stageEnvironment.js";
+import { findMissingMcpCommands } from "../preflight/mcpCommands.js";
 export function relPath(cwd, absPath) {
     return path.relative(cwd, absPath).replace(/\\/g, "/");
 }
@@ -99,6 +104,15 @@ function findingTaskError(cwd, absPath, message, code) {
         category: "task",
     }, "error");
 }
+function findingTriggerError(cwd, absPath, message, code) {
+    return baseFinding({
+        cwd,
+        absPath,
+        message,
+        code,
+        category: "trigger",
+    }, "error");
+}
 function findingCatalog(cwd, absPath, message, code, severity) {
     return baseFinding({
         cwd,
@@ -138,6 +152,11 @@ export function findingsFromLoadIssues(cwd, absPath, issues) {
                 findingTaskError(cwd, absPath, issue.message, issue.code),
             ];
         }
+        if (issue.category === "trigger") {
+            return [
+                findingTriggerError(cwd, absPath, issue.message, issue.code),
+            ];
+        }
         if (issue.category === "catalog") {
             const code = issue.code;
             const severity = code === "catalog.manifest_missing" ||
@@ -160,6 +179,35 @@ export function findingStageIdFilenameMismatch(cwd, absPath, fileStem, declaredI
         stageId: declaredId,
     }, "error");
 }
+/** Parent readdir case check — warn by default; error under --strict. */
+export async function findingPathCaseMismatch(cwd, referencedPath) {
+    const { readdir } = await import("node:fs/promises");
+    const abs = path.isAbsolute(referencedPath)
+        ? referencedPath
+        : path.resolve(cwd, referencedPath);
+    const parent = path.dirname(abs);
+    const base = path.basename(abs);
+    let entries;
+    try {
+        entries = await readdir(parent);
+    }
+    catch {
+        return null;
+    }
+    const exact = entries.includes(base);
+    if (exact)
+        return null;
+    const match = entries.find((e) => e.toLowerCase() === base.toLowerCase());
+    if (match === undefined)
+        return null;
+    return baseFinding({
+        cwd,
+        absPath: abs,
+        message: `Path casing differs on disk: referenced "${base}" but found "${match}"`,
+        code: "catalog.path_case_mismatch",
+        category: "catalog",
+    }, "warning");
+}
 async function checkStageIdFilename(cwd, stagePath) {
     const fileStem = path.basename(stagePath, ".yaml");
     try {
@@ -197,6 +245,100 @@ function collectMcpAllowlistNames(loaded) {
     }
     return [...names];
 }
+function findingsForStageSecrets(cwd, pipelinePath, loaded) {
+    const registry = loadSecretRegistry(process.env);
+    const findings = [];
+    for (const stage of loaded.stages) {
+        for (const decl of stage.secrets ?? []) {
+            if (isForeverDeniedSecret(decl.name)) {
+                findings.push(findingStageError(cwd, pipelinePath, `secret "${decl.name}" is permanently denied and cannot be granted`, "stage.denied_secret", stage.id));
+                continue;
+            }
+            if (!registry.has(decl.name)) {
+                findings.push(findingStageError(cwd, pipelinePath, `unknown secret "${decl.name}" is not in the Host secret registry`, "stage.unknown_secret", stage.id));
+            }
+        }
+    }
+    return findings;
+}
+const ABSOLUTE_PATH_IN_TEXT_RE = /(?:^|[\s"'`=:(])(\/(?:[^\s"'`;|&<>()]+))/g;
+const TRAILING_PATH_PUNCT_RE = /[.,:;!?)\]]+$/;
+export function collectAbsolutePathCandidates(text) {
+    const found = [];
+    const seen = new Set();
+    ABSOLUTE_PATH_IN_TEXT_RE.lastIndex = 0;
+    let match;
+    while ((match = ABSOLUTE_PATH_IN_TEXT_RE.exec(text)) !== null) {
+        const raw = match[1]?.replace(TRAILING_PATH_PUNCT_RE, "") ?? "";
+        if (!raw || !path.isAbsolute(raw) || seen.has(raw))
+            continue;
+        seen.add(raw);
+        found.push(raw);
+    }
+    return found;
+}
+export function isPathUnderStageflowHome(candidate, home) {
+    if (!path.isAbsolute(candidate))
+        return false;
+    const resolved = path.resolve(candidate);
+    const homeResolved = path.resolve(home);
+    return (resolved === homeResolved || resolved.startsWith(`${homeResolved}${path.sep}`));
+}
+function stageSourcePath(loaded, stageId) {
+    const source = loaded.stageSources?.[stageId];
+    if (source?.kind === "file")
+        return source.path;
+    return loaded.pipelinePath;
+}
+function stageflowHomeAbsolutePathMessage(stageId, location, absolutePath) {
+    return (`Stage "${stageId}" ${location} contains absolute path under STAGEFLOW_HOME ` +
+        `("${absolutePath}"). Use STAGEFLOW_CHECKOUT / STAGEFLOW_RUN_WORKSPACE ` +
+        `(and related binding env vars) instead of durable-home paths`);
+}
+function findingsForStageflowHomeAbsolutePaths(cwd, loaded) {
+    const home = globalStageflowHome();
+    const findings = [];
+    const seen = new Set();
+    const pushFinding = (stageId, absPath, location, absolutePath) => {
+        const key = `${stageId}\0${location}\0${absolutePath}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        findings.push(baseFinding({
+            cwd,
+            absPath,
+            message: stageflowHomeAbsolutePathMessage(stageId, location, absolutePath),
+            code: "catalog.stageflow_home_absolute_path",
+            category: "catalog",
+            pipelineId: loaded.pipeline.id,
+            stageId,
+        }, "error"));
+    };
+    const scanText = (stageId, absPath, location, text) => {
+        for (const candidate of collectAbsolutePathCandidates(text)) {
+            if (isPathUnderStageflowHome(candidate, home)) {
+                pushFinding(stageId, absPath, location, candidate);
+            }
+        }
+    };
+    for (const stage of loaded.stages) {
+        const absPath = stageSourcePath(loaded, stage.id);
+        scanText(stage.id, absPath, "system_prompt", stage.system_prompt);
+    }
+    for (const node of loaded.dag.nodes) {
+        const checks = node.completion?.checks ?? [];
+        for (const check of checks) {
+            if (check.type !== "command")
+                continue;
+            const absPath = stageSourcePath(loaded, node.id);
+            scanText(node.id, absPath, `verify command "${check.id}" run`, check.run);
+            if (typeof check.cwd === "string") {
+                scanText(node.id, absPath, `verify command "${check.id}" cwd`, check.cwd);
+            }
+        }
+    }
+    return findings;
+}
 async function findingsForStageMcpCatalog(cwd, loaded) {
     const allowlist = collectMcpAllowlistNames(loaded);
     const ctx = await resolveCatalogContext(cwd);
@@ -235,7 +377,17 @@ async function findingsForStageMcpCatalog(cwd, loaded) {
         }
         throw err;
     }
-    return [];
+    const findings = [];
+    const serversForPath = {};
+    for (const name of allowlist) {
+        const entry = catalog.servers[name];
+        if (entry)
+            serversForPath[name] = entry;
+    }
+    for (const missing of findMissingMcpCommands(serversForPath, process.env)) {
+        findings.push(findingCatalog(cwd, catalogAbsPath, `MCP server "${missing.serverName}" command "${missing.command}" was not found on PATH`, "catalog.mcp_command_missing", "error"));
+    }
+    return findings;
 }
 async function runPipelineValidation(nameOrPath, options) {
     const { cwd, validateStages } = options;
@@ -274,6 +426,8 @@ async function runPipelineValidation(nameOrPath, options) {
         findings.push(...findingsFromLoadIssues(cwd, pipelinePath, outcome.issues));
     }
     findings.push(...(await findingsForStageMcpCatalog(cwd, outcome.value)));
+    findings.push(...findingsForStageSecrets(cwd, pipelinePath, outcome.value));
+    findings.push(...findingsForStageflowHomeAbsolutePaths(cwd, outcome.value));
     if (validateStages && outcome.value.stageSources) {
         for (const source of Object.values(outcome.value.stageSources)) {
             if (source.kind === "file") {
@@ -330,7 +484,7 @@ function findingManifestMissing(cwd, projectRoot) {
 function findingEmptyCatalog(cwd, manifestPath, kind) {
     return findingCatalog(cwd, manifestPath, `Manifest catalog.${kind} is empty`, "catalog.empty_catalog", "warning");
 }
-async function collectPipelineIdsFromPaths(pipelinePaths) {
+export async function collectPipelineIdsFromPaths(pipelinePaths) {
     const idToPaths = new Map();
     for (const filePath of pipelinePaths) {
         try {
@@ -347,6 +501,20 @@ async function collectPipelineIdsFromPaths(pipelinePaths) {
     }
     return idToPaths;
 }
+export async function collectTaskIdsFromPaths(taskPaths) {
+    const ids = new Set();
+    for (const filePath of taskPaths) {
+        try {
+            const raw = await readYamlObject(filePath);
+            if (typeof raw?.id === "string")
+                ids.add(raw.id);
+        }
+        catch {
+            // unreadable files handled by task validation loop
+        }
+    }
+    return ids;
+}
 function findingsForDuplicatePipelineIds(cwd, idToPaths) {
     const findings = [];
     for (const [pipelineId, paths] of idToPaths) {
@@ -391,7 +559,7 @@ async function validateManifestAll(invocationCwd) {
     if (!scanPaths) {
         return findings;
     }
-    const { pipelinePaths, taskPaths } = scanPaths;
+    const { pipelinePaths, taskPaths, triggerPaths } = scanPaths;
     for (const pipelinePath of pipelinePaths) {
         const core = await runPipelineValidation(pipelinePath, {
             cwd: projectRoot,
@@ -409,6 +577,32 @@ async function validateManifestAll(invocationCwd) {
     }
     const idToPaths = await collectPipelineIdsFromPaths(pipelinePaths);
     findings.push(...findingsForDuplicatePipelineIds(projectRoot, idToPaths));
+    if (triggerPaths.length > 0) {
+        const pipelineIds = new Set(idToPaths.keys());
+        const taskIds = await collectTaskIdsFromPaths(taskPaths);
+        for (const triggerPath of triggerPaths) {
+            const outcome = await loadTriggerOutcome(triggerPath);
+            if (!outcome.ok) {
+                findings.push(...findingsFromLoadIssues(projectRoot, triggerPath, outcome.issues));
+                continue;
+            }
+            findings.push(...findingsForTriggerRefs(projectRoot, triggerPath, outcome.value, {
+                pipelineIds,
+                taskIds,
+            }));
+        }
+    }
+    return findings;
+}
+/** Confirms a trigger's `pipeline`/`task` refs resolve against known catalog ids. */
+export function findingsForTriggerRefs(cwd, absPath, trigger, refs) {
+    const findings = [];
+    if (!refs.pipelineIds.has(trigger.pipeline)) {
+        findings.push(findingTriggerError(cwd, absPath, `Trigger "${trigger.id}" references unknown pipeline "${trigger.pipeline}"`, "trigger.unknown_pipeline"));
+    }
+    if (trigger.task !== undefined && !refs.taskIds.has(trigger.task)) {
+        findings.push(findingTriggerError(cwd, absPath, `Trigger "${trigger.id}" references unknown task "${trigger.task}"`, "trigger.unknown_task"));
+    }
     return findings;
 }
 async function validateSingleTask(invocationCwd, taskArg) {
@@ -421,6 +615,26 @@ async function validateSingleTask(invocationCwd, taskArg) {
     }
     return [];
 }
+async function validateSingleTrigger(invocationCwd, triggerArg) {
+    const ctx = await resolveCatalogContext(invocationCwd);
+    const relCwd = ctx.projectRoot ?? invocationCwd;
+    const triggerPath = path.resolve(invocationCwd, triggerArg);
+    const outcome = await loadTriggerOutcome(triggerPath);
+    if (!outcome.ok) {
+        return findingsFromLoadIssues(relCwd, triggerPath, outcome.issues);
+    }
+    const scanPaths = await getCatalogScanPaths(ctx);
+    const pipelineIds = scanPaths
+        ? new Set((await collectPipelineIdsFromPaths(scanPaths.pipelinePaths)).keys())
+        : new Set();
+    const taskIds = scanPaths
+        ? await collectTaskIdsFromPaths(scanPaths.taskPaths)
+        : new Set();
+    return findingsForTriggerRefs(relCwd, triggerPath, outcome.value, {
+        pipelineIds,
+        taskIds,
+    });
+}
 export async function validateCatalog(options) {
     const cwd = options.cwd ?? process.cwd();
     const strict = options.strict ?? false;
@@ -430,6 +644,9 @@ export async function validateCatalog(options) {
     if (options.scope === "task" && !options.task) {
         throw new Error("validateCatalog: task is required when scope is \"task\"");
     }
+    if (options.scope === "trigger" && !options.trigger) {
+        throw new Error("validateCatalog: trigger is required when scope is \"trigger\"");
+    }
     const allFindings = [];
     if (options.scope === "pipeline") {
         return validatePipeline(options.pipeline, {
@@ -442,6 +659,9 @@ export async function validateCatalog(options) {
     else if (options.scope === "task") {
         allFindings.push(...(await validateSingleTask(cwd, options.task)));
     }
+    else if (options.scope === "trigger") {
+        allFindings.push(...(await validateSingleTrigger(cwd, options.trigger)));
+    }
     else {
         allFindings.push(...(await validateManifestAll(cwd)));
     }

package/dist/config/validateCompletionContract.js

@@ -45,6 +45,14 @@ export function validateCompletionContractForStage(stage, completion) {
             !stage.gate_kinds?.includes(check.kind)) {
             return failure(stage.id, `gate check "${check.id}" requires gate_kinds to include "${check.kind}"`);
         }
+        if (check.type === "browser_login") {
+            if (stage.browser?.check === undefined) {
+                return failure(stage.id, `check "${check.id}" requires the stage to declare browser.check`);
+            }
+            if (stage.browser.headed === false) {
+                return failure(stage.id, `check "${check.id}" is a human login check and needs a visible browser (browser.headed must not be false)`);
+            }
+        }
         if (check.type === "checkout_changes") {
             for (const field of check.path_fields ?? []) {
                 if (!isRequiredStringArrayField(stage.payload_schema, field)) {

package/dist/diagnostics/checks.d.ts

@@ -0,0 +1,39 @@
+import type { RunStore } from "../runstore/port.js";
+export type DiagnosticSeverity = "error" | "warn" | "skipped";
+export type DiagnosticCheckResult = {
+    id: string;
+    ok: boolean;
+    severity: DiagnosticSeverity;
+    message: string;
+    code?: string;
+    detail?: Record<string, unknown>;
+};
+export type ReadyzChecks = {
+    store_openable: boolean;
+    home_writable: boolean;
+    migrations_complete: boolean;
+    git_present: boolean;
+};
+export type ReadyzResult = {
+    ready: boolean;
+    checks: ReadyzChecks;
+    code?: string;
+};
+export declare function resetReadyzCacheForTests(): void;
+export declare function livezBody(): {
+    ok: true;
+    status: "live";
+};
+export declare function probeGitVersion(): Promise<string | undefined>;
+export declare function runReadyzChecks(options: {
+    store: RunStore;
+    homeDir?: string;
+    now?: number;
+    bypassCache?: boolean;
+}): Promise<ReadyzResult>;
+export type SchemaHealthStub = {
+    user_version: number | null;
+    schema_migrations: "present" | "absent" | "unknown";
+    note?: string;
+};
+export declare function readSchemaHealth(store: RunStore): SchemaHealthStub;

package/dist/diagnostics/checks.js

@@ -0,0 +1,135 @@
+import { accessSync, constants, writeFileSync, unlinkSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { globalStageflowHome } from "../project/globalHome.js";
+const execFileAsync = promisify(execFile);
+const READYZ_TTL_MS = 4_000;
+let readyzCache;
+export function resetReadyzCacheForTests() {
+    readyzCache = undefined;
+}
+export function livezBody() {
+    return { ok: true, status: "live" };
+}
+async function checkGitPresent() {
+    try {
+        await execFileAsync("git", ["--version"], {
+            timeout: 5_000,
+            windowsHide: true,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function probeGitVersion() {
+    try {
+        const { stdout } = await execFileAsync("git", ["--version"], {
+            timeout: 5_000,
+            windowsHide: true,
+        });
+        return stdout.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function checkHomeWritable(home) {
+    try {
+        accessSync(home, constants.W_OK);
+        const probe = `${home}/.stageflow-write-probe-${process.pid}`;
+        writeFileSync(probe, "ok");
+        unlinkSync(probe);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function checkStoreOpenable(store) {
+    try {
+        await store.listRuns();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function checkMigrationsComplete(store) {
+    const connection = store.connection;
+    if (connection === undefined || typeof connection.pragma !== "function") {
+        return true;
+    }
+    try {
+        const version = connection.pragma("user_version", { simple: true });
+        return typeof version === "number" && version >= 0;
+    }
+    catch {
+        return false;
+    }
+}
+export async function runReadyzChecks(options) {
+    const now = options.now ?? Date.now();
+    if (!options.bypassCache &&
+        readyzCache !== undefined &&
+        readyzCache.expiresAt > now) {
+        return readyzCache.result;
+    }
+    const home = options.homeDir ?? globalStageflowHome();
+    const checks = {
+        store_openable: await checkStoreOpenable(options.store),
+        home_writable: checkHomeWritable(home),
+        migrations_complete: checkMigrationsComplete(options.store),
+        git_present: await checkGitPresent(),
+    };
+    let code;
+    if (!checks.store_openable)
+        code = "store_not_openable";
+    else if (!checks.home_writable)
+        code = "home_not_writable";
+    else if (!checks.migrations_complete)
+        code = "migrations_incomplete";
+    else if (!checks.git_present)
+        code = "git_not_present";
+    const result = {
+        ready: code === undefined,
+        checks,
+        ...(code !== undefined ? { code } : {}),
+    };
+    readyzCache = { expiresAt: now + READYZ_TTL_MS, result };
+    return result;
+}
+export function readSchemaHealth(store) {
+    const connection = store.connection;
+    if (connection === undefined || typeof connection.pragma !== "function") {
+        return {
+            user_version: null,
+            schema_migrations: "unknown",
+            note: "Slot 1 schema reporting stub — store has no sqlite connection",
+        };
+    }
+    try {
+        const user_version = connection.pragma("user_version", {
+            simple: true,
+        });
+        let schema_migrations = "unknown";
+        if (typeof connection.prepare === "function") {
+            try {
+                connection.prepare(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'schema_migrations'`).get();
+                schema_migrations = "present";
+            }
+            catch {
+                schema_migrations = "absent";
+            }
+        }
+        return { user_version, schema_migrations };
+    }
+    catch {
+        return {
+            user_version: null,
+            schema_migrations: "unknown",
+            note: "Slot 1 schema reporting stub — pragma failed",
+        };
+    }
+}

package/dist/envelope/preEmitChecks.d.ts

@@ -26,4 +26,4 @@ export declare function declaredArtifactIssue(artifacts: readonly string[], chec
  * `gate` check with no `readQaTrail` fails closed (cannot be verified). No
  * `checks` (or an empty list) is a no-op.
  */
-export declare function assertPreEmitChecks(envelope: Pick<StageEnvelope, "artifacts">, options: PreEmitCheckOptions | undefined): Promise<void>;
+export declare function assertPreEmitChecks(envelope: Pick<StageEnvelope, "artifacts" | "payload">, options: PreEmitCheckOptions | undefined): Promise<void>;

package/dist/envelope/preEmitChecks.js

@@ -10,6 +10,7 @@
  * why this stays separate from `CompletionCheck`'s `artifact`/`gate` runners.
  */
 import { preEmitGateIssue } from "../hitl/qaTrail.js";
+import { loginCheckIssue } from "../browser/loginCheck.js";
 import { EnvelopeError } from "../types/envelope.js";
 function artifactListsBasename(artifact, basename) {
     return artifact === basename || artifact.endsWith(`/${basename}`);
@@ -42,6 +43,13 @@ export async function assertPreEmitChecks(envelope, options) {
             }
             continue;
         }
+        if (check.type === "browser_login_check") {
+            const issue = loginCheckIssue(envelope.payload, check);
+            if (issue !== undefined) {
+                throw new EnvelopeError(issue);
+            }
+            continue;
+        }
         // check.type === "gate"
         if (options?.readQaTrail === undefined) {
             throw new EnvelopeError("declared gate kinds cannot be verified without a QA trail reader");

package/dist/errors/codes.d.ts

@@ -0,0 +1,14 @@
+/** Stable network-facing error codes (snake_case). Keep strings unchanged once shipped. */
+export declare const BUSY_CAPACITY: "busy_capacity";
+export declare const BUSY_CHECKOUT: "busy_checkout";
+/** Per-caller concurrency quota: queued when under global capacity; reject when queue full. */
+export declare const BUSY_CALLER_QUOTA: "busy_caller_quota";
+export declare const ABORTED: "aborted";
+export declare const NETWORK_ERROR_CODES: readonly ["busy_capacity", "busy_checkout", "busy_caller_quota", "aborted", "unknown_project_root", "absolute_path_not_allowed", "path_outside_project_root", "catalog_root_unreadable", "ensure_project_not_allowed", "config_invalid", "config_unknown_key", "provider_not_configured", "a2a_configuration_error", "untrusted_config_origin", "command_not_on_path", "missing_tool", "tool_version_mismatch", "unknown_version", "secret_unavailable", "not_ready", "internal_error", "retry_in_progress", "hitl_not_retriable", "run_not_retryable", "stage_not_failed", "manual_recovery_required", "run_not_found", "stage_not_found", "artifact_not_found", "artifact_path_denied", "envelope_not_found", "insufficient_disk", "disk_check_failed", "shutting_down", "start.token_rejected", "inline_pipeline_too_large", "skills_invalid_name", "skills_invalid_path", "skills_missing_skill_md", "skills_payload_too_large", "pinned_sha_unavailable", "store_integrity_failed", "store_unsupported_filesystem", "tmpdir_unusable", "backup_insufficient_disk"];
+export type NetworkErrorCode = (typeof NETWORK_ERROR_CODES)[number] | string;
+export type NetworkErrorBody = {
+    code: NetworkErrorCode;
+    error: string;
+} & Record<string, unknown>;
+export declare function networkError(code: NetworkErrorCode, error: string, detail?: Record<string, unknown>): NetworkErrorBody;
+export declare function codeOrInternal(code: string | undefined): NetworkErrorCode;

package/dist/errors/codes.js

@@ -0,0 +1,59 @@
+/** Stable network-facing error codes (snake_case). Keep strings unchanged once shipped. */
+export const BUSY_CAPACITY = "busy_capacity";
+export const BUSY_CHECKOUT = "busy_checkout";
+/** Per-caller concurrency quota: queued when under global capacity; reject when queue full. */
+export const BUSY_CALLER_QUOTA = "busy_caller_quota";
+export const ABORTED = "aborted";
+export const NETWORK_ERROR_CODES = [
+    BUSY_CAPACITY,
+    BUSY_CHECKOUT,
+    BUSY_CALLER_QUOTA,
+    ABORTED,
+    "unknown_project_root",
+    "absolute_path_not_allowed",
+    "path_outside_project_root",
+    "catalog_root_unreadable",
+    "ensure_project_not_allowed",
+    "config_invalid",
+    "config_unknown_key",
+    "provider_not_configured",
+    "a2a_configuration_error",
+    "untrusted_config_origin",
+    "command_not_on_path",
+    "missing_tool",
+    "tool_version_mismatch",
+    "unknown_version",
+    "secret_unavailable",
+    "not_ready",
+    "internal_error",
+    "retry_in_progress",
+    "hitl_not_retriable",
+    "run_not_retryable",
+    "stage_not_failed",
+    "manual_recovery_required",
+    "run_not_found",
+    "stage_not_found",
+    "artifact_not_found",
+    "artifact_path_denied",
+    "envelope_not_found",
+    "insufficient_disk",
+    "disk_check_failed",
+    "shutting_down",
+    "start.token_rejected",
+    "inline_pipeline_too_large",
+    "skills_invalid_name",
+    "skills_invalid_path",
+    "skills_missing_skill_md",
+    "skills_payload_too_large",
+    "pinned_sha_unavailable",
+    "store_integrity_failed",
+    "store_unsupported_filesystem",
+    "tmpdir_unusable",
+    "backup_insufficient_disk",
+];
+export function networkError(code, error, detail) {
+    return { code, error, ...detail };
+}
+export function codeOrInternal(code) {
+    return code && code.length > 0 ? code : "internal_error";
+}

package/dist/git/cache.d.ts

@@ -0,0 +1,14 @@
+export declare function setBareCacheRemoteUrlOverrideForTests(override: ((repository: string) => string | undefined) | null): void;
+export declare function resetBareCacheStateForTests(): void;
+export declare function githubHttpsRemoteUrl(repository: string): string;
+export declare function bareCachePath(repository: string): string;
+export declare function remoteUrlForRepository(repository: string): string;
+export type EnsureBareCacheResult = {
+    cachePath: string;
+    fetched: boolean;
+};
+export type EnsureBareCacheOptions = {
+    env?: NodeJS.ProcessEnv;
+    signal?: AbortSignal;
+};
+export declare function ensureBareCache(repository: string, ref: string, options?: EnsureBareCacheOptions): Promise<EnsureBareCacheResult>;