@zq-silk/yui 0.6.0 → 0.6.2

package/dist/commands/workflowCommands.js

@@ -0,0 +1,415 @@
+import { dataError, taskNotFound, usageError } from "../errors/cliError.js";
+import { createTaskEvent } from "../event/taskEvent.js";
+import { defaultTableWidth, renderTable } from "../output/table.js";
+import { formatTimestamp } from "../output/timePresentation.js";
+import { createReleaseWorkflow, workflowStatus } from "../release/releaseWorkflow.js";
+import { runReleaseWorkflow } from "../release/releaseWorkflowEngine.js";
+import { openConfiguredTaskStore } from "../storage/sqliteStore.js";
+const STEP_KINDS = new Set([
+    "pr-create-or-reuse", "ci-confirm", "merge", "version-tag",
+    "npm-publish", "fresh-install-smoke", "cli-update",
+    "controller-replace", "project-migrate", "post-verify"
+]);
+const IRREVERSIBILITY_LEVELS = new Set([
+    "none", "reversible", "irreversible"
+]);
+export function runWorkflowCommand(args, store, options) {
+    const [command, ...rest] = args;
+    switch (command) {
+        case "create": return createWorkflow(rest, store, options);
+        case "show": return showWorkflow(rest, store);
+        case "list": return listWorkflows(rest, store);
+        case "status": return workflowStatusCommand(rest, store);
+        case "run":
+        case "resume":
+            throw usageError(`Task workflow ${command} is asynchronous; use the yui CLI or runWorkflowCommandAsync.`);
+        default:
+            throw usageError(command === undefined
+                ? "Task workflow command is required."
+                : `Unknown command: task workflow ${command}`);
+    }
+}
+export async function runWorkflowCommandAsync(args, store, options) {
+    const [command, ...rest] = args;
+    if (command !== "run" && command !== "resume") {
+        throw usageError(`Task workflow async command must be run or resume: ${String(command)}`);
+    }
+    const usage = `Task workflow ${command} usage: yui task workflow ${command} <task> <workflow-id> [--grant <grant-id>] [--max-steps <int>].`;
+    const parsed = parseTail(rest, new Set(["--grant", "--max-steps"]), usage);
+    exactPositionals(parsed.positionals, 2, usage);
+    const taskId = parsed.positionals[0];
+    requireTask(store, taskId);
+    const workflowId = parsed.positionals[1];
+    const existing = store.getReleaseWorkflow(taskId, workflowId);
+    if (existing === null) {
+        throw dataError(`Release workflow not found: ${taskId}/${workflowId}.`);
+    }
+    const ports = options.ports;
+    if (ports === undefined) {
+        throw usageError(`Task workflow ${command} requires ports; the yui CLI wires the real adapter.`, usage);
+    }
+    const grantId = optionalOption(parsed.options, "--grant");
+    let maxSteps = options.maxSteps;
+    if (parsed.options.has("--max-steps")) {
+        const value = Number.parseInt(parsed.options.get("--max-steps"), 10);
+        if (!Number.isSafeInteger(value) || value <= 0) {
+            throw usageError("--max-steps must be a positive integer.", usage);
+        }
+        maxSteps = value;
+    }
+    // The immutable run-intent event commits BEFORE the engine persists the
+    // first transition or calls an external system. A run that is killed,
+    // crashes, or whose engine rethrows after this point can never leave
+    // mutation or effect evidence without an audit record saying the run was
+    // attempted. FileTaskStore transactions are synchronous, so the async
+    // engine run cannot join this transaction; committing the intent first is
+    // what makes the trail crash-safe across the whole run.
+    const intentNow = clock(options);
+    store.transaction((tx) => {
+        recordTaskEvent(tx, taskId, "release-workflow.run-started", {
+            workflowId,
+            command,
+            grantId: grantId ?? existing.grantId
+        }, intentNow);
+    });
+    const result = await runReleaseWorkflow(store, taskId, workflowId, ports, {
+        ...(options.now === undefined ? {} : { now: options.now }),
+        ...(maxSteps === undefined ? {} : { maxSteps }),
+        ...(grantId === undefined ? {} : { grantId })
+    });
+    // The engine persisted every step transition for crash recovery. The
+    // outcome event and the workflow's final state commit together so the
+    // audit trail cannot lag the record on a normal engine return.
+    const eventNow = clock(options);
+    const eventPayload = {
+        workflowId,
+        grantId: result.workflow.grantId,
+        outcome: result.outcome,
+        ...(result.stopReason === undefined ? {} : { stopReason: result.stopReason }),
+        attempted: result.attempted.join(",")
+    };
+    try {
+        store.transaction((tx) => {
+            tx.saveReleaseWorkflow(taskId, result.workflow);
+            recordTaskEvent(tx, taskId, "release-workflow.run", eventPayload, eventNow);
+        });
+    }
+    catch (error) {
+        // The instance-level event save failed after a normal engine return. The
+        // engine already committed the final workflow state for crash recovery
+        // and the run-intent event above is durable, so the trail cannot be
+        // empty; fall back to a fresh store of the SAME backend so the outcome
+        // record commits to the authoritative store, then surface the original
+        // failure so the caller knows this path was compromised.
+        if (typeof store.rootDirectory === "function") {
+            const auditStore = openConfiguredTaskStore(store.rootDirectory());
+            recordTaskEvent(auditStore, taskId, "release-workflow.run", eventPayload, eventNow);
+        }
+        throw error;
+    }
+    return output(renderRun(result), result);
+}
+function workflowStatusCommand(args, store) {
+    const usage = "Task workflow status usage: yui task workflow status <task> <workflow-id>.";
+    const parsed = parseTail(args, new Set(), usage);
+    exactPositionals(parsed.positionals, 2, usage);
+    const taskId = parsed.positionals[0];
+    requireTask(store, taskId);
+    const workflow = store.getReleaseWorkflow(taskId, parsed.positionals[1]);
+    if (workflow === null) {
+        throw dataError(`Release workflow not found: ${taskId}/${parsed.positionals[1]}.`);
+    }
+    const lines = [`Workflow: ${workflow.id}`, `Status: ${workflowStatus(workflow)}`];
+    for (const entry of workflow.plan) {
+        const step = workflow.steps[entry.id];
+        const external = step.externalId === undefined ? "-" : step.externalId;
+        lines.push(`  [${step.status}] ${entry.id} (${entry.kind}) attempts=${step.attempts} ext=${external}`);
+    }
+    return output(lines.join("\n").concat("\n"), workflow);
+}
+function renderRun(result) {
+    const lines = [
+        `Workflow ${result.workflow.id}: ${result.outcome} (status ${result.status})`,
+        ...(result.stopReason === undefined ? [] : [`Stop: ${result.stopReason}`]),
+        `Attempted: ${result.attempted.length === 0 ? "-" : result.attempted.join(", ")}`
+    ];
+    return lines.join("\n").concat("\n");
+}
+function createWorkflow(args, store, options) {
+    const usage = "Task workflow create usage: yui task workflow create <task> --grant <grant-id> --source-repo <owner/name> --source-commit <sha> [--source-artifact <name@integrity>] --step <id>:<kind> (repeatable) [--step-irreversibility <id>=<level> (repeatable)] [--step-param <id>:<key>=<value> (repeatable)].";
+    const parsed = parseMultiValueTail(args, new Set(["--grant", "--source-repo", "--source-commit", "--source-artifact"]), new Set(["--step", "--step-irreversibility", "--step-param"]), usage);
+    exactPositionals(parsed.positionals, 1, usage);
+    const taskId = parsed.positionals[0];
+    requireTask(store, taskId);
+    const grantId = requiredOption(parsed.options, "--grant");
+    const grant = store.getCapabilityGrant(taskId, grantId);
+    if (grant === null) {
+        throw dataError(`Capability grant not found: ${taskId}/${grantId}.`);
+    }
+    const source = buildSource(parsed, usage);
+    const plan = buildPlan(parsed, usage);
+    const now = clock(options);
+    // The workflow record and its audit event commit in one transaction: a
+    // failed event save cannot leave a persisted workflow without its audit
+    // trail.
+    const workflow = store.transaction((tx) => {
+        const created = createReleaseWorkflow(tx.nextReleaseWorkflowId(taskId), taskId, { grantId, source, plan }, now);
+        tx.saveReleaseWorkflow(taskId, created);
+        recordTaskEvent(tx, taskId, "release-workflow.created", {
+            workflowId: created.id,
+            grantId: created.grantId,
+            commit: created.source.commit,
+            steps: created.plan.map((entry) => entry.id).join(",")
+        }, now);
+        return created;
+    });
+    return output(`Created release workflow ${workflow.id} with ${workflow.plan.length} steps.\n`, workflow);
+}
+function showWorkflow(args, store) {
+    const usage = "Task workflow show usage: yui task workflow show <task> <workflow-id>.";
+    const parsed = parseTail(args, new Set(), usage);
+    exactPositionals(parsed.positionals, 2, usage);
+    const taskId = parsed.positionals[0];
+    requireTask(store, taskId);
+    const workflow = store.getReleaseWorkflow(taskId, parsed.positionals[1]);
+    if (workflow === null) {
+        throw dataError(`Release workflow not found: ${taskId}/${parsed.positionals[1]}.`);
+    }
+    return output(renderWorkflow(workflow, store.getConfig().timeZone), workflow);
+}
+function listWorkflows(args, store) {
+    const usage = "Task workflow list usage: yui task workflow list <task>.";
+    const parsed = parseTail(args, new Set(), usage);
+    exactPositionals(parsed.positionals, 1, usage);
+    const taskId = parsed.positionals[0];
+    requireTask(store, taskId);
+    const workflows = store.listReleaseWorkflows(taskId);
+    if (workflows.length === 0) {
+        return output("No release workflows found.\n", []);
+    }
+    const rendered = `${renderTable(`Release workflows: ${taskId}`, [
+        { header: "ID", minWidth: 6, maxWidth: 22 },
+        { header: "Grant", minWidth: 6, maxWidth: 22 },
+        { header: "Source", minWidth: 10, maxWidth: 40 },
+        { header: "Steps", minWidth: 5, maxWidth: 8 },
+        { header: "Status", minWidth: 7, maxWidth: 12 }
+    ], workflows.map((workflow) => [
+        workflow.id,
+        workflow.grantId,
+        sourceSummary(workflow),
+        `${workflow.plan.length}`,
+        workflowStatus(workflow)
+    ]), defaultTableWidth())}\n`;
+    return output(rendered, workflows);
+}
+function buildSource(parsed, usage) {
+    const repo = requiredOption(parsed.options, "--source-repo");
+    const separator = repo.indexOf("/");
+    if (separator <= 0 || separator === repo.length - 1) {
+        throw usageError("--source-repo must use owner/name.", usage);
+    }
+    const commit = requiredOption(parsed.options, "--source-commit");
+    const artifactValue = optionalOption(parsed.options, "--source-artifact");
+    if (artifactValue === undefined) {
+        return {
+            repository: {
+                owner: repo.slice(0, separator).trim(),
+                name: repo.slice(separator + 1).trim()
+            },
+            commit
+        };
+    }
+    const at = artifactValue.indexOf("@");
+    if (at <= 0 || at === artifactValue.length - 1) {
+        throw usageError("--source-artifact must use name@integrity.", usage);
+    }
+    return {
+        repository: {
+            owner: repo.slice(0, separator).trim(),
+            name: repo.slice(separator + 1).trim()
+        },
+        commit,
+        artifact: {
+            name: artifactValue.slice(0, at).trim(),
+            integrity: artifactValue.slice(at + 1).trim()
+        }
+    };
+}
+function buildPlan(parsed, usage) {
+    const stepValues = parsed.multiOptions.get("--step") ?? [];
+    if (stepValues.length === 0) {
+        throw usageError("--step is required.", usage);
+    }
+    const plan = stepValues.map((value) => {
+        const separator = value.indexOf(":");
+        if (separator <= 0 || separator === value.length - 1) {
+            throw usageError("--step must use id:kind.", usage);
+        }
+        const id = value.slice(0, separator).trim();
+        const kind = value.slice(separator + 1).trim();
+        if (!STEP_KINDS.has(kind)) {
+            throw usageError(`--step kind is invalid: ${kind}.`, usage);
+        }
+        return { id, kind: kind };
+    });
+    const irreversibility = parsed.multiOptions.get("--step-irreversibility") ?? [];
+    for (const value of irreversibility) {
+        const separator = value.indexOf("=");
+        if (separator <= 0 || separator === value.length - 1) {
+            throw usageError("--step-irreversibility must use id=level.", usage);
+        }
+        const id = value.slice(0, separator).trim();
+        const level = value.slice(separator + 1).trim();
+        if (!IRREVERSIBILITY_LEVELS.has(level)) {
+            throw usageError("--step-irreversibility must be one of: none, reversible, irreversible.", usage);
+        }
+        const entry = plan.find((candidate) => candidate.id === id);
+        if (entry === undefined) {
+            throw usageError(`--step-irreversibility names an unknown step: ${id}.`, usage);
+        }
+        entry.irreversibility = level;
+    }
+    const stepParams = parsed.multiOptions.get("--step-param") ?? [];
+    for (const value of stepParams) {
+        const separator = value.indexOf(":");
+        if (separator <= 0 || separator === value.length - 1) {
+            throw usageError("--step-param must use id:key=value.", usage);
+        }
+        const id = value.slice(0, separator).trim();
+        const assignment = value.slice(separator + 1);
+        const equals = assignment.indexOf("=");
+        if (equals <= 0 || equals === assignment.length - 1) {
+            throw usageError("--step-param must use id:key=value.", usage);
+        }
+        const entry = plan.find((candidate) => candidate.id === id);
+        if (entry === undefined) {
+            throw usageError(`--step-param names an unknown step: ${id}.`, usage);
+        }
+        const key = assignment.slice(0, equals).trim();
+        const paramValue = assignment.slice(equals + 1).trim();
+        if (key.length === 0 || paramValue.length === 0) {
+            throw usageError("--step-param must use id:key=value.", usage);
+        }
+        entry.params = { ...(entry.params ?? {}), [key]: paramValue };
+    }
+    return plan;
+}
+function sourceSummary(workflow) {
+    const { owner, name } = workflow.source.repository;
+    const shortCommit = workflow.source.commit.slice(0, 7);
+    return `${owner}/${name}@${shortCommit}`;
+}
+function renderWorkflow(workflow, timeZone) {
+    const lines = [
+        `Workflow: ${workflow.id}`,
+        `Task: ${workflow.taskId}`,
+        `Grant: ${workflow.grantId}`,
+        `Source: ${sourceSummary(workflow)}`,
+        `Status: ${workflowStatus(workflow)}`,
+        "Steps:"
+    ];
+    for (const entry of workflow.plan) {
+        const step = workflow.steps[entry.id];
+        const external = step.externalId === undefined ? "-" : step.externalId;
+        lines.push(`  [${step.status}] ${entry.id} (${entry.kind}) attempts=${step.attempts} ext=${external}`);
+    }
+    lines.push(`Created: ${formatTimestamp(workflow.createdAt, timeZone)}`);
+    lines.push(`Updated: ${formatTimestamp(workflow.updatedAt, timeZone)}`);
+    return lines.join("\n").concat("\n");
+}
+function requireTask(store, taskId) {
+    const id = requiredText(taskId, "Task id");
+    const task = store.getTask(id);
+    if (task === null)
+        throw taskNotFound(id);
+    return task;
+}
+function recordTaskEvent(store, taskId, type, payload, now) {
+    store.saveEvent(taskId, createTaskEvent(store.nextEventId(taskId), taskId, type, payload, now));
+}
+function requiredOption(options, name) {
+    return requiredText(options.get(name), name);
+}
+function optionalOption(options, name) {
+    if (!options.has(name))
+        return undefined;
+    return requiredText(options.get(name), name);
+}
+function requiredText(value, label) {
+    const normalized = value?.trim();
+    if (normalized === undefined || normalized.length === 0) {
+        throw usageError(`${label} is required.`);
+    }
+    return normalized;
+}
+function clock(options) {
+    return options.now?.() ?? new Date();
+}
+function output(value, data) {
+    return data === undefined
+        ? { kind: "output", output: value }
+        : { kind: "output", output: value, data };
+}
+function exactPositionals(values, count, usage) {
+    if (values.length !== count || values.some((value) => value.trim().length === 0)) {
+        throw usageError(usage);
+    }
+}
+function parseTail(args, valueOptions, usage) {
+    const positionals = [];
+    const options = new Map();
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (!value.startsWith("--")) {
+            positionals.push(value);
+            continue;
+        }
+        if (!valueOptions.has(value)) {
+            throw usageError(`Unsupported option: ${value}.`, usage);
+        }
+        if (options.has(value)) {
+            throw usageError(`Option may only be specified once: ${value}.`, usage);
+        }
+        const optionValue = args[index + 1];
+        if (optionValue === undefined || optionValue.startsWith("--")) {
+            throw usageError(`${value} is required.`, usage);
+        }
+        options.set(value, optionValue);
+        index += 1;
+    }
+    return { positionals, options };
+}
+function parseMultiValueTail(args, valueOptions, repeatOptions, usage) {
+    const positionals = [];
+    const options = new Map();
+    const multiOptions = new Map();
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (!value.startsWith("--")) {
+            positionals.push(value);
+            continue;
+        }
+        if (!valueOptions.has(value) && !repeatOptions.has(value)) {
+            throw usageError(`Unsupported option: ${value}.`, usage);
+        }
+        if (repeatOptions.has(value)) {
+            const optionValue = args[index + 1];
+            if (optionValue === undefined || optionValue.startsWith("--")) {
+                throw usageError(`${value} is required.`, usage);
+            }
+            multiOptions.set(value, [...(multiOptions.get(value) ?? []), optionValue]);
+            index += 1;
+            continue;
+        }
+        if (options.has(value)) {
+            throw usageError(`Option may only be specified once: ${value}.`, usage);
+        }
+        const optionValue = args[index + 1];
+        if (optionValue === undefined || optionValue.startsWith("--")) {
+            throw usageError(`${value} is required.`, usage);
+        }
+        options.set(value, optionValue);
+        index += 1;
+    }
+    return { positionals, options, multiOptions };
+}

