@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/agent/commands/accounts.js

@@ -9,13 +9,10 @@
  *   /accounts login <id>      run the official CLI login at the account's dir
  *   /accounts remove <id>     drop an account from the pool
  */
-import { spawnSync } from 'node:child_process';
 import { configStore } from '../../config.js';
-import { buildLoginCommand, canonicalAccountProvider, defaultAccountDir, defaultSourceFor, ensureAccountDir, findCodexHomeCollision, isAccountProvider, probeAccountUsable, sourceDir, } from '../backends/account_pool.js';
-import { loginAutoRunEnabled, loginFailureReasonText, runLoginCommand } from '../backends/account_login.js';
-import { notifyAccountsChanged } from '../backends/account_events.js';
+import { canonicalAccountProvider, defaultAccountDir, defaultSourceFor, findCodexHomeCollision, isAccountProvider, probeAccountUsable, sourceDir, } from '../backends/account_pool.js';
 import { codexStatusCache } from '../backends/codex_account_status.js';
-import { runKimiDeviceLogin } from '../backends/kimi_code_auth.js';
+import { applyAccountOp } from '../../web/accounts_mirror.js';
 const PROVIDER_LABELS = {
     claude_code: 'Claude Code (claude CLI)',
     codex_app_server: 'Codex (codex app-server)',
@@ -121,21 +118,28 @@ function parseAdd(args) {
     }
     return { provider, id, label: labelParts.join(' ') || id, path };
 }
