@zq-silk/yui 0.15.11 → 0.16.0

package/dist/commands/projectCommands.js

@@ -1,14 +1,14 @@
 import { existsSync } from "node:fs";
 import { readdir, rename, rm } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { usageError } from "../errors/cliError.js";
+import { CliError, usageError } from "../errors/cliError.js";
 import { defaultTableWidth, renderTable } from "../output/table.js";
 import { healCheckoutSwap, restoreCheckoutSwap, swapManagedCheckout } from "../repository/checkoutSwap.js";
-import { NodeGitWorkspace } from "../repository/gitWorkspace.js";
+import { GitWorkspaceRefreshError, NodeGitWorkspace } from "../repository/gitWorkspace.js";
 import { acquireProjectMaintenanceLock } from "../repository/projectMaintenanceLock.js";
 import { addProjectKnowledge, addKnowledgeProposal, assertProjectActive, decideKnowledgeProposal, createProject, findKnowledgeProposal, findKnowledgeProposalByFingerprint, knowledgeEvidenceDigest, knowledgeProposalFingerprint, managedProjectPath, planKnowledgeAcceptance, retireProject, retireProjectKnowledge, resolveProject, updateProjectKnowledge, updateProjectMetadata, validateProject, validateProjectName } from "../repository/project.js";
 import { managedWorkspacesRoot } from "../storage/homeLayout.js";
