@tomflow/proflow-platform-cli 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @tomflow/proflow-platform-cli
 
+## 0.1.4
+
+### Patch Changes
+
+- Make upgrade planning emit configuration writes only when a real config target exists, and fail before package mutation when new required configuration is missing.
+
+## 0.1.3
+
+### Patch Changes
+
+- Real-1 final remediation and black-box release closure
+
 ## 0.1.2
 
 ### Patch Changes

package/dist/deployment/adapter.d.ts

@@ -5,7 +5,7 @@ export declare const behaviorAdapter: {
             ok: boolean;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.2";
+            moduleVersion: "0.1.4";
             data?: {} | null;
         };
         observedEffects: never[];
@@ -16,7 +16,7 @@ export declare const behaviorAdapter: {
             ok: boolean;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.2";
+            moduleVersion: "0.1.4";
             data?: {} | null;
         };
         observedEffects: never[];
@@ -27,7 +27,7 @@ export declare const behaviorAdapter: {
             ok: boolean;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.2";
+            moduleVersion: "0.1.4";
             data?: {} | null;
         };
         observedEffects: never[];
@@ -38,7 +38,7 @@ export declare const behaviorAdapter: {
             ok: boolean;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.2";
+            moduleVersion: "0.1.4";
             data?: {} | null;
         };
         observedEffects: never[];
@@ -49,7 +49,7 @@ export declare const behaviorAdapter: {
             ok: boolean;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.2";
+            moduleVersion: "0.1.4";
             data?: {} | null;
         };
         observedEffects: never[];

package/dist/deployment/descriptor.d.ts

