@zq-silk/yui 0.2.0 → 0.4.2

package/dist/commands/globalRoleCommands.js

@@ -1,22 +1,24 @@
 import { roleNotFound, usageError } from "../errors/cliError.js";
 import { createRoleSessionSet, recordRoleAgentSession } from "../executor/agentExecutor.js";
-import { resolveAgentAdapter } from "../executor/agentAdapter.js";
-import { resolveAgentEnvironment } from "../agent/agent.js";
+import { resolveEffectiveLaunch } from "../executor/effectiveLaunch.js";
 import { defaultTableWidth, renderTable } from "../output/table.js";
 import { activeRoleSummary, renderRoleDetails } from "../output/rolePresentation.js";
-import { activeRoleAgentBinding, createGlobalRole, createRoleAgentBinding, switchActiveRoleAgent, updateGlobalRole } from "../role/role.js";
+import { activeRoleAgentBinding, createGlobalRole, createRoleAgentBinding, switchActiveRoleAgent, unbindRoleAgent, updateGlobalRole } from "../role/role.js";
 import { isSystemRoleName, SYSTEM_ROLE_NAMES, systemRoleDescription } from "../role/systemRoles.js";
 import { hasAgentConfigOptions, parseRoleOptions, patchRoleAgentBinding, roleOptionSpecs, roleProfileFrom, roleProfilePatch } from "./roleConfiguration.js";
