oh-my-codex 0.15.2 → 0.16.0

package/dist/team/api-interop.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve as resolvePath } from 'node:path';
+import { omxStateDir } from '../utils/paths.js';
 import { sendWorkerMessage, shutdownTeam } from './runtime.js';
 import { TEAM_NAME_SAFE_PATTERN, WORKER_NAME_SAFE_PATTERN, TASK_ID_SAFE_PATTERN, TEAM_TASK_STATUSES, TEAM_EVENT_TYPES, TEAM_TASK_APPROVAL_STATUSES, } from './contracts.js';
 import { readTeamEvents, waitForTeamEvent } from './state/events.js';
@@ -10,6 +11,7 @@ import { readLatestTeamProgressEvidenceMs } from './progress-evidence.js';
 import { resolveCanonicalTeamStateRoot } from './state-root.js';
 import { buildLeaderMailboxTriggerDirective, buildMailboxTriggerDirective } from './worker-bootstrap.js';
 import { teamBroadcast as broadcastMessage, teamListMailbox as listMailboxMessages, teamMarkMessageDelivered as markMessageDelivered, teamMarkMessageNotified as markMessageNotified, teamListDispatchRequests, teamMarkDispatchRequestNotified, teamMarkDispatchRequestDelivered, teamCreateTask, teamReadTask, teamListTasks, teamUpdateTask, teamClaimTask, teamTransitionTaskStatus, teamReleaseTaskClaim, teamCleanup, teamReadConfig, teamReadManifest, teamReadWorkerStatus, teamReadWorkerHeartbeat, teamUpdateWorkerHeartbeat, teamWriteWorkerInbox, teamWriteWorkerIdentity, teamAppendEvent, teamGetSummary, teamWriteShutdownRequest, teamReadShutdownAck, teamReadMonitorSnapshot, teamReadPhase, teamReadLeaderAttention, teamWriteMonitorSnapshot, teamReadTaskApproval, teamWriteTaskApproval, } from './team-ops.js';
