cool-workflow 0.1.85 → 0.1.86

package/dist/onramp.js

@@ -0,0 +1,421 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.optionEnabled = optionEnabled;
+exports.npmCommand = npmCommand;
+exports.nodeSmokeCommand = nodeSmokeCommand;
+exports.detectSourceCheckout = detectSourceCheckout;
+exports.shellQuote = shellQuote;
+exports.buildDoctorOnramp = buildDoctorOnramp;
+exports.resolveChangedFiles = resolveChangedFiles;
+exports.evaluateOnrampContract = evaluateOnrampContract;
+exports.recommendSmokeTests = recommendSmokeTests;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const CURATED_SMOKE_MAP = [
+    {
+        patterns: ["src/doctor.ts", "src/onramp.ts", "scripts/onramp-check.js"],
+        smokes: ["doctor-smoke.js", "onramp-check-smoke.js"]
+    },
+    {
+        patterns: ["README.md", "docs/getting-started.md", "docs/index.md"],
+        smokes: ["quickstart-readme-path-smoke.js", "doctor-smoke.js"]
+    },
+    {
+        patterns: ["src/cli.ts", "src/cli/"],
+        smokes: ["cli-command-surface-smoke.js", "cli-jsonmode-parity-smoke.js", "cli-mcp-parity-smoke.js"]
+    },
+    {
+        patterns: ["src/orchestrator.ts"],
+        smokes: ["cli-mcp-parity-smoke.js"]
+    },
+    {
+        patterns: ["src/capability-registry.ts", "scripts/parity-check.js"],
+        smokes: ["cli-mcp-parity-smoke.js", "cli-jsonmode-parity-smoke.js", "parity-doc-sync-smoke.js"]
+    },
+    {
+        patterns: ["src/mcp-server.ts", "src/mcp-surface.ts"],
+        smokes: ["mcp-surface-registry-smoke.js", "mcp-app-surface-smoke.js", "cli-mcp-parity-smoke.js"]
+    },
+    {
+        patterns: ["src/run-export.ts", "src/types/run.ts"],
+        smokes: ["run-export-import-smoke.js", "run-export-restore-resume-smoke.js", "run-inspect-archive-smoke.js"]
+    },
+    {
+        patterns: ["src/capability-core.ts", "src/drive.ts", "src/agent-config.ts"],
+        smokes: ["quickstart-smoke.js", "quickstart-check-smoke.js", "agent-delegation-drive-smoke.js"]
+    },
+    {
+        patterns: ["src/telemetry", "src/worker-accept/telemetry"],
+        smokes: ["telemetry-ledger-smoke.js", "telemetry-attestation-smoke.js", "telemetry-verify-signatures-smoke.js"]
+    },
+    {
+        patterns: ["src/workbench", "ui/workbench/"],
+        smokes: ["web-desktop-workbench-smoke.js"]
+    },
+    {
+        patterns: ["src/scheduler.ts", "src/scheduling.ts", "src/daemon.ts", "src/triggers.ts"],
+        smokes: ["schedule-routine-daemon-smoke.js", "sched-policy-validation-smoke.js"]
+    },
+    {
+        patterns: ["src/multi-agent", "src/topology.ts", "src/coordinator", "src/evidence-reasoning.ts", "src/state-explosion"],
+        smokes: [
+            "multi-agent-runtime-core-smoke.js",
+            "multi-agent-topologies-map-reduce-smoke.js",
+            "multi-agent-topologies-debate-smoke.js",
+            "multi-agent-topologies-judge-panel-smoke.js",
+            "multi-agent-cli-mcp-surface-smoke.js",
+            "blackboard-state-explosion-management-smoke.js"
+        ]
+    }
+];
+function optionEnabled(value) {
+    if (value === undefined || value === false)
+        return false;
+    if (typeof value === "string" && ["", "0", "false", "no"].includes(value.toLowerCase()))
+        return false;
+    return true;
+}
+function npmCommand(cwd, script) {
+    const source = detectSourceCheckout(cwd);
+    const base = `npm run ${script}`;
+    return source ? `${source.chdir}${base}` : base;
+}
+function nodeSmokeCommand(cwd, smoke) {
+    const source = detectSourceCheckout(cwd);
+    const base = `node test/${smoke}`;
+    return source ? `${source.chdir}${base}` : base;
+}
+function detectSourceCheckout(cwd) {
+    const resolved = node_path_1.default.resolve(cwd);
+    const candidates = [resolved, node_path_1.default.join(resolved, "plugins", "cool-workflow")];
+    for (const candidate of candidates) {
+        try {
+            const pkg = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(candidate, "package.json"), "utf8"));
+            if (pkg.name === "cool-workflow") {
+                return {
+                    packageDir: candidate,
+                    chdir: candidate === resolved ? "" : `cd ${shellQuote(node_path_1.default.relative(resolved, candidate) || ".")} && `
+                };
+            }
+        }
+        catch {
+            /* keep looking */
+        }
+    }
+    return undefined;
+}
+function shellQuote(value) {
+    if (/^[A-Za-z0-9_./:-]+$/.test(value))
+        return value;
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function buildDoctorOnramp(options = {}) {
+    const cwd = node_path_1.default.resolve(options.cwd || process.cwd());
+    const agentCommand = "--agent-command builtin:claude";
+    const onramp = {
+        schemaVersion: 1,
+        summary: "start small, run the short gate while changing code, then run the full gate before release",
+        sections: [
+            {
+                id: "first-run",
+                title: "First Run",
+                summary: "Prove the tool, check the setup, then make one report.",
+                actions: [
+                    {
+                        id: "demo",
+                        title: "Prove tamper checks",
+                        command: "cw demo tamper",
+                        reason: "Shows the core trust check without an agent or a repo."
+                    },
+                    {
+                        id: "setup",
+                        title: "Check setup",
+                        command: "cw doctor --onramp",
+                        reason: "Names local setup trouble before a run is made."
+                    },
+                    {
+                        id: "dry-run",
+                        title: "Check a real run",
+                        command: `cw quickstart architecture-review --check --repo /path/to/repo --question "What are the main risks?" ${agentCommand}`,
+                        reason: "Does no writes and no agent call; it checks inputs first."
+                    },
+                    {
+                        id: "report",
+                        title: "Make the report",
+                        command: `cw quickstart architecture-review --repo /path/to/repo --question "What are the main risks?" ${agentCommand}`,
+                        reason: "Runs the short user path: ask, run, verify, report."
+                    },
+                    {
+                        id: "bundle",
+                        title: "Make a bundle",
+                        command: `cw quickstart architecture-review --repo /path/to/repo --question "What are the main risks?" ${agentCommand} --bundle`,
+                        reason: "Seals a completed report into a portable file the receiver can check offline."
+                    },
+                    {
+                        id: "verify-bundle",
+                        title: "Check the bundle",
+                        command: "cw report verify-bundle report.cwrun.json",
+                        reason: "Checks the report bundle without the source repo or a .cw tree."
+                    }
+                ]
+            },
+            {
+                id: "change-loop",
+                title: "Change Loop",
+                summary: "Use the small checks while changing code; save the slow full gate for the end.",
+                actions: [
+                    {
+                        id: "build",
+                        title: "Type check the change",
+                        command: npmCommand(cwd, "build"),
+                        reason: "Fast first check for TypeScript errors."
+                    },
+                    {
+                        id: "target-smoke",
+                        title: "Run the closest smoke",
+                        command: nodeSmokeCommand(cwd, "doctor-smoke.js"),
+                        reason: "Replace this smoke name with the one that covers your changed path."
+                    },
+                    {
+                        id: "fast-suite",
+                        title: "Run the parallel suite",
+                        command: npmCommand(cwd, "test:fast"),
+                        reason: "Runs all smokes with isolated state and parallel workers."
+                    }
+                ]
+            },
+            {
+                id: "surface-guard",
+                title: "Surface Guard",
+                summary: "Keep the wide runner, CLI, and MCP faces tied to one source.",
+                actions: [
+                    {
+                        id: "registry",
+                        title: "Declare each new verb once",
+                        command: npmCommand(cwd, "parity:check"),
+                        reason: "Fails if CLI and MCP drift from the capability registry."
+                    },
+                    {
+                        id: "manifest",
+                        title: "Check generated faces",
+                        command: npmCommand(cwd, "gen:manifests -- --check"),
+                        reason: "Fails if plugin manifests drift from source."
+                    }
+                ]
+            },
+            {
+                id: "release-gate",
+                title: "Release Gate",
+                summary: "Run the full gate only when the batch is ready.",
+                actions: [
+                    {
+                        id: "release-check",
+                        title: "Dry-run the release gate",
+                        command: npmCommand(cwd, "release:check"),
+                        reason: "Builds, checks docs and generated files, runs the parallel suite, and makes no tag."
+                    }
+                ]
+            }
+        ]
+    };
+    if (options.changedFrom) {
+        const changed = resolveChangedFiles({ cwd, changedFrom: options.changedFrom, env: options.env });
+        const contract = evaluateOnrampContract(changed.files, { cwd });
+        onramp.changedFiles = changed;
+        onramp.contract = contract;
+        onramp.recommendedChecks = {
+            summary: contract.recommendedSmokeTests.length
+                ? "run the closest smoke tests first, then the fast suite and release gate"
+                : "no changed files were found; use the normal short checks",
+            smokeTests: contract.recommendedSmokeTests,
+            commands: contract.recommendedCommands
+        };
+    }
+    return onramp;
+}
+function resolveChangedFiles(options = {}) {
+    const cwd = node_path_1.default.resolve(options.cwd || process.cwd());
+    const root = gitRoot(cwd);
+    const baseRef = resolveBaseRef(root, options.changedFrom, options.env || process.env);
+    const files = new Set();
+    for (const file of gitLines(root, ["diff", "--name-only", baseRef, "--"]))
+        files.add(normalizeChangedPath(file));
+    for (const file of gitLines(root, ["ls-files", "--others", "--exclude-standard"]))
+        files.add(normalizeChangedPath(file));
+    return { baseRef, files: [...files].filter(Boolean).sort() };
+}
+function evaluateOnrampContract(files, options = {}) {
+    const cwd = node_path_1.default.resolve(options.cwd || process.cwd());
+    const normalized = [...new Set(files.map((file) => normalizeChangedPath(file)).filter(Boolean))].sort();
+    const issues = [];
+    const runtimeFiles = normalized.filter(isRuntimeSource);
+    const appFiles = normalized.filter((file) => file.startsWith("plugins/cool-workflow/apps/"));
+    const typeFiles = normalized.filter((file) => file.startsWith("plugins/cool-workflow/src/types/") && file.endsWith(".ts"));
+    const scriptFiles = normalized.filter((file) => file.startsWith("plugins/cool-workflow/scripts/"));
+    const surfaceFiles = normalized.filter(isSurfaceFile);
+    const smokeFiles = normalized.filter((file) => /^plugins\/cool-workflow\/test\/.+-smoke\.js$/.test(file));
+    const docFiles = normalized.filter(isDocFile);
+    const iterationFiles = normalized.filter((file) => file === "ITERATION_LOG.md");
+    const sourceAppOrScript = runtimeFiles.length > 0 || typeFiles.length > 0 || appFiles.length > 0 || scriptFiles.length > 0;
+    if ((runtimeFiles.length > 0 || appFiles.length > 0) && smokeFiles.length === 0) {
+        issues.push({
+            code: "runtime-smoke-required",
+            detail: "Runtime or app changes must include at least one smoke test change.",
+            fix: "Add or update a focused test/*-smoke.js file for the changed behavior.",
+            files: [...runtimeFiles, ...appFiles]
+        });
+    }
+    if (typeFiles.length > 0 && runtimeFiles.length === 0 && appFiles.length === 0) {
+        issues.push({
+            code: "types-without-runtime",
+            detail: "Type-only source changes are not a valid cycle.",
+            fix: "Add the runtime behavior that reads the type, or remove the type-only change.",
+            files: typeFiles
+        });
+    }
+    if (surfaceFiles.length > 0 && docFiles.length === 0) {
+        issues.push({
+            code: "surface-docs-required",
+            detail: "CLI, MCP, or capability surface changes must update public docs.",
+            fix: "Update README.md or plugins/cool-workflow/docs/*.md with the changed surface.",
+            files: surfaceFiles
+        });
+    }
+    if (sourceAppOrScript && iterationFiles.length === 0) {
+        issues.push({
+            code: "iteration-log-required",
+            detail: "Source, app, or script changes must be recorded in ITERATION_LOG.md.",
+            fix: "Append one cycle row with goal, files, tests, gate, and tag decision.",
+            files: [...runtimeFiles, ...typeFiles, ...appFiles, ...scriptFiles]
+        });
+    }
+    const recommendedSmokeTests = recommendSmokeTests(normalized, cwd);
+    return {
+        ok: issues.length === 0,
+        changedFiles: normalized,
+        recommendedSmokeTests,
+        recommendedCommands: recommendedCommands(normalized, recommendedSmokeTests, cwd),
+        issues
+    };
+}
+function recommendSmokeTests(files, cwd = process.cwd()) {
+    const normalized = files.map((file) => normalizeChangedPath(file));
+    const smokes = new Set();
+    const curatedFiles = new Set();
+    for (const file of normalized) {
+        const pluginPath = stripPluginPrefix(file);
+        for (const entry of CURATED_SMOKE_MAP) {
+            const matched = entry.patterns.some((pattern) => pluginPath === pattern || pluginPath.startsWith(pattern));
+            if (matched) {
+                curatedFiles.add(file);
+                for (const smoke of entry.smokes)
+                    smokes.add(smoke);
+            }
+        }
+    }
+    const available = availableSmokeTests(cwd);
+    for (const file of normalized) {
+        if (curatedFiles.has(file))
+            continue;
+        const pluginPath = stripPluginPrefix(file);
+        if (!pluginPath.startsWith("src/"))
+            continue;
+        const base = node_path_1.default.basename(pluginPath, ".ts");
+        const direct = `${base}-smoke.js`;
+        if (available.includes(direct))
+            smokes.add(direct);
+        const tokens = base.split(/[^a-zA-Z0-9]+/).filter((token) => token.length >= 3);
+        for (const smoke of available) {
+            if (tokens.some((token) => smoke.includes(token)))
+                smokes.add(smoke);
+        }
+    }
+    return [...smokes].sort();
+}
+function recommendedCommands(files, smokes, cwd) {
+    const commands = new Set();
+    commands.add(npmCommand(cwd, "build"));
+    for (const smoke of smokes)
+        commands.add(nodeSmokeCommand(cwd, smoke));
+    commands.add(npmCommand(cwd, "test:fast"));
+    if (files.some(isSurfaceFile))
+        commands.add(npmCommand(cwd, "parity:check"));
+    if (files.some(isSurfaceFile))
+        commands.add(npmCommand(cwd, "gen:manifests -- --check"));
+    commands.add(npmCommand(cwd, "release:check"));
+    return [...commands];
+}
+function resolveBaseRef(root, changedFrom, env) {
+    if (changedFrom)
+        return verifyRef(root, changedFrom);
+    if (env.CW_ONRAMP_BASE)
+        return verifyRef(root, env.CW_ONRAMP_BASE);
+    const baseBranch = env.GITHUB_BASE_REF ? `origin/${env.GITHUB_BASE_REF}` : "origin/main";
+    const mergeBase = gitOne(root, ["merge-base", "HEAD", baseBranch]);
+    if (mergeBase)
+        return mergeBase;
+    return verifyRef(root, "HEAD");
+}
+function verifyRef(root, ref) {
+    const resolved = gitOne(root, ["rev-parse", "--verify", `${ref}^{commit}`]);
+    if (!resolved)
+        throw new Error(`Unknown onramp base ref: ${ref}`);
+    return ref;
+}
+function gitRoot(cwd) {
+    return gitOne(node_path_1.default.resolve(cwd), ["rev-parse", "--show-toplevel"]) || node_path_1.default.resolve(cwd);
+}
+function gitLines(cwd, args) {
+    const result = (0, node_child_process_1.spawnSync)("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    if (result.status !== 0)
+        return [];
+    return String(result.stdout || "").split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+}
+function gitOne(cwd, args) {
+    return gitLines(cwd, args)[0] || "";
+}
+function availableSmokeTests(cwd) {
+    const source = detectSourceCheckout(cwd);
+    const testDir = source ? node_path_1.default.join(source.packageDir, "test") : node_path_1.default.join(node_path_1.default.resolve(cwd), "test");
+    try {
+        return node_fs_1.default.readdirSync(testDir).filter((file) => file.endsWith("-smoke.js")).sort();
+    }
+    catch {
+        return [];
+    }
+}
+function normalizeChangedPath(file) {
+    const normalized = file.replace(/\\/g, "/").replace(/^\.\//, "");
+    if (/^(src|apps|scripts|test|docs|dist|manifest|ui|workflows)\//.test(normalized)) {
+        return `plugins/cool-workflow/${normalized}`;
+    }
+    return normalized;
+}
+function stripPluginPrefix(file) {
+    return file.startsWith("plugins/cool-workflow/") ? file.slice("plugins/cool-workflow/".length) : file;
+}
+function isRuntimeSource(file) {
+    return file.startsWith("plugins/cool-workflow/src/") && file.endsWith(".ts") && !file.startsWith("plugins/cool-workflow/src/types/");
+}
+function isSurfaceFile(file) {
+    const pluginPath = stripPluginPrefix(file);
+    return (pluginPath === "src/cli.ts" ||
+        pluginPath.startsWith("src/cli/") ||
+        pluginPath === "src/capability-registry.ts" ||
+        pluginPath === "src/mcp-server.ts" ||
+        pluginPath === "src/mcp-surface.ts" ||
+        pluginPath === "src/orchestrator.ts" ||
+        pluginPath === "scripts/parity-check.js");
+}
+function isDocFile(file) {
+    return (file === "README.md" ||
+        file === "CHANGELOG.md" ||
+        file === "RELEASE.md" ||
+        file.startsWith("docs/") ||
+        file === "plugins/cool-workflow/README.md" ||
+        file.startsWith("plugins/cool-workflow/docs/"));
+}

package/dist/orchestrator.js

@@ -178,7 +178,7 @@ class CoolWorkflowRunner {
             return {
                 valid: false,
                 appId: target,
-                appPath: node_path_1.default.resolve(target),
+                appPath: this.resolveFromBase(target),
                 issues
             };
         }
@@ -188,7 +188,7 @@ class CoolWorkflowRunner {
         if (!id)
             throw new Error("App id must include at least one letter or digit");
         const title = String(options.title || titleize(id));
-        const destinationDir = node_path_1.default.resolve(String(options.directory || options.output || node_path_1.default.join(this.appsDir, id)));
+        const destinationDir = this.resolveFromBase(String(options.directory || options.output || node_path_1.default.join(this.appsDir, id)));
         const manifestPath = node_path_1.default.join(destinationDir, "app.json");
         const entrypointPath = node_path_1.default.join(destinationDir, "workflow.js");
         if (!options.force && (node_fs_1.default.existsSync(manifestPath) || node_fs_1.default.existsSync(entrypointPath))) {
@@ -205,8 +205,7 @@ class CoolWorkflowRunner {
     }
     packageApp(appId, options = {}) {
         const record = this.loadWorkflowAppById(appId);
-        const destination = node_path_1.default.resolve(String(options.output ||
-            node_path_1.default.join(process.cwd(), ".cw", "packages", `${record.app.id}-${record.app.version}.cwapp.json`)));
+        const destination = this.resolveFromBase(String(options.output || node_path_1.default.join(".cw", "packages", `${record.app.id}-${record.app.version}.cwapp.json`)));
         node_fs_1.default.mkdirSync(node_path_1.default.dirname(destination), { recursive: true });
         (0, state_1.writeJson)(destination, {
             schemaVersion: 1,
@@ -221,7 +220,7 @@ class CoolWorkflowRunner {
         if (!id)
             throw new Error("Workflow id must include at least one letter or digit");
         const title = String(options.title || titleize(id));
-        const destination = node_path_1.default.resolve(String(options.output || node_path_1.default.join(this.workflowsDir, `${id}.workflow.js`)));
+        const destination = this.resolveFromBase(String(options.output || node_path_1.default.join(this.workflowsDir, `${id}.workflow.js`)));
         if (node_fs_1.default.existsSync(destination) && !options.force) {
             throw new Error(`Refusing to overwrite existing workflow: ${destination}`);
         }
@@ -248,7 +247,7 @@ class CoolWorkflowRunner {
         return lifecycleOps.dispatch(this.loadRun(runId), options);
     }
     recordResult(runId, taskId, resultPath, options = {}) {
-        return lifecycleOps.recordResult(this.loadRun(runId), taskId, resultPath, options);
+        return lifecycleOps.recordResult(this.loadRun(runId), taskId, this.resolveFromBase(resultPath), options);
     }
     listWorkers(runId, options = {}) {
         return (0, worker_isolation_1.listWorkerScopes)(this.loadRun(runId), {
@@ -272,13 +271,13 @@ class CoolWorkflowRunner {
         return (0, worker_isolation_1.writeWorkerManifest)(run, worker);
     }
     recordWorkerOutput(runId, workerId, resultPath, options = {}) {
-        return lifecycleOps.recordWorkerOutput(this.loadRun(runId), workerId, resultPath, options);
+        return lifecycleOps.recordWorkerOutput(this.loadRun(runId), workerId, this.resolveFromBase(resultPath), options);
     }
     recordWorkerFailure(runId, workerId, message, options = {}) {
         return lifecycleOps.recordWorkerFailure(this.loadRun(runId), workerId, message, options);
     }
     validateWorker(runId, workerId, targetPath) {
-        return (0, worker_isolation_1.validateWorkerBoundary)(this.loadRun(runId), workerId, targetPath ? { path: targetPath } : {});
+        return (0, worker_isolation_1.validateWorkerBoundary)(this.loadRun(runId), workerId, targetPath ? { path: this.resolveFromBase(targetPath) } : {});
     }
     // Audit domain — delegated to ./orchestrator/audit-operations (v0.1.40 P3
     // router pattern). The runner stays the routing surface; the logic lives in the
@@ -314,13 +313,13 @@ class CoolWorkflowRunner {
         return auditOps.recordAuditDecision(this.loadRun(runId), workerId, options);
     }
     listSandboxProfiles(options = {}) {
-        return (0, sandbox_profile_1.listBundledSandboxProfiles)((0, sandbox_profile_1.sandboxContextForValidation)(String(options.cwd || process.cwd())));
+        return (0, sandbox_profile_1.listBundledSandboxProfiles)((0, sandbox_profile_1.sandboxContextForValidation)(String(options.cwd || this.invocationCwd())));
     }
     showSandboxProfile(profileId, options = {}) {
-        return (0, sandbox_profile_1.showBundledSandboxProfile)(profileId, (0, sandbox_profile_1.sandboxContextForValidation)(String(options.cwd || process.cwd())));
+        return (0, sandbox_profile_1.showBundledSandboxProfile)(profileId, (0, sandbox_profile_1.sandboxContextForValidation)(String(options.cwd || this.invocationCwd())));
     }
     validateSandboxProfile(profileFile, options = {}) {
-        return (0, sandbox_profile_1.validateSandboxProfileFile)(profileFile, (0, sandbox_profile_1.sandboxContextForValidation)(String(options.cwd || process.cwd())));
+        return (0, sandbox_profile_1.validateSandboxProfileFile)(this.resolveFromBase(profileFile), (0, sandbox_profile_1.sandboxContextForValidation)(String(options.cwd || this.invocationCwd())));
     }
     listBackends(options = {}) {
         void options;
@@ -331,7 +330,7 @@ class CoolWorkflowRunner {
         return (0, execution_backend_1.backendShowPayload)(backendId);
     }
     probeBackend(backendId, options = {}) {
-        return (0, execution_backend_1.backendProbePayload)(backendId, { cwd: String(options.cwd || process.cwd()) });
+        return (0, execution_backend_1.backendProbePayload)(backendId, { cwd: String(options.cwd || this.invocationCwd()) });
     }
     // Candidate domain — delegated to ./orchestrator/candidate-operations.
     listCandidates(runId, options = {}) {
@@ -716,6 +715,12 @@ class CoolWorkflowRunner {
     loadRun(runId) {
         return (0, state_1.loadRunFromCwd)(runId, this.baseDir);
     }
+    invocationCwd() {
+        return this.baseDir || process.cwd();
+    }
+    resolveFromBase(target) {
+        return node_path_1.default.resolve(this.invocationCwd(), target);
+    }
     loadWorkflowAppById(appId) {
         const record = this.loadWorkflowApps().find((candidate) => candidate.app.id === appId);
         if (!record)
@@ -725,7 +730,7 @@ class CoolWorkflowRunner {
     loadWorkflowAppTarget(target) {
         if (!target)
             throw new Error("Missing workflow app path or id");
-        const resolved = node_path_1.default.resolve(target);
+        const resolved = this.resolveFromBase(target);
         if (node_fs_1.default.existsSync(resolved)) {
             const stat = node_fs_1.default.statSync(resolved);
             if (stat.isDirectory())
@@ -821,9 +826,9 @@ function formatHelp() {
         "",
         "Commands:",
         "  list",
-        "  doctor [--json]   (check your setup: Node, agent backend, git, writable state)",
+        "  doctor [--json] [--onramp] [--changed-from REF]   (check setup and show the shortest safe next steps)",
         "  init <workflow-id> [--title TEXT] [--output PATH]",
-        "  quickstart [app-id] [--repo PATH] [--question TEXT] [--agent-command CMD] [--once] [--preview]",
+        "  quickstart [app-id] [--repo PATH] [--question TEXT] [--agent-command CMD] [--check] [--once] [--preview]",
         "  plan <workflow-id> [--repo PATH] [--question TEXT] [--invariant TEXT]",
         "  status <run-id> [--json|--format json]",
         "  next <run-id> [--limit N]",

package/dist/version.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MIN_SUPPORTED_RUN_STATE_SCHEMA_VERSION = exports.LEGACY_RUN_STATE_SCHEMA_VERSION = exports.CURRENT_RUN_STATE_SCHEMA_VERSION = exports.WORKFLOW_APP_SCHEMA_VERSION = exports.CURRENT_COOL_WORKFLOW_VERSION = void 0;
-exports.CURRENT_COOL_WORKFLOW_VERSION = "0.1.85";
+exports.CURRENT_COOL_WORKFLOW_VERSION = "0.1.86";
 exports.WORKFLOW_APP_SCHEMA_VERSION = 1;
 exports.CURRENT_RUN_STATE_SCHEMA_VERSION = 1;
 exports.LEGACY_RUN_STATE_SCHEMA_VERSION = 0;

package/dist/workbench-host.js

@@ -99,14 +99,7 @@ class WorkbenchHost {
             }
             const runMatch = /^\/api\/run\/([^/]+)$/.exec(route);
             if (runMatch) {
-                const previousCwd = process.cwd();
-                process.chdir(this.cwd);
-                try {
-                    return this.send(res, 200, (0, workbench_1.buildWorkbenchRunView)(this.runner, runMatch[1]));
-                }
-                finally {
-                    process.chdir(previousCwd);
-                }
+                return this.send(res, 200, (0, workbench_1.buildWorkbenchRunView)(this.runner.withBaseDir(this.cwd), runMatch[1]));
             }
             this.send(res, 404, { error: `no such read-only view: ${route}` });
         }

package/docs/agent-delegation-drive.7.md

@@ -128,6 +128,7 @@ node dist/cli.js backend agent config            # show the effective config (se
 node dist/cli.js backend probe agent --json      # ready iff configured, else unverified
 
 # drive a real repo end-to-end (zero hand-written result.md)
+node dist/cli.js quickstart architecture-review --check --repo /path/to/repo --question "Is the design sound?" --agent-command "node $(pwd)/scripts/agents/claude-p-agent.js {{input}} {{result}}"
 node dist/cli.js run architecture-review --drive --repo /path/to/repo --question "Is the design sound?"
 node dist/cli.js run architecture-review --drive --once --repo /path/to/repo --question "..."   # one step
 node dist/cli.js run drive <run-id> --json       # read-only preview of the next step
@@ -135,12 +136,22 @@ node dist/cli.js run drive <run-id> --json       # read-only preview of the next
 # quickstart --resume: a guided stop-then-resume a newcomer can WITNESS in <5 min
 node dist/cli.js quickstart --resume --repo /path/to/repo --question "..."   # advances ONE step, prints a continue line
 node dist/cli.js quickstart --run <run-id> --resume                          # continues that run to completion
+node dist/cli.js quickstart --run <run-id> --resume --bundle                  # continues, then seals a completed run
 ```
 
+`quickstart --check` is a zero-write preflight. It does not make a run, write
+`.cw/`, call the agent, write a report, or commit. It checks the app id, repo,
+question, agent config, and (with `--bundle`) the trust-key shape, then gives the
+next command to run. A blocked check exits non-zero, so scripts may use it as a
+gate before a real run.
+
 `quickstart --resume` with no `--run` drives a single step and prints a
 copy-pasteable `cw quickstart --run <id> --resume` continue line; run it again with
 the `--run <id>` to finish. The continuing invocation echoes `resumedFrom: <id>`.
 Bare `quickstart` (no `--resume`) is unchanged — it drives straight to the end.
+When `--bundle` is present on the fresh resume step, no bundle is sealed until
+the run is complete; the continue line keeps `--bundle` so the second command
+finishes and seals the report.
 
 For faster first results, use the opt-in fast app in place of changing the full
 review contract:
@@ -171,9 +182,15 @@ an Assess cache hit. A cache hit still goes through `recordWorkerOutput`
 validation; a corrupt cached result parks/fails closed rather than spawning a
 quiet fallback.
 
+Verify and Verdict also get the source-context instruction so they do not have to
+start by scanning the repo again. They are not result-cached; they still have to
+cite evidence and make the final check from the accepted Map and Assess work.
+
 `--metrics` is diagnostic and opt-in. It adds elapsed milliseconds, step counts,
-agent-spawn counts, and `result-cache` hit counts to the wrapper JSON payload;
-without it, the wrapper's default output shape stays unchanged.
+agent-spawn counts, `result-cache` hit counts, source-context bytes/digest, and
+one row per driven task with phase, task id, elapsed time, and spawn/cache state
+to the wrapper JSON payload; without it, the wrapper's default output shape stays
+unchanged.
 
 `{{manifest}}`, `{{input}}`, `{{result}}`, `{{workerDir}}`, `{{model}}`, and
 `{{prompt}}` are put into DISCRETE argv elements (never a shell-interpreted
@@ -272,3 +289,5 @@ Loaders fail closed on corrupt state; store writes are made safe under more than
 No other change to this page in v0.1.84.
 
 0.1.85
+
+0.1.86