+import { hasRoleLaunchContextOptions, validateConfiguredRoleSkills } from "./roleSkillValidation.js";
+import { assertRoleRuntimeMutationAllowed } from "./roleRuntimeGuard.js";
 export function runGlobalRoleCommand(args, store, options = {}) {
     const [command, ...rest] = args;
     switch (command) {
-        case "add": return addRole(rest, store);
+        case "add": return addRole(rest, store, options);
         case "list": return listRoles(rest, store);
         case "show": return showRole(rest, store);
-        case "update": return updateRole(rest, store);
+        case "update": return updateRole(rest, store, options);
         case "remove": return removeRole(rest, store);
         case "bind": return bindRole(rest, store);
-        case "enter": return enterRole(rest, store, options);
+        case "unbind": return unbindRole(rest, store);
+        case "enter": return enterRole(rest, store);
         case "session": return roleSession(rest, store, options);
         default:
             throw usageError(command === undefined
@@ -24,25 +26,32 @@ export function runGlobalRoleCommand(args, store, options = {}) {
                 : `Unknown command: role ${command}`);
     }
 }
-function addRole(args, store) {
+function addRole(args, store, options) {
     const [rawName, ...tail] = args;
     const name = roleName(rawName);
     const parsed = parseRoleOptions(tail, roleOptionSpecs({
         update: false, includeAgent: true, includeWorkspace: true
     }));
     const agentId = required(parsed.one("--agent"), "--agent");
-    const agent = requireAgent(agentId, store);
     if (parsed.has("--workspace") && trimmed(parsed.one("--workspace")) === undefined) {
         throw usageError("--workspace is required.");
     }
-    const workspace = trimmed(parsed.one("--workspace"))
-        ?? store.getConfig().defaultWorkspace
-        ?? process.cwd();
-    const binding = patchRoleAgentBinding(createRoleAgentBinding(definition(agent)), parsed);
-    const role = createGlobalRole(name, [binding], agent.id, workspace, new Date(), roleProfileFrom(parsed));
-    const created = store.createGlobalRoleIfAbsent(role);
-    if (created === null)
-        throw usageError(`Role already exists: ${name}.`);
+    const now = new Date();
+    const created = store.transaction((tx) => {
+        assertRoleRuntimeMutationAllowed(tx, { scope: "global", roleName: name }, "creation");
+        const agent = requireAgent(agentId, tx);
+        const workspace = trimmed(parsed.one("--workspace"))
+            ?? tx.getConfig().defaultWorkspace
+            ?? process.cwd();
+        const binding = patchRoleAgentBinding(createRoleAgentBinding(definition(agent)), parsed);
+        const profile = roleProfileFrom(parsed);
+        validateConfiguredRoleSkills(options.yuiHome, profile.skills ?? []);
+        const role = createGlobalRole(name, [binding], agent.id, workspace, now, profile);
+        const result = tx.createGlobalRoleIfAbsent(role);
+        if (result === null)
+            throw usageError(`Role already exists: ${name}.`);
+        return result;
+    });
     return presentRole(`Added role ${name}`, created, store);
 }
 function listRoles(args, store) {
@@ -85,10 +94,9 @@ function showRole(args, store) {
         sessions: store.getGlobalRoleSessionSet(name)
     });
 }
-function updateRole(args, store) {
+function updateRole(args, store, options) {
     const [rawName, ...tail] = args;
     const name = roleName(rawName);
-    const role = requireRole(name, store);
     const parsed = parseRoleOptions(tail, roleOptionSpecs({
         update: true, includeAgent: true, includeWorkspace: true
     }));
@@ -102,25 +110,35 @@ function updateRole(args, store) {
         throw usageError("At least one role update option is required.");
     }
     const workspace = trimmed(parsed.one("--workspace"));
-    let bindings = role.agentBindings;
-    if (hasAgentConfigOptions(parsed)) {
-        const agentId = parsed.one("--agent")?.trim() || role.activeAgentId;
-        const agent = requireAgent(agentId, store);
-        const binding = role.agentBindings[agentId] ?? createRoleAgentBinding(definition(agent));
-        const activeSession = store.getGlobalRoleSessionSet(name)?.sessions[agentId];
-        if (agentId === role.activeAgentId && activeSession?.status === "running") {
-            throw usageError("Active Agent settings cannot be changed while its native process is running.");
+    const next = store.transaction((tx) => {
+        const role = requireRole(name, tx);
+        const changesLaunchContext = hasRoleLaunchContextOptions(parsed);
+        const changesAgentConfig = hasAgentConfigOptions(parsed);
+        if (changesLaunchContext || changesAgentConfig) {
+            assertRoleRuntimeMutationAllowed(tx, {
+                scope: "global",
+                roleName: role.name
+            }, "desired launch configuration update");
         }
-        bindings = { ...role.agentBindings, [agentId]: patchRoleAgentBinding(binding, parsed) };
-    }
-    const next = {
-        ...updateGlobalRole(role, {
+        let bindings = role.agentBindings;
+        if (changesAgentConfig) {
+            const agentId = parsed.one("--agent")?.trim() || role.activeAgentId;
+            const agent = requireAgent(agentId, tx);
+            assertOperatorAdapterAvailable(role, agent);
+            const binding = role.agentBindings[agentId] ?? createRoleAgentBinding(definition(agent));
+            bindings = { ...role.agentBindings, [agentId]: patchRoleAgentBinding(binding, parsed) };
+        }
+        const updated = updateGlobalRole(role, {
             ...(workspace === undefined ? {} : { workspace }),
             ...(bindings === role.agentBindings ? {} : { agentBindings: bindings }),
             ...roleProfilePatch(parsed)
-        }, new Date())
-    };
-    store.saveGlobalRole(next);
+        }, new Date());
+        if (changesLaunchContext) {
+            validateConfiguredRoleSkills(options.yuiHome, updated.skills ?? []);
+        }
+        tx.saveGlobalRole(updated);
+        return updated;
+    });
     return renderRoleDetails(`Updated role ${name}`, next, {
         kind: isSystemRoleName(name) ? "system" : "global",
         sessions: store.getGlobalRoleSessionSet(name)
@@ -131,25 +149,51 @@ function bindRole(args, store) {
     const name = roleName(rawName);
     const agentId = required(rawAgentId, "Agent id");
     assertNoArguments(rest, "Role bind usage: yui role bind <role> <agent-id>");
-    const role = requireRole(name, store);
-    const agent = requireAgent(agentId, store);
-    const binding = role.agentBindings[agentId] ?? createRoleAgentBinding(definition(agent));
-    const withBinding = updateGlobalRole(role, {
-        agentBindings: { ...role.agentBindings, [agentId]: binding }
-    }, new Date());
-    if (agentId === role.activeAgentId) {
-        store.saveGlobalRole(withBinding);
-        return presentRole(`Role ${name} already bound to ${agentId}`, withBinding, store);
-    }
-    const existingSet = store.getGlobalRoleSessionSet(name);
-    const activeSession = existingSet?.sessions[role.activeAgentId];
-    try {
-        const switched = switchActiveRoleAgent(withBinding, existingSet ?? createRoleSessionSet({ scope: "global", roleName: name }, role.activeAgentId, new Date()), agentId, { activeRun: false, nativeProcessRunning: activeSession?.status === "running" }, new Date());
-        store.saveGlobalRoleWithSessionSet(switched.role, switched.sessions);
-        return presentRole(`Bound role ${name} to ${agentId}`, switched.role, store);
-    }
-    catch (error) {
-        throw usageError(error instanceof Error ? error.message : String(error));
+    const now = new Date();
+    const result = store.transaction((tx) => {
+        const role = requireRole(name, tx);
+        assertRoleRuntimeMutationAllowed(tx, {
+            scope: "global",
+            roleName: role.name
+        }, "desired Agent binding update");
+        const agent = requireAgent(agentId, tx);
+        assertOperatorAdapterAvailable(role, agent);
+        const binding = role.agentBindings[agentId] ?? createRoleAgentBinding(definition(agent));
+        const withBinding = updateGlobalRole(role, {
+            agentBindings: { ...role.agentBindings, [agentId]: binding }
+        }, now);
+        if (agentId === role.activeAgentId) {
+            tx.saveGlobalRole(withBinding);
+            return {
+                message: `Role ${name} already bound to ${agentId}`,
+                role: withBinding
+            };
+        }
+        const existingSet = tx.getGlobalRoleSessionSet(name);
+        const activeSession = existingSet?.sessions[existingSet.activeAgentId];
+        try {
+            const switched = switchActiveRoleAgent(withBinding, existingSet ?? createRoleSessionSet({ scope: "global", roleName: name }, role.activeAgentId, now), agentId, {
+                activeRun: false,
+                nativeProcessRunning: activeSession !== undefined
+                    && activeSession.status !== "stopped"
+            }, now);
+            tx.saveGlobalRoleWithSessionSet(switched.role, switched.sessions);
+            return { message: `Bound role ${name} to ${agentId}`, role: switched.role };
+        }
+        catch (error) {
+            throw usageError(error instanceof Error ? error.message : String(error));
+        }
+    });
+    return presentRole(result.message, result.role, store);
+}
+function assertOperatorAdapterAvailable(role, agent) {
+    if (role.name !== "operator" || Object.hasOwn(role.agentBindings, agent.id))
+        return;
+    const existing = Object.values(role.agentBindings).find((binding) => binding.adapterId === agent.adapterId);
+    if (existing !== undefined) {
+        throw usageError(`Operator already has a ${agent.adapterId} Agent: ${existing.agentId}. `
+            + "Update that Agent's configuration, or activate another adapter and "
+            + "unbind it before binding this Agent.");
     }
 }
 function removeRole(args, store) {
@@ -158,25 +202,44 @@ function removeRole(args, store) {
     assertNoArguments(rest, "Role remove usage: yui role remove <role>");
     if (isSystemRoleName(name))
         throw usageError(`System role cannot be removed: ${name}`);
-    const role = requireRole(name, store);
-    const active = store.getGlobalRoleSessionSet(name)?.sessions[role.activeAgentId];
-    if (active?.status === "running") {
-        throw usageError(`GlobalRole is active and cannot be removed: ${name}.`);
-    }
-    if (!store.removeGlobalRole(name))
-        throw roleNotFound(name);
+    store.transaction((tx) => {
+        const role = requireRole(name, tx);
+        assertRoleRuntimeMutationAllowed(tx, {
+            scope: "global",
+            roleName: role.name
+        }, "removal");
+        const sessions = tx.getGlobalRoleSessionSet(name);
+        if (Object.values(sessions?.sessions ?? {}).some(({ status }) => status !== "stopped")) {
+            throw usageError(`GlobalRole is active and cannot be removed: ${name}.`);
+        }
+        if (!tx.removeGlobalRole(name))
+            throw roleNotFound(name);
+    });
     return `Removed role ${name}\n`;
 }
-function enterRole(args, store, options) {
+function unbindRole(args, store) {
+    const [rawName, rawAgentId, ...rest] = args;
+    const name = roleName(rawName);
+    const agentId = required(rawAgentId, "Agent id");
+    assertNoArguments(rest, "Role unbind usage: yui role unbind <role> <agent-id>");
+    store.transaction((tx) => {
+        const role = requireRole(name, tx);
+        try {
+            const result = unbindRoleAgent(role, tx.getGlobalRoleSessionSet(name), agentId, new Date());
+            tx.saveGlobalRoleWithSessionSet(result.role, result.sessions);
+        }
+        catch (error) {
+            throw usageError(error instanceof Error ? error.message : String(error));
+        }
+    });
+    return `Unbound Agent ${agentId} from role ${name}\n`;
+}
+function enterRole(args, store) {
     const [rawName, ...rest] = args;
     const name = roleName(rawName);
     assertNoArguments(rest, "Role enter usage: yui role enter <role>");
     const role = requireRole(name, store);
-    const agent = requireAgent(role.activeAgentId, store);
-    const set = store.getGlobalRoleSessionSet(name);
-    const session = set?.sessions[role.activeAgentId] ?? null;
-    const launch = compileGlobalRoleLaunch(role, agent, session?.nativeSessionId, options);
-    return { kind: "enter", role, launch };
+    return { kind: "enter", role };
 }
 function roleSession(args, store, options) {
     const [command, rawName, ...tail] = args;
@@ -192,40 +255,48 @@ function roleSession(args, store, options) {
     if (nativeSessionId.trim() !== nativeSessionId || nativeSessionId.length === 0) {
         throw usageError("Native session id must not contain surrounding whitespace.");
     }
-    const role = requireRole(name, store);
-    const binding = activeRoleAgentBinding(role);
-    const agent = requireAgent(binding.agentId, store);
     const environment = options.env ?? process.env;
-    assertSessionProvenance(command, role, nativeSessionId, environment);
-    const set = store.getGlobalRoleSessionSet(name)
-        ?? createRoleSessionSet({ scope: "global", roleName: name }, role.activeAgentId, new Date());
-    const existing = set.sessions[role.activeAgentId] ?? null;
-    const input = () => ({
-        agentId: binding.agentId,
-        adapterId: binding.adapterId,
-        nativeSessionId,
-        policy: "fixed",
-        status: environment.YUI_ROLE === name ? "running" : "ready"
-    });
-    if (command === "record") {
-        if (existing !== null && existing.nativeSessionId !== nativeSessionId) {
-            throw usageError("GlobalRole session replacement must be explicit.");
+    return store.transaction((tx) => {
+        const role = requireRole(name, tx);
+        assertRoleRuntimeMutationAllowed(tx, {
+            scope: "global",
+            roleName: role.name
+        }, "manual native session update");
+        const binding = activeRoleAgentBinding(role);
+        requireAgent(binding.agentId, tx);
+        assertSessionProvenance(command, role, nativeSessionId, environment);
+        const now = new Date();
+        const set = tx.getGlobalRoleSessionSet(name)
+            ?? createRoleSessionSet({ scope: "global", roleName: name }, role.activeAgentId, now);
+        const existing = set.sessions[role.activeAgentId] ?? null;
+        const input = {
+            agentId: binding.agentId,
+            adapterId: binding.adapterId,
+            nativeSessionId,
+            policy: "fixed",
+            status: environment.YUI_ROLE === name ? "running" : "ready",
+            effective: resolveEffectiveLaunch({ role, purpose: "execution" })
+        };
+        if (command === "record") {
+            if (existing !== null && existing.nativeSessionId !== nativeSessionId) {
+                throw usageError("GlobalRole session replacement must be explicit.");
+            }
+            tx.saveGlobalRoleSessionSet(recordRoleAgentSession(set, input, now));
+            return `Recorded native session for role ${name}\n`;
         }
-        store.saveGlobalRoleSessionSet(recordRoleAgentSession(set, input(), new Date()));
-        return `Recorded native session for role ${name}\n`;
-    }
-    if (existing === null) {
-        throw usageError("Native session replacement requires an existing native session.");
-    }
-    if (existing.status === "running") {
-        throw usageError("Native session replacement is blocked while the native Agent process is running.");
-    }
-    if (existing.nativeSessionId === nativeSessionId) {
-        throw usageError("Native session replacement requires a different native session identity.");
-    }
-    const reason = required(parsed.one("--reason"), "--reason").trim();
-    store.saveGlobalRoleSessionSet(recordRoleAgentSession(set, input(), new Date()));
-    return `Replaced native session for role ${name}\n`;
+        if (existing === null) {
+            throw usageError("Native session replacement requires an existing native session.");
+        }
+        if (existing.status !== "stopped") {
+            throw usageError("Native session replacement is blocked while the native Agent process is running.");
+        }
+        if (existing.nativeSessionId === nativeSessionId) {
+            throw usageError("Native session replacement requires a different native session identity.");
+        }
+        required(parsed.one("--reason"), "--reason");
+        tx.saveGlobalRoleSessionSet(recordRoleAgentSession(set, input, now));
+        return `Replaced native session for role ${name}\n`;
+    });
 }
 function assertSessionProvenance(command, role, nativeSessionId, environment) {
     const values = [
@@ -282,35 +353,6 @@ function parseOptions(args, specs) {
         many: (option) => [...(values.get(option) ?? [])]
     };
 }
-function compileGlobalRoleLaunch(role, agent, nativeSessionId, options) {
-    const adapter = resolveAgentAdapter(agent.adapterId);
-    const input = {
-        agent: definition(agent),
-        config: activeRoleAgentBinding(role).config,
-        workspace: role.workspace,
-        systemPrompt: role.systemPrompt
-    };
-    const compiled = nativeSessionId === undefined
-        ? adapter.compileNew(input)
-        : adapter.compileResume({ ...input, nativeSessionId });
-    const baseEnvironment = options.env ?? process.env;
-    return {
-        command: agent.command,
-        args: compiled.argv,
-        env: stringEnvironment({
-            ...baseEnvironment,
-            ...resolveAgentEnvironment(definition(agent), baseEnvironment),
-            ...(options.yuiHome === undefined ? {} : { YUI_HOME: options.yuiHome }),
-            YUI_ROLE: role.name,
-            YUI_AGENT_ID: agent.id,
-            YUI_ADAPTER_ID: agent.adapterId,
-            YUI_WORKSPACE: role.workspace
-        })
-    };
-}
-function stringEnvironment(environment) {
-    return Object.fromEntries(Object.entries(environment).filter((entry) => entry[1] !== undefined));
-}
 function definition(agent) {
     return { ...agent, baseArgs: [...agent.baseArgs], environment: [...agent.environment], source: "custom" };
 }

package/dist/commands/jobCommands.js

@@ -1,6 +1,7 @@
 import { runtimeError, taskNotFound, usageError } from "../errors/cliError.js";
 import { defaultTableWidth, renderTable } from "../output/table.js";
-import { queueLeaderWakeup } from "../scheduler/wakeupQueue.js";
+import { formatTimestamp } from "../output/timePresentation.js";
+import { enqueueWork } from "../coordination/workMailboxQueue.js";
 const WAKEUP_PREFIX = "leader-wakeup:";
 const RECOVERY_PREFIX = "leader-recovery:";
 /**
@@ -23,6 +24,7 @@ function listJobs(args, store) {
     const jobs = collectJobs(store);
     if (jobs.length === 0)
         return "No scheduler jobs found.\n";
+    const timeZone = store.getConfig().timeZone;
     return `${renderTable("Scheduler jobs", [
         { header: "Job", minWidth: 12, maxWidth: 44 },
         { header: "Task", minWidth: 6, maxWidth: 20 },
@@ -35,7 +37,7 @@ function listJobs(args, store) {
         job.taskId,
         job.kind,
         job.status,
-        job.updatedAt,
+        formatTimestamp(job.updatedAt, timeZone),
         job.detail
     ]), defaultTableWidth())}\n`;
 }
@@ -55,14 +57,17 @@ function collectJobs(store) {
         }
         const failure = store.getLeaderFailure(task.id);
         const notification = store.getOperatorNotification(task.id);
-        if (failure !== null || notification !== null) {
+        const recoveryNotification = notification?.type === "leader-recovery-failed"
+            ? notification
+            : null;
+        if (failure !== null || recoveryNotification !== null) {
             jobs.push({
                 id: `${RECOVERY_PREFIX}${task.id}`,
                 taskId: task.id,
                 kind: "leader-recovery",
                 status: "failed",
-                detail: failure?.message ?? notification?.message ?? "Leader recovery failed.",
-                updatedAt: failure?.lastFailedAt ?? notification?.updatedAt ?? task.updatedAt
+                detail: failure?.message ?? recoveryNotification?.message ?? "Leader recovery failed.",
+                updatedAt: failure?.lastFailedAt ?? recoveryNotification?.updatedAt ?? task.updatedAt
             });
         }
     }
@@ -88,13 +93,18 @@ function retryJob(args, store, options) {
         if (task.status !== "active") {
             throw usageError(`Leader recovery can only be retried for an active Task: ${task.id}.`);
         }
-        if (tx.getLeaderFailure(task.id) === null && tx.getOperatorNotification(task.id) === null) {
+        if (tx.getLeaderFailure(task.id) === null
+            && tx.getOperatorNotification(task.id)?.type !== "leader-recovery-failed") {
             throw usageError(`Job not found: ${id}.`);
         }
         tx.clearLeaderFailure(task.id);
         tx.clearOperatorNotification(task.id);
-        queueLeaderWakeup(tx, task.id, "recovery-retry", now);
+        enqueueWork(tx, { kind: "role", taskId: task.id, roleName: "leader" }, "recovery-retry", now, [{ type: "task", id: task.id }]);
     });
-    runtime.notifyStateChanged(taskId);
+    const target = { kind: "role", taskId, roleName: "leader" };
+    if (runtime.notifyMailboxChanged !== undefined)
+        runtime.notifyMailboxChanged(target);
+    else
+        runtime.notifyStateChanged(taskId);
     return `Retry requested for ${id}\n`;
 }

package/dist/commands/operatorCommands.js

@@ -1,18 +1,42 @@
 import { usageError } from "../errors/cliError.js";
+import { createRoleSessionSet } from "../executor/agentExecutor.js";
+import { listOperatorSessions, prepareOperatorNewSession, prepareOperatorResumeSession } from "../operator/operatorSessionHistory.js";
+import { defaultTableWidth, renderTable } from "../output/table.js";
+import { formatRelativeTimestamp } from "../output/timePresentation.js";
+import { updateGlobalRole } from "../role/role.js";
 import { submitOperatorMessage } from "./taskCommands.js";
-/** Operator is intentionally small: interactive entry is owned by the tmux CLI path. */
+import { readCommandText } from "./textInput.js";
+/** Operator command parsing never launches or attaches a native process. */
 export function runOperatorCommand(args, store, options = {}) {
     const [command, ...rest] = args;
-    if (command !== "submit") {
-        throw usageError(command === undefined
-            ? "Operator command is required."
-            : `Unknown command: operator ${command}`);
+    switch (command) {
+        case "list": return listSessions(rest, store, options);
+        case "new": return newSession(rest, store);
+        case "resume": return resumeSession(rest, store);
+        case "submit": return submit(rest, store, options);
+        default:
+            throw usageError(command === undefined
+                ? "Operator command is required."
+                : `Unknown command: operator ${command}`);
     }
-    const usage = "Operator submit usage: yui operator submit <body> [--task <id>].";
+}
+function submit(rest, store, options) {
+    const usage = "Operator submit usage: yui operator submit (<body>|--body-file <path|->) [--task <id>].";
     const positionals = [];
     let taskId;
+    let bodyFile;
     for (let index = 0; index < rest.length; index += 1) {
         const value = rest[index];
+        if (value === "--body-file") {
+            if (bodyFile !== undefined)
+                throw usageError("Option may only be specified once: --body-file.", usage);
+            const candidate = rest[index + 1];
+            if (candidate === undefined || candidate.startsWith("--"))
+                throw usageError("--body-file is required.", usage);
+            bodyFile = candidate;
+            index += 1;
+            continue;
+        }
         if (value !== "--task") {
             if (value.startsWith("--"))
                 throw usageError(`Unsupported option: ${value}.`, usage);
@@ -28,11 +52,137 @@ export function runOperatorCommand(args, store, options = {}) {
         taskId = candidate.trim();
         index += 1;
     }
-    if (positionals.length !== 1 || positionals[0].trim().length === 0) {
+    if (positionals.length > 1)
         throw usageError(usage);
-    }
+    const body = readCommandText(positionals[0], bodyFile, "--body", usage);
+    return {
+        kind: "output",
+        output: submitOperatorMessage(body, taskId, store, options)
+    };
+}
+function listSessions(args, store, options) {
+    if (args.length !== 0)
+        throw usageError("Operator list usage: yui operator list.");
+    const sessions = listOperatorSessions(store.getGlobalRoleSessionSet("operator"));
+    const now = options.now?.() ?? new Date();
+    const output = sessions.length === 0
+        ? "○ No Operator sessions are available.\n"
+        : `${renderTable("Operator sessions", [
+            { header: "Updated", minWidth: 7, maxWidth: 12 },
+            { header: "Agent", minWidth: 6, maxWidth: 16 },
+            { header: "Conversation", minWidth: 20, maxWidth: 72 },
+            { header: "State", minWidth: 7, maxWidth: 10 }
+        ], sessions.map((session) => [
+            formatRelativeTimestamp(session.updatedAt, now),
+            adapterLabel(session.adapterId),
+            session.displayTitle,
+            session.state
+        ]), options.width ?? defaultTableWidth())}\n\n${sessions.length} session${sessions.length === 1 ? "" : "s"}\n`;
     return {
         kind: "output",
-        output: submitOperatorMessage(positionals[0], taskId, store, options)
+        output,
+        data: { sessions }
+    };
+}
+function newSession(args, store) {
+    let agentId;
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (value !== "--agent") {
+            throw usageError(value.startsWith("--")
+                ? `Unsupported option: ${value}.`
+                : `Unexpected argument: ${value}.`, "Operator new usage: yui operator new [--agent <id>].");
+        }
+        if (agentId !== undefined)
+            throw usageError("Option may only be specified once: --agent.");
+        agentId = requiredValue(args[index + 1], "--agent");
+        index += 1;
+    }
+    const role = requireOperator(store);
+    const targetAgentId = agentId ?? role.activeAgentId;
+    if (!Object.hasOwn(role.agentBindings, targetAgentId)) {
+        throw usageError(`Operator Agent is not bound: ${targetAgentId}.`);
+    }
+    return { kind: "session", action: "new", targetAgentId };
+}
+function resumeSession(args, store) {
+    let ref;
+    let last = false;
+    for (const value of args) {
+        if (value === "--last") {
+            if (last)
+                throw usageError("Option may only be specified once: --last.");
+            last = true;
+            continue;
+        }
+        if (value.startsWith("--"))
+            throw usageError(`Unsupported option: ${value}.`);
+        if (ref !== undefined) {
+            throw usageError("Operator resume accepts only one session reference.");
+        }
+        ref = value;
+    }
+    if (last && ref !== undefined) {
+        throw usageError("Operator resume accepts either a session reference or --last.");
+    }
+    const sessions = listOperatorSessions(store.getGlobalRoleSessionSet("operator"));
+    const selectedRef = last ? sessions[0]?.ref : ref;
+    if (selectedRef === undefined) {
+        throw usageError(last
+            ? "No Operator session is available to resume."
+            : "Operator resume requires a session selection.");
+    }
+    const selected = sessions.find((session) => session.ref === selectedRef);
+    if (selected === undefined)
+        throw usageError(`Operator session not found: ${selectedRef}.`);
+    const role = requireOperator(store);
+    if (!Object.hasOwn(role.agentBindings, selected.agentId)) {
+        throw usageError(`Operator session Agent is no longer bound: ${selected.agentId}.`);
+    }
+    return {
+        kind: "session",
+        action: "resume",
+        targetAgentId: selected.agentId,
+        ref: selected.ref
     };
 }
+export function applyOperatorSessionControl(control, store, now = new Date()) {
+    return store.transaction((tx) => {
+        const role = requireOperator(tx);
+        const binding = role.agentBindings[control.targetAgentId];
+        if (binding === undefined) {
+            throw usageError(`Operator Agent is not bound: ${control.targetAgentId}.`);
+        }
+        const current = tx.getGlobalRoleSessionSet(role.name)
+            ?? createRoleSessionSet({ scope: "global", roleName: role.name }, role.activeAgentId, now);
+        const sessions = control.action === "new"
+            ? prepareOperatorNewSession(current, control.targetAgentId, now)
+            : prepareOperatorResumeSession(current, control.ref, now);
+        const selected = sessions.sessions[control.targetAgentId];
+        if (selected !== undefined && selected.adapterId !== binding.adapterId) {
+            throw usageError(`Operator session adapter does not match Agent: ${control.targetAgentId}.`);
+        }
+        const updatedRole = updateGlobalRole(role, { activeAgentId: control.targetAgentId }, now);
+        tx.saveGlobalRoleWithSessionSet(updatedRole, sessions);
+        return { role: updatedRole, sessions };
+    });
+}
+function requireOperator(store) {
+    const role = store.getGlobalRole("operator");
+    if (role === null)
+        throw usageError("Operator is not configured. Run yui setup first.");
+    return role;
+}
+function adapterLabel(adapterId) {
+    return adapterId === "codex"
+        ? "Codex"
+        : adapterId === "claude"
+            ? "Claude"
+            : adapterId;
+}
+function requiredValue(value, option) {
+    if (value === undefined || value.startsWith("--") || value.trim().length === 0) {
+        throw usageError(`${option} is required.`);
+    }
+    return value.trim();
+}