stageflow 0.2.0 → 0.3.0

package/dist/config/validateCatalog.js

@@ -1,12 +1,18 @@
-import { readdir } from "node:fs/promises";
 import path from "node:path";
-import { loadPipelineOutcome, loadPipelineValidated } from "./loadPipeline.js";
+import { loadPipelineOutcome, resolvePipelinePath } from "./loadPipeline.js";
 import { loadStageOutcome } from "./loadStage.js";
+import { loadTaskOutcome } from "./loadTask.js";
 import { readYamlObject } from "./readYamlObject.js";
-import { extractPipelineStageIds } from "./resolvePipelineDag.js";
+import { resolveCatalogContext } from "./resolveCatalogContext.js";
+import { getCatalogScanPaths } from "./browseCatalog.js";
+import { manifestPathForProject } from "./loadStageflowManifest.js";
 export function relPath(cwd, absPath) {
-    return path.relative(cwd, absPath);
+    return path.relative(cwd, absPath).replace(/\\/g, "/");
 }
+const STRICT_CATALOG_WARNINGS = new Set([
+    "catalog.manifest_missing",
+    "catalog.empty_catalog",
+]);
 const SEVERITY_RANK = {
     error: 0,
     warning: 1,
@@ -28,7 +34,7 @@ function sortFindings(findings) {
 export function effectiveSeverity(finding, strict) {
     if (strict &&
         finding.severity === "warning" &&
-        finding.code === "catalog.orphan_stage") {
+        STRICT_CATALOG_WARNINGS.has(finding.code)) {
         return "error";
     }
     return finding.severity;
@@ -82,6 +88,24 @@ function findingStageError(cwd, absPath, message, code, stageId) {
         stageId,
     }, "error");
 }
+function findingTaskError(cwd, absPath, message, code) {
+    return baseFinding({
+        cwd,
+        absPath,
+        message,
+        code,
+        category: "task",
+    }, "error");
+}
+function findingCatalog(cwd, absPath, message, code, severity) {
+    return baseFinding({
+        cwd,
+        absPath,
+        message,
+        code,
+        category: "catalog",
+    }, severity);
+}
 export function findingsFromLoadIssues(cwd, absPath, issues) {
     return issues.flatMap((issue) => {
         if (issue.category === "pipeline") {
@@ -94,6 +118,18 @@ export function findingsFromLoadIssues(cwd, absPath, issues) {
                 findingStageError(cwd, absPath, issue.message, issue.code, issue.stageId),
             ];
         }
+        if (issue.category === "task") {
+            return [
+                findingTaskError(cwd, absPath, issue.message, issue.code),
+            ];
+        }
+        if (issue.category === "catalog") {
+            const code = issue.code;
+            const severity = code === "catalog.manifest_missing" || code === "catalog.empty_catalog"
+                ? "warning"
+                : "error";
+            return [findingCatalog(cwd, absPath, issue.message, code, severity)];
+        }
         return [];
     });
 }
@@ -107,40 +143,6 @@ export function findingStageIdFilenameMismatch(cwd, absPath, fileStem, declaredI
         stageId: declaredId,
     }, "error");
 }