-async function addAccount(parsed) {
-    if (configStore.getAccount(parsed.id)) {
-        return { error: 'duplicate_id', message: `An account with id "${parsed.id}" already exists. Remove it first or pick another id.` };
-    }
-    const dir = parsed.path ?? defaultAccountDir(parsed.provider, parsed.id);
-    const source = defaultSourceFor(parsed.provider, dir);
-    const collision = findCodexHomeCollision(configStore.listAccounts(), source);
-    if (collision) {
-        return { error: 'codex_home_collision', message: `That Codex credential home is already used by "${collision.label}". Choose another path.` };
+/** All mutating CLI and terminal-panel actions use the same owner admission and
+ * canonical operation as the mirror. The owner callback holds its runtime lease. */
+async function applyOperation(body, ctx) {
+    return ctx.applyAccountOperation
+        ? ctx.applyAccountOperation(body)
+        : applyAccountOp(body, configStore, () => ctx.reloadAgent());
+}
+function showOperationResult(result, ctx) {
+    say(ctx, [result.ok ? result.message : result.error, result.loginCommand]
+        .filter(Boolean).join('\n\n'));
+}
+async function addAccount(parsed, ctx) {
+    const result = await applyOperation({ op: 'add', ...parsed }, ctx);
+    if (!result.ok) {
+        const dir = parsed.path ?? defaultAccountDir(parsed.provider, parsed.id);
+        const collision = findCodexHomeCollision(configStore.listAccounts(), defaultSourceFor(parsed.provider, dir));
+        return {
+            error: configStore.getAccount(parsed.id) ? 'duplicate_id' : collision ? 'codex_home_collision' : 'operation_failed',
+            message: result.error ?? 'Account operation failed.',
+        };
     }
-    ensureAccountDir(source);
-    const account = { id: parsed.id, label: parsed.label, provider: parsed.provider, source };
-    configStore.addAccount(account);
-    await configStore.save();
-    return { account };
+    return { account: configStore.getAccount(parsed.id) };
 }
 async function handleAdd(args, ctx) {
     const parsed = parseAdd(args);
@@ -143,7 +147,7 @@ async function handleAdd(args, ctx) {
         say(ctx, parsed);
         return;
     }
-    const result = await addAccount(parsed);
+    const result = await addAccount(parsed, ctx);
     if ('error' in result) {
         say(ctx, result.message);
         return;
@@ -162,151 +166,20 @@ async function handleAdd(args, ctx) {
 async function handleUse(args, ctx) {
     const id = args[0];
     if (!id) {
-        say(ctx, `Usage: /accounts use <id>`);
+        say(ctx, 'Usage: /accounts use <id>');
         return;
     }
-    const account = configStore.getAccount(id);
-    if (!account) {
-        say(ctx, `No account "${id}". See /accounts.`);
-        return;
-    }
-    if (account.source.kind === 'codex_home') {
-        const status = await codexStatusCache.read(account.source.path, true);
-        if (status.state === 'reauth_required' || status.state === 'unavailable') {
-            say(ctx, status.state === 'reauth_required'
-                ? `"${account.label}" needs a fresh ChatGPT sign-in. Run /accounts login ${account.id}, then switch again.`
-                : `"${account.label}" could not be verified. Refresh its status or sign in, then switch again.`);
-            return;
-        }
-    }
-    configStore.setActiveAccount(account.provider, account.id);
-    await configStore.save();
-    const accountKey = canonicalAccountProvider(account.provider);
-    const isCurrentProvider = canonicalAccountProvider(configStore.getProvider()) === accountKey;
-    if (!probeAccountUsable(account)) {
-        say(ctx, `"${account.label}" is now the active ${PROVIDER_LABELS[account.provider]} account, but it has no credentials yet. Run /accounts login ${account.id}.`);
-        return;
-    }
-    if (isCurrentProvider) {
-        ctx.reloadAgent();
-        say(ctx, `Switched live ${PROVIDER_LABELS[account.provider]} account to "${account.label}".`);
-    }
-    else {
-        say(ctx, `Set "${account.label}" active for ${PROVIDER_LABELS[account.provider]}. It goes live when you switch to that provider with /model.`);
-    }
+    showOperationResult(await applyOperation({ op: 'use', id }, ctx), ctx);
 }
 async function handleLogin(args, ctx) {
     const id = args[0];
     if (!id) {
-        say(ctx, `Usage: /accounts login <id>`);
-        return;
-    }
-    const account = configStore.getAccount(id);
-    if (!account) {
-        say(ctx, `No account "${id}". See /accounts.`);
+        say(ctx, 'Usage: /accounts login <id>');
         return;
     }
-    ensureAccountDir(account.source);
-    // kimi_code: native device-flow login — no external CLI involved. Show the
-    // user code + link here, poll until the browser step completes.
-    if (account.source.kind === 'kimi_creds_file') {
-        const credsPath = account.source.path;
-        say(ctx, 'Starting Kimi sign-in…');
-        try {
-            const result = await runKimiDeviceLogin({
-                authFilePath: credsPath,
-                onCode: (flow) => {
-                    say(ctx, [
-                        `Open this link to sign in "${account.label}":`,
-                        '',
-                        `  ${flow.verificationUriComplete}`,
-                        '',
-                        `and confirm the code: ${flow.userCode}`,
-                        '',
-                        'Waiting for the sign-in to complete…',
-                    ].join('\n'));
-                },
-            });
-            if (result.outcome === 'succeeded') {
-                notifyAccountsChanged();
-                // Hot-swap only when this login changes creds the live agent is using.
-                const isCurrentActive = configStore.getActiveAccount(configStore.getProvider())?.id === account.id;
-                if (isCurrentActive)
-                    ctx.reloadAgent();
-                say(ctx, `"${account.label}" is signed in. Make it live with: /accounts use ${account.id}`);
-            }
-            else {
-                const why = result.outcome === 'denied'
-                    ? `the sign-in was denied${result.description ? ` (${result.description})` : ''}`
-                    : result.outcome === 'expired'
-                        ? 'the code expired'
-                        : 'the sign-in timed out';
-                say(ctx, `Kimi sign-in failed — ${why}. Try again: /accounts login ${account.id}`);
-            }
-        }
-        catch (error) {
-            say(ctx, `Kimi sign-in failed: ${error.message}`);
-        }
-        return;
-    }
-    const login = buildLoginCommand(account);
-    const manualHint = [
-        `Run this in a terminal to sign in "${account.label}" (no token enters ztc):`,
-        '',
-        `  ${login.display}`,
-        '',
-        `Then: /accounts use ${account.id}`,
-    ].join('\n');
-    // A blocking spawnSync(stdio:'inherit') would freeze the Node event loop —
-    // and with it every mirror pane — for the entire OAuth, and attach the login
-    // prompt to a terminal a web-mirror user cannot see. When there is no TTY, OR
-    // a web mirror is attached, auto-run the OAuth with piped stdio (non-blocking)
-    // and only hand the command back if it fails. No token enters ztc either way.
-    if (!process.stdout.isTTY || ctx.mirror?.isRunning()) {
-        if (!loginAutoRunEnabled()) {
-            say(ctx, manualHint);
-            return;
-        }
-        say(ctx, `Signing in "${account.label}" on the ztc host — complete it in the browser…`);
-        const attempt = await runLoginCommand(login, () => probeAccountUsable(account));
-        if (attempt.outcome === 'succeeded') {
-            if (account.source.kind === 'codex_home') {
-                codexStatusCache.invalidate(account.source.path);
-                const status = await codexStatusCache.read(account.source.path, true);
-                if (status.state === 'reauth_required' || status.state === 'unavailable') {
-                    notifyAccountsChanged();
-                    say(ctx, `"${account.label}" saved credentials, but the ChatGPT subscription could not be verified. Run /accounts login ${account.id} again.`);
-                    return;
-                }
-            }
-            notifyAccountsChanged();
-            say(ctx, `"${account.label}" is signed in. Make it live with: /accounts use ${account.id}`);
-        }
-        else {
-            say(ctx, [`Auto sign-in failed — ${loginFailureReasonText(attempt)}.`, '', manualHint].join('\n'));
-        }
-        return;
-    }
-    say(ctx, `Launching: ${login.display}\nComplete the login in the browser, then return here.`);
-    const result = spawnSync(login.command, login.args, { stdio: 'inherit', env: login.env });
-    if (result.error) {
-        say(ctx, [
-            `Couldn't launch "${login.command}" (${result.error.message}).`,
-            `Run it yourself:`,
-            '',
-            `  ${login.display}`,
-        ].join('\n'));
-        return;
-    }
-    let ready = probeAccountUsable(account);
-    if (ready && account.source.kind === 'codex_home') {
-        codexStatusCache.invalidate(account.source.path);
-        const status = await codexStatusCache.read(account.source.path, true);
-        ready = status.state === 'ready' || status.state === 'quota_unavailable';
-    }
-    say(ctx, ready
-        ? `"${account.label}" is signed in. Make it live with: /accounts use ${account.id}`
-        : `Login exited without usable credentials in ${sourceDir(account.source)}. Try again: /accounts login ${account.id}`);
+    // The canonical operation returns pending while the official/device login
+    // runs. Completion notification and idle-safe reload belong to the owner.
+    showOperationResult(await applyOperation({ op: 'login', id }, ctx), ctx);
 }
 function describeRotation() {
     const r = configStore.getRotation();
@@ -327,50 +200,45 @@ async function handleRotation(args, ctx) {
         say(ctx, describeRotation());
         return;
     }
+    const patch = { op: 'rotation' };
     switch (field) {
         case 'on':
-            configStore.setRotation({ enabled: true });
+            patch.enabled = true;
             break;
         case 'off':
-            configStore.setRotation({ enabled: false });
+            patch.enabled = false;
             break;
         case 'mode':
             if (value !== 'failover' && value !== 'round_robin') {
                 say(ctx, 'Usage: /accounts rotation mode failover|round_robin');
                 return;
             }
-            configStore.setRotation({ mode: value });
+            patch.mode = value;
             break;
         case 'subagents':
             if (value !== 'inherit' && value !== 'pool') {
                 say(ctx, 'Usage: /accounts rotation subagents inherit|pool');
                 return;
             }
-            configStore.setRotation({ subagentInheritance: value });
+            patch.subagentInheritance = value;
             break;
         default:
             say(ctx, `Unknown rotation field "${field}".\n\n${describeRotation()}`);
             return;
     }
-    await configStore.save();
-    // Re-mint the agent so a freshly enabled pool wraps (or unwraps) the backend now.
-    ctx.reloadAgent();
-    say(ctx, describeRotation());
+    const result = await applyOperation(patch, ctx);
+    if (!result.ok)
+        showOperationResult(result, ctx);
+    else
+        say(ctx, describeRotation());
 }
 async function handleRemove(args, ctx) {
     const id = args[0];
     if (!id) {
-        say(ctx, `Usage: /accounts remove <id>`);
-        return;
-    }
-    const account = configStore.getAccount(id);
-    if (!account) {
-        say(ctx, `No account "${id}". See /accounts.`);
+        say(ctx, 'Usage: /accounts remove <id>');
         return;
     }
-    configStore.removeAccount(id);
-    await configStore.save();
-    say(ctx, `Removed "${account.label}" (${id}) from the pool. Its credential dir was left in place:\n  ${sourceDir(account.source)}`);
+    showOperationResult(await applyOperation({ op: 'remove', id }, ctx), ctx);
 }
 // --- interactive terminal settings page (text list in non-interactive output) ---
 function accountFamily(provider) {
@@ -440,10 +308,11 @@ function interactiveAddPage(ctx, provider) {
                                     id,
                                     label: draft.label.trim() || id,
                                     path: draft.path.trim() || undefined,
-                                }).then(result => {
+                                }, ctx).then(result => {
                                     if ('error' in result) {
-                                        error = result.error === 'duplicate_id' ? 'Account ID already exists' : 'Credential directory in use';
-                                        errorField = result.error === 'duplicate_id' ? 'id' : 'path';
+                                        error = result.error === 'duplicate_id' ? 'Account ID already exists'
+                                            : result.error === 'codex_home_collision' ? 'Credential directory in use' : result.message;
+                                        errorField = result.error === 'duplicate_id' ? 'id' : result.error === 'codex_home_collision' ? 'path' : 'create';
                                         showPage(errorField);
                                     }
                                     else {

package/dist/agent/commands/attention.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from './types.js';
+export declare const attentionCommand: Command;

package/dist/agent/commands/attention.js

@@ -0,0 +1,67 @@
+const USAGE = '/attention [list [page]|show <ID>|answer <ID> <text or JSON>|approve|deny <ID> [reason]|dismiss <ID>]';
+function describe(item) {
+    const seconds = Math.max(0, Math.floor((Date.now() - Date.parse(item.createdAt)) / 1000));
+    const age = seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m`;
+    return `${item.id}\n  ${item.kind} · ${item.agent} · session ${item.sessionId} · pane ${item.paneId} · ${age}\n  Task: ${item.task}\n  Needs you: ${item.blocker}\n  Action: /attention ${item.primaryAction === 'inspect' ? 'show' : item.primaryAction} ${item.id}`;
+}
+export const attentionCommand = {
+    name: 'attention', description: 'Inspect and resolve requests that need a human', usage: USAGE,
+    handler: async (args, ctx) => {
+        const say = (content) => ctx.addMessage({ role: 'system', content });
+        const action = args[0] ?? 'list';
+        if (ctx.commandOrigin === 'agent' && !['list', 'show'].includes(action)) {
+            say('Only you can answer, approve or acknowledge human attention.');
+            return;
+        }
+        try {
+            if (!ctx.attention)
+                throw new Error('Open the attention queue in the native overseer session.');
+            if (action === 'list') {
+                const page = Number(args[1] ?? 1);
+                if (!Number.isSafeInteger(page) || page < 1)
+                    throw new Error('Page must be a positive integer.');
+                const snapshot = ctx.attention.snapshot(100, (page - 1) * 100);
+                say(snapshot.total === 0 ? 'No requests need your attention.' : [`Human attention · ${snapshot.total} items · page ${page}`,
+                    ...snapshot.items.map(describe), ...(snapshot.total > page * 100 ? [`Next: /attention list ${page + 1}`] : [])].join('\n'));
+                return;
+            }
+            const id = args[1];
+            if (!id)
+                throw new Error(USAGE);
+            if (action === 'dismiss') {
+                ctx.attention.dismiss(id);
+                say('Attention acknowledged.');
+                return;
+            }
+            if (action === 'approve' || action === 'deny') {
+                ctx.attention.respond(id, { decision: action, reason: args.slice(2).join(' ') });
+                say(`Approval ${action === 'approve' ? 'approved' : 'denied'}.`);
+                return;
+            }
+            const snapshot = ctx.attention.snapshot();
+            // Search all pages so an ID in a large queue retains its exact owner.
+            let item = snapshot.items.find(item => item.id === id);
+            for (let offset = 100; !item && offset < snapshot.total; offset += 100) {
+                item = ctx.attention.snapshot(100, offset).items.find(item => item.id === id);
+            }
+            if (!item)
+                throw new Error('Stale attention request; inspect the current queue.');
+            if (action === 'show') {
+                say(describe(item));
+                return;
+            }
+            if (action === 'answer') {
+                const text = args.slice(2).join(' ');
+                const response = item.kind === 'prompt'
+                    ? text.trim().startsWith('{') ? JSON.parse(text) : { value: text } : text;
+                ctx.attention.respond(id, response);
+                say('Answer delivered to its request owner.');
+                return;
+            }
+            throw new Error(USAGE);
+        }
+        catch (error) {
+            say(`Attention: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+};

package/dist/agent/commands/auth.js

@@ -3,12 +3,15 @@ import { runRouterAuthCommand } from '../../router_auth.js';
 export const authCommand = {
     name: 'auth',
     description: 'Manage Zerg Router authentication',
-    usage: '<login|logout|status> [options]',
+    usage: '<login|logout|status|readiness|billing> [options]',
+    agentRunnable: false,
     handler: async (args, ctx) => {
         if (args.length === 0 || args[0] === 'help') {
             ctx.addMessage({ role: 'system', content: [
                     'Zerg Router authentication:',
                     '  /auth login [--url <origin>] [--no-browser] - Sign in through your browser',
+                    '  /auth readiness [--json] - Check personal funding and model availability without using quota',
+                    '  /auth billing [--no-browser] - Review personal pay-as-you-go funding in the browser',
                     '  /auth status [--json] - Show the current Router session',
                     '  /auth logout [--local-only] - Sign out',
                     '',
@@ -17,11 +20,24 @@ export const authCommand = {
             return;
         }
         try {
-            await runRouterAuthCommand(args, message => {
+            // Keep process-only --router-url overrides when signing in from a session.
+            const origin = args[0] === 'login' && !args.includes('--url')
+                ? configStore.get().zergProxyUrl : undefined;
+            await runRouterAuthCommand(origin ? [...args, '--url', origin] : args, message => {
                 ctx.addMessage({ role: 'system', content: message.trimEnd() });
             });
             if (args[0] === 'login' || args[0] === 'logout') {
                 await configStore.refresh();
+                if (args[0] === 'login' && configStore.resolveLLMBackendConfig().useProxy) {
+                    // Sign-in changes catalog ownership. Discover before constructing the
+                    // backend so the first turn uses the new account's model metadata.
+                    try {
+                        await ctx.models.catalog?.(undefined, { refresh: true });
+                    }
+                    catch {
+                        // Catalog availability must not undo a successful sign-in.
+                    }
+                }
                 // Logout must dispose of the old backend without building a new one
                 // from missing credentials. Login builds from the newly loaded session.
                 ctx.reloadAgent({ defer: args[0] === 'logout' });

package/dist/agent/commands/board.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from './types.js';
+export declare const boardCommand: Command;

package/dist/agent/commands/board.js

@@ -0,0 +1,169 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { BOARD_PENDING_MAX_BYTES } from '../../board/binding.js';
+import { boardRequest, configuredBoardOrigin, boardCardResponse, boardDetailsResponse, boardAttachmentResponse } from '../../board/client.js';
+import { buildSessionEvidencePackage } from '../../diagnostics/session_evidence_package.js';
+import { loadSessionFromFile, updateSessionBoardBinding } from '../../session.js';
+import { projectTaskHandoff } from '../../session_handoff_contract.js';
+import { withPathLock } from '../../utils/path_lock.js';
+const usage = '/board attach <board-uuid> <card-uuid> | create <board-uuid> <column-uuid> <title> | status | refresh | state <running|blocked|review|done> <state-uuid> | share | sync | discard <operation-uuid> | detach';
+const identity = (value) => z.string().uuid('Invalid Zergboard UUID').parse(value);
+const taskId = (session) => session.task_handoff?.taskId
+    ?? `request:${session.messages.find(message => message.role === 'user')?.id ?? session.metadata.id}`;
+async function run(args, ctx) {
+    const action = args[0];
+    if (!action)
+        return usage;
+    if (!['status'].includes(action) && ctx.commandOrigin === 'agent')
+        return 'Zergboard writes and association changes require an explicit user command.';
+    if (!ctx.checkpointSession || !ctx.getSessionId)
+        return 'Zergboard sync requires a host with a saved session checkpoint.';
+    const sessionId = ctx.getSessionId();
+    const file = await ctx.checkpointSession();
+    // Distinct from the canonical writer lock: serialize whole board operations
+    // in this process, but allow ordinary autosaves while HTTP is pending.
+    return withPathLock(file + '.board-operation', async () => {
+        const session = await loadSessionFromFile(file, false);
+        if (!session || session.metadata.id !== sessionId)
+            throw new Error('Zergboard checkpoint does not belong to the current session');
+        let binding = session.board_binding;
+        const save = async (next) => {
+            await updateSessionBoardBinding(file, sessionId, binding, next);
+            binding = next;
+        };
+        const origin = configuredBoardOrigin();
+        if (binding && binding.origin !== origin)
+            throw new Error('Configured Zergboard origin differs from the attached destination');
+        if (action === 'discard') {
+            if (args.length !== 2)
+                return usage;
+            const key = identity(args[1]);
+            if (!binding?.pending || binding.pending.key !== key)
+                return 'Discard requires the matching pending operation ID; use /board status to inspect it.';
+            // This is an explicit local retirement, not remote cancellation. An
+            // accepted operation can still exist even when its receipt was lost.
+            const next = binding.pending.kind === 'create' ? undefined : { ...binding, pending: undefined };
+            await save(next);
+            return `Pending operation ${key} discarded locally; remote outcome remains unknown. Inspect Zergboard before choosing a fresh operation; /board refresh acknowledges manual changes on an attached card.`;
+        }
+        if (action === 'detach') {
+            if (args.length !== 1)
+                return usage;
+            if (binding?.pending)
+                return `Pending operation ${binding.pending.key} has an unknown remote outcome. Use /board sync first; explicitly /board discard ${binding.pending.key} only after inspecting Zergboard.`;
+            await save(undefined);
+            return 'Zergboard card detached; remote card unchanged.';
+        }
+        if (action === 'attach' || action === 'create') {
+            if (binding)
+                return 'Session already linked or has a pending operation. Use /board status or /board sync; detach before choosing a different task.';
+            const boardId = identity(args[1]), target = identity(args[2]);
+            if (action === 'attach' && args.length !== 3)
+                return usage;
+            if (action === 'create' && args.length < 4)
+                return usage;
+            const details = await boardRequest(origin, sessionId, `/api/boards/${boardId}`, boardDetailsResponse);
+            if (details.board.id !== boardId)
+                throw new Error('Zergboard response belongs to a different board');
+            const next = { version: 1, sessionId, taskUuid: randomUUID(), taskId: taskId(session), origin, boardId };
+            if (action === 'attach') {
+                const { card } = await boardRequest(origin, sessionId, `/api/cards/${target}`, boardCardResponse);
+                if (card.id !== target || card.board_id !== boardId)
+                    throw new Error('Zergboard card belongs to a different board');
+                await save({ ...next, cardId: card.id, revision: card.revision });
+                return `Attached Zergboard card ${card.id} to task ${next.taskUuid}. ${card.title} — ${card.status} (revision ${card.revision}).`;
+            }
+            if (!details.columns.some(column => column.id === target))
+                throw new Error('Zergboard column does not belong to the selected board');
+            const title = z.string().min(1).max(255).parse(args.slice(3).join(' '));
+            await save({ ...next, pending: { kind: 'create', key: randomUUID(), body: { boardId, columnId: target, title,
+                        description: `ZTC session ${sessionId}\nTask ${next.taskUuid}\nSource task ${next.taskId}\nCompletion requires an explicit user decision; idle is not completion.` } } });
+        }
+        else if (!binding)
+            return 'No Zergboard card attached. ' + usage;
+        if (!binding)
+            throw new Error('Zergboard association unavailable');
+        if (action === 'status' || action === 'refresh') {
+            if (args.length !== 1)
+                return usage;
+            if (!binding.cardId)
+                return `Zergboard creation pending for task ${binding.taskUuid}; operation ${binding.pending?.key}. Use /board sync first; inspect Zergboard before explicitly discarding an unknown outcome.`;
+            const { card } = await boardRequest(origin, sessionId, `/api/cards/${binding.cardId}`, boardCardResponse);
+            if (card.id !== binding.cardId || card.board_id !== binding.boardId)
+                throw new Error('Attached card moved to a different board; sync refused');
+            if (action === 'refresh') {
+                if (binding.pending)
+                    return `Pending operation ${binding.pending.key} retains its original revision. Use /board sync first; inspect Zergboard before explicitly /board discard ${binding.pending.key}.`;
+                await save({ ...binding, revision: card.revision });
+            }
+            return `Zergboard ${card.id}: ${card.title} — ${card.status}, state ${card.state_id ?? 'unknown'}, revision ${card.revision}; acknowledged revision ${binding.revision}. Task ${binding.taskUuid}.${binding.pending ? ` Pending operation ${binding.pending.key} retained; use /board sync first; inspect Zergboard before explicitly discarding an unknown outcome.` : ''} Idle never establishes completion.`;
+        }
+        if (action === 'state') {
+            if (args.length !== 3 || !['running', 'blocked', 'review', 'done'].includes(args[1]))
+                return usage;
+            if (!binding.cardId || binding.pending)
+                return 'Reconcile the pending operation with /board sync before changing state.';
+            const stateId = identity(args[2]);
+            const details = await boardRequest(origin, sessionId, `/api/boards/${binding.boardId}`, boardDetailsResponse);
+            const state = details.states.find(state => state.id === stateId);
+            if (details.board.id !== binding.boardId || !state || (args[1] === 'done') !== (state.kind === 'done'))
+                throw new Error('Selected state is not a matching state on the attached board');
+            const { card } = await boardRequest(origin, sessionId, `/api/cards/${binding.cardId}`, boardCardResponse, { method: 'PATCH', body: { stateId }, revision: binding.revision });
+            if (card.id !== binding.cardId || card.board_id !== binding.boardId || card.state_id !== stateId)
+                throw new Error('Zergboard state receipt does not match the requested card/state');
+            await save({ ...binding, revision: card.revision });
+            return `Zergboard ${args[1]} decision saved: ${card.status}, revision ${card.revision}.`;
+        }
+        if (action === 'share') {
+            if (args.length !== 1)
+                return usage;
+            if (binding.pending)
+                return 'Pending operation retained. Use /board sync before sharing a newer checkpoint.';
+            if (!binding.cardId)
+                return 'Create or attach a card before sharing evidence.';
+            if (binding.taskId !== taskId(session))
+                return 'Current session task changed; detach and explicitly attach the new task before sharing evidence.';
+            const pkg = buildSessionEvidencePackage({ sessionId, messages: session.messages, diagnostics: session.diagnostics,
+                evidence: session.evidence, taskHandoff: session.task_handoff ? projectTaskHandoff(session.task_handoff) : null });
+            if (binding.lastEvidence?.packageId === pkg.packageId)
+                return `Evidence package ${pkg.packageId} already shared as attachment ${binding.lastEvidence.attachmentId}.`;
+            const bytes = Buffer.from(JSON.stringify(pkg));
+            if (bytes.length > BOARD_PENDING_MAX_BYTES)
+                return 'Evidence package exceeds the 512 KiB sync limit. Use /clipboard package save to export the full package to a file.';
+            await save({ ...binding, pending: { kind: 'evidence', key: randomUUID(), packageId: pkg.packageId,
+                    expectedRevision: binding.revision, body: { filename: `ztc-${pkg.packageId}.json`, mime_type: 'application/json', data: bytes.toString('base64') } } });
+        }
+        if (['sync', 'share', 'create'].includes(action)) {
+            if (action === 'sync' && args.length !== 1)
+                return usage;
+            const pending = binding.pending;
+            if (!pending)
+                return 'No pending Zergboard operation. Use /board status to inspect the remote card.';
+            if (pending.kind === 'create') {
+                const { card } = await boardRequest(origin, sessionId, '/api/cards/terminal-sync-v1', boardCardResponse, { method: 'POST', body: pending.body, key: pending.key });
+                if (card.board_id !== binding.boardId)
+                    throw new Error('Zergboard creation receipt belongs to a different board');
+                await save({ ...binding, pending: undefined, cardId: card.id, revision: card.revision });
+                return `Attached Zergboard card ${card.id} to task ${binding.taskUuid}.`;
+            }
+            const receipt = await boardRequest(origin, sessionId, `/api/cards/${binding.cardId}/terminal-evidence-v1`, boardAttachmentResponse, { method: 'POST', body: pending.body, key: pending.key, revision: pending.expectedRevision });
+            if (receipt.attachment.card_id !== binding.cardId)
+                throw new Error('Zergboard evidence receipt belongs to a different card');
+            await save({ ...binding, pending: undefined, revision: receipt.revision,
+                lastEvidence: { packageId: pending.packageId, attachmentId: receipt.attachment.id, revision: receipt.revision } });
+            return `Evidence receipt saved: attachment ${receipt.attachment.id}, package ${pending.packageId}. Receipt proves accepted bytes; it does not establish task completion.`;
+        }
+        return usage;
+    });
+}
+export const boardCommand = { name: 'board', description: 'Attach a saved session to Zergboard and explicitly sync state/evidence', usage,
+    async handler(args, ctx) {
+        try {
+            ctx.addMessage({ role: 'system', content: await run(args, ctx) });
+        }
+        catch (error) {
+            // Never echo remote response bodies or credentials into the transcript.
+            const message = error instanceof Error ? error.message : 'Request failed';
+            ctx.addMessage({ role: 'system', content: `Zergboard: ${message}. Operation outcome may be unknown; pending intent is retained for /board sync.` });
+        }
+    } };