@zq-silk/yui 0.6.0 → 0.6.2

package/dist/commands/resourcesCommands.js

@@ -0,0 +1,274 @@
+/**
+ * `yui resources gc` — Resource GC command (Issue 10).
+ *
+ * Dry-run by default. `--apply` quarantines releasable resources only when
+ * `resources.gcMode=quarantine` is set; `--purge` permanently deletes
+ * quarantined resources after the observation window; `--restore` rolls back
+ * every quarantined resource to its original path.
+ */
+import { resolve } from "node:path";
+import { usageError } from "../errors/cliError.js";
+import { defaultTableWidth, renderTable } from "../output/table.js";
+import { applyResourceGc, planResourceGc, purgeResourceQuarantine, restoreAllResourceGc } from "../resources/resourceGc.js";
+import { createResourceRegistryStore } from "../resources/resourceRegistryStore.js";
+import { resourceKindLabel, resourceOwnerLabel } from "../resources/resourceDiscovery.js";
+import { resolveResourcesGcMode } from "../config/yuiConfig.js";
+export async function runResourcesCommand(args, store, options = {}) {
+    const [command, ...rest] = args;
+    if (command !== "gc") {
+        throw usageError("Unknown resources command. Available: yui resources gc "
+            + "[--dry-run|--apply|--purge|--restore] [--quarantine-ttl-hours <hours>].");
+    }
+    return runGcCommand(rest, store, options);
+}
+async function runGcCommand(args, store, options) {
+    const action = parseGcAction(args);
+    const ttlHours = parseTtlHours(args);
+    const now = options.now?.() ?? new Date();
+    const home = resolve(store.rootDirectory());
+    const mode = resolveGcMode(store);
+    const projects = store.listProjects();
+    const managedWorkspaces = collectManagedWorkspaces(store);
+    const taskStatusById = collectTaskStatuses(store);
+    const activeWorkspaceOwnerPaths = collectActiveWorkspaceOwnerPaths(store);
+    if (action === "restore") {
+        const result = await restoreAllResourceGc(home, { now });
+        return {
+            output: renderRestoreResult(result),
+            data: result
+        };
+    }
+    if (action === "purge") {
+        if (mode !== "quarantine") {
+            return {
+                output: "resources.gcMode=report; purge skipped. "
+                    + "Set resources.gcMode=quarantine to enable purge.",
+                data: { mode, action: "purge", skipped: true }
+            };
+        }
+        const result = await purgeResourceQuarantine(home, { now, ttlHours, managedWorkspaces });
+        return {
+            output: renderPurgeResult(result),
+            data: result
+        };
+    }
+    const plan = await planResourceGc({
+        home,
+        registryStore: createResourceRegistryStore(home),
+        projects,
+        managedWorkspaces,
+        taskStatusById,
+        mode,
+        now,
+        quarantineTtlHours: ttlHours,
+        activeWorkspaceOwnerPaths
+    });
+    if (action === "apply" && mode === "quarantine") {
+        const result = await applyResourceGc({
+            home,
+            registryStore: createResourceRegistryStore(home),
+            projects,
+            managedWorkspaces,
+            taskStatusById,
+            mode,
+            now,
+            quarantineTtlHours: ttlHours,
+            activeWorkspaceOwnerPaths
+        }, plan);
+        return {
+            output: renderApplyResult(result),
+            data: result
+        };
+    }
+    return {
+        output: renderPlan(plan, action),
+        data: plan
+    };
+}
+function parseGcAction(args) {
+    const flags = new Set(args);
+    if (flags.has("--apply"))
+        return "apply";
+    if (flags.has("--purge"))
+        return "purge";
+    if (flags.has("--restore"))
+        return "restore";
+    return "dry-run";
+}
+function parseTtlHours(args) {
+    const index = args.indexOf("--quarantine-ttl-hours");
+    if (index === -1)
+        return 24;
+    const value = Number(args[index + 1]);
+    if (!Number.isFinite(value) || value < 1 || value > 24 * 30) {
+        throw usageError("Quarantine TTL hours must be between 1 and 720.");
+    }
+    return value;
+}
+function resolveGcMode(store) {
+    return resolveResourcesGcMode(store.getConfig().resourcesGcMode);
+}
+function collectManagedWorkspaces(store) {
+    const workspaces = [];
+    for (const task of store.listTasks()) {
+        workspaces.push(...store.listManagedWorkspaces(task.id));
+    }
+    return workspaces;
+}
+function collectTaskStatuses(store) {
+    const statuses = new Map();
+    for (const task of store.listTasks()) {
+        statuses.set(task.id, task.status);
+    }
+    return statuses;
+}
+/** Workspace paths claimed by active durable Jobs (AgentRuns). */
+function collectActiveWorkspaceOwnerPaths(store) {
+    const paths = [];
+    for (const task of store.listTasks()) {
+        for (const run of store.listAgentRuns(task.id)) {
+            if (run.status !== "active")
+                continue;
+            const workspace = run.workspace;
+            if (workspace === undefined)
+                continue;
+            paths.push(workspace.root, ...workspace.entries.map((entry) => entry.path));
+        }
+    }
+    return paths;
+}
+function renderPlan(plan, action) {
+    const lines = [];
+    const modeNotice = plan.mode === "report" && action === "apply"
+        ? "resources.gcMode=report; apply shadowed (no changes). "
+            + "Set resources.gcMode=quarantine to enable.\n"
+        : "";
+    lines.push(`${modeNotice}Resource GC plan (${plan.mode}, ${action}) at ${plan.generatedAt}`);
+    lines.push(`Home: ${plan.home}`);
+    lines.push("");
+    if (plan.scan.diagnostics.length > 0) {
+        lines.push("Scan diagnostics:");
+        for (const diag of plan.scan.diagnostics) {
+            lines.push(`  [${diag.severity}] ${diag.source}: ${diag.message}`);
+        }
+        lines.push("");
+    }
+    if (plan.records.length === 0) {
+        lines.push("No resources discovered.");
+        return lines.join("\n");
+    }
+    const rows = plan.records.map((record) => [
+        record.id,
+        resourceKindLabel(record.kind),
+        truncate(record.path, 60),
+        resourceOwnerLabel(record.owner),
+        formatSize(record.sizeBytes),
+        record.cleanliness,
+        record.activeRefs.length === 0 ? "-" : `${record.activeRefs.length} ref(s)`,
+        record.disposition,
+        record.blocker ?? ""
+    ]);
+    lines.push(renderTable("Resources", [
+        { header: "ID", minWidth: 16, maxWidth: 16 },
+        { header: "Kind", minWidth: 14, maxWidth: 14 },
+        { header: "Path", minWidth: 20, maxWidth: 60 },
+        { header: "Owner", minWidth: 16, maxWidth: 32 },
+        { header: "Size", minWidth: 10, maxWidth: 12 },
+        { header: "Clean", minWidth: 8, maxWidth: 8 },
+        { header: "Refs", minWidth: 8, maxWidth: 10 },
+        { header: "Disposition", minWidth: 14, maxWidth: 16 },
+        { header: "Blocker", minWidth: 10, maxWidth: 40 }
+    ], rows, defaultTableWidth()));
+    lines.push("");
+    lines.push(`Summary: ${plan.releasable.length} releasable, `
+        + `${plan.retained.length} retained, `
+        + `${plan.quarantined.length} quarantined, `
+        + `${plan.deleted.length} deleted.`);
+    return lines.join("\n");
+}
+function renderApplyResult(result) {
+    const lines = [];
+    lines.push(`Resource GC apply at ${result.planned.generatedAt}`);
+    lines.push(`Home: ${result.planned.home}`);
+    lines.push("");
+    if (result.applied.length > 0) {
+        lines.push(`Quarantined ${result.applied.length} resource(s):`);
+        for (const record of result.applied) {
+            lines.push(`  ${record.id} ${resourceKindLabel(record.kind)} ${record.path}`);
+        }
+    }
+    if (result.failed.length > 0) {
+        lines.push(`Failed ${result.failed.length} resource(s):`);
+        for (const record of result.failed) {
+            lines.push(`  ${record.id} ${record.path}: ${record.blocker ?? "unknown"}`);
+        }
+    }
+    if (result.restored.length > 0) {
+        lines.push(`Restored ${result.restored.length} resource(s) from quarantine.`);
+    }
+    if (result.applied.length === 0 && result.failed.length === 0 && result.restored.length === 0) {
+        lines.push("No releasable resources.");
+    }
+    return lines.join("\n");
+}
+function renderRestoreResult(result) {
+    const lines = [];
+    lines.push(`Resource GC restore at ${result.planned.generatedAt}`);
+    lines.push(`Home: ${result.planned.home}`);
+    lines.push("");
+    if (result.restored.length > 0) {
+        lines.push(`Restored ${result.restored.length} resource(s):`);
+        for (const record of result.restored) {
+            lines.push(`  ${record.id} ${resourceKindLabel(record.kind)} ${record.path}`);
+        }
+    }
+    if (result.failed.length > 0) {
+        lines.push(`Failed ${result.failed.length} resource(s):`);
+        for (const record of result.failed) {
+            lines.push(`  ${record.id}: ${record.blocker ?? "unknown"}`);
+        }
+    }
+    if (result.restored.length === 0 && result.failed.length === 0) {
+        lines.push("No quarantined resources to restore.");
+    }
+    return lines.join("\n");
+}
+function renderPurgeResult(result) {
+    const lines = [];
+    lines.push(`Resource GC purge at ${result.planned.generatedAt}`);
+    lines.push(`Home: ${result.planned.home}`);
+    lines.push("");
+    if (result.purged.length > 0) {
+        lines.push(`Purged ${result.purged.length} resource(s):`);
+        for (const record of result.purged) {
+            lines.push(`  ${record.id} ${resourceKindLabel(record.kind)}`);
+        }
+    }
+    if (result.restored.length > 0) {
+        lines.push(`Restored ${result.restored.length} resource(s) with new live references.`);
+    }
+    if (result.failed.length > 0) {
+        lines.push(`Failed ${result.failed.length} resource(s):`);
+        for (const record of result.failed) {
+            lines.push(`  ${record.id}: ${record.blocker ?? "unknown"}`);
+        }
+    }
+    if (result.purged.length === 0 && result.restored.length === 0 && result.failed.length === 0) {
+        lines.push("No quarantined resources past the observation window.");
+    }
+    return lines.join("\n");
+}
+function formatSize(bytes) {
+    if (bytes === undefined)
+        return "?";
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KiB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GiB`;
+}
+function truncate(value, max) {
+    return value.length <= max ? value : `…${value.slice(-(max - 1))}`;
+}

package/dist/commands/sessionCommands.js

@@ -0,0 +1,104 @@
+import { usageError } from "../errors/cliError.js";
+import { defaultTableWidth, renderTable } from "../output/table.js";
+export function parseSessionReconcileOptions(args) {
+    const allowed = new Set(["--report", "--cleanup"]);
+    if (args.some((argument) => !allowed.has(argument))) {
+        throw usageError("Session reconcile usage: yui session reconcile [--report] [--cleanup].");
+    }
+    return {
+        report: args.includes("--report") || !args.includes("--cleanup"),
+        cleanup: args.includes("--cleanup")
+    };
+}
+/**
+ * `yui session reconcile` — read-only durable/physical reconciliation report
+ * by default. `--cleanup` performs exact-owner termination of live roots
+ * belonging to terminal/archived Tasks.
+ */
+export async function runSessionReconcileCommand(input) {
+    if (input.options.cleanup) {
+        const before = input.reconciliation.report();
+        const targets = before.entries.filter((entry) => entry.archiveBlocked);
+        for (const entry of targets) {
+            const owner = entry.owner.scope === "task"
+                ? {
+                    scope: "task",
+                    taskId: entry.owner.taskId,
+                    roleName: entry.owner.roleName
+                }
+                : {
+                    scope: "global",
+                    roleName: entry.owner.roleName
+                };
+            await input.reconciliation.terminateOwner(owner);
+        }
+    }
+    const report = input.reconciliation.report();
+    const exitCode = report.summary.archiveBlockers > 0 ? 5 : 0;
+    return {
+        output: renderSessionReconciliationReport(report),
+        data: report,
+        exitCode
+    };
+}
+export function renderSessionReconciliationReport(report, width = defaultTableWidth()) {
+    const lines = [
+        "Session reconciliation",
+        "",
+        `Owners: ${report.summary.owners}; live physical roots: `
+            + `${report.summary.livePhysicalRoots}; archive blockers: `
+            + `${report.summary.archiveBlockers}; verification gaps: `
+            + `${report.summary.verificationGaps}.`
+    ];
+    if (report.entries.length === 0) {
+        lines.push("", "No Session owner records found.");
+        return lines.join("\n");
+    }
+    lines.push("", renderTable("Session owners", [
+        { header: "Task", minWidth: 8, maxWidth: 18 },
+        { header: "Role", minWidth: 12, maxWidth: 22 },
+        { header: "Agent", minWidth: 7, maxWidth: 14 },
+        { header: "Durable", minWidth: 8, maxWidth: 10 },
+        { header: "Physical", minWidth: 8, maxWidth: 10 },
+        { header: "PID", minWidth: 5, maxWidth: 8 },
+        { header: "RSS", minWidth: 8, maxWidth: 11 },
+        { header: "Children", minWidth: 8, maxWidth: 8 },
+        { header: "Last stop", minWidth: 12, maxWidth: 16 },
+        { header: "Mismatch", minWidth: 12, maxWidth: 30 },
+        { header: "Archive", minWidth: 7, maxWidth: 9 }
+    ], report.entries.map((entry) => [
+        entry.owner.scope === "global"
+            ? "global"
+            : (entry.owner.taskId ?? "—"),
+        entry.owner.roleName,
+        entry.agentId,
+        entry.durableStatus,
+        entry.physical === undefined
+            ? "gap"
+            : entry.physical.alive
+                ? "live"
+                : "absent",
+        entry.physical === undefined ? "—" : String(entry.physical.pid),
+        entry.physical === undefined || entry.physical.rssBytes <= 0
+            ? "—"
+            : formatBytes(entry.physical.rssBytes),
+        entry.physical === undefined ? "—" : String(entry.physical.childCount),
+        entry.lastStopOutcome ?? "—",
+        entry.mismatch ?? "—",
+        entry.archiveBlocked ? "blocked" : "ok"
+    ]), width));
+    return lines.join("\n");
+}
+function formatBytes(bytes) {
+    if (bytes <= 0)
+        return "—";
+    const units = ["B", "KiB", "MiB", "GiB", "TiB"];
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    const digits = value >= 10 || unit === 0 ? 0 : 1;
+    return `${value.toFixed(digits)} ${units[unit]}`;
+}

package/dist/commands/taskActor.js

@@ -4,6 +4,8 @@ import { formatAgentRunReceiptId } from "../task/taskRecordReference.js";
 const LEADER_ROLE = "leader";
 const LEADER_ACTION_RUN_ENV = "YUI_LEADER_ACTION_RUN_ID";
 const LEADER_ACTION_RECEIPT_ENV = "YUI_LEADER_ACTION_RECEIPT_ID";
+/** rr13: Per-Session DurableJob caller key injected at native Session launch. */
+const JOB_CALLER_KEY_ENV = "YUI_JOB_CALLER_KEY";
 export function taskActor(environment, taskId) {
     const env = environment ?? {};
     if (env.YUI_SESSION_SCOPE === "task"
@@ -27,6 +29,121 @@ export function taskActor(environment, taskId) {
     }
     return "user";
 }
+/**
+ * rr8: Resolve the caller identity for a `job.start`/`job.cancel` request from
+ * the managed Session environment. The Controller binds the declared job owner
+ * to this identity — a Reviewer is rejected outright, a Worker can only touch
+ * its own Work Item's jobs, and a Leader or plain user retains full access.
+ *
+ * rr12: The identity is now Controller-verified rather than self-reported:
+ * - A managed Task Session (`YUI_SESSION_SCOPE=task`) returns `scope: "task"`
+ *   with its Role and Run. A Leader additionally carries the current in-flight
+ *   Turn receipt (preferring the explicit `YUI_LEADER_ACTION_*` assertion over
+ *   a possibly-stale `YUI_RUN_ID`), which the Controller verifies through the
+ *   same active-Run + in-flight + Session check as `job.acknowledge`.
+ *
+ * rr13: A managed Task Session also carries `callerKey` — the
+ * `YUI_JOB_CALLER_KEY` injected at its native Session launch. The Controller
+ * hashes it and compares against the durable `jobCallerKeyHashes` map, so a
+ * client that reads durable state cannot replay the caller. A `user`-scope
+ * caller is rejected outright for job.start/job.cancel (fail-closed); the
+ * human operator acts through the Leader Session.
+ *
+ * A managed Task Session may only start jobs for its own Task. An incomplete
+ * managed identity (role/agent/run/session vars without a scope) is rejected
+ * rather than silently downgraded to user authority.
+ */
+export function resolveJobCaller(environment, taskId, store) {
+    const env = environment ?? {};
+    if (env.YUI_SESSION_SCOPE === "task") {
+        if (env.YUI_TASK_ID !== taskId) {
+            throw usageError("A managed Task Session may not start Jobs for a different Task.");
+        }
+        const role = env.YUI_ROLE;
+        // rr13: Carry the per-Session caller key so the Controller can verify the
+        // channel binding. Absent on a managed Session = fail-closed at the
+        // Controller boundary.
+        const callerKey = env[JOB_CALLER_KEY_ENV];
+        if (role === LEADER_ROLE) {
+            // Prefer the explicit current-turn Leader assertion over a possibly
+            // stale YUI_RUN_ID/launch. The Controller verifies it against the
+            // active in-flight Leader Run.
+            const assertion = leaderActionAssertion(env);
+            if (assertion !== undefined && assertion !== "invalid") {
+                return {
+                    scope: "task",
+                    taskId,
+                    role,
+                    runId: assertion.runId,
+                    receiptId: assertion.receiptId,
+                    ...(callerKey === undefined ? {} : { callerKey })
+                };
+            }
+        }
+        return {
+            scope: "task",
+            taskId,
+            role,
+            ...(env.YUI_RUN_ID === undefined ? {} : { runId: env.YUI_RUN_ID }),
+            ...(callerKey === undefined ? {} : { callerKey })
+        };
+    }
+    if (env.YUI_SESSION_SCOPE === "global") {
+        return userCaller(store, taskId);
+    }
+    if (env.YUI_ROLE !== undefined
+        || env.YUI_AGENT_ID !== undefined
+        || env.YUI_RUN_ID !== undefined
+        || env.YUI_NATIVE_SESSION_ID !== undefined) {
+        throw usageError("Managed Agent identity is incomplete; refusing to infer user authority.");
+    }
+    return userCaller(store, taskId);
+}
+/**
+ * rr12: Build a `scope: "user"` caller. When a store is available, attach the
+ * active in-flight Leader assertion so the Controller can verify the request
+ * acts under real Leader authority. Without a store, return the bare
+ * `{scope: "user"}` which the Controller rejects (fail-closed).
+ */
+function userCaller(store, taskId) {
+    if (store === undefined)
+        return { scope: "user" };
+    const runId = activeLeaderRunId(store, taskId);
+    if (runId === undefined) {
+        throw usageError("job.start/job.cancel user scope requires an active in-flight Task Leader: "
+            + `${taskId}.`);
+    }
+    return {
+        scope: "user",
+        leaderAssertion: {
+            runId,
+            receiptId: formatAgentRunReceiptId(taskId, runId)
+        }
+    };
+}
+/**
+ * rr12: Resolve the current in-flight Task Leader Run for a non-managed
+ * (operator/bare-shell) caller. Unlike `taskLeaderActionRunId`, this does not
+ * require managed Leader environment variables — it verifies the durable
+ * state directly: an active Leader Run whose Role Session is currently
+ * in-flight with the matching receipt. Returns undefined when no Leader is
+ * active or in flight.
+ */
+function activeLeaderRunId(store, taskId) {
+    const run = store.getActiveAgentRun(taskId, LEADER_ROLE);
+    if (run === null || run.status !== "active" || run.roleName !== LEADER_ROLE) {
+        return undefined;
+    }
+    const sessions = store.getTaskRoleSessionSet(taskId, LEADER_ROLE);
+    const expectedReceipt = formatAgentRunReceiptId(taskId, run.id);
+    if (sessions === null
+        || sessions.inFlight === null
+        || sessions.inFlight.runId !== run.id
+        || sessions.inFlight.receiptId !== expectedReceipt) {
+        return undefined;
+    }
+    return run.id;
+}
 /**
  * Resolve an exact current Task Leader Run for event attribution.
  *

package/dist/commands/taskChangeSetCommands.js

@@ -0,0 +1,60 @@
+import { usageError } from "../errors/cliError.js";
+import { resolveTaskRecordReference } from "../task/taskRecordReference.js";
+/**
+ * Read-only ChangeSet inspection, including its optional integration manifest.
+ */
+export async function runTaskChangeSetCommand(args, store) {
+    const [command, ...rest] = args;
+    if (command === "show")
+        return show(rest, store);
+    throw usageError(command === undefined
+        ? "Task ChangeSet command is required."
+        : `Unknown command: task change-set ${command}`);
+}
+function show(args, store) {
+    if (args.length !== 1) {
+        throw usageError("Task ChangeSet show usage: yui task change-set show <task>/<change-set>.");
+    }
+    let reference;
+    try {
+        reference = resolveTaskRecordReference(args[0], {
+            kind: "changeSet",
+            label: "ChangeSet"
+        });
+    }
+    catch (error) {
+        throw usageError(error instanceof Error ? error.message : String(error));
+    }
+    const changeSet = store.getChangeSet(reference.taskId, reference.localId);
+    if (changeSet === null) {
+        throw usageError(`ChangeSet not found: ${reference.taskId}/${reference.localId}.`);
+    }
+    return {
+        output: renderChangeSet(changeSet),
+        data: { changeSet }
+    };
+}
+function renderChangeSet(changeSet) {
+    const lines = [
+        `ChangeSet: ${changeSet.id}`,
+        `Task: ${changeSet.taskId}`,
+        `WorkItem: ${changeSet.workItemId}`,
+        `Project: ${changeSet.projectId}`,
+        `Base: ${changeSet.baseCommit}`,
+        `Head: ${changeSet.headCommit}`,
+        `Branch: ${changeSet.branch}`,
+        `Changed paths: ${changeSet.changedPaths.length}`,
+        ...changeSet.changedPaths.map((path) => `  ${path}`),
+        `Created: ${changeSet.createdAt}`
+    ];
+    if (changeSet.manifest === undefined) {
+        lines.push("Manifest: -");
+    }
+    else {
+        const manifest = changeSet.manifest;
+        lines.push("Manifest:", `  Tags: ${manifest.tags.join(", ")}`, `  Deleted paths: ${manifest.deletedPaths.length}`, ...manifest.deletedPaths.map((path) => `    ${path}`), `  Target: ${manifest.targetRef ?? "-"}`, `  Evidence: ${manifest.evidenceRefs.length === 0
+            ? "-"
+            : manifest.evidenceRefs.join(", ")}`);
+    }
+    return `${lines.join("\n")}\n`;
+}