-import { projectActor } from "./taskActor.js";
+import { projectActor } from "../task/taskAuthority.js";
 export async function runProjectCommand(args, store, options = {}) {
     const [command, ...rest] = args;
     if (command === "add" || command === "clone") {
@@ -22,10 +22,14 @@ export async function runProjectCommand(args, store, options = {}) {
     }
     if (command === "refresh") {
         const refreshed = await refreshProject(rest, store, options);
+        const head = refreshed.changed
+            ? `Refreshed project ${refreshed.project.id}: ${refreshed.fromCommit} -> ${refreshed.toCommit}`
+            : `Project ${refreshed.project.id} HEAD is already current at ${refreshed.toCommit}`;
+        const tracking = refreshed.tracking;
         return {
-            output: refreshed.changed
-                ? `Refreshed project ${refreshed.project.id}: ${refreshed.fromCommit} -> ${refreshed.toCommit}\n`
-                : `Project ${refreshed.project.id} is already current at ${refreshed.toCommit}\n`,
+            output: `${head}\n` + (tracking.status === "unmanaged"
+                ? `Tracking unmanaged: ${tracking.reason}\n`
+                : `Tracking ${tracking.status}: ${tracking.ref} at ${tracking.toCommit}\n`),
             data: refreshed
         };
     }
@@ -101,14 +105,23 @@ async function refreshProject(args, store, options) {
     // RFC Phase 1: hold the per-Project maintenance fence for the whole refresh
     // so Task workspace preparation and other maintenance cannot interleave
     // with the canonical branch/working-tree move.
-    const releaseMaintenance = acquireProjectMaintenanceLock(store.rootDirectory(), project.id);
+    const releaseMaintenance = await acquireProjectMaintenanceLock(store.rootDirectory(), project.id, { signal: options.signal });
     try {
+        const current = requireUnchangedMaintenanceProject(store, project, "refresh");
         const refreshed = await (options.git ?? new NodeGitWorkspace()).refresh({
-            repositoryPath: project.path,
-            remoteUrl: project.remoteUrl,
-            stableRef: project.stableBranch
+            repositoryPath: current.path,
+            remoteUrl: current.remoteUrl,
+            stableRef: current.stableBranch
         });
-        return { project, ...refreshed };
+        return { project: current, ...refreshed };
+    }
+    catch (error) {
+        if (error instanceof GitWorkspaceRefreshError) {
+            throw new CliError("RUNTIME_ERROR", error.message, undefined, {
+                projectId: project.id, refresh: error.result
+            });
+        }
+        throw error;
     }
     finally {
         releaseMaintenance();
@@ -131,8 +144,9 @@ async function diagnoseProject(args, store, options) {
         };
     }
     const git = options.git ?? new NodeGitWorkspace();
-    const releaseMaintenance = acquireProjectMaintenanceLock(store.rootDirectory(), project.id);
+    const releaseMaintenance = await acquireProjectMaintenanceLock(store.rootDirectory(), project.id, { signal: options.signal });
     try {
+        requireUnchangedMaintenanceProject(store, project, "diagnose");
         const current = await git.inspect(project.path, "HEAD");
         const remote = await git.resolveRemoteBaseline({
             repositoryPath: project.path,
@@ -307,13 +321,14 @@ async function migrateProject(args, store, options) {
     // Migration rewrites the Project's Git repository: hold the per-Project
     // maintenance fence so no rebuild/archive/cleanup (or a second migrate)
     // interleaves, and the Controller defers worktree preparation meanwhile.
-    const releaseMaintenance = acquireProjectMaintenanceLock(store.rootDirectory(), project.id);
+    const releaseMaintenance = await acquireProjectMaintenanceLock(store.rootDirectory(), project.id, { signal: options.signal });
     try {
         // Re-read the Project under the fence. A concurrent migration may have
         // completed and switched the catalog to the Home-managed repo since the
         // record was resolved above; the stale snapshot must not drive any Git
         // effect (in particular it must not delete the now-canonical repo).
         const current = requireProject(store, project.id);
+        assertProjectActive(current, "migrate");
         if (current.ownership === "managed") {
             throw usageError(`Project is already Home-managed: ${project.id}.`);
         }
@@ -588,7 +603,7 @@ async function resetProject(args, store, options) {
         throw usageError(`Project reset requires matching stable and development branches: ${project.id}.`);
     }
     const git = options.git ?? new NodeGitWorkspace();
-    const releaseMaintenance = acquireProjectMaintenanceLock(store.rootDirectory(), project.id);
+    const releaseMaintenance = await acquireProjectMaintenanceLock(store.rootDirectory(), project.id, { signal: options.signal });
     try {
         // Re-read under the fence so a concurrent catalog change can never drive
         // a destructive Git effect from a stale snapshot.
@@ -713,7 +728,7 @@ async function replaceProject(args, store, options) {
             + "Re-run with --discard-local to acknowledge that the checkout and any uncommitted state will be discarded.");
     }
     const git = options.git ?? new NodeGitWorkspace();
-    const releaseMaintenance = acquireProjectMaintenanceLock(store.rootDirectory(), project.id);
+    const releaseMaintenance = await acquireProjectMaintenanceLock(store.rootDirectory(), project.id, { signal: options.signal });
     try {
         const current = requireProject(store, project.id);
         assertProjectActive(current, "replace");
@@ -922,8 +937,9 @@ async function deleteProjectCommand(args, store, options) {
     // every failure restores it, so the catalog never loses its recoverable
     // entry while a live checkout (or its failure) is still in play.
     const tombstone = join(store.rootDirectory(), "projects", `.delete-${project.id}`);
-    const releaseMaintenance = acquireProjectMaintenanceLock(store.rootDirectory(), project.id);
+    const releaseMaintenance = await acquireProjectMaintenanceLock(store.rootDirectory(), project.id, { signal: options.signal });
     try {
+        requireUnchangedMaintenanceProject(store, project, "delete");
         // Heal a crashed earlier attempt before the prechecks turn.
         await healCheckoutSwap({ currentPath: project.path, backupPath: tombstone });
         if (existsSync(project.path)) {
@@ -1289,6 +1305,19 @@ function projectKnowledge(args, store, options) {
         ? "Project knowledge command is required."
         : `Unknown command: project knowledge ${command}`);
 }
+/** Waiting yields to catalog writers too; never apply stale Git/lifecycle inputs. */
+function requireUnchangedMaintenanceProject(store, expected, action) {
+    const current = requireProject(store, expected.id);
+    if (current.path !== expected.path
+        || current.remoteUrl !== expected.remoteUrl
+        || current.stableBranch !== expected.stableBranch
+        || current.developmentBranch !== expected.developmentBranch
+        || current.ownership !== expected.ownership
+        || current.status !== expected.status) {
+        throw new Error(`Project changed while waiting to ${action}: ${expected.id}; read current state before retrying.`);
+    }
+    return current;
+}
 function requireProject(store, reference) {
     const project = resolveProject(store.listProjects(), reference);
     if (project === null)
@@ -1468,9 +1497,6 @@ function proposeKnowledge(args, store, options) {
  * digest at proposal time, so a later Agent can verify the source record.
  */
 function requireProposalEvidence(store, parsed) {
-    if (store.getTask === undefined) {
-        throw usageError("Knowledge promotion requires Task evidence, which this store does not provide.");
-    }
     const task = store.getTask(parsed.task);
     if (task === null)
         throw usageError(`Task not found: ${parsed.task}.`);
@@ -1482,9 +1508,6 @@ function requireProposalEvidence(store, parsed) {
     };
     let evidence;
     if (parsed.decision !== undefined) {
-        if (store.getDecision === undefined) {
-            throw usageError("Knowledge promotion requires Decision evidence, which this store does not provide.");
-        }
         const decision = store.getDecision(task.id, parsed.decision);
         if (decision === null) {
             throw usageError(`Decision not found: ${parsed.decision} in Task ${task.id}.`);
@@ -1492,9 +1515,6 @@ function requireProposalEvidence(store, parsed) {
         evidence = `${decision.title}\n${decision.rationale}`;
     }
     else if (parsed.milestone !== undefined) {
-        if (store.getMilestone === undefined) {
-            throw usageError("Knowledge promotion requires Milestone evidence, which this store does not provide.");
-        }
         const milestone = store.getMilestone(task.id, parsed.milestone);
         if (milestone === null) {
             throw usageError(`Milestone not found: ${parsed.milestone} in Task ${task.id}.`);

package/dist/commands/resourcesCommands.js

@@ -7,12 +7,11 @@
  * every quarantined resource to its original path.
  */
 import { resolve } from "node:path";
+import { resolveResourcesGcMode, resolveResourcesQuarantineTtlHours } from "../config/yuiConfig.js";
 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, resolveResourcesQuarantineTtlHours } from "../config/yuiConfig.js";
+import { applyResourceGc, planResourceGc, readResourceGcState, purgeResourceQuarantine, restoreAllResourceGc } from "../resources/resourceGc.js";
 export async function runResourcesCommand(args, store, options = {}) {
     const [command, ...rest] = args;
     if (command !== "gc") {
@@ -27,10 +26,7 @@ async function runGcCommand(args, store, options) {
     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);
+    const { projects, managedWorkspaces, taskStatusById, activeWorkspaceOwnerPaths, sessionOwners } = readResourceGcState(store);
     if (action === "restore") {
         const result = await restoreAllResourceGc(home, { now });
         return {
@@ -46,7 +42,7 @@ async function runGcCommand(args, store, options) {
                 data: { mode, action: "purge", skipped: true }
             };
         }
-        const result = await purgeResourceQuarantine(home, { now, ttlHours, managedWorkspaces });
+        const result = await purgeResourceQuarantine(home, { now, ttlHours, managedWorkspaces }, store);
         return {
             output: renderPurgeResult(result),
             data: result
@@ -54,7 +50,7 @@ async function runGcCommand(args, store, options) {
     }
     const plan = await planResourceGc({
         home,
-        registryStore: createResourceRegistryStore(home),
+        sessionOwners,
         projects,
         managedWorkspaces,
         taskStatusById,
@@ -66,7 +62,7 @@ async function runGcCommand(args, store, options) {
     if (action === "apply" && mode === "quarantine") {
         const result = await applyResourceGc({
             home,
-            registryStore: createResourceRegistryStore(home),
+            sessionOwners,
             projects,
             managedWorkspaces,
             taskStatusById,
@@ -74,7 +70,7 @@ async function runGcCommand(args, store, options) {
             now,
             quarantineTtlHours: ttlHours,
             activeWorkspaceOwnerPaths
-        }, plan);
+        }, plan, store);
         return {
             output: renderApplyResult(result),
             data: result
@@ -109,35 +105,6 @@ function parseTtlHours(args, store) {
 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.listRuns(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"
@@ -207,6 +174,9 @@ function renderApplyResult(result) {
     if (result.restored.length > 0) {
         lines.push(`Restored ${result.restored.length} resource(s) from quarantine.`);
     }
+    for (const record of result.planned.retained) {
+        lines.push(`Retained ${record.id} ${record.path}: ${record.blocker ?? "current ownership or live reference"}`);
+    }
     if (result.applied.length === 0 && result.failed.length === 0 && result.restored.length === 0) {
         lines.push("No releasable resources.");
     }

package/dist/commands/roleConfiguration.js

@@ -187,12 +187,8 @@ function permissionPatch(binding, parsed) {
     }
     const current = binding.config.permission;
     if (selected !== "configured" && !nativeOptions) {
-        // Nothing about permission was named, so the binding keeps what it already
-        // had. The fallback applies only to a binding that somehow carries no
-        // permission at all, and it must be the adapter's own default rather than a
-        // fixed `bypass`: ACP defaults to `default`, and defaulting it to bypass
-        // here would widen authority the user never granted.
-        return structuredClone(current ?? defaultRoleAgentConfig(binding.adapterId).permission);
+        // The validated binding always has its explicit permission strategy.
+        return structuredClone(current);
     }
     const permission = current?.strategy === "configured"
         ? structuredClone(current)

package/dist/commands/taskActivationCommands.js

@@ -1,11 +1,11 @@
 import { createHash } from "node:crypto";
-import { usageError } from "../errors/cliError.js";
-import { currentManagedRuntime } from "../runtime/managedCaller.js";
 import { enqueueWork } from "../coordination/workMailboxQueue.js";
+import { usageError } from "../errors/cliError.js";
 import { SYSTEM_LEADER_ROLE } from "../role/systemRoles.js";
+import { currentManagedRuntime } from "../runtime/managedCaller.js";
 import { describeEnvironmentPlan } from "../task/taskActivation.js";
 import { cancelTaskActivation, requestTaskActivation, taskActivationOperationRef } from "../task/taskActivationService.js";
-import { taskLocalActor } from "./taskActor.js";
+import { taskLocalActor } from "../task/taskAuthority.js";
 /**
  * Explicit Activation requests.
  *
@@ -52,10 +52,6 @@ function requestActivation(args, store, options) {
         actorId: caller.actorId,
         authorityRef: caller.authorityRef,
         environmentPlan,
-        // The activation-request command is the explicit activation boundary, so
-        // every request it records carries an explicit provable origin (task-32
-        // §2.4). A develop submission records its own request with `submit-develop`.
-        origin: "explicit",
         ...(caller.planningRunId === undefined ? {} : { callerRunId: caller.planningRunId })
     }, now));
     // An immediate request has nothing left to wait for, so ask the Controller to
@@ -65,7 +61,7 @@ function requestActivation(args, store, options) {
         store.transaction((tx) => {
             enqueueWork(tx, { kind: "task", taskId }, "activation-requested", now, [{ type: "task", id: taskId }]);
         });
-        void options.runtime?.notifyMailboxChanged?.({ kind: "task", taskId });
+        void options.runtime?.notifyMailboxChanged({ kind: "task", taskId });
     }
     const request = result.request;
     const lines = [

package/dist/commands/taskAgentCapabilities.js

@@ -0,0 +1,9 @@
+import { exactPositionals, parseTail } from "./taskCommandSupport.js";
+export function parseTaskAgentCapabilityQuery(args) {
+    const usage = "Usage: yui task role capabilities <task> <role> [--error <event-id>] [--refresh]";
+    const parsed = parseTail(args, new Set(["--error"]), usage, new Set(["--refresh"]));
+    exactPositionals(parsed.positionals, 2, usage);
+    const errorId = parsed.options.get("--error");
+    return { taskId: parsed.positionals[0], roleName: parsed.positionals[1],
+        ...(errorId === undefined ? {} : { errorId }), refresh: parsed.options.has("--refresh") };
+}

package/dist/commands/taskCommandSupport.js

@@ -0,0 +1,155 @@
+import { taskNotFound, usageError } from "../errors/cliError.js";
+import { createTaskEvent } from "../event/taskEvent.js";
+import { formatTimestamp } from "../output/timePresentation.js";
+import { SYSTEM_LEADER_ROLE as LEADER_ROLE } from "../role/systemRoles.js";
+import { currentManagedRuntime } from "../runtime/managedCaller.js";
+import { taskLocalActor as resolveTaskLocalActor } from "../task/taskAuthority.js";
+export function recordTaskEvent(store, taskId, type, payload, now) {
+    return recordTaskEventRecord(store, taskId, type, payload, now);
+}
+export function leaderActionEventPayload(store, taskId, options) {
+    const caller = currentManagedRuntime(store, options.environment, taskId, "leader");
+    // A long-lived Session may be handling direct input while another request
+    // awaits admission. The Role's active pointer cannot prove command origin.
+    return caller === undefined ? {} : { leaderNativeSessionId: caller.nativeSessionId };
+}
+export function recordTaskEventRecord(store, taskId, type, payload, now) {
+    const event = createTaskEvent(store.nextEventId(taskId), taskId, type, payload, now);
+    store.saveEvent(taskId, event);
+    return event;
+}
+export function requireTask(store, taskId) {
+    const id = requiredText(taskId, "Task id");
+    const task = store.getTask(id);
+    if (task === null)
+        throw taskNotFound(id);
+    return task;
+}
+export function assertTaskOpen(task) {
+    if (task.status === "completed") {
+        throw usageError(`Task ${task.id} is completed; reopen it before continuing.`);
+    }
+    if (task.status === "archived")
+        throw usageError(`Task is archived: ${task.id}.`);
+    if (task.status === "cancelled")
+        throw usageError(`Task is retired: ${task.id}.`);
+}
+export function taskActor(store, options, taskId) {
+    return resolveTaskLocalActor(store, options.environment, taskId);
+}
+export function parseMultiValueTail(args, valueOptions, repeatOptions, usage, flagOptions = new Set()) {
+    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) && !flagOptions.has(value)) {
+            throw usageError(`Unsupported option: ${value}.`, usage);
+        }
+        if (flagOptions.has(value)) {
+            if (options.has(value))
+                throw usageError(`Option may only be specified once: ${value}.`, usage);
+            options.set(value, "");
+            continue;
+        }
+        if (repeatOptions.has(value)) {
+            const optionValue = args[index + 1];
+            if (optionValue === undefined || optionValue.startsWith("--")) {
+                throw usageError(`${value} is required.`, usage);
+            }
+            const existing = multiOptions.get(value) ?? [];
+            multiOptions.set(value, [...existing, 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 };
+}
+export function parseTail(args, valueOptions, usage, flagOptions = new Set()) {
+    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) && !flagOptions.has(value)) {
+            throw usageError(`Unsupported option: ${value}.`, usage);
+        }
+        if (options.has(value))
+            throw usageError(`Option may only be specified once: ${value}.`, usage);
+        if (flagOptions.has(value)) {
+            options.set(value, "");
+            continue;
+        }
+        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 };
+}
+export function requiredOption(options, name) {
+    return requiredText(options.get(name), name);
+}
+export function optionalNonEmptyOption(options, name) {
+    if (!options.has(name))
+        return undefined;
+    return requiredText(options.get(name), name);
+}
+export function exactPositionals(values, count, usage) {
+    if (values.length !== count || values.some((value) => value.trim().length === 0)) {
+        throw usageError(usage);
+    }
+}
+export function requiredText(value, label) {
+    const normalized = value?.trim();
+    if (normalized === undefined || normalized.length === 0)
+        throw usageError(`${label} is required.`);
+    return normalized;
+}
+export function trimmed(value) {
+    const normalized = value?.trim();
+    return normalized === undefined || normalized.length === 0 ? undefined : normalized;
+}
+export function presentTime(value, timeZone) {
+    return formatTimestamp(value, timeZone);
+}
+export function output(value, data) {
+    return data === undefined
+        ? { kind: "output", output: value }
+        : { kind: "output", output: value, data };
+}
+export function clock(options) {
+    return options.now?.() ?? new Date();
+}
+export function taskMailbox(taskId) {
+    return { kind: "task", taskId };
+}
+export function roleMailbox(taskId, roleName) {
+    return { kind: "role", taskId, roleName };
+}
+export function leaderMailbox(taskId) {
+    return roleMailbox(taskId, LEADER_ROLE);
+}
+export function taskRef(id) {
+    return { type: "task", id };
+}
+export function notifyMailbox(runtime, target) {
+    void runtime?.notifyMailboxChanged(target);
+}

package/dist/commands/taskCommandTypes.js

@@ -0,0 +1 @@
+export {};