package/dist/config/yuiConfig.js

@@ -1,6 +1,31 @@
 export const DEFAULT_RECONCILIATION_INTERVAL_SECONDS = 120;
 export const MIN_RECONCILIATION_INTERVAL_SECONDS = 5;
 export const MAX_RECONCILIATION_INTERVAL_SECONDS = 300;
+export const DEFAULT_RESOURCES_GC_MODE = "report";
+/**
+ * Resolves the Resource GC mode. `report` (default) only reports candidates;
+ * `quarantine` allows `yui resources gc --apply` to quarantine releasable
+ * resources.
+ */
+export function resolveResourcesGcMode(value) {
+    if (value === undefined)
+        return DEFAULT_RESOURCES_GC_MODE;
+    if (value === "report" || value === "quarantine")
+        return value;
+    throw new TypeError("resourcesGcMode must be 'report' or 'quarantine'.");
+}
+/**
+ * Whether the Controller may automatically quarantine resources for terminal
+ * Tasks. Defaults to false: automatic GC is always opt-in, and permanent
+ * deletion remains a manual, delayed step.
+ */
+export function resolveResourcesGcAutoQuarantine(value) {
+    if (value === undefined)
+        return false;
+    if (typeof value === "boolean")
+        return value;
+    throw new TypeError("resourcesGcAutoQuarantine must be a boolean.");
+}
 /**
  * Resolves the durable Yui setting used for low-frequency recovery
  * reconciliation. Normal durable state changes wake the Controller through
@@ -16,3 +41,40 @@ export function reconciliationIntervalMilliseconds(value) {
     }
     return seconds * 1_000;
 }
+/**
+ * Issue 07 (Leader convergence) feature mode. `display` only shows the
+ * read-only next-action decision support; `warn` additionally reports
+ * duplicate deliveries and semantic-budget warnings; `enforce` hard-blocks
+ * only exact duplicates, while semantic-budget exhaustion remains a warning
+ * because it must not override Leader judgment. The mode is additive and
+ * optional — Homes without it keep the `display` default, so no config
+ * migration is required.
+ */
+export const LEADER_NEXT_ACTION_MODES = ["display", "warn", "enforce"];
+export const DEFAULT_LEADER_NEXT_ACTION_MODE = "display";
+export function resolveLeaderNextActionMode(value) {
+    if (value === undefined || value === null)
+        return DEFAULT_LEADER_NEXT_ACTION_MODE;
+    if (typeof value !== "string") {
+        throw new TypeError("leaderNextActionMode must be display, warn, or enforce.");
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized.length === 0)
+        return DEFAULT_LEADER_NEXT_ACTION_MODE;
+    if (!LEADER_NEXT_ACTION_MODES.includes(normalized)) {
+        throw new TypeError("leaderNextActionMode must be display, warn, or enforce.");
+    }
+    return normalized;
+}
+/**
+ * Resolve the effective mode. An explicit environment override
+ * (`YUI_LEADER_NEXT_ACTION_MODE`) wins over the durable config value so a
+ * single CLI invocation can be tightened or loosened without a config write.
+ */
+export function leaderNextActionMode(configured, env = process.env) {
+    const override = env.YUI_LEADER_NEXT_ACTION_MODE;
+    if (override !== undefined && override.trim().length > 0) {
+        return resolveLeaderNextActionMode(override);
+    }
+    return resolveLeaderNextActionMode(configured);
+}