@@ -3,7 +3,7 @@ export declare const descriptor: {
     readonly contractVersion: "1.0.0";
     readonly moduleRef: "platform-cli";
     readonly packageName: "@tomflow/proflow-platform-cli";
-    readonly moduleVersion: "0.1.2";
+    readonly moduleVersion: "0.1.4";
     readonly kind: "cli";
     readonly templateVersion: "1.0.0";
     readonly platformCompatibility: ">=1.0.0 <2.0.0";

package/dist/deployment/descriptor.js

@@ -3,7 +3,7 @@ export const descriptor = {
     contractVersion: "1.0.0",
     moduleRef: "platform-cli",
     packageName: "@tomflow/proflow-platform-cli",
-    moduleVersion: "0.1.2",
+    moduleVersion: "0.1.4",
     kind: "cli",
     templateVersion: "1.0.0",
     platformCompatibility: ">=1.0.0 <2.0.0",

package/dist/src/apply/apply.d.ts

@@ -12,6 +12,8 @@ export interface ApplyContext {
     current: PlanInput;
     driver: PackageManagerDriver;
     observer?: RealityObserver;
+    /** Rebuilds installed descriptors/bindings after a package mutation. */
+    refreshCatalog?: () => Promise<ModuleCatalog>;
 }
 /**
  * Applies a frozen deployment plan deterministically. Every step is re-checked

package/dist/src/apply/apply.js

@@ -1,7 +1,7 @@
 import { PlatformError } from "../errors.js";
 import { ensureLayout } from "../paths.js";
 import { emptyDeploymentState, loadDeploymentState, loadPlan, saveDeploymentState, } from "../persistence/index.js";
-import { checkPlanStale, evaluateStepCheck, } from "../planner/index.js";
+import { checkPlanStale, ExecuteStrategy, evaluateStepCheck, } from "../planner/index.js";
 import { acquireWorkspaceLock } from "../security/index.js";
 import { executeStep } from "./execute.js";
 import { createRealityObserver } from "./reality.js";
@@ -21,10 +21,11 @@ function failureMessage(error) {
  */
 export async function applyPlan(context) {
     const driver = context.driver;
-    const observer = context.observer ??
+    let catalog = context.catalog;
+    let observer = context.observer ??
         createRealityObserver({
             paths: context.paths,
-            catalog: context.catalog,
+            catalog,
             driver,
         });
     await ensureLayout(context.paths);
@@ -105,7 +106,7 @@ export async function applyPlan(context) {
             }
             let outcome;
             try {
-                outcome = await executeStep({ paths: context.paths, catalog: context.catalog, driver }, step, plan);
+                outcome = await executeStep({ paths: context.paths, catalog, driver }, step, plan);
             }
             catch (error) {
                 stepResults.push({
@@ -125,6 +126,20 @@ export async function applyPlan(context) {
             }
             switch (outcome.kind) {
                 case "SUCCEEDED": {
+                    if (step.executeStrategy === ExecuteStrategy.lifecycleUninstall) {
+                        // A lifecycle uninstall is owned by the module adapter. Its typed
+                        // SUCCEEDED result is the authoritative teardown confirmation. An
+                        // idempotent uninstall can legitimately leave status UNBOUND/UNKNOWN,
+                        // so a second status probe must not reinterpret that successful
+                        // teardown as a failed lifecycle:stopped postcondition.
+                        stepResults.push({
+                            stepRef: step.stepRef,
+                            moduleRef: step.moduleRef,
+                            status: "EXECUTED",
+                            message: `${step.moduleRef} owner confirmed lifecycle uninstall`,
+                        });
+                        break;
+                    }
                     // Postcondition re-check: only a genuinely successful mutation is
                     // confirmed; an effect that cannot be confirmed stops the apply
                     // rather than blindly repeating it.
@@ -168,6 +183,34 @@ export async function applyPlan(context) {
                         status: "EXECUTED",
                         message: post.reason,
                     });
+                    if (step.kind === "package" && context.refreshCatalog !== undefined) {
+                        try {
+                            catalog = await context.refreshCatalog();
+                            if (context.observer === undefined) {
+                                observer = createRealityObserver({
+                                    paths: context.paths,
+                                    catalog,
+                                    driver,
+                                });
+                            }
+                        }
+                        catch (error) {
+                            stepResults.push({
+                                stepRef: step.stepRef,
+                                moduleRef: step.moduleRef,
+                                status: "FAILED",
+                                message: `post-package catalog refresh failed: ${failureMessage(error)}`,
+                            });
+                            state.updatedAt = nowIso();
+                            await saveDeploymentState(context.paths, state);
+                            return {
+                                planRef: plan.planRef,
+                                outcome: "FAILED",
+                                stepResults,
+                                completedAt: nowIso(),
+                            };
+                        }
+                    }
                     break;
                 }
                 case "ACTION_REQUIRED": {

package/dist/src/apply/current.js

@@ -65,6 +65,20 @@ export async function rebuildCurrentAssumptions(catalog, plan) {
             facts: diagnosis.facts,
         };
     }
+    if (plan.intent === "uninstall") {
+        // A persisted uninstall plan does not store uninstallScope. Recover the only
+        // legal scope from its module set for the staleness re-plan: any core module
+        // can only have entered the plan through whole-instance uninstall.
+        const uninstallScope = plan.resolvedModules.some((module) => module.installClass === "core")
+            ? "platform-instance"
+            : "module";
+        return {
+            intent: plan.intent,
+            modules,
+            targets: plan.moduleTargets,
+            uninstallScope,
+        };
+    }
     return {
         intent: plan.intent,
         modules,

package/dist/src/apply/execute.js

@@ -6,6 +6,29 @@ import { cleanupRemovableFilesystemEffects } from "./cleanup.js";
 function moduleOf(plan, step) {
     return plan.resolvedModules.find((module) => module.moduleRef === step.moduleRef);
 }
+function moduleSourceForMaterialization(module) {
+    if (module.source.type === "registry") {
+        throw new PlatformError("APPLY_FAILED", `registry bootstrap target ${module.packageName} has no local config materializer`);
+    }
+    return {
+        type: module.source.type,
+        packageName: module.packageName,
+        ...(module.source.path === undefined ? {} : { path: module.source.path }),
+    };
+}
+async function materializeModuleOwnedConfig(deps, module, config) {
+    const namespace = await deps.catalog.loadAdapter(moduleSourceForMaterialization(module));
+    if (typeof namespace !== "object" || namespace === null)
+        return;
+    const materializer = Reflect.get(namespace, "materializeProductionConfig");
+    if (typeof materializer !== "function")
+        return;
+    await materializer({
+        moduleRef: module.moduleRef,
+        config: config.values,
+        workspaceRoot: deps.paths.root,
+    });
+}
 function configForStep(plan, step, module) {
     const target = plan.moduleTargets.find((entry) => entry.moduleRef === step.moduleRef);
     if (target?.config === undefined)
@@ -98,6 +121,11 @@ export async function executeStep(deps, step, plan) {
             if (config === undefined) {
                 throw new PlatformError("APPLY_FAILED", `module ${step.moduleRef} has no config target to materialize`);
             }
+            // The Platform-owned public config is authoritative apply reality. Do not
+            // commit it until the module-owned materializer has accepted the target;
+            // otherwise a failed materializer can leave a false-satisfied config step
+            // that a same-plan resume would incorrectly SKIP.
+            await materializeModuleOwnedConfig(deps, module, config);
             await materializeConfig(deps.paths, config);
             return { kind: "SUCCEEDED" };
         }

package/dist/src/binding/production-bindings.d.ts

@@ -2,6 +2,7 @@ import type { ResolvedModule } from "../contracts.ts";
 type ResolvedSource = ResolvedModule["source"];
 export interface DeploymentAdapterBinding {
     behaviorAdapter: Record<string, unknown>;
+    materializeProductionConfig?: (...args: unknown[]) => unknown;
 }
 export type ProductionBindingFactory = (input: {
     moduleRef: string;
@@ -30,16 +31,5 @@ export interface ProductionBindingOptions {
     importAdapter: (packageName: string, source: ResolvedSource) => Promise<Record<string, unknown>>;
 }
 export declare function importRawAdapter(packageName: string, source: ResolvedSource, workspaceRoot: string): Promise<Record<string, unknown>>;
-/**
- * The shipped Platform CLI production binding factory. For every discovered
- * module it imports the module's own `deployment/adapter.ts` and, when that
- * adapter exposes a `createProductionBinding` factory, invokes it with the
- * module's materialized config to obtain a real bound adapter. A module without
- * a production factory — or whose import/factory fails, or which has no
- * materialized config the adapter accepts — is left out of the map, so the
- * catalog falls back to the module's unbound default, which must fail-closed
- * (ACTION_REQUIRED / NOT_READY). Platform CLI never invents a service or
- * resource reality: it only relays the adapter's own current reality.
- */
 export declare function buildProductionBindings(options: ProductionBindingOptions): Promise<ReadonlyMap<string, DeploymentAdapterBinding>>;
 export {};

package/dist/src/binding/production-bindings.js

@@ -45,6 +45,14 @@ export async function importRawAdapter(packageName, source, workspaceRoot) {
  * (ACTION_REQUIRED / NOT_READY). Platform CLI never invents a service or
  * resource reality: it only relays the adapter's own current reality.
  */
+function materializerBinding(namespace) {
+    const materializer = namespace.materializeProductionConfig;
+    return typeof materializer === "function"
+        ? {
+            materializeProductionConfig: materializer,
+        }
+        : {};
+}
 export async function buildProductionBindings(options) {
     const bindings = new Map();
     for (const module of options.modules) {
@@ -69,6 +77,7 @@ export async function buildProductionBindings(options) {
                             : {});
                     bindings.set(module.packageName, {
                         behaviorAdapter: managedServiceAdapter(options.workspaceRoot, module, processBinding.serviceProcess, probeAdapter),
+                        ...materializerBinding(namespace),
                     });
                 }
                 // A formal service package that exposes the process seam must never fall
@@ -92,7 +101,10 @@ export async function buildProductionBindings(options) {
                 binding !== null &&
                 typeof binding.behaviorAdapter === "object" &&
                 binding.behaviorAdapter !== null) {
-                bindings.set(module.packageName, binding);
+                bindings.set(module.packageName, {
+                    ...binding,
+                    ...materializerBinding(namespace),
+                });
             }
         }
         catch {

package/dist/src/cli.d.ts

@@ -20,4 +20,5 @@ export interface CliRuntimeOptions {
     cwd?: string;
     globalRoot?: string;
 }
+export declare function renderHumanResult(machineOutput: string): string;
 export declare function runCli(argv: readonly string[], runtime?: CliRuntimeOptions): Promise<string>;

package/dist/src/cli.js

@@ -86,7 +86,7 @@ function parseArgs(argv) {
 }
 function requiredOptionValue(argv, index, option) {
     const value = argv[index + 1];
-    if (value === undefined || value.startsWith("-")) {
+    if (value === undefined || value === "" || value.startsWith("-")) {
         throw new PlatformError("INVALID_REQUEST", `${option} requires a value`);
     }
     return value;
@@ -309,14 +309,41 @@ async function handleInstallerPreflight(root) {
             : "BLOCKED";
     return outcome("preflight", status, result);
 }
+async function loadEffectiveConfig(ctx, modules, configFile) {
+    const effective = {};
+    for (const module of modules) {
+        const stored = await loadConfig(ctx.paths, module.moduleRef);
+        if (stored === undefined)
+            continue;
+        effective[module.moduleRef] = {
+            ...stored.publicValues,
+            ...stored.secretValues,
+        };
+    }
+    const provided = await loadConfigFile(configFile);
+    for (const [moduleRef, values] of Object.entries(provided)) {
+        effective[moduleRef] = {
+            ...(effective[moduleRef] ?? {}),
+            ...values,
+        };
+    }
+    return effective;
+}
 async function handlePreflight(ctx, args) {
     const modules = await discoverModules({ catalog: ctx.catalog });
     const selected = selectModules(modules, args.positional[0]);
-    const config = await loadConfigFile(args.configFile);
-    const result = await runPreflight(selected, { config, catalog: ctx.catalog });
-    return result.ok
-        ? outcome("preflight", "SUCCEEDED", result)
-        : outcome("preflight", "BLOCKED", result);
+    const config = await loadEffectiveConfig(ctx, selected, args.configFile);
+    const result = await runPreflight(selected, {
+        config,
+        catalog: ctx.catalog,
+        paths: ctx.paths,
+    });
+    const status = result.status === "READY"
+        ? "SUCCEEDED"
+        : result.status === "ACTION_REQUIRED"
+            ? "ACTION_REQUIRED"
+            : "BLOCKED";
+    return outcome("preflight", status, result);
 }
 async function handlePlan(ctx, args) {
     const intent = args.intent;
@@ -423,6 +450,7 @@ async function handlePlan(ctx, args) {
             currentDescriptors,
             targetDescriptors,
             targets,
+            config,
         });
         await savePlan(ctx.paths, plan);
         return outcome("plan", "SUCCEEDED", {
@@ -431,9 +459,15 @@ async function handlePlan(ctx, args) {
             plan,
         });
     }
+    if (intent === "configure") {
+        const plan = planDeployment({ intent, modules: selected, config });
+        await savePlan(ctx.paths, plan);
+        return outcome("plan", "SUCCEEDED", { planRef: plan.planRef, plan });
+    }
     const preflight = await runPreflight(selected, {
         config,
         catalog: ctx.catalog,
+        paths: ctx.paths,
     });
     if (preflight.status === "NOT_READY" ||
         preflight.status === "ACTION_REQUIRED") {
@@ -472,6 +506,11 @@ async function handleApply(ctx, args) {
         driver: createWorkspacePackageManagerDriver({
             workspaceRoot: ctx.paths.root,
         }),
+        ...(plan.intent === "upgrade"
+            ? {
+                refreshCatalog: async () => (await buildContext(ctx.paths.root)).catalog,
+            }
+            : {}),
     });
     const status = result.outcome === "COMPLETE"
         ? "SUCCEEDED"
@@ -499,6 +538,23 @@ async function handleManagedMutation(ctx, args, intent) {
     if (planned.status !== "SUCCEEDED") {
         return { ...planned, command: intent };
     }
+    if (intent === "upgrade") {
+        const data = planned.data;
+        if (typeof data === "object" && data !== null && !Array.isArray(data)) {
+            const plan = Reflect.get(data, "plan");
+            if (typeof plan === "object" &&
+                plan !== null &&
+                !Array.isArray(plan) &&
+                Array.isArray(Reflect.get(plan, "steps")) &&
+                Reflect.get(plan, "steps").length === 0) {
+                return outcome("upgrade", "SUCCEEDED", {
+                    ...data,
+                    alreadyLatest: true,
+                    changed: false,
+                });
+            }
+        }
+    }
     const planRef = planRefFromOutcome(planned);
     const applied = await handleApply(ctx, {
         ...args,
@@ -639,23 +695,37 @@ async function handleInstallWithGlobalBinding(args, runtime) {
     const operationLock = await acquireGlobalOperationLock(runtime.globalRoot);
     try {
         const requestedWorkspace = await resolveRequestedInstallWorkspace(args, runtime);
-        const claimed = await claimWorkspaceBinding({
-            workspace: requestedWorkspace,
-            globalRoot: runtime.globalRoot,
-        });
-        const initialBinding = claimed.binding;
-        if (claimed.alreadyBound &&
-            initialBinding.state === "INSTALLED" &&
-            args.positional[0] === undefined) {
+        const existing = await loadGlobalBinding(runtime.globalRoot);
+        if (existing !== undefined &&
+            existing.workspaceRealPath !== requestedWorkspace) {
+            throw new PlatformError("WORKSPACE_ALREADY_BOUND", `ProFlow is already bound to ${existing.workspaceRealPath}; uninstall it before installing ${requestedWorkspace}`);
+        }
+        if (existing?.state === "INSTALLED" && args.positional[0] === undefined) {
             return withWorkspace(outcome("install", "SUCCEEDED", {
                 alreadyInstalled: true,
                 changed: false,
-                boundWorkspace: initialBinding.workspaceRealPath,
-            }), initialBinding);
+                boundWorkspace: existing.workspaceRealPath,
+            }), existing);
         }
-        if (initialBinding.state === "UNINSTALLING") {
+        if (existing?.state === "UNINSTALLING") {
             throw new PlatformError("GLOBAL_OPERATION_LOCKED", "the bound Platform Instance is marked UNINSTALLING; finish recovery before installing");
         }
+        // Gate A runs before claiming a fresh global binding. Deterministic local
+        // failures (package-manager conflict, missing executable, registry down,
+        // unwritable Workspace) therefore do not leave a fake BROKEN installation.
+        // The global operation lock keeps this preflight + claim sequence atomic
+        // against other Platform mutations.
+        const installer = await preflightInstallerEnvironment({
+            workspaceRoot: requestedWorkspace,
+        });
+        if (installer.status !== "READY") {
+            return outcome("install", installer.status === "ACTION_REQUIRED" ? "ACTION_REQUIRED" : "BLOCKED", { requestedWorkspace, preflight: installer });
+        }
+        const claimed = await claimWorkspaceBinding({
+            workspace: requestedWorkspace,
+            globalRoot: runtime.globalRoot,
+        });
+        const initialBinding = claimed.binding;
         let activeBinding = initialBinding;
         const controlsPlatformState = !claimed.alreadyBound || initialBinding.state !== "INSTALLED";
         if (controlsPlatformState && initialBinding.state !== "INSTALLING") {
@@ -889,7 +959,7 @@ async function handleDoctor(ctx, args) {
 async function handleManifest(ctx, args) {
     const modules = await discoverModules({ catalog: ctx.catalog });
     const selected = selectModules(modules, args.positional[0]);
-    const config = await loadConfigFile(args.configFile);
+    const config = await loadEffectiveConfig(ctx, selected, args.configFile);
     const manifest = await buildManifest({
         catalog: ctx.catalog,
         modules: selected,
@@ -1096,7 +1166,125 @@ function toMachineResult(outcomeResult) {
             : {}),
     });
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function humanDetailLines(data) {
+    if (!isRecord(data)) {
+        return data === undefined ? [] : [String(data)];
+    }
+    const lines = [];
+    for (const key of [
+        "installed",
+        "bindingState",
+        "boundWorkspace",
+        "requestedWorkspace",
+        "alreadyInstalled",
+        "alreadyLatest",
+        "changed",
+        "bindingCleared",
+        "resourcesCleaned",
+        "planRef",
+        "outcome",
+    ]) {
+        const value = data[key];
+        if (typeof value === "string" ||
+            typeof value === "number" ||
+            typeof value === "boolean") {
+            lines.push(`${key}: ${String(value)}`);
+        }
+    }
+    if (typeof data.nextAction === "string" && data.nextAction !== "") {
+        lines.push(`Next: ${data.nextAction}`);
+    }
+    const findings = data.findings;
+    let hasMissingConfig = false;
+    if (Array.isArray(findings) && findings.length > 0) {
+        lines.push("Findings:");
+        for (const finding of findings) {
+            if (!isRecord(finding))
+                continue;
+            const severity = typeof finding.severity === "string"
+                ? finding.severity.toUpperCase()
+                : "INFO";
+            const code = typeof finding.code === "string" ? finding.code : "CHECK";
+            if (code === "CONFIG_MISSING")
+                hasMissingConfig = true;
+            const moduleRef = typeof finding.moduleRef === "string" ? ` ${finding.moduleRef}` : "";
+            const message = typeof finding.message === "string" ? finding.message : "";
+            lines.push(`- [${severity}] ${code}${moduleRef}${message === "" ? "" : `: ${message}`}`);
+        }
+    }
+    if (hasMissingConfig) {
+        lines.push("Next: review .proflow/deployment/generated/INSTALL.md, create the required config file, then run platform plan --intent configure --config <file> and platform apply <planRef>.");
+    }
+    const preflight = data.preflight;
+    if (isRecord(preflight)) {
+        const nested = humanDetailLines(preflight);
+        if (nested.length > 0) {
+            lines.push("Preflight:", ...nested.map((line) => `  ${line}`));
+        }
+    }
+    return lines;
+}
+export function renderHumanResult(machineOutput) {
+    const parsed = JSON.parse(machineOutput);
+    if (!isRecord(parsed))
+        return machineOutput;
+    const data = parsed.data;
+    if (isRecord(data) && typeof data.version === "string") {
+        return `ProFlow Platform CLI ${data.version}`;
+    }
+    if (isRecord(data) && typeof data.usage === "string") {
+        const commands = Array.isArray(data.commands)
+            ? data.commands.filter((item) => typeof item === "string")
+            : [];
+        const examples = Array.isArray(data.examples)
+            ? data.examples.filter((item) => typeof item === "string")
+            : [];
+        return [
+            "ProFlow Platform CLI",
+            "",
+            `Usage: ${data.usage}`,
+            ...(commands.length === 0
+                ? []
+                : ["", `Commands: ${commands.join(", ")}`]),
+            ...(examples.length === 0
+                ? []
+                : ["", "Common flows:", ...examples.map((item) => `  ${item}`)]),
+        ].join("\n");
+    }
+    const status = typeof parsed.status === "string" ? parsed.status : "UNKNOWN";
+    const lines = [`ProFlow: ${status}`];
+    const workspace = parsed.workspace;
+    if (isRecord(workspace) && typeof workspace.boundWorkspace === "string") {
+        lines.push(`Workspace: ${workspace.boundWorkspace}`);
+    }
+    const error = parsed.error;
+    if (isRecord(error)) {
+        const code = typeof error.code === "string" ? error.code : "COMMAND_FAILED";
+        const message = typeof error.message === "string" ? error.message : "Unknown error";
+        lines.push(`Error: ${code}: ${message}`);
+    }
+    lines.push(...humanDetailLines(data));
+    if (lines.length === 1 && status === "SUCCEEDED") {
+        lines.push(`Version: ${MODULE_VERSION}`, "Next: run platform --help");
+    }
+    return lines.join("\n");
+}
 export async function runCli(argv, runtime = {}) {
+    const filtered = argv.filter((argument) => argument !== "--json");
+    if (filtered.length === 1 &&
+        (filtered[0] === "--version" || filtered[0] === "-v")) {
+        return JSON.stringify({
+            contract: "deployment.result.v1",
+            ok: true,
+            status: "SUCCEEDED",
+            moduleRef: MODULE_REF,
+            moduleVersion: MODULE_VERSION,
+            data: { version: MODULE_VERSION },
+        });
+    }
     if (argv.includes("--help") || argv.includes("-h")) {
         return JSON.stringify({
             contract: "deployment.result.v1",
@@ -1107,10 +1295,19 @@ export async function runCli(argv, runtime = {}) {
             data: {
                 usage: "platform <command> [module|package] [--workspace <path>] [--json]",
                 commands: [...COMMANDS],
+                examples: [
+                    "platform preflight --intent install --workspace <path>",
+                    "platform install [module|package] [--workspace <path>]",
+                    "platform preflight  # startup/runtime readiness for the bound Workspace",
+                    "platform plan --intent configure --config <file>",
+                    "platform apply <planRef>",
+                    "platform start | status | verify | doctor | stop | restart",
+                    "platform uninstall  # uninstall the bound Platform Instance, not the global CLI",
+                    "append --json for the stable machine-readable contract",
+                ],
             },
         });
     }
-    const filtered = argv.filter((argument) => argument !== "--json");
     if (filtered.length === 0) {
         return JSON.stringify({
             contract: "deployment.result.v1",
@@ -1123,8 +1320,10 @@ export async function runCli(argv, runtime = {}) {
     return toMachineResult(await dispatchCommand(filtered, runtime));
 }
 if (import.meta.main) {
-    const output = await runCli(process.argv.slice(2));
-    process.stdout.write(`${output}\n`);
+    const argv = process.argv.slice(2);
+    const output = await runCli(argv);
+    const rendered = argv.includes("--json") ? output : renderHumanResult(output);
+    process.stdout.write(`${rendered}\n`);
     const parsed = JSON.parse(output);
     if (typeof parsed === "object" &&
         parsed !== null &&

package/dist/src/errors.d.ts

@@ -1,4 +1,4 @@
-export declare const platformErrorCodes: readonly ["INVALID_REQUEST", "DESCRIPTOR_INVALID", "DUPLICATE_IDENTITY", "DEPENDENCY_UNRESOLVED", "DEPENDENCY_INCOMPATIBLE", "DEPENDENCY_CYCLE", "CONFIG_MISSING", "SECRET_REF_INVALID", "PLAN_STALE", "PLAN_NOT_FOUND", "PLAN_INVALID", "WORKSPACE_LOCKED", "WORKSPACE_NOT_FOUND", "WORKSPACE_NOT_WRITABLE", "WORKSPACE_NOT_BOUND", "WORKSPACE_ALREADY_BOUND", "BOUND_WORKSPACE_MISSING", "WORKSPACE_INSTANCE_INVALID", "GLOBAL_BINDING_INVALID", "GLOBAL_BINDING_LOCKED", "GLOBAL_OPERATION_LOCKED", "PACKAGE_MANAGER_UNSUPPORTED", "PACKAGE_MANAGER_CONFLICT", "PACKAGE_MANAGER_UNAVAILABLE", "LIFECYCLE_UNSUPPORTED", "SECRET_LEAK", "APPLY_FAILED", "UPGRADE_FAILED", "CORE_PACKAGE_REQUIRED", "UNINSTALL_FAILED", "VERIFY_FAILED", "REGISTRY_UNAVAILABLE", "REGISTRY_AUTH_REQUIRED", "REGISTRY_RESPONSE_INVALID", "PACKAGE_NOT_FOUND", "PACKAGE_NOT_PROFLOW", "COMMAND_FAILED"];
+export declare const platformErrorCodes: readonly ["INVALID_REQUEST", "DESCRIPTOR_INVALID", "DUPLICATE_IDENTITY", "DEPENDENCY_UNRESOLVED", "DEPENDENCY_INCOMPATIBLE", "DEPENDENCY_CYCLE", "CONFIG_MISSING", "CONFIG_INVALID", "SECRET_REF_INVALID", "PLAN_STALE", "PLAN_NOT_FOUND", "PLAN_INVALID", "WORKSPACE_LOCKED", "WORKSPACE_NOT_FOUND", "WORKSPACE_NOT_WRITABLE", "WORKSPACE_NOT_BOUND", "WORKSPACE_ALREADY_BOUND", "BOUND_WORKSPACE_MISSING", "WORKSPACE_INSTANCE_INVALID", "GLOBAL_BINDING_INVALID", "GLOBAL_BINDING_LOCKED", "GLOBAL_OPERATION_LOCKED", "PACKAGE_MANAGER_UNSUPPORTED", "PACKAGE_MANAGER_CONFLICT", "PACKAGE_MANAGER_UNAVAILABLE", "LIFECYCLE_UNSUPPORTED", "SECRET_LEAK", "APPLY_FAILED", "UPGRADE_FAILED", "CORE_PACKAGE_REQUIRED", "UNINSTALL_FAILED", "VERIFY_FAILED", "REGISTRY_UNAVAILABLE", "REGISTRY_AUTH_REQUIRED", "REGISTRY_RESPONSE_INVALID", "PACKAGE_NOT_FOUND", "PACKAGE_NOT_PROFLOW", "COMMAND_FAILED"];
 export type PlatformErrorCode = (typeof platformErrorCodes)[number];
 export declare class PlatformError extends Error {
     readonly code: PlatformErrorCode;

package/dist/src/errors.js

@@ -6,6 +6,7 @@ export const platformErrorCodes = [
     "DEPENDENCY_INCOMPATIBLE",
     "DEPENDENCY_CYCLE",
     "CONFIG_MISSING",
+    "CONFIG_INVALID",
     "SECRET_REF_INVALID",
     "PLAN_STALE",
     "PLAN_NOT_FOUND",

package/dist/src/install/environment.js

@@ -102,7 +102,7 @@ export async function preflightInstallerEnvironment(options) {
     if (npmVersion !== undefined) {
         try {
             registry = await resolveScopeRegistry(options.workspaceRoot, runner);
-            await runner.run(["ping", "--json", "--prefer-online", `--registry=${registry}`], options.workspaceRoot);
+            await runner.run(["ping", "--json", "--prefer-online", `--registry=${registry}`], options.workspaceRoot, 10_000);
             findings.push({
                 code: "REGISTRY_READY",
                 severity: "info",

package/dist/src/install/install.js

@@ -111,6 +111,47 @@ export function renderInstallDoc(input) {
         }
         lines.push("");
     }
+    const missingRequiredConfig = {};
+    for (const module of modules) {
+        const resolved = resolveModuleConfig(module, input.config?.[module.moduleRef]);
+        for (const slot of module.configSlots) {
+            if (!slot.required || resolved.values[slot.key] !== undefined)
+                continue;
+            const placeholder = slot.type === "secretRef"
+                ? "secret://provider/name"
+                : slot.type === "url"
+                    ? "https://example.invalid"
+                    : slot.type === "path"
+                        ? "/absolute/path"
+                        : slot.type === "moduleRef"
+                            ? "module-ref"
+                            : "<value>";
+            const moduleConfig = missingRequiredConfig[module.moduleRef] ?? {};
+            moduleConfig[slot.key] = placeholder;
+            missingRequiredConfig[module.moduleRef] = moduleConfig;
+        }
+    }
+    lines.push("## Configure Before Start");
+    lines.push("");
+    if (Object.keys(missingRequiredConfig).length === 0) {
+        lines.push("No required configuration is currently missing. Re-run `platform preflight --intent start` before starting to confirm current runtime readiness.");
+    }
+    else {
+        lines.push("Create a JSON config file (for example `./proflow-config.json`) using the required missing slots below. Replace placeholders with real environment-specific values. `secretRef` values must remain opaque references such as `secret://provider/name`; do not place raw secrets in this file.");
+        lines.push("");
+        lines.push("```json");
+        lines.push(JSON.stringify({ modules: missingRequiredConfig }, null, 2));
+        lines.push("```");
+        lines.push("");
+        lines.push("Apply and re-check the configuration:");
+        lines.push("");
+        lines.push("1. `platform plan --intent configure --config ./proflow-config.json`");
+        lines.push("2. Copy the returned `planRef`.");
+        lines.push("3. `platform apply <planRef>`");
+        lines.push("4. `platform preflight --intent start`");
+        lines.push("5. Resolve any remaining human or external-resource actions reported by preflight, then run the same preflight command again until the Platform reports the expected readiness state.");
+    }
+    lines.push("");
     lines.push("## Verification Plan");
     lines.push("");
     for (const module of modules) {

package/dist/src/lifecycle/dispatch.js

@@ -110,7 +110,58 @@ async function runInOrder(catalog, modules, order, primitive) {
  * `start` primitive only to modules that declare it.
  */
 export async function startModules(catalog, modules) {
-    return runInOrder(catalog, modules, buildDependencyGraph(modules).order, "start");
+    const graph = buildDependencyGraph(modules);
+    const byRef = new Map(modules.map((module) => [module.moduleRef, module]));
+    const resultByRef = new Map();
+    const results = [];
+    for (const moduleRef of graph.order) {
+        const module = byRef.get(moduleRef);
+        if (module === undefined)
+            continue;
+        if (!module.lifecycle.includes("start")) {
+            const skipped = await runOne(catalog, module, "start");
+            results.push(skipped);
+            resultByRef.set(moduleRef, skipped);
+            continue;
+        }
+        const blockingDependency = graph.edges
+            .filter((edge) => edge.from === moduleRef)
+            .map((edge) => edge.to)
+            .find((dependencyRef) => {
+            const dependencyModule = byRef.get(dependencyRef);
+            if (!dependencyModule?.lifecycle.includes("start"))
+                return false;
+            const dependencyResult = resultByRef.get(dependencyRef);
+            return dependencyResult?.result?.status !== "SUCCEEDED";
+        });
+        if (blockingDependency !== undefined) {
+            const blocked = {
+                moduleRef,
+                primitive: "start",
+                status: "EXECUTED",
+                result: {
+                    contract: "deployment.result.v1",
+                    ok: false,
+                    status: "BLOCKED",
+                    moduleRef: module.moduleRef,
+                    moduleVersion: module.moduleVersion,
+                    error: {
+                        code: "COMMAND_FAILED",
+                        message: `dependency ${blockingDependency} did not start successfully; ${moduleRef} was not started`,
+                        retryable: true,
+                    },
+                },
+                observedEffects: [],
+            };
+            results.push(blocked);
+            resultByRef.set(moduleRef, blocked);
+            continue;
+        }
+        const result = await runOne(catalog, module, "start");
+        results.push(result);
+        resultByRef.set(moduleRef, result);
+    }
+    return results;
 }
 /**
  * Stops a module set in reverse dependency topological order, dispatching the

package/dist/src/lifecycle/service-process.js

@@ -195,6 +195,15 @@ export async function managedServiceStatus(paths, module) {
         observedEffects: [],
     };
 }
+async function waitForStartupStability(pid, milliseconds = 500) {
+    const deadline = Date.now() + milliseconds;
+    while (Date.now() < deadline) {
+        if (!isAlive(pid))
+            return false;
+        await new Promise((resolveWait) => setTimeout(resolveWait, 50));
+    }
+    return isAlive(pid);
+}
 export async function startManagedService(paths, module, rawBinding) {
     const existing = await readRecord(paths, module.moduleRef);
     if (existing && (await isOwnedProcess(existing))) {
@@ -243,13 +252,20 @@ export async function startManagedService(paths, module, rawBinding) {
                 result: failed(module, "service process spawned without pid"),
                 observedEffects: [],
             };
+        const pid = child.pid;
+        if (!(await waitForStartupStability(pid))) {
+            return {
+                result: failed(module, `service process ${pid} exited during startup stabilization`),
+                observedEffects: [],
+            };
+        }
         child.unref();
         const record = {
             contract: "deployment.service-process-state.v1",
             moduleRef: module.moduleRef,
             packageName: module.packageName,
             moduleVersion: module.moduleVersion,
-            pid: child.pid,
+            pid,
             startedAt: new Date().toISOString(),
             binPath,
             configPath,
@@ -257,8 +273,22 @@ export async function startManagedService(paths, module, rawBinding) {
             stderrPath,
         };
         await writeJsonAtomic(recordPath(paths, module.moduleRef), record, 0o600);
+        const observed = await managedServiceStatus(paths, module);
+        if (observed.result.status !== "SUCCEEDED") {
+            await removeRecord(paths, module.moduleRef);
+            try {
+                process.kill(pid, "SIGTERM");
+            }
+            catch {
+                // process already exited between observations
+            }
+            return {
+                result: failed(module, `service process ${pid} could not be observed as the owned RUNNING process after spawn`),
+                observedEffects: [],
+            };
+        }
         return {
-            result: { ...base(module), data: { state: "RUNNING", pid: child.pid } },
+            ...observed,
             observedEffects: ["Manage the declared service process"],
         };
     }

package/dist/src/persistence/guards.js

@@ -19,6 +19,7 @@ function isDeploymentIntent(value) {
     return (value === "install" ||
         value === "configure" ||
         value === "upgrade" ||
+        value === "uninstall" ||
         value === "repair");
 }
 function isSelectedModuleFact(value) {

package/dist/src/planner/check.js

@@ -76,7 +76,18 @@ function checkConfig(step, plan, reality) {
             return notSatisfied(`required config ${slot.key} is missing`);
         }
     }
-    return satisfied(`required config materialized for ${step.moduleRef}`);
+    // A configure step is satisfied only when current persisted reality matches
+    // the immutable target carried by this plan. Required-key presence alone is
+    // insufficient: a failed/partial prior apply can leave every key present but
+    // with values that the module-owned materializer rejected.
+    const target = plan.moduleTargets.find((entry) => entry.moduleRef === step.moduleRef)?.config;
+    for (const [key, expected] of Object.entries(target ?? {})) {
+        const observed = reality.configValues[key];
+        if (observed !== expected) {
+            return notSatisfied(`config ${key} for ${step.moduleRef} is ${observed === undefined ? "not observed" : "not at the planned target"}`);
+        }
+    }
+    return satisfied(`planned config materialized for ${step.moduleRef}`);
 }
 function checkVerify(step, plan, reality) {
     const module = moduleOf(plan, step);

package/dist/src/planner/plan.js

@@ -52,14 +52,14 @@ function planInstallOrConfigure(input) {
     const graph = buildDependencyGraph(modules);
     const steps = input.intent === "install"
         ? installSteps(modules, graph)
-        : configureSteps(modules, graph);
+        : configureSteps(modules, graph, input.targets ?? [], input.config);
     return assemblePlan({
         intent: input.intent,
         modules,
         targets: input.targets ?? [],
         config: input.config,
         steps,
-        humanActions: humanActionsFromModules(modules),
+        humanActions: input.intent === "install" ? humanActionsFromModules(modules) : [],
         now: input.now ?? new Date(),
     });
 }
@@ -90,35 +90,23 @@ function installSteps(modules, graph) {
     }
     return steps;
 }
-function configureSteps(modules, graph) {
+function configureSteps(modules, graph, targets, config) {
     const seq = createSequencer();
     const byRef = new Map(modules.map((module) => [module.moduleRef, module]));
+    const targetByRef = new Map(targets.map((target) => [target.moduleRef, target]));
     const steps = [];
     for (const ref of graph.order) {
         const module = byRef.get(ref);
-        if (module === undefined)
+        if (module === undefined || module.configSlots.length === 0)
             continue;
-        if (module.configSlots.length > 0) {
-            steps.push(configStep(seq, module));
-        }
-        if (module.kind === "external-resource") {
-            const step = externalResourceStep(seq, module);
-            if (step !== undefined)
-                steps.push(step);
-        }
-        if (module.kind === "service") {
-            if (module.lifecycle.includes("restart")) {
-                steps.push(lifecycleStep(seq, module, "restart"));
-            }
-            else if (module.lifecycle.includes("start")) {
-                steps.push(lifecycleStep(seq, module, "start"));
-            }
-        }
-        for (const requirement of module.requirements) {
-            if (requirement.kind === "human") {
-                steps.push(humanStep(seq, module, requirement.action));
-            }
-        }
+        const explicitConfig = targetByRef.get(ref)?.config;
+        const providedConfig = config?.[ref];
+        const hasMaterializationTarget = (explicitConfig !== undefined &&
+            Object.keys(explicitConfig).length > 0) ||
+            (providedConfig !== undefined && Object.keys(providedConfig).length > 0);
+        if (!hasMaterializationTarget)
+            continue;
+        steps.push(configStep(seq, module));
     }
     return steps;
 }

package/dist/src/planner/upgrade.js

@@ -71,8 +71,17 @@ export function planUpgrade(input) {
             throw new PlatformError("UPGRADE_FAILED", `upgrade ${ref} has breaking changes but declares no migrate lifecycle: ${assessment.breakingChanges.join("; ")}`);
         }
         const dependencies = deps.get(ref) ?? [];
+        const configTarget = input.config?.[ref];
+        const missingRequiredConfig = module.configSlots
+            .filter((slot) => slot.required &&
+            slot.default === undefined &&
+            configTarget?.[slot.key] === undefined)
+            .map((slot) => slot.key);
+        if (missingRequiredConfig.length > 0) {
+            throw new PlatformError("UPGRADE_FAILED", `upgrade ${ref} requires configuration before package mutation: ${missingRequiredConfig.join(", ")}`);
+        }
         steps.push(packageStep(seq, module, "upgrade", dependencies));
-        if (module.configSlots.length > 0) {
+        if (configTarget !== undefined) {
             steps.push(configStep(seq, module));
         }
         if (assessment?.migrationRequired === true) {

package/dist/src/preflight/config.d.ts

@@ -8,3 +8,4 @@ export interface ResolvedModuleConfig {
 }
 export declare function resolveModuleConfig(module: ResolvedModule, provided: Record<string, string> | undefined): ResolvedModuleConfig;
 export declare function checkConfigReadiness(modules: readonly ResolvedModule[], config: Record<string, Record<string, string>> | undefined): PreflightFinding[];
+export declare function checkConfigReality(modules: readonly ResolvedModule[], config: Record<string, Record<string, string>> | undefined): Promise<PreflightFinding[]>;

package/dist/src/preflight/config.js

@@ -1,3 +1,5 @@
+import { constants } from "node:fs";
+import { access, readFile, stat } from "node:fs/promises";
 import { PlatformError } from "../errors.js";
 import { isValidSecretRef } from "../security/redact.js";
 function compareRef(a, b) {
@@ -43,3 +45,44 @@ export function checkConfigReadiness(modules, config) {
     }
     return findings;
 }
+function requiresExistingInputFile(key, sensitive) {
+    return (sensitive === true ||
+        /(?:ConfigPath|ProfilesFile|CredentialFile|TokenFile|tokenFile|credentialFile)$/.test(key));
+}
+function requiresJsonFile(key) {
+    return /(?:ConfigPath|ProfilesFile)$/.test(key);
+}
+export async function checkConfigReality(modules, config) {
+    const findings = [];
+    for (const module of [...modules].sort((a, b) => compareRef(a.moduleRef, b.moduleRef))) {
+        for (const slot of module.configSlots) {
+            if (slot.type !== "path")
+                continue;
+            const value = config?.[module.moduleRef]?.[slot.key] ??
+                (slot.default === undefined ? undefined : String(slot.default));
+            if (!value || !requiresExistingInputFile(slot.key, slot.sensitive))
+                continue;
+            try {
+                await access(value, constants.R_OK);
+                const info = await stat(value);
+                if (!info.isFile())
+                    throw new Error("not a file");
+                const raw = await readFile(value, "utf8");
+                if (slot.sensitive === true && raw.trim().length < 32) {
+                    throw new Error("credential/token file is shorter than 32 characters");
+                }
+                if (requiresJsonFile(slot.key))
+                    JSON.parse(raw);
+            }
+            catch (error) {
+                findings.push({
+                    code: "CONFIG_INVALID",
+                    severity: "error",
+                    moduleRef: module.moduleRef,
+                    message: `config path "${slot.key}" for ${module.moduleRef} is not runtime-ready: ${error instanceof Error ? error.message : String(error)}`,
+                });
+            }
+        }
+    }
+    return findings;
+}

package/dist/src/preflight/preflight.d.ts

@@ -1,8 +1,10 @@
 import type { ResolvedModule } from "../contracts.ts";
 import type { ModuleCatalog } from "../modules.ts";
+import type { WorkspacePaths } from "../paths.ts";
 import type { PreflightResult } from "./findings.ts";
 export interface PreflightOptions {
     config?: Record<string, Record<string, string>>;
     catalog?: ModuleCatalog;
+    paths?: WorkspacePaths;
 }
 export declare function runPreflight(modules: readonly ResolvedModule[], options?: PreflightOptions): Promise<PreflightResult>;

package/dist/src/preflight/preflight.js

@@ -1,11 +1,25 @@
 import { PlatformError } from "../errors.js";
 import { buildDependencyGraph, ModuleRefUnresolvedError, } from "../graph/graph.js";
 import { dispatchLifecycle } from "../lifecycle/index.js";
-import { checkConfigReadiness } from "./config.js";
+import { loadLatestVerification } from "../persistence/index.js";
+import { checkConfigReadiness, checkConfigReality } from "./config.js";
 import { probeAllRequirements } from "./requirements.js";
 function compareRef(a, b) {
     return a < b ? -1 : a > b ? 1 : 0;
 }
+async function humanVerifiedModules(modules, paths) {
+    const verified = new Set();
+    if (paths === undefined)
+        return verified;
+    for (const module of modules) {
+        const latest = await loadLatestVerification(paths, module.moduleRef);
+        if (latest?.result === "PASS" &&
+            latest.moduleVersion === module.moduleVersion) {
+            verified.add(module.moduleRef);
+        }
+    }
+    return verified;
+}
 export async function runPreflight(modules, options = {}) {
     const findings = [];
     let dependency;
@@ -33,7 +47,9 @@ export async function runPreflight(modules, options = {}) {
         }
     }
     findings.push(...checkConfigReadiness(modules, options.config));
-    const requirementProbes = await probeAllRequirements(modules);
+    findings.push(...(await checkConfigReality(modules, options.config)));
+    const verifiedHumanModules = await humanVerifiedModules(modules, options.paths);
+    const requirementProbes = await probeAllRequirements(modules, verifiedHumanModules);
     for (const probe of requirementProbes) {
         if (probe.status === "ACTION_REQUIRED") {
             findings.push({

package/dist/src/preflight/requirements.d.ts

@@ -7,5 +7,5 @@ export interface RequirementProbe {
     status: ProbeStatus;
     message: string;
 }
-export declare function probeAllRequirements(modules: readonly ResolvedModule[]): Promise<RequirementProbe[]>;
-export declare function probeRequirement(moduleRef: string, requirement: ModuleRequirement, modules: readonly ResolvedModule[]): Promise<RequirementProbe>;
+export declare function probeAllRequirements(modules: readonly ResolvedModule[], humanVerifiedModuleRefs?: ReadonlySet<string>): Promise<RequirementProbe[]>;
+export declare function probeRequirement(moduleRef: string, requirement: ModuleRequirement, modules: readonly ResolvedModule[], humanVerifiedModuleRefs?: ReadonlySet<string>): Promise<RequirementProbe>;

package/dist/src/preflight/requirements.js

@@ -5,17 +5,17 @@ import { versionSatisfies } from "../modules.js";
 function compareRef(a, b) {
     return a < b ? -1 : a > b ? 1 : 0;
 }
-export async function probeAllRequirements(modules) {
+export async function probeAllRequirements(modules, humanVerifiedModuleRefs = new Set()) {
     const sorted = [...modules].sort((a, b) => compareRef(a.moduleRef, b.moduleRef));
     const results = [];
     for (const module of sorted) {
         for (const requirement of module.requirements) {
-            results.push(await probeRequirement(module.moduleRef, requirement, modules));
+            results.push(await probeRequirement(module.moduleRef, requirement, modules, humanVerifiedModuleRefs));
         }
     }
     return results;
 }
-export async function probeRequirement(moduleRef, requirement, modules) {
+export async function probeRequirement(moduleRef, requirement, modules, humanVerifiedModuleRefs = new Set()) {
     switch (requirement.kind) {
         case "runtime":
             return probeRuntime(moduleRef, requirement);
@@ -30,12 +30,19 @@ export async function probeRequirement(moduleRef, requirement, modules) {
         case "module-contract":
             return probeModuleContract(moduleRef, requirement, modules);
         case "human":
-            return {
-                moduleRef,
-                requirement,
-                status: "ACTION_REQUIRED",
-                message: requirement.action,
-            };
+            return humanVerifiedModuleRefs.has(moduleRef)
+                ? {
+                    moduleRef,
+                    requirement,
+                    status: "PASS",
+                    message: `human prerequisite verified for ${moduleRef}`,
+                }
+                : {
+                    moduleRef,
+                    requirement,
+                    status: "ACTION_REQUIRED",
+                    message: requirement.action,
+                };
     }
 }
 function probeRuntime(moduleRef, requirement) {

package/dist/src/registry/npm-registry.d.ts

@@ -6,7 +6,7 @@ export interface NpmCommandResult {
     stderr: string;
 }
 export interface NpmCommandRunner {
-    run(args: readonly string[], cwd: string): Promise<NpmCommandResult>;
+    run(args: readonly string[], cwd: string, timeoutMs?: number): Promise<NpmCommandResult>;
 }
 export interface RegistryModuleCandidate {
     packageName: string;

package/dist/src/registry/npm-registry.js

@@ -12,12 +12,13 @@ export const PRO_FLOW_SCOPE = "@tomflow";
 export const PRO_FLOW_PACKAGE_PREFIX = "@tomflow/proflow-";
 export function systemNpmRunner() {
     return {
-        async run(args, cwd) {
+        async run(args, cwd, timeoutMs) {
             try {
                 const result = await execFileAsync("npm", [...args], {
                     cwd,
                     encoding: "utf8",
                     maxBuffer: 4 * 1024 * 1024,
+                    ...(timeoutMs === undefined ? {} : { timeout: timeoutMs }),
                 });
                 return { stdout: result.stdout, stderr: result.stderr };
             }

package/dist/src/security/lock.js

@@ -45,6 +45,32 @@ function lockedError(existing) {
         : `pid=${existing.pid} planRef=${existing.planRef} since=${existing.createdAt} fingerprint=${existing.workspaceFingerprint}`;
     return new PlatformError("WORKSPACE_LOCKED", `workspace apply already in progress (${details})`);
 }
+function isProvablyDeadPid(pid) {
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        return errorHasCode(error, "ESRCH");
+    }
+}
+async function reclaimProvablyStaleLock(paths, expectedFingerprint) {
+    const existing = await readWorkspaceLock(paths);
+    if (existing === undefined ||
+        existing.workspaceFingerprint !== expectedFingerprint ||
+        !isProvablyDeadPid(existing.pid)) {
+        return false;
+    }
+    try {
+        await unlink(workspaceLockPath(paths));
+        return true;
+    }
+    catch (error) {
+        if (errorHasCode(error, "ENOENT"))
+            return true;
+        throw error;
+    }
+}
 // v1 single-process exclusive lock: O_EXCL create, no distributed coordination,
 // and no reclaim of a lock that cannot be proven stale.
 export async function acquireWorkspaceLock(paths, planRef) {
@@ -61,10 +87,22 @@ export async function acquireWorkspaceLock(paths, planRef) {
         handle = await open(file, "wx", 0o644);
     }
     catch (error) {
-        if (errorHasCode(error, "EEXIST")) {
+        if (!errorHasCode(error, "EEXIST"))
+            throw error;
+        if (await reclaimProvablyStaleLock(paths, record.workspaceFingerprint)) {
+            try {
+                handle = await open(file, "wx", 0o644);
+            }
+            catch (retryError) {
+                if (errorHasCode(retryError, "EEXIST")) {
+                    throw lockedError(await readWorkspaceLock(paths));
+                }
+                throw retryError;
+            }
+        }
+        else {
             throw lockedError(await readWorkspaceLock(paths));
         }
-        throw error;
     }
     try {
         await handle.writeFile(`${JSON.stringify(record, null, 2)}\n`, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomflow/proflow-platform-cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -24,8 +24,8 @@
     "@tomflow/proflow-module-contract": "^0.1.1"
   },
   "devDependencies": {
-    "@tomflow/proflow-module-template": "^0.1.2",
-    "@tomflow/proflow-deployment-conformance": "^0.1.2"
+    "@tomflow/proflow-deployment-conformance": "^0.1.2",
+    "@tomflow/proflow-module-template": "^0.1.2"
   },
   "description": "Deterministic platform-level deployment discovery, planning, lifecycle and verification CLI.",
   "keywords": [

package/proflow.module.json

@@ -3,7 +3,7 @@
 	"contractVersion": "1.0.0",
 	"moduleRef": "platform-cli",
 	"packageName": "@tomflow/proflow-platform-cli",
-	"moduleVersion": "0.1.2",
+	"moduleVersion": "0.1.4",
 	"kind": "cli",
 	"templateVersion": "1.0.0",
 	"platformCompatibility": ">=1.0.0 <2.0.0",