+import { listTeamLookupCandidates, resolveTeamNameForCurrentContext, TeamLookupAmbiguityError } from './team-identity.js';
 const TEAM_UPDATE_TASK_MUTABLE_FIELDS = new Set(['subject', 'description', 'blocked_by', 'requires_code_change']);
 const TEAM_UPDATE_TASK_REQUEST_FIELDS = new Set(['team_name', 'task_id', 'workingDirectory', ...TEAM_UPDATE_TASK_MUTABLE_FIELDS]);
 export const LEGACY_TEAM_MCP_TOOLS = [
@@ -217,7 +219,7 @@ function buildIdleState(teamName, summary, snapshot, recentEvents) {
     };
 }
 function readLatestLeaderRuntimeActivityMs(cwd) {
-    const path = join(cwd, '.omx', 'state', 'leader-runtime-activity.json');
+    const path = join(omxStateDir(cwd), 'leader-runtime-activity.json');
     if (!existsSync(path))
         return Number.NaN;
     try {
@@ -342,7 +344,7 @@ function parseValidatedTaskIdArray(value, fieldName) {
 function teamStateExists(teamName, candidateCwd) {
     if (!TEAM_NAME_SAFE_PATTERN.test(teamName))
         return false;
-    const teamRoot = join(candidateCwd, '.omx', 'state', 'team', teamName);
+    const teamRoot = join(resolveCanonicalTeamStateRoot(candidateCwd), 'team', teamName);
     return existsSync(join(teamRoot, 'config.json')) || existsSync(join(teamRoot, 'tasks')) || existsSync(teamRoot);
 }
 function readTeamStateRootFromManifest(path) {
@@ -363,7 +365,7 @@ function stateRootToWorkingDirectory(stateRoot) {
     return dirname(dirname(absolute));
 }
 function resolveTeamWorkingDirectoryFromMetadata(teamName, candidateCwd) {
-    const teamRoot = join(candidateCwd, '.omx', 'state', 'team', teamName);
+    const teamRoot = join(resolveCanonicalTeamStateRoot(candidateCwd), 'team', teamName);
     if (!existsSync(teamRoot))
         return null;
     const fromManifest = readTeamStateRootFromManifest(join(teamRoot, 'manifest.v2.json'));
@@ -433,9 +435,9 @@ export function buildLegacyTeamDeprecationHint(legacyName, originalArgs) {
     }
     return `Use CLI interop: omx team api ${operation} --input '${payload}' --json`;
 }
-function validateCommonFields(args) {
+function validateCommonFields(args, options = {}) {
     const teamName = String(args.team_name || '').trim();
-    if (teamName && !TEAM_NAME_SAFE_PATTERN.test(teamName)) {
+    if (!options.skipTeamName && teamName && !TEAM_NAME_SAFE_PATTERN.test(teamName)) {
         throw new Error(`Invalid team_name: "${teamName}". Must match /^[a-z0-9][a-z0-9-]{0,29}$/ (lowercase alphanumeric + hyphens, max 30 chars).`);
     }
     for (const workerField of ['worker', 'from_worker', 'to_worker']) {
@@ -449,17 +451,43 @@ function validateCommonFields(args) {
         throw new Error(`Invalid task_id: "${rawTaskId}". Must be a positive integer (digits only, max 20 digits).`);
     }
 }
+function normalizeTeamDisplayLookupName(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 30)
+        .replace(/-$/, '');
+}
+function assertUnsafeTeamNameMatchesKnownDisplay(rawTeamName, cwd) {
+    if (TEAM_NAME_SAFE_PATTERN.test(rawTeamName))
+        return;
+    const normalized = normalizeTeamDisplayLookupName(rawTeamName);
+    const matchesKnownDisplay = listTeamLookupCandidates(cwd).some((candidate) => {
+        return normalizeTeamDisplayLookupName(candidate.displayName) === normalized
+            || normalizeTeamDisplayLookupName(candidate.requestedName) === normalized;
+    });
+    if (!matchesKnownDisplay) {
+        throw new Error(`Invalid team_name: "${rawTeamName}". Must match /^[a-z0-9][a-z0-9-]{0,29}$/ or resolve to an existing display name.`);
+    }
+}
 export async function executeTeamApiOperation(operation, args, fallbackCwd) {
     try {
-        validateCommonFields(args);
-        const teamNameForCwd = String(args.team_name || '').trim();
-        const cwd = teamNameForCwd ? resolveTeamWorkingDirectory(teamNameForCwd, fallbackCwd) : fallbackCwd;
+        validateCommonFields(args, { skipTeamName: true });
+        const rawTeamNameForCwd = String(args.team_name || '').trim();
+        if (rawTeamNameForCwd)
+            assertUnsafeTeamNameMatchesKnownDisplay(rawTeamNameForCwd, fallbackCwd);
+        const resolvedTeamName = rawTeamNameForCwd ? resolveTeamNameForCurrentContext(rawTeamNameForCwd, fallbackCwd) : '';
+        const cwd = resolvedTeamName ? resolveTeamWorkingDirectory(resolvedTeamName, fallbackCwd) : fallbackCwd;
+        const opArgs = resolvedTeamName ? { ...args, team_name: resolvedTeamName } : args;
+        validateCommonFields(opArgs);
         switch (operation) {
             case 'send-message': {
-                const teamName = String(args.team_name || '').trim();
-                const fromWorker = String(args.from_worker || '').trim();
-                const toWorker = String(args.to_worker || '').trim();
-                const body = String(args.body || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
+                const fromWorker = String(opArgs.from_worker || '').trim();
+                const toWorker = String(opArgs.to_worker || '').trim();
+                const body = String(opArgs.body || '').trim();
                 if (!fromWorker) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'from_worker is required. You must identify yourself.' } };
                 }
@@ -525,9 +553,9 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                 return { ok: true, operation, data: { message, dispatch: outcome } };
             }
             case 'broadcast': {
-                const teamName = String(args.team_name || '').trim();
-                const fromWorker = String(args.from_worker || '').trim();
-                const body = String(args.body || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
+                const fromWorker = String(opArgs.from_worker || '').trim();
+                const body = String(opArgs.body || '').trim();
                 if (!teamName || !fromWorker || !body) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name, from_worker, body are required' } };
                 }
@@ -535,9 +563,9 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                 return { ok: true, operation, data: { count: messages.length, messages } };
             }
             case 'mailbox-list': {
-                const teamName = String(args.team_name || '').trim();
-                const worker = String(args.worker || '').trim();
-                const includeDelivered = args.include_delivered !== false;
+                const teamName = String(opArgs.team_name || '').trim();
+                const worker = String(opArgs.worker || '').trim();
+                const includeDelivered = opArgs.include_delivered !== false;
                 if (!teamName || !worker) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name and worker are required' } };
                 }
@@ -546,9 +574,9 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                 return { ok: true, operation, data: { worker, count: messages.length, messages } };
             }
             case 'mailbox-mark-delivered': {
-                const teamName = String(args.team_name || '').trim();
-                const worker = String(args.worker || '').trim();
-                const messageId = String(args.message_id || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
+                const worker = String(opArgs.worker || '').trim();
+                const messageId = String(opArgs.message_id || '').trim();
                 if (!teamName || !worker || !messageId) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name, worker, message_id are required' } };
                 }
@@ -577,9 +605,9 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                 };
             }
             case 'mailbox-mark-notified': {
-                const teamName = String(args.team_name || '').trim();
-                const worker = String(args.worker || '').trim();
-                const messageId = String(args.message_id || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
+                const worker = String(opArgs.worker || '').trim();
+                const messageId = String(opArgs.message_id || '').trim();
                 if (!teamName || !worker || !messageId) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name, worker, message_id are required' } };
                 }
@@ -587,23 +615,23 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                 return { ok: true, operation, data: { worker, message_id: messageId, notified } };
             }
             case 'create-task': {
-                const teamName = String(args.team_name || '').trim();
-                const subject = String(args.subject || '').trim();
-                const description = String(args.description || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
+                const subject = String(opArgs.subject || '').trim();
+                const description = String(opArgs.description || '').trim();
                 if (!teamName || !subject || !description) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name, subject, description are required' } };
                 }
-                const owner = args.owner;
-                const blockedBy = args.blocked_by;
-                const requiresCodeChange = args.requires_code_change;
+                const owner = opArgs.owner;
+                const blockedBy = opArgs.blocked_by;
+                const requiresCodeChange = opArgs.requires_code_change;
                 const task = await teamCreateTask(teamName, {
                     subject, description, status: 'pending', owner: owner || undefined, blocked_by: blockedBy, requires_code_change: requiresCodeChange,
                 }, cwd);
                 return { ok: true, operation, data: { task } };
             }
             case 'read-task': {
-                const teamName = String(args.team_name || '').trim();
-                const taskId = String(args.task_id || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
+                const taskId = String(opArgs.task_id || '').trim();
                 if (!teamName || !taskId) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name and task_id are required' } };
                 }
@@ -613,7 +641,7 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                     : { ok: false, operation, error: { code: 'task_not_found', message: 'task_not_found' } };
             }
             case 'list-tasks': {
-                const teamName = String(args.team_name || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
                 if (!teamName) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name is required' } };
                 }
@@ -621,8 +649,8 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                 return { ok: true, operation, data: { count: tasks.length, tasks } };
             }
             case 'update-task': {
-                const teamName = String(args.team_name || '').trim();
-                const taskId = String(args.task_id || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
+                const taskId = String(opArgs.task_id || '').trim();
                 if (!teamName || !taskId) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name and task_id are required' } };
                 }
@@ -637,26 +665,26 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                 }
                 const updates = {};
                 if ('subject' in args) {
-                    if (typeof args.subject !== 'string') {
+                    if (typeof opArgs.subject !== 'string') {
                         return { ok: false, operation, error: { code: 'invalid_input', message: 'subject must be a string when provided' } };
                     }
-                    updates.subject = args.subject.trim();
+                    updates.subject = opArgs.subject.trim();
                 }
                 if ('description' in args) {
-                    if (typeof args.description !== 'string') {
+                    if (typeof opArgs.description !== 'string') {
                         return { ok: false, operation, error: { code: 'invalid_input', message: 'description must be a string when provided' } };
                     }
-                    updates.description = args.description.trim();
+                    updates.description = opArgs.description.trim();
                 }
                 if ('requires_code_change' in args) {
-                    if (typeof args.requires_code_change !== 'boolean') {
+                    if (typeof opArgs.requires_code_change !== 'boolean') {
                         return { ok: false, operation, error: { code: 'invalid_input', message: 'requires_code_change must be a boolean when provided' } };
                     }
-                    updates.requires_code_change = args.requires_code_change;
+                    updates.requires_code_change = opArgs.requires_code_change;
                 }
                 if ('blocked_by' in args) {
                     try {
-                        updates.blocked_by = parseValidatedTaskIdArray(args.blocked_by, 'blocked_by');
+                        updates.blocked_by = parseValidatedTaskIdArray(opArgs.blocked_by, 'blocked_by');
                     }
                     catch (error) {
                         return { ok: false, operation, error: { code: 'invalid_input', message: error.message } };
@@ -668,13 +696,13 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                     : { ok: false, operation, error: { code: 'task_not_found', message: 'task_not_found' } };
             }
             case 'claim-task': {
-                const teamName = String(args.team_name || '').trim();
-                const taskId = String(args.task_id || '').trim();
-                const worker = String(args.worker || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
+                const taskId = String(opArgs.task_id || '').trim();
+                const worker = String(opArgs.worker || '').trim();
                 if (!teamName || !taskId || !worker) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name, task_id, worker are required' } };
                 }
-                const rawExpectedVersion = args.expected_version;
+                const rawExpectedVersion = opArgs.expected_version;
                 if (rawExpectedVersion !== undefined && (!isFiniteInteger(rawExpectedVersion) || rawExpectedVersion < 1)) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'expected_version must be a positive integer when provided' } };
                 }
@@ -682,13 +710,13 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                 return { ok: true, operation, data: result };
             }
             case 'transition-task-status': {
-                const teamName = String(args.team_name || '').trim();
-                const taskId = String(args.task_id || '').trim();
-                const from = String(args.from || '').trim();
-                const to = String(args.to || '').trim();
-                const claimToken = String(args.claim_token || '').trim();
-                const transitionResult = args.result;
-                const transitionError = args.error;
+                const teamName = String(opArgs.team_name || '').trim();
+                const taskId = String(opArgs.task_id || '').trim();
+                const from = String(opArgs.from || '').trim();
+                const to = String(opArgs.to || '').trim();
+                const claimToken = String(opArgs.claim_token || '').trim();
+                const transitionResult = opArgs.result;
+                const transitionError = opArgs.error;
                 if (!teamName || !taskId || !from || !to || !claimToken) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name, task_id, from, to, claim_token are required' } };
                 }
@@ -709,10 +737,10 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                 return { ok: true, operation, data: result };
             }
             case 'release-task-claim': {
-                const teamName = String(args.team_name || '').trim();
-                const taskId = String(args.task_id || '').trim();
-                const claimToken = String(args.claim_token || '').trim();
-                const worker = String(args.worker || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
+                const taskId = String(opArgs.task_id || '').trim();
+                const claimToken = String(opArgs.claim_token || '').trim();
+                const worker = String(opArgs.worker || '').trim();
                 if (!teamName || !taskId || !claimToken || !worker) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name, task_id, claim_token, worker are required' } };
                 }
@@ -720,7 +748,7 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                 return { ok: true, operation, data: result };
             }
             case 'read-config': {
-                const teamName = String(args.team_name || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
                 if (!teamName)
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name is required' } };
                 const config = await teamReadConfig(teamName, cwd);
@@ -729,7 +757,7 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                     : { ok: false, operation, error: { code: 'team_not_found', message: 'team_not_found' } };
             }
             case 'read-manifest': {
-                const teamName = String(args.team_name || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
                 if (!teamName)
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name is required' } };
                 const manifest = await teamReadManifest(teamName, cwd);
@@ -738,27 +766,27 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                     : { ok: false, operation, error: { code: 'manifest_not_found', message: 'manifest_not_found' } };
             }
             case 'read-worker-status': {
-                const teamName = String(args.team_name || '').trim();
-                const worker = String(args.worker || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
+                const worker = String(opArgs.worker || '').trim();
                 if (!teamName || !worker)
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name and worker are required' } };
                 const status = await teamReadWorkerStatus(teamName, worker, cwd);
                 return { ok: true, operation, data: { worker, status } };
             }
             case 'read-worker-heartbeat': {
-                const teamName = String(args.team_name || '').trim();
-                const worker = String(args.worker || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
+                const worker = String(opArgs.worker || '').trim();
                 if (!teamName || !worker)
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name and worker are required' } };
                 const heartbeat = await teamReadWorkerHeartbeat(teamName, worker, cwd);
                 return { ok: true, operation, data: { worker, heartbeat } };
             }
             case 'update-worker-heartbeat': {
-                const teamName = String(args.team_name || '').trim();
-                const worker = String(args.worker || '').trim();
-                const pid = args.pid;
-                const turnCount = args.turn_count;
-                const alive = args.alive;
+                const teamName = String(opArgs.team_name || '').trim();
+                const worker = String(opArgs.worker || '').trim();
+                const pid = opArgs.pid;
+                const turnCount = opArgs.turn_count;
+                const alive = opArgs.alive;
                 if (!teamName || !worker || typeof pid !== 'number' || typeof turnCount !== 'number' || typeof alive !== 'boolean') {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name, worker, pid, turn_count, alive are required' } };
                 }
@@ -766,9 +794,9 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                 return { ok: true, operation, data: { worker } };
             }
             case 'write-worker-inbox': {
-                const teamName = String(args.team_name || '').trim();
-                const worker = String(args.worker || '').trim();
-                const content = String(args.content || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
+                const worker = String(opArgs.worker || '').trim();
+                const content = String(opArgs.content || '').trim();
                 if (!teamName || !worker || !content) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name, worker, content are required' } };
                 }
@@ -776,10 +804,10 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                 return { ok: true, operation, data: { worker } };
             }
             case 'write-worker-identity': {
-                const teamName = String(args.team_name || '').trim();
-                const worker = String(args.worker || '').trim();
-                const index = args.index;
-                const role = String(args.role || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
+                const worker = String(opArgs.worker || '').trim();
+                const index = opArgs.index;
+                const role = String(opArgs.role || '').trim();
                 if (!teamName || !worker || typeof index !== 'number' || !role) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name, worker, index, role are required' } };
                 }
@@ -787,21 +815,21 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                     name: worker,
                     index,
                     role,
-                    assigned_tasks: args.assigned_tasks ?? [],
-                    pid: args.pid,
-                    pane_id: args.pane_id,
-                    working_dir: args.working_dir,
-                    worktree_path: args.worktree_path,
-                    worktree_branch: args.worktree_branch,
-                    worktree_detached: args.worktree_detached,
-                    team_state_root: args.team_state_root,
+                    assigned_tasks: opArgs.assigned_tasks ?? [],
+                    pid: opArgs.pid,
+                    pane_id: opArgs.pane_id,
+                    working_dir: opArgs.working_dir,
+                    worktree_path: opArgs.worktree_path,
+                    worktree_branch: opArgs.worktree_branch,
+                    worktree_detached: opArgs.worktree_detached,
+                    team_state_root: opArgs.team_state_root,
                 }, cwd);
                 return { ok: true, operation, data: { worker } };
             }
             case 'append-event': {
-                const teamName = String(args.team_name || '').trim();
-                const eventType = String(args.type || '').trim();
-                const worker = String(args.worker || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
+                const eventType = String(opArgs.type || '').trim();
+                const worker = String(opArgs.worker || '').trim();
                 if (!teamName || !eventType || !worker) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name, type, worker are required' } };
                 }
@@ -811,29 +839,29 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                 const event = await teamAppendEvent(teamName, {
                     type: eventType,
                     worker,
-                    task_id: args.task_id,
-                    message_id: args.message_id ?? null,
-                    reason: args.reason,
-                    state: args.state,
-                    prev_state: args.prev_state,
-                    to_worker: args.to_worker,
-                    worker_count: typeof args.worker_count === 'number' ? args.worker_count : undefined,
-                    source_type: args.source_type,
-                    metadata: parseOptionalMetadata(args.metadata),
+                    task_id: opArgs.task_id,
+                    message_id: opArgs.message_id ?? null,
+                    reason: opArgs.reason,
+                    state: opArgs.state,
+                    prev_state: opArgs.prev_state,
+                    to_worker: opArgs.to_worker,
+                    worker_count: typeof opArgs.worker_count === 'number' ? opArgs.worker_count : undefined,
+                    source_type: opArgs.source_type,
+                    metadata: parseOptionalMetadata(opArgs.metadata),
                 }, cwd);
                 return { ok: true, operation, data: { event } };
             }
             case 'read-events': {
-                const teamName = String(args.team_name || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
                 if (!teamName) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name is required' } };
                 }
-                const wakeableOnly = parseOptionalBoolean(args.wakeable_only, 'wakeable_only');
-                const eventType = parseOptionalEventType(args.type);
-                const worker = typeof args.worker === 'string' ? args.worker.trim() : '';
-                const taskId = typeof args.task_id === 'string' ? args.task_id.trim() : '';
+                const wakeableOnly = parseOptionalBoolean(opArgs.wakeable_only, 'wakeable_only');
+                const eventType = parseOptionalEventType(opArgs.type);
+                const worker = typeof opArgs.worker === 'string' ? opArgs.worker.trim() : '';
+                const taskId = typeof opArgs.task_id === 'string' ? opArgs.task_id.trim() : '';
                 const events = await readTeamEvents(teamName, cwd, {
-                    afterEventId: typeof args.after_event_id === 'string' ? args.after_event_id.trim() || undefined : undefined,
+                    afterEventId: typeof opArgs.after_event_id === 'string' ? opArgs.after_event_id.trim() || undefined : undefined,
                     wakeableOnly: wakeableOnly ?? false,
                     type: eventType ?? undefined,
                     worker: worker || undefined,
@@ -844,24 +872,24 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                     operation,
                     data: {
                         count: events.length,
-                        cursor: events.at(-1)?.event_id ?? (typeof args.after_event_id === 'string' ? args.after_event_id.trim() : ''),
+                        cursor: events.at(-1)?.event_id ?? (typeof opArgs.after_event_id === 'string' ? opArgs.after_event_id.trim() : ''),
                         events,
                     },
                 };
             }
             case 'await-event': {
-                const teamName = String(args.team_name || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
                 if (!teamName) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name is required' } };
                 }
-                const timeoutMs = parseOptionalNonNegativeInteger(args.timeout_ms, 'timeout_ms') ?? 30_000;
-                const pollMs = parseOptionalNonNegativeInteger(args.poll_ms, 'poll_ms');
-                const wakeableOnly = parseOptionalBoolean(args.wakeable_only, 'wakeable_only');
-                const eventType = parseOptionalEventType(args.type);
-                const worker = typeof args.worker === 'string' ? args.worker.trim() : '';
-                const taskId = typeof args.task_id === 'string' ? args.task_id.trim() : '';
+                const timeoutMs = parseOptionalNonNegativeInteger(opArgs.timeout_ms, 'timeout_ms') ?? 30_000;
+                const pollMs = parseOptionalNonNegativeInteger(opArgs.poll_ms, 'poll_ms');
+                const wakeableOnly = parseOptionalBoolean(opArgs.wakeable_only, 'wakeable_only');
+                const eventType = parseOptionalEventType(opArgs.type);
+                const worker = typeof opArgs.worker === 'string' ? opArgs.worker.trim() : '';
+                const taskId = typeof opArgs.task_id === 'string' ? opArgs.task_id.trim() : '';
                 const result = await waitForTeamEvent(teamName, cwd, {
-                    afterEventId: typeof args.after_event_id === 'string' ? args.after_event_id.trim() || undefined : undefined,
+                    afterEventId: typeof opArgs.after_event_id === 'string' ? opArgs.after_event_id.trim() || undefined : undefined,
                     timeoutMs,
                     pollMs: pollMs ?? undefined,
                     wakeableOnly: wakeableOnly ?? false,
@@ -880,7 +908,7 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                 };
             }
             case 'read-idle-state': {
-                const teamName = String(args.team_name || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
                 if (!teamName) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name is required' } };
                 }
@@ -900,7 +928,7 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                 };
             }
             case 'read-stall-state': {
-                const teamName = String(args.team_name || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
                 if (!teamName) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name is required' } };
                 }
@@ -943,7 +971,7 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                 };
             }
             case 'get-summary': {
-                const teamName = String(args.team_name || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
                 if (!teamName)
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name is required' } };
                 const summary = await teamGetSummary(teamName, cwd);
@@ -952,7 +980,7 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                     : { ok: false, operation, error: { code: 'team_not_found', message: 'team_not_found' } };
             }
             case 'cleanup': {
-                const teamName = String(args.team_name || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
                 if (!teamName)
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name is required' } };
                 const force = args.force === true;
@@ -961,16 +989,16 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                 return { ok: true, operation, data: { team_name: teamName, cleanup_mode: 'shutdown' } };
             }
             case 'orphan-cleanup': {
-                const teamName = String(args.team_name || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
                 if (!teamName)
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name is required' } };
                 await teamCleanup(teamName, cwd);
                 return { ok: true, operation, data: { team_name: teamName, cleanup_mode: 'orphan_cleanup' } };
             }
             case 'write-shutdown-request': {
-                const teamName = String(args.team_name || '').trim();
-                const worker = String(args.worker || '').trim();
-                const requestedBy = String(args.requested_by || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
+                const worker = String(opArgs.worker || '').trim();
+                const requestedBy = String(opArgs.requested_by || '').trim();
                 if (!teamName || !worker || !requestedBy) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name, worker, requested_by are required' } };
                 }
@@ -978,24 +1006,24 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                 return { ok: true, operation, data: { worker } };
             }
             case 'read-shutdown-ack': {
-                const teamName = String(args.team_name || '').trim();
-                const worker = String(args.worker || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
+                const worker = String(opArgs.worker || '').trim();
                 if (!teamName || !worker) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name and worker are required' } };
                 }
-                const ack = await teamReadShutdownAck(teamName, worker, cwd, args.min_updated_at);
+                const ack = await teamReadShutdownAck(teamName, worker, cwd, opArgs.min_updated_at);
                 return { ok: true, operation, data: { worker, ack } };
             }
             case 'read-monitor-snapshot': {
-                const teamName = String(args.team_name || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
                 if (!teamName)
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name is required' } };
                 const snapshot = await teamReadMonitorSnapshot(teamName, cwd);
                 return { ok: true, operation, data: { snapshot } };
             }
             case 'write-monitor-snapshot': {
-                const teamName = String(args.team_name || '').trim();
-                const snapshot = args.snapshot;
+                const teamName = String(opArgs.team_name || '').trim();
+                const snapshot = opArgs.snapshot;
                 if (!teamName || !snapshot) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name and snapshot are required' } };
                 }
@@ -1003,8 +1031,8 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                 return { ok: true, operation, data: {} };
             }
             case 'read-task-approval': {
-                const teamName = String(args.team_name || '').trim();
-                const taskId = String(args.task_id || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
+                const taskId = String(opArgs.task_id || '').trim();
                 if (!teamName || !taskId) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name and task_id are required' } };
                 }
@@ -1012,18 +1040,18 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
                 return { ok: true, operation, data: { approval } };
             }
             case 'write-task-approval': {
-                const teamName = String(args.team_name || '').trim();
-                const taskId = String(args.task_id || '').trim();
-                const status = String(args.status || '').trim();
-                const reviewer = String(args.reviewer || '').trim();
-                const decisionReason = String(args.decision_reason || '').trim();
+                const teamName = String(opArgs.team_name || '').trim();
+                const taskId = String(opArgs.task_id || '').trim();
+                const status = String(opArgs.status || '').trim();
+                const reviewer = String(opArgs.reviewer || '').trim();
+                const decisionReason = String(opArgs.decision_reason || '').trim();
                 if (!teamName || !taskId || !status || !reviewer || !decisionReason) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'team_name, task_id, status, reviewer, decision_reason are required' } };
                 }
                 if (!TEAM_TASK_APPROVAL_STATUSES.includes(status)) {
                     return { ok: false, operation, error: { code: 'invalid_input', message: `status must be one of: ${TEAM_TASK_APPROVAL_STATUSES.join(', ')}` } };
                 }
-                const rawRequired = args.required;
+                const rawRequired = opArgs.required;
                 if (rawRequired !== undefined && typeof rawRequired !== 'boolean') {
                     return { ok: false, operation, error: { code: 'invalid_input', message: 'required must be a boolean when provided' } };
                 }
@@ -1040,6 +1068,9 @@ export async function executeTeamApiOperation(operation, args, fallbackCwd) {
         }
     }
     catch (error) {
+        if (error instanceof TeamLookupAmbiguityError) {
+            return { ok: false, operation, error: { code: 'ambiguous_team_name', message: error.message, details: { candidates: error.candidates } } };
+        }
         return {
             ok: false,
             operation,