@zq-silk/yui 2.15.0 → 2.17.0

package/dist/cli/commandCatalog.js

@@ -176,13 +176,15 @@ const roleChildren = [
     },
     { name: "list", discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment", "global"] }, summary: "List global Roles." },
     { name: "show", discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment", "global"] }, summary: "Show one global Role.", usage: "yui config role show <name>" },
+    { name: "enable", discovery: { surface: "public", audiences: ["public", "operator"] }, summary: "Enable new execution and template selection; does not start a Session.", usage: "yui config role enable <name>" },
+    { name: "disable", discovery: { surface: "public", audiences: ["public", "operator"] }, summary: "Disable new execution and template selection; keeps running Sessions and input.", usage: "yui config role disable <name>" },
     {
         name: "update", discovery: { surface: "public", audiences: ["public", "operator"] },
         summary: "Update a global Role.",
         usage: "yui config role update <name> [profile options] [clear options]",
-        options: ["--agent", "--workspace", ...roleProfileOptions, ...roleAgentOptions,
+        options: ["--enabled", "--agent", "--workspace", ...roleProfileOptions, ...roleAgentOptions,
             ...roleProfileClearOptions, ...roleAgentClearOptions, "--yes"],
-        optionValues: roleAgentOptionValues,
+        optionValues: { ...roleAgentOptionValues, "--enabled": ["true", "false"] },
         fileOptions: ["--workspace"]
     },
     { name: "remove", discovery: { surface: "public", audiences: ["public", "operator"] }, summary: "Remove a global Role.", usage: "yui config role remove <name>" },
@@ -238,17 +240,19 @@ const profileChildren = [
         name: "add", discovery: { surface: "public", audiences: ["public", "operator"] },
         summary: "Add a reusable Agent Profile that inherits Worker runtime or selects one explicit Agent.",
         usage: "yui config profile add <id> [--access <read|write>] [--inherit-worker | --agent <id> [--model <model>] [--effort <effort>]] [Profile settings]",
-        options: ["--access", ...agentProfileOptions],
-        optionValues: { "--access": ["read", "write"] }
+        options: ["--enabled", "--access", ...agentProfileOptions],
+        optionValues: { "--enabled": ["true", "false"], "--access": ["read", "write"] }
     },
     { name: "list", discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment", "global"] }, summary: "List Agent Profiles." },
     { name: "show", discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment", "global"] }, summary: "Show one Agent Profile.", usage: "yui config profile show <id>" },
+    { name: "enable", discovery: { surface: "public", audiences: ["public", "operator"] }, summary: "Enable new Profile applications; existing Task bindings are unchanged.", usage: "yui config profile enable <id>" },
+    { name: "disable", discovery: { surface: "public", audiences: ["public", "operator"] }, summary: "Disable new Profile applications without deleting configuration.", usage: "yui config profile disable <id>" },
     {
         name: "update", discovery: { surface: "public", audiences: ["public", "operator"] },
         summary: "Update an Agent Profile's behavior or runtime source.",
         usage: "yui config profile update <id> [--access <read|write>] [--inherit-worker | [--agent <id>] [--model <model>|--clear-model] [--effort <effort>|--clear-effort]] [Profile settings]",
-        options: ["--access", ...agentProfileOptions, ...agentProfileClearOptions],
-        optionValues: { "--access": ["read", "write"] }
+        options: ["--enabled", "--access", ...agentProfileOptions, ...agentProfileClearOptions],
+        optionValues: { "--enabled": ["true", "false"], "--access": ["read", "write"] }
     },
     { name: "remove", discovery: { surface: "public", audiences: ["public", "operator"] }, summary: "Remove a custom Agent Profile.", usage: "yui config profile remove <id>" },
     { name: "reset", discovery: { surface: "public", audiences: ["public", "operator"] }, summary: "Reset all built-in Agent Profiles." }
@@ -688,7 +692,7 @@ const taskChildren = [
         name: "role", discovery: { surface: "managed", audiences: ["operator", "leader"] },
         summary: "Manage Roles within a Task.",
         sections: [{ id: "manage", title: "Commands", entries: [
-                    "add", "list", "status", "show", "update", "remove", "bind", "unbind",
+                    "add", "list", "status", "show", "update", "enable", "disable", "remove", "bind", "unbind",
                     "capabilities", "session", "interrupt", "view", "takeover", "release"
                 ] }],
         children: [
@@ -707,6 +711,8 @@ const taskChildren = [
                 options: ["--cursor"]
             },
             { name: "show", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Show one Task Role.", usage: "yui task role show <task> <role> [--cursor <cursor>]", options: ["--cursor"] },
+            { name: "enable", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Enable this Task Role; does not change Task execution authority.", usage: "yui task role enable <task> <role>" },
+            { name: "disable", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Block new execution of this Task Role without stopping its current Run.", usage: "yui task role disable <task> <role>" },
             { name: "capabilities", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Read native options using this Role's desired or exact failed launch configuration.",
                 usage: "yui task role capabilities <task> <role> [--error <event-id>] [--refresh]",
                 options: ["--error", "--refresh"] },
@@ -714,9 +720,9 @@ const taskChildren = [
                 name: "update", discovery: { surface: "managed", audiences: ["operator", "leader"] },
                 summary: "Update a Task Role; Agent settings target the named or active binding without switching it.",
                 usage: "yui task role update <task> <role> [--profile <id>] [--agent <id>] [--environment <preparation-id> | --managed-environment] [Role and Agent settings]",
-                options: ["--profile", "--agent", "--environment", "--managed-environment", ...roleProfileOptions, ...roleAgentOptions,
+                options: ["--enabled", "--profile", "--agent", "--environment", "--managed-environment", ...roleProfileOptions, ...roleAgentOptions,
                     ...roleProfileClearOptions, ...roleAgentClearOptions, "--yes"],
-                optionValues: roleAgentOptionValues
+                optionValues: { ...roleAgentOptionValues, "--enabled": ["true", "false"] }
             },
             { name: "remove", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Remove a Task Role.", usage: "yui task role remove <task> <role>" },
             { name: "bind", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Bind and activate an Agent for a Task Role.", usage: "yui task role bind <task> <role> <agent-id>" },
@@ -1394,7 +1400,7 @@ export const ROOT_COMMAND = buildNode({
                     examples: ["yui config profile list", "yui config profile show implementer"],
                     sections: [
                         { id: "inspect", title: "Inspect", entries: ["list", "show"] },
-                        { id: "manage", title: "Manage", entries: ["add", "update", "remove", "reset"] }
+                        { id: "manage", title: "Manage", entries: ["add", "update", "enable", "disable", "remove", "reset"] }
                     ],
                     children: profileChildren
                 },
@@ -1404,7 +1410,7 @@ export const ROOT_COMMAND = buildNode({
                     examples: ["yui config role list", "yui config role show operator"],
                     sections: [
                         { id: "inspect", title: "Inspect", entries: ["list", "show"] },
-                        { id: "manage", title: "Manage", entries: ["add", "update", "remove", "bind", "unbind"] }
+                        { id: "manage", title: "Manage", entries: ["add", "update", "enable", "disable", "remove", "bind", "unbind"] }
                     ],
                     children: roleChildren
                 },

package/dist/cli/interactionCandidates.js

@@ -21,9 +21,22 @@ export async function getSelectionCandidates(selector, ports, args) {
             return { ...set, defaultValue };
         }
         case "agent-profiles":
-            return entities("Agent Profile", "Select Agent Profile", await list(ports, "profile.list", {}), ["id", "revision", "defaultAccess", "agentId"]);
-        case "global-roles":
-            return entities("global role", "Select global Role", await list(ports, "role.list", {}), ["name", "activeAgentId", "workspace"]);
+            return entities("Agent Profile", "Select Agent Profile", (await list(ports, "profile.list", {}))
+                .filter(p => selector.actionTarget || p.enabled !== false
+                && p.effectiveRuntime?.status !== "unavailable")
+                .map(p => ({ ...p, availability: p.enabled === false ? "disabled" : "enabled" })), ["id", "availability", "revision", "defaultAccess", "agentId"]);
+        case "global-roles": {
+            let roles = await list(ports, "role.list", {});
+            // Review uses a Task-local binding first; a disabled same-named template
+            // must not hide an independently enabled existing Reviewer (or vice versa).
+            if (args[0] === "task" && args[1] === "review" && args[2] === "request" && args[3] !== undefined) {
+                const local = await list(ports, "task.role.list", { taskId: args[3] });
+                roles = [...roles.filter(r => !local.some(t => t.name === r.name)), ...local];
+            }
+            return entities("global role", "Select global Role", roles
+                .filter(r => selector.actionTarget && !(args[0] === "session" && args[1] === "enter") || r.enabled !== false)
+                .map(r => ({ ...r, availability: r.enabled === false ? "disabled" : "enabled" })), ["name", "availability", "activeAgentId", "workspace"]);
+        }
         case "jobs":
             return entities("job", "Select job", await list(ports, "jobs.list", {}), ["id", "type", "status"]);
         case "input-requests": {
@@ -41,9 +54,11 @@ export async function getSelectionCandidates(selector, ports, args) {
             const taskId = dependencyValue(selector, args);
             if (taskId === undefined)
                 return null;
-            const roles = orderRoleOptions(await list(ports, "task.role.list", { taskId }));
+            const roles = orderRoleOptions((await list(ports, "task.role.list", { taskId }))
+                .filter(r => selector.actionTarget || r.enabled !== false))
+                .map(r => ({ ...r, availability: r.enabled === false ? "disabled" : "enabled" }));
             return entities("task role", `Select Task role: ${taskId}`, roles, [
-                "name", "kind", "activeAgentId"
+                "name", "availability", "kind", "activeAgentId"
             ]);
         }
         case "task-decisions": {

package/dist/cli/interactionPolicy.js

@@ -92,7 +92,7 @@ export const INTERACTION_POLICIES = Object.freeze([
             "--search": "value"
         }
     },
-    ...["show", "update", "remove", "enter", "context"].map((command) => ({
+    ...["show", "update", "remove", "enable", "disable", "enter", "context"].map((command) => ({
         commandPath: command === "enter" || command === "context"
             ? ["session", command]
             : ["config", "role", command],
@@ -129,12 +129,13 @@ export const INTERACTION_POLICIES = Object.freeze([
         commandPath: ["config", "profile", "add"],
         selectors: [],
         trailingOptions: {
+            "--enabled": "value",
             "--description": "value", "--instructions": "value",
             "--skill": "value", "--agent": "value", "--model": "value",
             "--effort": "value", "--access": "value", "--inherit-worker": "flag"
         }
     },
-    ...["show", "update", "remove"].map((command) => ({
+    ...["show", "update", "remove", "enable", "disable"].map((command) => ({
         commandPath: ["config", "profile", command],
         selectors: [{
                 argumentIndex: 3,
@@ -145,7 +146,7 @@ export const INTERACTION_POLICIES = Object.freeze([
         ...(command === "update"
             ? {
                 trailingOptions: {
-                    "--description": "option-like-value",
+                    "--enabled": "value", "--description": "option-like-value",
                     "--instructions": "option-like-value", "--skill": "value",
                     "--agent": "value", "--inherit-worker": "flag",
                     "--model": "option-like-value", "--effort": "option-like-value",
@@ -380,7 +381,7 @@ export const INTERACTION_POLICIES = Object.freeze([
         commandPath: ["task", "role", "list"],
         selectors: [{ argumentIndex: 3, entity: "task", provider: "tasks", actionTarget: true }]
     },
-    ...["show", "status", "update", "remove"].map((command) => ({
+    ...["show", "status", "update", "remove", "enable", "disable"].map((command) => ({
         commandPath: ["task", "role", command],
         selectors: [
             { argumentIndex: 3, entity: "task", provider: "tasks", actionTarget: true },

package/dist/cli/roleWizard.js

@@ -281,6 +281,7 @@ async function settingsSection(title, io, taskRole) {
 }
 async function updateRoleSettings(args, role, ports, io, taskRole) {
     const fields = [
+        { value: "enabled", cells: ["Enabled (not Session state)", role.enabled === false ? "false" : "true"] },
         profileChoice("description", "Description", role.description),
         profileChoice("responsibilities", "Responsibilities", role.responsibilities),
         profileChoice("constraints", "Constraints", role.constraints),
@@ -292,6 +293,11 @@ async function updateRoleSettings(args, role, ports, io, taskRole) {
     const field = await choose("Role settings", fields, [TEXT_COLUMN, { header: "Current", minWidth: 12, maxWidth: 52 }], io, undefined, "field");
     if (field === undefined)
         return { kind: "cancelled", args };
+    if (field === "enabled") {
+        const value = await choose("Allow new execution; running Sessions are not stopped", [{ value: "true", cells: ["Enabled"] }, { value: "false", cells: ["Disabled"] }], [TEXT_COLUMN], io, role.enabled === false ? "false" : "true", "enabled");
+        return value === undefined ? { kind: "cancelled", args }
+            : { kind: "resolved", args: [...args, "--enabled", value] };
+    }
     if (field === "active-agent") {
         const target = await selectActiveAgent(role, ports, io);
         if (target === undefined)
@@ -672,6 +678,7 @@ function asRole(value) {
     }));
     return {
         name,
+        enabled: input.enabled !== false,
         activeAgentId,
         agentBindings,
         ...(stringField(input, "workspace") === undefined ? {} : { workspace: stringField(input, "workspace") }),

package/dist/commands/globalRoleCommands.js

@@ -10,6 +10,7 @@ import { inboxEntryCategory } from "../message/inboxTurn.js";
 import { checkCurrentSkills, SKILL_REUSE_RULE } from "../context/currentSkills.js";
 import { runtimeDiagnosticGroups, runtimeDiagnosticEvidence } from "../controller/globalRuntimeAttention.js";
 import { roleSkillIds } from "../context/roleSessionContext.js";
+import { isEnabled } from "../role/availability.js";
 import { createRoleSessionSet, recordRoleAgentSession } from "../executor/agentExecutor.js";
 import { resolveEffectiveLaunch } from "../executor/effectiveLaunch.js";
 import { managedGlobalRoleWorkspace } from "../storage/homeLayout.js";
@@ -96,6 +97,12 @@ export function runGlobalRoleCommand(args, store, options = {}) {
         case "show": return showRole(rest, store);
         case "context": return roleContext(rest, store, options);
         case "update": return updateRole(rest, store, options);
+        case "enable":
+        case "disable": {
+            if (rest.length !== 1)
+                throw usageError(`Usage: yui config role ${command} <role>`);
+            return updateRole([rest[0], "--enabled", String(command === "enable")], store, options);
+        }
         case "remove": return removeRole(rest, store);
         case "bind": return bindRole(rest, store);
         case "unbind": return unbindRole(rest, store);
@@ -292,7 +299,7 @@ function listRoles(args, store) {
     for (const name of SYSTEM_ROLE_NAMES) {
         const role = store.getGlobalRole(name);
         rows.set(name, role === null
-            ? [name, "system", "?", "?", "?", "?"]
+            ? [name, "system", "?", "?", "?", "?", "?"]
             : roleListRow(role, "system"));
     }
     for (const role of store.listGlobalRoles()) {
@@ -305,6 +312,7 @@ function listRoles(args, store) {
     return `${renderTable("Roles", [
         { header: "Role", minWidth: 4, maxWidth: 24 },
         { header: "Kind", minWidth: 6, maxWidth: 8 },
+        { header: "Enabled", minWidth: 7, maxWidth: 8 },
         { header: "Active Agent", minWidth: 8, maxWidth: 20 },
         { header: "Model", minWidth: 8, maxWidth: 22 },
         { header: "Effort", minWidth: 8, maxWidth: 14 },
@@ -344,6 +352,9 @@ function updateRole(args, store, options) {
     const workspace = trimmed(parsed.one("--workspace"));
     const next = store.transaction((tx) => {
         const role = requireRole(name, tx);
+        if (parsed.seen.size === 1 && parsed.has("--enabled")
+            && isEnabled(role) === roleProfilePatch(parsed).enabled)
+            return role;
         const changesLaunchContext = hasRoleLaunchContextOptions(parsed);
         const changesAgentConfig = hasAgentConfigOptions(parsed);
         if (changesLaunchContext || changesAgentConfig) {
@@ -971,7 +982,7 @@ function presentRole(title, role, store) {
 }
 function roleListRow(role, kind) {
     const summary = activeRoleSummary(role);
-    return [role.name, kind, summary.agent, summary.model, summary.effort, role.workspace];
+    return [role.name, kind, String(isEnabled(role)), summary.agent, summary.model, summary.effort, role.workspace];
 }
 function renderMissingSystemRole(name) {
     return [

package/dist/commands/operatorCommands.js

@@ -1,4 +1,5 @@
 import { agentAdapterLabel as adapterLabel } from "../agent/adapterCatalog.js";
+import { assertRoleEnabled } from "../role/availability.js";
 import { usageError } from "../errors/cliError.js";
 import { createRoleSessionSet } from "../executor/agentExecutor.js";
 import { TASK_SUBMISSION_INTENTS } from "../message/message.js";
@@ -222,6 +223,7 @@ function resumeSession(args, store) {
 export function applyOperatorSessionControl(control, store, now = new Date()) {
     return store.transaction((tx) => {
         const role = requireOperator(tx);
+        assertRoleEnabled(role);
         const binding = role.agentBindings[control.targetAgentId];
         if (binding === undefined) {
             throw usageError(`Operator Agent is not bound: ${control.targetAgentId}.`);

package/dist/commands/profileCommands.js

@@ -1,4 +1,5 @@
 import { usageError } from "../errors/cliError.js";
+import { isEnabled, parseEnabled } from "../role/availability.js";
 import { defaultTableWidth, renderTable } from "../output/table.js";
 import { BUILTIN_PROFILE_IDS, builtinAgentProfileInputs, createAgentProfile, updateAgentProfile } from "../profile/agentProfile.js";
 import { resolveAgentProfileRuntime, resolveAgentProfileView } from "../profile/agentProfileRuntime.js";
@@ -35,7 +36,7 @@ export function previewProfileAgentConfigurationMutation(args, store) {
     else {
         return undefined;
     }
-    const runtime = resolveAgentProfileRuntime(profile, store);
+    const runtime = resolveAgentProfileRuntime(profile, store, { configurationOnly: true });
     if (runtime.status === "unavailable")
         throw usageError(runtime.reason);
     return {
@@ -51,6 +52,11 @@ export function runProfileCommand(args, store, now = () => new Date(), options =
         case "list": return listProfiles(rest, store);
         case "show": return showProfile(rest, store);
         case "update": return updateProfile(rest, store, now(), options);
+        case "enable":
+        case "disable": {
+            const id = oneArg(rest, `Usage: yui config profile ${command} <id>`);
+            return updateProfile([id, "--enabled", String(command === "enable")], store, now(), options);
+        }
         case "remove": return removeProfile(rest, store);
         case "reset": return resetProfiles(rest, store, now());
         default:
@@ -68,6 +74,7 @@ function addProfile(args, store, now, options) {
     assertOptionPairs(parsed);
     const profile = createAgentProfile({
         id,
+        ...(parsed.has("--enabled") ? { enabled: parseEnabled(parsed.one("--enabled")) } : {}),
         defaultAccess: parseAccess(parsed.one("--access") ?? "read"),
         ...profileValues(parsed),
         runtime: addedRuntime(parsed, usage)
@@ -91,6 +98,7 @@ function listProfiles(args, store) {
         ? "No Agent Profiles found.\n"
         : `${renderTable("Agent Profiles", [
             { header: "Profile", minWidth: 7, maxWidth: 24 },
+            { header: "Enabled", minWidth: 7, maxWidth: 8 },
             { header: "Revision", minWidth: 8, maxWidth: 10 },
             { header: "Access", minWidth: 6, maxWidth: 8 },
             { header: "Runtime", minWidth: 9, maxWidth: 14 },
@@ -109,6 +117,7 @@ function showProfile(args, store) {
     return {
         output: `${[
             `Agent Profile: ${profile.id}`,
+            `Enabled: ${isEnabled(profile)}`,
             `Revision: ${profile.revision}`,
             `Default access: ${profile.defaultAccess}`,
             `Description: ${profile.description ?? "-"}`,
@@ -140,8 +149,14 @@ function updateProfile(args, store, now, options) {
         throw usageError("At least one Profile option is required.", usage);
     assertOptionPairs(parsed);
     const current = requireProfile(store, id);
+    if (parsed.seen.size === 1 && parsed.has("--enabled")
+        && isEnabled(current) === parseEnabled(parsed.one("--enabled"))) {
+        return { output: `Agent Profile ${id} is already ${isEnabled(current) ? "enabled" : "disabled"}\n`,
+            data: resolveAgentProfileView(current, store) };
+    }
     const runtime = updatedRuntime(current, parsed, usage);
     const updated = updateAgentProfile(current, {
+        ...(parsed.has("--enabled") ? { enabled: parseEnabled(parsed.one("--enabled")) } : {}),
         ...(parsed.has("--access") ? { defaultAccess: parseAccess(parsed.one("--access")) } : {}),
         ...profilePatch(parsed),
         ...(runtime === undefined ? {} : { runtime })
@@ -187,6 +202,7 @@ function resetProfiles(args, store, now) {
     };
 }
 const BASE_OPTIONS = [
+    ["--enabled", "value"],
     ["--access", "value"],
     ["--description", "value"],
     ["--instructions", "value"],
@@ -307,7 +323,7 @@ function assertRuntimeSourceOptions(parsed, usage) {
 function validateExplicitRuntime(profile, store, options) {
     if (profile.runtime.source !== "explicit")
         return;
-    const runtime = resolveAgentProfileRuntime(profile, store);
+    const runtime = resolveAgentProfileRuntime(profile, store, { configurationOnly: true });
     if (runtime.status === "unavailable")
         throw usageError(runtime.reason);
     options.validateAgentConfiguration?.({
@@ -320,6 +336,7 @@ function profileListRow(view) {
     const { profile, runtime } = view;
     return [
         profile.id,
+        String(isEnabled(profile)),
         String(profile.revision),
         profile.defaultAccess,
         runtime.source,

package/dist/commands/roleConfiguration.js

@@ -1,4 +1,5 @@
 import { usageError } from "../errors/cliError.js";
+import { parseEnabled } from "../role/availability.js";
 import { defaultRoleAgentConfig, resolveAgentAdapter } from "../executor/agentAdapter.js";
 const PROFILE_OPTIONS = [
     ["--description", "value"],
@@ -64,6 +65,7 @@ export function roleOptionSpecs(input) {
         ...(input.includeAgent === true ? [["--agent", "value"]] : []),
         ...(input.includeWorkspace === true ? [["--workspace", "value"]] : []),
         ...(input.update ? [["--yes", "flag"]] : []),
+        ...(input.update ? [["--enabled", "value"]] : []),
         ...PROFILE_OPTIONS,
         ...agentValueOptions,
         ...agentRepeatableOptions,
@@ -123,6 +125,7 @@ export function roleProfilePatch(parsed) {
         ["--skill", "--clear-skills"]
     ]);
     return {
+        ...(parsed.has("--enabled") ? { enabled: parseEnabled(parsed.one("--enabled")) } : {}),
         ...(parsed.has("--description") ? { description: requiredText(parsed.one("--description")) } : {}),
         ...(parsed.has("--clear-description") ? { description: undefined } : {}),
         ...(parsed.has("--responsibility")

package/dist/commands/taskCommands.js

@@ -3,6 +3,7 @@ import { isDeepStrictEqual } from "node:util";
 import { taskMessageInboxReceipt } from "../message/taskInboxOwnership.js";
 import { agentExecutionComponentLabel } from "../agent/executionComponents.js";
 import { assertLeaderArchiveAdmission } from "../task/leaderArchiveAuthority.js";
+import { assertRoleEnabled, isEnabled } from "../role/availability.js";
 import { createRun, runExecutionObservation, runPurposeAdmitsTaskState } from "../agentRun/agentRun.js";
 import { isGitArtifactRefString, parseGitArtifactRef } from "../artifacts/gitArtifactRef.js";
 import { contextContentDigest, contextSnapshotRef } from "../context/contextSnapshot.js";
@@ -2251,6 +2252,11 @@ function taskRoleCommand(args, store, options) {
         return showTaskRole(rest, store);
     if (command === "update")
         return updateTaskRole(rest, store, options);
+    if (command === "enable" || command === "disable") {
+        if (rest.length !== 2)
+            throw usageError(`Usage: yui task role ${command} <task> <role>`);
+        return updateTaskRole([...rest, "--enabled", String(command === "enable")], store, options);
+    }
     if (command === "remove")
         return output(removeTaskRole(rest, store, options));
     if (command === "bind")
@@ -2751,6 +2757,7 @@ function listTaskRoles(args, store, options) {
     const statuses = inspectTaskRoleRuntimeStatuses(task.id, roles, store, options.runtime?.inspectTaskRolePanes?.(task.id) ?? [], options.now?.() ?? new Date());
     const data = recordPage(statuses.map(status => ({
         roleName: status.roleName, agentId: status.agentId, recordedHealth: status.health,
+        enabled: isEnabled(status.role),
         hostObservation: "not-requested",
         openInput: taskRoleOpenInputLabel(status), activeWork: taskRoleActiveWorkLabel(status),
         lastRun: taskRoleLastRunLabel(status), nativeSession: taskRoleNativeSessionLabel(status),
@@ -2810,6 +2817,9 @@ function updateTaskRole(args, store, options) {
         taskActor(tx, options, task.id);
         const role = requireRole(tx, task.id, roleName);
         const changesEnvironment = parsed.has("--environment") || parsed.has("--managed-environment");
+        if (parsed.seen.size === 1 && parsed.has("--enabled")
+            && isEnabled(role) === roleProfilePatch(parsed).enabled)
+            return role;
         const changesLaunchContext = hasRoleLaunchContextOptions(parsed) || parsed.has("--profile")
             || changesEnvironment;
         const changesAgentConfig = hasAgentConfigOptions(parsed);
@@ -3562,6 +3572,7 @@ function dispatchWork(args, store, options) {
         }
         const roles = lanePlan.roles.map((name) => requireRole(tx, task.id, name));
         for (const role of roles) {
+            assertRoleEnabled(role);
             if (tx.getActiveRun(task.id, role.name) !== null) {
                 throw usageError(`${task.id}/${role.name} already has an active run.`);
             }
@@ -3570,6 +3581,7 @@ function dispatchWork(args, store, options) {
         let workItemForDispatch = prepareWorkItemDispatch(item, now);
         if (lanePlan.roles.length === 0) {
             const role = requireRole(tx, task.id, assignee);
+            assertRoleEnabled(role);
             if (tx.getActiveRun(task.id, role.name) !== null) {
                 throw usageError(`${task.id}/${role.name} already has an active run.`);
             }
@@ -4383,6 +4395,9 @@ function assertTaskReviewRequestLane(store, taskId, reviewerRoleName, reusableRo
     assertReviewerAvailable(store, taskId, reviewerRoleName, reusableRound);
 }
 function assertReviewerAvailable(store, taskId, reviewerRoleName, reusableRound) {
+    const role = store.getRole(taskId, reviewerRoleName);
+    if (role !== null)
+        assertRoleEnabled(role);
     const availability = projectReviewerAvailability(store, taskId, reviewerRoleName);
     if (availability.kind === "available")
         return;
@@ -5001,6 +5016,7 @@ function retryRunOperation(args, store, options) {
             throw usageError(`Task does not admit ${previous.purpose} retry: ${task.id}/${task.status}.`);
         }
         const role = requireRole(tx, task.id, previous.roleName);
+        assertRoleEnabled(role);
         if (tx.getActiveRun(task.id, role.name) !== null) {
             throw usageError(`${task.id}/${role.name} already has an active run.`);
         }

package/dist/commands/taskRoleRuntimeStatus.js

@@ -1,5 +1,6 @@
 import { isDeepStrictEqual } from "node:util";
 import { runExecutionObservation } from "../agentRun/agentRun.js";
+import { isEnabled, roleDisabledReason } from "../role/availability.js";
 import { hasRuntimeCleanupObligation, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { currentProviderConversation, managedProviderTurnId } from "../runtime/providerRuntimeIdentity.js";
 import { isRoleRunStalled, latestStallProgressAt } from "../scheduler/roleRunStall.js";
@@ -118,6 +119,8 @@ export function renderTaskRoleRuntimeStatus(status) {
         `Task Role status: ${status.taskId}/${status.roleName}`,
         "",
         `  Health           ${status.health}`,
+        `  Enabled          ${isEnabled(status.role)}`,
+        ...(!isEnabled(status.role) ? [`  Availability     ${roleDisabledReason(status.role)}`] : []),
         `  Reason           ${status.healthReason}`,
         `  Open inputs      ${status.openInputRequestCount}`,
         `  Agent            ${status.agentId}`,

package/dist/controller/agentJobControl.js

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { assertRoleEnabled } from "../role/availability.js";
 import { mkdirSync } from "node:fs";
 import { isDeepStrictEqual } from "node:util";
 import { join } from "node:path";
@@ -63,7 +64,8 @@ function requireTaskTarget(store, target, runnable = true) {
     const task = store.getTask(target.taskId);
     if (!task || runnable && (task.status !== "active" || task.executionGate.state !== "enabled"))
         throw new Error("Task Agent requires an active, execution-enabled Task.");
-    if (!store.getRole(target.taskId, target.roleName))
+    const role = store.getRole(target.taskId, target.roleName);
+    if (!role)
         throw new Error("Task Agent Role is unavailable.");
     const recipient = taskRecipient(store, target);
     if (recipient.ownerRunId) {
@@ -117,6 +119,7 @@ function ownedRole(store, home, job, runId, now) {
     const jobOwner = { scope: job.scope, jobId: job.id, ...(isolated ? { runId } : {}) };
     const existing = store.getGlobalRole(name);
     if (existing) {
+        assertRoleEnabled(existing);
         if (!isDeepStrictEqual(existing.jobOwner, jobOwner) || existing.activeAgentId !== job.configuration.target.agentId) {
             throw new Error("Job Role binding changed; inspect its Session/configuration before dispatch.");
         }
@@ -155,6 +158,9 @@ function queueAttempt(store, home, job, runId, index, now) {
     const inputControl = { action: "queue", requestId: `job-agent:${runId}:${index}` };
     let messageId;
     if (recipient.scope === "global") {
+        const role = store.getGlobalRole(recipient.roleName);
+        if (role !== null)
+            assertRoleEnabled(role);
         messageId = store.nextGlobalRoleMessageId();
         let message = createGlobalRoleMessage(messageId, recipient.roleName, body, "system", { type: "system" }, now, { inputControl });
         const set = store.getGlobalRoleSessionSet(recipient.roleName);
@@ -165,6 +171,7 @@ function queueAttempt(store, home, job, runId, index, now) {
     }
     else {
         requireTaskTarget(store, { ...recipient });
+        assertRoleEnabled(store.getRole(recipient.taskId, recipient.roleName));
         const resolved = taskRecipient(store, recipient);
         messageId = store.nextMessageId(recipient.taskId);
         store.saveMessage(recipient.taskId, createTaskMessage(messageId, recipient.taskId, body, "system", { type: "system" }, now, { ...(resolved.ownerRunId ? { recipient: resolved } : {}), inputControl }));
@@ -256,6 +263,7 @@ export function controlAgentJob(store, home, job, input, now) {
         if (op === "session-new") {
             if (!role)
                 throw new Error("Create the Job Role first.");
+            assertRoleEnabled(role);
             assertRoleRuntimeMutationAllowed(store, { scope: "global", roleName }, "Job Session replacement");
             const set = store.getGlobalRoleSessionSet(roleName);
             const old = set?.sessions[set.activeAgentId];

package/dist/controller/fileSchedulerStoreAdapter.js

@@ -3145,9 +3145,9 @@ function recordTaskRuntimeNativeSession(store, input, now) {
     if (task.status === "archived") {
         throw new Error(`Cannot register a native session for archived Task: ${input.taskId}.`);
     }
-    // A Draft registers a Session only for its planning Turn. Admission is decided
-    // by the active Turn's purpose through the one shared invariant, so a Draft
-    // still cannot open an execution Session before activation.
+    // A Draft admits its first planning Run, restoration of that exact Session,
+    // or the selected successor's initialization after verified replacement.
+    // Ordinary Draft notifications and native hooks cannot create a Session.
     const admittingRun = store.getActiveRun(input.taskId, input.roleName);
     const existingPlanning = activeLiveRoleAgentSession(store.getTaskRoleSessionSet(input.taskId, input.roleName));
     if (!(admittingRun !== null
@@ -3156,6 +3156,9 @@ function recordTaskRuntimeNativeSession(store, input, now) {
         && !(task.status === "draft" && task.executionGate.state === "enabled" && input.roleName === "leader"
             && existingPlanning?.effective.executionAuthority === "planning"
             && existingPlanning.nativeSessionId === input.nativeSessionId)
+        && !(task.status === "draft" && task.executionGate.state === "enabled" && input.roleName === "leader"
+            && input.effective?.executionAuthority === "planning"
+            && draftReplacementInitializationIsCurrent(store, input.taskId, input.agentId))
         && (task.status !== "active" || task.executionGate.state !== "enabled")) {
         throw new Error(`Cannot register a native session for a Task that is not active: ${input.taskId}.`);
     }
@@ -3191,6 +3194,32 @@ function recordTaskRuntimeNativeSession(store, input, now) {
     store.saveRoleSessionSet(updated);
     return updated.sessions[input.agentId];
 }
+/** The existing initialization wake is the launch authority, not historical
+ * planning success or an arbitrary "session-replaced" reason. It is retained
+ * on startup rejection for the normal explicit wake retry/replacement path. */
+function draftReplacementInitializationIsCurrent(store, taskId, agentId) {
+    const sessions = store.getTaskRoleSessionSet(taskId, "leader");
+    if (sessions === null || sessions.activeAgentId !== agentId
+        || sessions.sessions[agentId] !== undefined || sessions.providerBinding !== null
+        || hasRuntimeCleanupObligation(store.getWorkMailbox(runtimeLifecycleTarget({
+            scope: "task", taskId, roleName: "leader"
+        }))))
+        return false;
+    const processing = store.getWorkMailbox({ kind: "role", taskId, roleName: "leader" })?.processing;
+    if (!processing?.owner.startsWith("leader-notification:"))
+        return false;
+    const wake = store.getTaskWake(taskId, processing.owner.slice("leader-notification:".length));
+    if (wake === null || !wake.reasons.includes("session-replaced"))
+        return false;
+    const events = store.listEventsByType(taskId, ["runtime.session-replaced", "notification.delivery"]);
+    const replacement = events.filter(event => event.type === "runtime.session-replaced"
+        && event.payload.roleName === "leader").at(-1);
+    return replacement !== undefined
+        && (wake.refs ?? []).some(ref => ref.type === "event" && ref.taskId === taskId && ref.id === replacement.id)
+        && !events.some(event => event.type === "notification.delivery"
+            && event.payload.attemptId === processing.batchId
+            && event.payload.outcome !== "deferred");
+}
 function recordGlobalRuntimeNativeSession(store, input, now) {
     const role = store.getGlobalRole(input.roleName);
     if (role === null)
@@ -3271,6 +3300,7 @@ function mapRole(store, role) {
     return {
         taskId: role.taskId,
         name: role.name,
+        enabled: role.enabled !== false,
         activeAgentId: role.activeAgentId,
         adapterId: binding.adapterId,
         ...(binding.config.model === undefined ? {} : { model: binding.config.model }),
@@ -3307,8 +3337,9 @@ function taskSessionEffective(store, taskId, roleName, agentId, existing) {
         ?? store.getTaskWorkspace(taskId)
         ?? undefined;
     const effective = resolveEffectiveLaunch({
+        store,
         role,
-        purpose: "execution",
+        purpose: store.getTask(taskId)?.status === "draft" && roleName === "leader" ? "planning" : "execution",
         ...(workspace === undefined ? {} : { workspace }),
         ...(item === null ? {} : { workItemWriteProjectIds: item.writeProjectIds })
     });