-function findingCatalogDuplicatePipelineId(cwd, absPath, pipelineId, conflictingPaths) {
-    const relConflicts = conflictingPaths.map((p) => relPath(cwd, p));
-    return baseFinding({
-        cwd,
-        absPath,
-        message: `Duplicate pipeline id "${pipelineId}" declared in: ${relConflicts.join(", ")}`,
-        code: "catalog.duplicate_pipeline_id",
-        category: "catalog",
-        pipelineId,
-    }, "error");
-}
-function findingCatalogOrphanStage(cwd, absPath, stageId) {
-    return baseFinding({
-        cwd,
-        absPath,
-        message: `Stage "${stageId}" is not referenced by any pipeline`,
-        code: "catalog.orphan_stage",
-        category: "catalog",
-        stageId,
-    }, "warning");
-}
-async function listYamlFiles(dir) {
-    let entries;
-    try {
-        entries = await readdir(dir, { withFileTypes: true });
-    }
-    catch {
-        return [];
-    }
-    return entries
-        .filter((entry) => entry.isFile() && entry.name.endsWith(".yaml"))
-        .map((entry) => path.join(dir, entry.name))
-        .sort((a, b) => a.localeCompare(b));
-}
 async function checkStageIdFilename(cwd, stagePath) {
     const fileStem = path.basename(stagePath, ".yaml");
     try {
@@ -169,52 +171,79 @@ async function validateStageFile(cwd, stagePath) {
     }
     return findings;
 }
-async function validatePipelineFile(pipelinePath, options) {
-    const { cwd, stagesDir, validateStages } = options;
-    const findings = [];
-    const referencedStageIds = new Set();
-    let pipelineId;
+async function runPipelineValidation(nameOrPath, options) {
+    const { cwd, validateStages } = options;
+    let pipelinePath;
     try {
-        const raw = await readYamlObject(pipelinePath);
-        if (typeof raw?.id === "string") {
-            pipelineId = raw.id;
-            if (Array.isArray(raw.stages)) {
-                const stageIds = extractPipelineStageIds(raw.stages);
-                if (stageIds) {
-                    for (const stageId of stageIds) {
-                        referencedStageIds.add(stageId);
-                    }
-                }
-            }
-        }
+        pipelinePath = await resolvePipelinePath(nameOrPath, cwd);
     }
-    catch {
-        // loadPipelineOutcome will report read errors
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            findings: findingsFromLoadIssues(cwd, path.resolve(cwd, nameOrPath), [
+                {
+                    code: "pipeline.load_error",
+                    message,
+                    category: "pipeline",
+                },
+            ]),
+        };
     }
-    const outcome = await loadPipelineOutcome(pipelinePath, { cwd, stagesDir });
+    const outcome = await loadPipelineOutcome(pipelinePath, { cwd });
+    const findings = [];
     if (!outcome.ok) {
         findings.push(...findingsFromLoadIssues(cwd, pipelinePath, outcome.issues));
-        if (validateStages) {
-            for (const stageId of referencedStageIds) {
-                const stagePath = path.join(stagesDir, `${stageId}.yaml`);
-                findings.push(...(await validateStageFile(cwd, stagePath)));
+        return { ok: false, findings };
+    }
+    if (validateStages && outcome.value.stageSources) {
+        for (const source of Object.values(outcome.value.stageSources)) {
+            if (source.kind === "file") {
+                findings.push(...(await validateStageFile(cwd, source.path)));
             }
         }
-        return { findings, pipelineId, referencedStageIds };
     }
-    for (const stageId of outcome.value.pipeline.stages) {
-        referencedStageIds.add(stageId);
-        if (validateStages) {
-            const stagePath = path.join(stagesDir, `${stageId}.yaml`);
-            findings.push(...(await validateStageFile(cwd, stagePath)));
-        }
+    if (findings.some((finding) => finding.severity === "error")) {
+        return { ok: false, findings };
     }
-    return { findings, pipelineId: outcome.value.pipeline.id, referencedStageIds };
+    return { ok: true, loaded: outcome.value, findings };
+}
+export async function validatePipeline(nameOrPath, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const validateStages = options.validateStages ?? true;
+    const strict = options.strict ?? false;
+    const core = await runPipelineValidation(nameOrPath, { cwd, validateStages });
+    return buildValidationResult("pipeline", core.findings, strict);
 }
-async function collectPipelineIds(pipelinesDir) {
-    const files = await listYamlFiles(pipelinesDir);
+export async function loadPipelineValidated(nameOrPath, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const validateStages = options.validateStages ?? true;
+    const core = await runPipelineValidation(nameOrPath, { cwd, validateStages });
+    if (core.ok) {
+        return { ok: true, loaded: core.loaded };
+    }
+    return { ok: false, findings: core.findings };
+}
+function findingCatalogDuplicatePipelineId(cwd, absPath, pipelineId, conflictingPaths) {
+    const relConflicts = conflictingPaths.map((p) => relPath(cwd, p));
+    return baseFinding({
+        cwd,
+        absPath,
+        message: `Duplicate pipeline id "${pipelineId}" declared in: ${relConflicts.join(", ")}`,
+        code: "catalog.duplicate_pipeline_id",
+        category: "catalog",
+        pipelineId,
+    }, "error");
+}
+function findingManifestMissing(cwd, projectRoot) {
+    return findingCatalog(cwd, manifestPathForProject(projectRoot), "No stageflow.yaml manifest found at project root", "catalog.manifest_missing", "warning");
+}
+function findingEmptyCatalog(cwd, manifestPath, kind) {
+    return findingCatalog(cwd, manifestPath, `Manifest catalog.${kind} is empty`, "catalog.empty_catalog", "warning");
+}
+async function collectPipelineIdsFromPaths(pipelinePaths) {
     const idToPaths = new Map();
-    for (const filePath of files) {
+    for (const filePath of pipelinePaths) {
         try {
             const raw = await readYamlObject(filePath);
             if (typeof raw?.id !== "string")
@@ -240,83 +269,91 @@ function findingsForDuplicatePipelineIds(cwd, idToPaths) {
     }
     return findings;
 }
-async function collectReferencedStageIds(pipelinesDir) {
-    const files = await listYamlFiles(pipelinesDir);
-    const referenced = new Set();
-    for (const filePath of files) {
-        try {
-            const raw = await readYamlObject(filePath);
-            if (typeof raw?.id !== "string" || !Array.isArray(raw.stages))
-                continue;
-            const stageIds = extractPipelineStageIds(raw.stages);
-            if (!stageIds)
-                continue;
-            for (const stageId of stageIds) {
-                referenced.add(stageId);
-            }
+async function validateManifestAll(invocationCwd) {
+    const ctx = await resolveCatalogContext(invocationCwd);
+    const findings = [];
+    if (ctx.manifestStatus === "not_git" || ctx.manifestStatus === "missing") {
+        if (ctx.projectRoot) {
+            findings.push(findingManifestMissing(invocationCwd, ctx.projectRoot));
         }
-        catch {
-            // skip unreadable
+        else {
+            findings.push(findingCatalog(invocationCwd, path.resolve(invocationCwd), "Not inside a git repository; no catalog manifest", "catalog.manifest_missing", "warning"));
         }
+        return findings;
     }
-    return referenced;
-}
-async function findingsForOrphanStages(cwd, stagesDir, referencedStageIds) {
-    const findings = [];
-    const stageFiles = await listYamlFiles(stagesDir);
-    for (const stagePath of stageFiles) {
-        const stageId = path.basename(stagePath, ".yaml");
-        if (referencedStageIds.has(stageId))
-            continue;
-        findings.push(findingCatalogOrphanStage(cwd, stagePath, stageId));
-        findings.push(...(await validateStageFile(cwd, stagePath)));
+    if (ctx.manifestStatus === "invalid") {
+        const manifestPath = ctx.projectRoot
+            ? manifestPathForProject(ctx.projectRoot)
+            : path.resolve(invocationCwd, "stageflow.yaml");
+        findings.push(...findingsFromLoadIssues(invocationCwd, manifestPath, ctx.issues));
+        return findings;
+    }
+    const { projectRoot, manifest } = ctx;
+    if (!projectRoot || !manifest) {
+        return findings;
+    }
+    if (manifest.manifest.catalog.pipelines.length === 0) {
+        findings.push(findingEmptyCatalog(invocationCwd, manifest.path, "pipelines"));
+    }
+    if (manifest.manifest.catalog.tasks.length === 0) {
+        findings.push(findingEmptyCatalog(invocationCwd, manifest.path, "tasks"));
+    }
+    const scanPaths = await getCatalogScanPaths(ctx);
+    if (!scanPaths) {
+        return findings;
+    }
+    const { pipelinePaths, taskPaths } = scanPaths;
+    for (const pipelinePath of pipelinePaths) {
+        const core = await runPipelineValidation(pipelinePath, {
+            cwd: projectRoot,
+            validateStages: true,
+        });
+        if (!core.ok) {
+            findings.push(...core.findings);
+        }
     }
+    for (const taskPath of taskPaths) {
+        const outcome = await loadTaskOutcome(taskPath);
+        if (!outcome.ok) {
+            findings.push(...findingsFromLoadIssues(projectRoot, taskPath, outcome.issues));
+        }
+    }
+    const idToPaths = await collectPipelineIdsFromPaths(pipelinePaths);
+    findings.push(...findingsForDuplicatePipelineIds(projectRoot, idToPaths));
     return findings;
 }
+async function validateSingleTask(invocationCwd, taskArg) {
+    const ctx = await resolveCatalogContext(invocationCwd);
+    const relCwd = ctx.projectRoot ?? invocationCwd;
+    const taskPath = path.resolve(invocationCwd, taskArg);
+    const outcome = await loadTaskOutcome(taskPath);
+    if (!outcome.ok) {
+        return findingsFromLoadIssues(relCwd, taskPath, outcome.issues);
+    }
+    return [];
+}
 export async function validateCatalog(options) {
     const cwd = options.cwd ?? process.cwd();
-    const stagesDir = options.stagesDir ?? path.join(cwd, "stages");
     const strict = options.strict ?? false;
-    const pipelinesDir = path.join(cwd, "pipelines");
     if (options.scope === "pipeline" && !options.pipeline) {
         throw new Error("validateCatalog: pipeline is required when scope is \"pipeline\"");
     }
+    if (options.scope === "task" && !options.task) {
+        throw new Error("validateCatalog: task is required when scope is \"task\"");
+    }
     const allFindings = [];
     if (options.scope === "pipeline") {
-        const result = await loadPipelineValidated(options.pipeline, {
+        return validatePipeline(options.pipeline, {
             cwd,
-            stagesDir,
             validateStages: true,
+            strict,
         });
-        if (!result.ok) {
-            allFindings.push(...result.findings);
-        }
+    }
+    else if (options.scope === "task") {
+        allFindings.push(...(await validateSingleTask(cwd, options.task)));
     }
     else {
-        const referencedStageIds = await collectReferencedStageIds(pipelinesDir);
-        const pipelineFiles = await listYamlFiles(pipelinesDir);
-        for (const pipelinePath of pipelineFiles) {
-            const result = await validatePipelineFile(pipelinePath, {
-                cwd,
-                stagesDir,
-                validateStages: false,
-            });
-            allFindings.push(...result.findings);
-            for (const stageId of result.referencedStageIds) {
-                referencedStageIds.add(stageId);
-            }
-        }
-        const validatedStages = new Set();
-        for (const stageId of referencedStageIds) {
-            if (validatedStages.has(stageId))
-                continue;
-            validatedStages.add(stageId);
-            const stagePath = path.join(stagesDir, `${stageId}.yaml`);
-            allFindings.push(...(await validateStageFile(cwd, stagePath)));
-        }
-        const idToPaths = await collectPipelineIds(pipelinesDir);
-        allFindings.push(...findingsForDuplicatePipelineIds(cwd, idToPaths));
-        allFindings.push(...(await findingsForOrphanStages(cwd, stagesDir, referencedStageIds)));
+        allFindings.push(...(await validateManifestAll(cwd)));
     }
     return buildValidationResult(options.scope, allFindings, strict);
 }

package/dist/envelope/check.js

@@ -25,6 +25,13 @@ export function assertRequiredEnvelope(value) {
         summary: record.summary,
         artifacts: record.artifacts,
     };
+    if (record.fork_choice !== undefined) {
+        if (!Array.isArray(record.fork_choice) ||
+            !record.fork_choice.every((item) => typeof item === "string")) {
+            throw new EnvelopeError("fork_choice must be an array of strings");
+        }
+        envelope.fork_choice = record.fork_choice;
+    }
     if (record.payload !== undefined) {
         if (record.payload === null ||
             typeof record.payload !== "object" ||

package/dist/envelope/forkChoice.d.ts

@@ -0,0 +1,3 @@
+import type { ForkEmitContext } from "../types/forkChoice.js";
+export declare function assertForkEnvelope(params: unknown, forkEmitContext: ForkEmitContext): void;
+export declare function normalizeForkChoice(raw: string[] | undefined, mode: "emit" | "stored", forkEmitContext?: ForkEmitContext): Set<string>;

package/dist/envelope/forkChoice.js

@@ -0,0 +1,47 @@
+/**
+ * Emit mode rejects missing fork_choice on fork success; stored mode treats
+ * undefined as an empty choice set (scheduler defensive path).
+ */
+import { EnvelopeError } from "../types/envelope.js";
+function assertForkChoiceLegality(choices, forkEmitContext) {
+    const { immediateSuccessorIds, forkShape } = forkEmitContext;
+    for (const id of choices) {
+        if (!immediateSuccessorIds.includes(id)) {
+            throw new EnvelopeError(`fork_choice contains non-immediate successor: ${id}`);
+        }
+    }
+    if (choices.length === 0) {
+        if (forkShape === null || !forkShape.allowNone) {
+            throw new EnvelopeError("fork_choice must not be empty");
+        }
+    }
+    if (forkShape !== null && forkShape.cardinality === "one" && choices.length !== 1) {
+        throw new EnvelopeError("fork shape requires exactly one choice");
+    }
+}
+export function assertForkEnvelope(params, forkEmitContext) {
+    const record = params;
+    if (record.status === "failure")
+        return;
+    if (record.fork_choice === undefined) {
+        throw new EnvelopeError("fork stage must include fork_choice on success");
+    }
+    assertForkChoiceLegality(record.fork_choice, forkEmitContext);
+}
+export function normalizeForkChoice(raw, mode, forkEmitContext) {
+    if (mode === "stored") {
+        if (raw === undefined)
+            return new Set();
+        return new Set(raw);
+    }
+    if (forkEmitContext === undefined) {
+        if (raw === undefined)
+            return new Set();
+        return new Set(raw);
+    }
+    if (raw === undefined) {
+        throw new EnvelopeError("fork stage must include fork_choice on success");
+    }
+    assertForkChoiceLegality(raw, forkEmitContext);
+    return new Set(raw);
+}

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+export { findProjectRoot, clearFindProjectRootCacheForTests, } from "./project/findProjectRoot.js";
+export { globalStageflowHome, ensureGlobalHome, } from "./project/globalHome.js";
+export { resolveProjectContext, legacyProjectContext, type ProjectContext, } from "./project/resolveProjectContext.js";
+export { resolveStageflowContext, projectContextFromStageflow, type StageflowContext, type CatalogManifestStatus, } from "./project/resolveStageflowContext.js";
 export { PACKAGE_NAME } from "./package-meta.js";
 export type { StageEnvelope } from "./types/envelope.js";
 export { assertRequiredEnvelope, isAdvancingEnvelope, } from "./envelope/check.js";

package/dist/index.js

@@ -1,3 +1,7 @@
+export { findProjectRoot, clearFindProjectRootCacheForTests, } from "./project/findProjectRoot.js";
+export { globalStageflowHome, ensureGlobalHome, } from "./project/globalHome.js";
+export { resolveProjectContext, legacyProjectContext, } from "./project/resolveProjectContext.js";
+export { resolveStageflowContext, projectContextFromStageflow, } from "./project/resolveStageflowContext.js";
 export { PACKAGE_NAME } from "./package-meta.js";
 export { assertRequiredEnvelope, isAdvancingEnvelope, } from "./envelope/check.js";
 export { runPipeline, startPipeline } from "./runtime/pipelineRunner.js";

package/dist/mcp/projectRun.d.ts

@@ -19,6 +19,9 @@ export type McpRunProjection = {
     run_id: string;
     pipeline_id: string;
     task_id?: string;
+    pipeline_path?: string;
+    task_path?: string;
+    project_root?: string;
     status: RunDetail["status"];
     created_at: string;
     updated_at?: string;

package/dist/mcp/projectRun.js

@@ -3,6 +3,13 @@ export function projectRunForMcp(detail) {
         run_id: detail.run_id,
         pipeline_id: detail.pipeline_id,
         task_id: detail.task_id,
+        ...(detail.pipeline_path !== undefined
+            ? { pipeline_path: detail.pipeline_path }
+            : {}),
+        ...(detail.task_path !== undefined ? { task_path: detail.task_path } : {}),
+        ...(detail.project_root !== undefined
+            ? { project_root: detail.project_root }
+            : {}),
         status: detail.status,
         created_at: detail.created_at,
         updated_at: detail.updated_at,

package/dist/mcp/tools.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { listPipelines } from "../config/listConfig.js";
+import { browseCatalog } from "../config/browseCatalog.js";
 import { projectRunForMcp } from "./projectRun.js";
 import { readRunArtifact } from "./readArtifact.js";
 const taskFileSchema = z.object({
@@ -9,6 +9,15 @@ const taskFileSchema = z.object({
     constraints: z.string().optional(),
     checkout: z.string().optional(),
 });
+const startRunSchema = z
+    .object({
+    pipeline: z.string().describe("Filesystem path to a pipeline YAML file"),
+    task_path: z.string().optional(),
+    task: taskFileSchema.optional(),
+})
+    .refine((data) => Boolean(data.task_path) !== Boolean(data.task), {
+    message: "Exactly one of task_path or task is required",
+});
 function textResult(data, isError = false) {
     return {
         content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
@@ -18,11 +27,18 @@ function textResult(data, isError = false) {
 export function registerMcpTools(server, deps) {
     const { manager, store, cwd } = deps;
     server.registerTool("list_pipelines", {
-        description: "List runnable pipeline ids from the factory cwd",
+        description: "List manifest-declared pipeline paths from the project catalog",
+        inputSchema: z.object({}),
+    }, async () => {
+        const catalog = await browseCatalog(cwd);
+        return textResult({ pipelines: catalog.pipelines });
+    });
+    server.registerTool("list_tasks", {
+        description: "List manifest-declared task paths from the project catalog",
         inputSchema: z.object({}),
     }, async () => {
-        const pipelines = await listPipelines(cwd);
-        return textResult({ pipelines });
+        const catalog = await browseCatalog(cwd);
+        return textResult({ tasks: catalog.tasks });
     });
     server.registerTool("list_runs", {
         description: "List known pipeline runs",
@@ -36,16 +52,17 @@ export function registerMcpTools(server, deps) {
         inputSchema: z.object({}),
     }, async () => textResult(manager.getHealth()));
     server.registerTool("start_run", {
-        description: "Start a pipeline with an inline TaskFile (not written under tasks/). Returns { runId }. On conflict returns isError with code busy_capacity (soft max full) or busy_checkout (same checkout leased), plus activeCount/maxConcurrent/activeRunIds and optional conflictingRunId/conflictingCheckout.",
-        inputSchema: z.object({
-            pipeline: z.string(),
-            task: taskFileSchema,
-        }),
-    }, async ({ pipeline, task }) => {
+        description: "Start a pipeline run using a filesystem pipeline path and either task_path (catalog task file) or an inline task object. Returns { runId }. On conflict returns isError with code busy_capacity (soft max full) or busy_checkout (same checkout leased), plus activeCount/maxConcurrent/activeRunIds and optional conflictingRunId/conflictingCheckout.",
+        inputSchema: startRunSchema,
+    }, async ({ pipeline, task_path, task }) => {
         if (!pipeline.trim()) {
             return textResult({ error: "pipeline is required" }, true);
         }
-        const result = await manager.startRun({ pipeline, task });
+        const taskInput = task_path ?? task;
+        if (taskInput === undefined) {
+            return textResult({ error: "Exactly one of task_path or task is required" }, true);
+        }
+        const result = await manager.startRun({ pipeline, task: taskInput });
         if (!result.ok) {
             const { ok: _ok, reason, ...rest } = result;
             return textResult({ error: reason, ...rest }, true);

package/dist/project/findProjectRoot.d.ts

@@ -0,0 +1,2 @@
+export declare function findProjectRoot(startDir: string): string | null;
+export declare function clearFindProjectRootCacheForTests(): void;

package/dist/project/findProjectRoot.js

@@ -0,0 +1,51 @@
+import { existsSync, realpathSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+const cache = new Map();
+function normalizeRoot(dir) {
+    try {
+        return realpathSync(path.resolve(dir));
+    }
+    catch {
+        return path.resolve(dir);
+    }
+}
+export function findProjectRoot(startDir) {
+    const normalized = path.resolve(startDir);
+    if (cache.has(normalized)) {
+        return cache.get(normalized) ?? null;
+    }
+    let result = null;
+    try {
+        const stdout = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            cwd: normalized,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const trimmed = stdout.trim();
+        if (trimmed.length > 0) {
+            result = normalizeRoot(trimmed);
+        }
+    }
+    catch {
+        result = walkForGitRoot(normalized);
+    }
+    cache.set(normalized, result);
+    return result;
+}
+function walkForGitRoot(startDir) {
+    let dir = path.resolve(startDir);
+    for (;;) {
+        if (existsSync(path.join(dir, ".git"))) {
+            return normalizeRoot(dir);
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            return null;
+        }
+        dir = parent;
+    }
+}
+export function clearFindProjectRootCacheForTests() {
+    cache.clear();
+}

package/dist/project/globalHome.d.ts

@@ -0,0 +1,2 @@
+export declare function globalStageflowHome(): string;
+export declare function ensureGlobalHome(): string;

package/dist/project/globalHome.js

@@ -0,0 +1,19 @@
+import { chmodSync, mkdirSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export function globalStageflowHome() {
+    return path.join(os.homedir(), ".stageflow");
+}
+export function ensureGlobalHome() {
+    const globalHome = globalStageflowHome();
+    mkdirSync(globalHome, { recursive: true });
+    const agentDir = path.join(globalHome, "agent");
+    mkdirSync(agentDir, { recursive: true });
+    try {
+        chmodSync(agentDir, 0o700);
+    }
+    catch {
+        // best-effort on non-POSIX
+    }
+    return globalHome;
+}

package/dist/project/resolveProjectContext.d.ts

@@ -0,0 +1,9 @@
+export type ProjectContext = {
+    invocationCwd: string;
+    projectRoot: string;
+    globalHome: string;
+    isGitProject: boolean;
+};
+export declare function resolveProjectContext(invocationCwd: string): ProjectContext;
+export declare function legacyProjectContext(cwd: string): ProjectContext;
+export declare function asProjectContext(input: ProjectContext | string): ProjectContext;