package/dist/controller/clientRuntime.js

@@ -8,6 +8,8 @@ import { hasRuntimeLifecycleWork } from "../runtime/lifecycleReservation.js";
 import { assertControllerStatusIdentity } from "../runtime/exactControlPlane.js";
 import { EPHEMERAL_DOMAIN_ENVIRONMENT_NAMES } from "./domainIdentity.js";
 import { YUI_VERSION, yuiVersionIdentity } from "../version.js";
+import { SessionOwnerReconciliation } from "./sessionOwnerReconciliation.js";
+import { WorkspaceCleanupBlockedError } from "../repository/taskWorkspacePreparer.js";
 const STARTUP_TIMEOUT_MS = 5_000;
 // A lifecycle RPC may legitimately occupy the Controller for 30 seconds.
 // Restart must allow that request to drain before deciding shutdown is stuck.
@@ -19,6 +21,15 @@ const CONFIGURATION_REFRESH_TIMEOUT_MS = 500;
 const CONTROLLER_OPERATIONAL_ENVIRONMENT = [
     ...AGENT_OPERATIONAL_ENVIRONMENT_NAMES,
     "YUI_TMUX_BIN",
+    // Issue 01: YUI_STORE_BACKEND/YUI_STORE_WORKER are reserved for tests and
+    // explicit recovery commands. A Controller spawned by such a command must
+    // inherit the forced backend; otherwise a layout-7 test Home silently opens
+    // SQLite, creates yui.db, and diverges from the file store the test writes.
+    "YUI_STORE_BACKEND",
+    "YUI_STORE_WORKER",
+    // rr13/test: Forward the liveness seam so an integration test's Controller
+    // subprocess does not reap a saved active Leader Run without a real tmux role.
+    "YUI_TEST_ROLE_LIVENESS_PRESENT",
     ...EPHEMERAL_DOMAIN_ENVIRONMENT_NAMES
 ];
 /**
@@ -255,9 +266,14 @@ function controllerSpawnEnvironment(home, source) {
         // The Controller remains authoritative for reporting an invalid/unavailable
         // home. Environment filtering must never fall back to forwarding all names.
     }
+    // Merge with process.env so a partial source (e.g. a managed-Session env
+    // that only carries YUI_SESSION_SCOPE/YUI_TASK_ID) still forwards
+    // operational vars like YUI_STORE_BACKEND and PATH. The source wins on
+    // conflict; the whitelist still gates every forwarded name.
+    const effectiveSource = { ...process.env, ...source };
     const environment = {};
     for (const name of allowed) {
-        const value = source[name];
+        const value = effectiveSource[name];
         if (value !== undefined)
             environment[name] = value;
     }
@@ -439,6 +455,31 @@ export class FileTaskWorkflowRuntime {
             }
         }
     }
+    /**
+     * Issue 03 archive postcondition. Re-verifies physical absence after the
+     * runtime stop and blocks archive while any owned Provider root is still
+     * live, preserving the owner records for Operator recovery.
+     */
+    async assertTaskPhysicalResourcesReleased(taskId) {
+        const reconciliation = new SessionOwnerReconciliation({
+            home: this.home,
+            store: this.store,
+            environment: this.clientOptions.environment,
+            tmux: this.tmux
+        });
+        const records = this.store.listSessionOwners().filter((record) => (record.owner.scope === "task" && record.owner.taskId === taskId));
+        if (records.length === 0)
+            return;
+        const report = reconciliation.report();
+        const blockers = report.entries.filter((entry) => (entry.owner.scope === "task"
+            && entry.owner.taskId === taskId
+            && entry.archiveBlocked));
+        if (blockers.length === 0)
+            return;
+        throw new WorkspaceCleanupBlockedError("physical-resource-live", `task:${taskId}`, true, `Task archive blocked: ${blockers.length} owned physical resource(s) still live: `
+            + blockers.map((entry) => (`${entry.owner.roleName}/${entry.launchId}`
+                + ` (pid ${entry.physical?.alive === true ? entry.physical.pid : "?"})`)).join("; "));
+    }
     async stopGlobalRoleSession(roleName) {
         if (this.store.getGlobalRole(roleName) === null) {
             throw new Error(`Global Role not found: ${roleName}.`);