wehandoff 0.0.1 → 0.1.0

package/bin/wehandoff.mjs

@@ -0,0 +1,1682 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import { resolveToken, resolveBaseUrl, callApi, callApiRaw } from './_whf/http.mjs';
+import {
+  findEntry,
+  buildManifest,
+  renderHelpEntry,
+  renderTopHelp,
+  resolveResource,
+} from './_whf/registry.mjs';
+import {
+  assetDir,
+  clearMerged,
+  isDirty,
+  readMeta,
+  readWorkingCopy,
+  threeWayMerge,
+  writeMergedConflict,
+  writeMeta,
+  writeWorkingBody,
+  writeWorkingCopy,
+} from './_whf/shared-asset.mjs';
+
+// Where the local working copy for a shared asset lives — surfaced in `asset
+// share/pull` output so the user knows which file to edit before `asset push`.
+const assetDirHint = (assetId) => assetDir(assetId);
+
+function ok(payload) {
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+  process.exit(0);
+}
+
+function fail(message, code = 1) {
+  process.stdout.write(`${JSON.stringify({ error: message })}\n`);
+  process.exit(code);
+}
+
+// Print a structured payload AND exit non-zero — for an expected non-success
+// outcome that still carries actionable fields (e.g. an `asset push` 3-way
+// conflict reporting the .merged path). Unlike fail(), it does NOT wrap the
+// payload under { error }, so callers read the fields directly.
+function failJson(payload, code = 1) {
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) {
+        out[arg.slice(2)] = true;
+      } else {
+        out[arg.slice(2)] = next;
+        i++;
+      }
+    } else {
+      out._.push(arg);
+    }
+  }
+  return out;
+}
+
+function firstParagraph(markdown) {
+  const withoutFrontmatter = markdown.replace(/^---\s*\n[\s\S]*?\n---\s*\n?/, '');
+  return withoutFrontmatter
+    .split(/\n\s*\n/)
+    .map((p) => p.trim().replace(/\s+/g, ' '))
+    .find(Boolean);
+}
+
+function readSkillSnapshot(name) {
+  const paths = [
+    resolvePath(process.cwd(), '.claude', 'skills', name, 'skill.md'),
+    resolvePath(process.cwd(), '.claude', 'skills', name, 'SKILL.md'),
+    resolvePath(process.cwd(), 'skills', name, 'skill.md'),
+    resolvePath(process.cwd(), 'skills', name, 'SKILL.md'),
+  ];
+  const path = paths.find((p) => existsSync(p));
+  if (!path) fail(`skill not found: ${name}`);
+  const description = firstParagraph(readFileSync(path, 'utf8')) ?? '';
+  return { skill_name: name, skill_description: description.slice(0, 500) };
+}
+
+function help() {
+  // Top-level help is generated from the command registry (single source of
+  // truth) so it can never drift from `which` or per-verb `--help` (NO.1535).
+  process.stdout.write(`${renderTopHelp()}\n`);
+}
+
+// package.json version — surfaced in the `which` manifest so an agent sees
+// exactly which CLI build it is talking to.
+function cliVersion() {
+  try {
+    const pkgPath = resolvePath(import.meta.dirname ?? process.cwd(), '..', 'package.json');
+    return JSON.parse(readFileSync(pkgPath, 'utf8')).version ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+    help();
+    process.exit(0);
+  }
+
+  // Resolve back-compat resource aliases (DEC-191: `issue` → canonical `task`)
+  // ONCE here, so every downstream branch — the dispatch if-chain, per-verb help,
+  // and `which`'s --resource filter — sees the canonical noun. `whf issue …`
+  // keeps working silently (no nag); help/manifest advertise `task`.
+  const [rawResource, verb, ...rest] = argv;
+  const resource = resolveResource(rawResource);
+
+  // `which` is the capability manifest — it runs BEFORE the token gate so an
+  // agent can bootstrap the whole command surface with zero auth (redesign §3).
+  // It exposes verb/flag metadata + the resolved baseUrl, no data.
+  if (resource === 'which') {
+    const wargs = parseArgs([verb, ...rest].filter((x) => x !== undefined));
+    const resourceFilter =
+      typeof wargs.resource === 'string' ? resolveResource(wargs.resource) : undefined;
+    ok(buildManifest({ version: cliVersion(), baseUrl: resolveBaseUrl(), resourceFilter }));
+  }
+
+  // Per-verb `--help` is generated from the registry entry — also pre-token-gate
+  // (help needs no auth). Returns the single registry entry as JSON (usage/flags/output).
+  if (verb === '--help' || rest.includes('--help')) {
+    const entry = findEntry(resource, verb === '--help' ? undefined : verb);
+    if (entry) ok(renderHelpEntry(entry));
+    // no registry entry → fall through to legacy/usage handling below.
+  }
+
+  // `workflow run <script> [...flags]` is a LOCAL command — it runs the TS orchestrator
+  // via tsx, needs no cloud token, so handle it before the token gate below.
+  if (resource === 'workflow' && verb === 'run') {
+    const { spawnSync } = await import('node:child_process');
+    const { fileURLToPath } = await import('node:url');
+    const nodePath = await import('node:path');
+    const repoRoot = nodePath.resolve(nodePath.dirname(fileURLToPath(import.meta.url)), '..');
+    const runCli = nodePath.join(repoRoot, 'apps/desktop/src/main/agent/orchestrator/run-cli.ts');
+    const r = spawnSync('pnpm', ['exec', 'tsx', runCli, ...rest], {
+      cwd: repoRoot,
+      stdio: 'inherit',
+    });
+    process.exit(r.status ?? 1);
+  }
+
+  const args = parseArgs(rest);
+  const token = resolveToken();
+  if (!token) fail('no token: set WEHANDOFF_CLI_TOKEN or ~/.wehandoff/cli-token');
+  const baseUrl = resolveBaseUrl();
+
+  try {
+    // ask — agent reverse-asks the human with structured options (SPEC §15 /
+    // DEC-227 ask_card = AskUserQuestion group). channel form publishes a card +
+    // inbox item; session form is inbox-only. No sub-verb, so re-parse flags from
+    // [verb, ...rest].
+    //
+    // One ask = a group of 1..N questions. Two input shapes:
+    //   --question <q> --options "a|b|c"            a single-question group (N=1)
+    //   --questions '[{"question":"…","options":["a","b"]}, …]'   the full group
+    if (resource === 'ask') {
+      const a = parseArgs([verb, ...rest].filter(Boolean));
+      let questions;
+      if (a.questions) {
+        try {
+          questions = JSON.parse(String(a.questions));
+        } catch {
+          fail('--questions must be valid JSON (an array of { question, options })');
+        }
+      } else if (a.question && a.options) {
+        questions = [
+          {
+            question: String(a.question),
+            options: String(a.options)
+              .split('|')
+              .map((s) => s.trim())
+              .filter(Boolean),
+          },
+        ];
+      }
+      if (!questions || !Array.isArray(questions) || (!a.channel && !a.session)) {
+        fail(
+          'usage: wehandoff ask (--question <q> --options "a|b|c" | --questions \'[{"question":"…","options":["a","b"]}]\') (--channel <id> --as-agent <id> [--user <id>] | --session <id>)'
+        );
+      }
+      return ok(
+        await callApi(
+          {
+            method: 'POST',
+            path: '/api/cli/asks',
+            body: {
+              room_id: a.channel,
+              session_id: a.session,
+              user_id: a.user,
+              questions,
+              as_agent_id: a['as-agent'],
+            },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // inbox push — agent pushes a generic HITL card to a user's inbox (inbox
+    // spec §5 / §2.4: 一张卡=谁推的+从哪来+一句话+几个按钮). Buttons default to
+    // resolve actions (choice recorded server-side); channel/session 反问语义
+    // belongs to `wehandoff ask` above.
+    if (resource === 'inbox') {
+      if (verb !== 'push') fail(`unknown inbox subcommand: ${verb ?? '(none)'}`);
+      const options = String(args.options ?? '')
+        .split('|')
+        .map((s) => s.trim())
+        .filter(Boolean);
+      if (!args.title || options.length === 0) {
+        fail(
+          'usage: wehandoff inbox push --title <t> --options "a|b|c" [--user <id>] [--issue <id>] [--preview <id>] [--payload <json>]'
+        );
+      }
+      let payload;
+      if (args.payload) {
+        try {
+          payload = JSON.parse(String(args.payload));
+        } catch {
+          fail('--payload must be valid JSON');
+        }
+      }
+      return ok(
+        await callApi(
+          {
+            method: 'POST',
+            path: '/api/cli/inbox',
+            body: {
+              title: args.title,
+              options,
+              ...(args.user ? { user_id: args.user } : {}),
+              ...(args.issue ? { issue_id: args.issue } : {}),
+              ...(args.preview ? { preview_id: args.preview } : {}),
+              ...(payload ? { payload } : {}),
+            },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // message send / reply — agent (or its owner) posts a text message into a
+    // channel it belongs to (SPEC §16 「agent 也可显式 whf message send」).
+    // --image <path>: upload PNG/JPG → attach to the message so it renders as
+    // a real image in the forum/room (NO.2060). Mirrors task comment --image flow.
+    if (resource === 'message' && (verb === 'send' || verb === 'reply')) {
+      if (!args.channel || !args.text) {
+        fail(
+          `usage: wehandoff message ${verb} --channel <id> --text <t>${verb === 'reply' ? ' --to <msgId>' : ''} [--as-agent <id>] [--image <png>]`
+        );
+      }
+      if (verb === 'reply' && !args.to)
+        fail('usage: wehandoff message reply --channel <id> --to <msgId> --text <t>');
+
+      // --image: upload the image bytes to the attachments bucket, then attach
+      // to the message. Three-step mirrors task comment --image (lines 629-668).
+      let attachments;
+      if (args.image) {
+        const imgPath = resolvePath(String(args.image));
+        if (!existsSync(imgPath)) fail(`image not found: ${imgPath}`);
+        const filename = imgPath.split(/[/\\]/).pop() || 'image.png';
+        const ext = (filename.split('.').pop() || '').toLowerCase();
+        const mime = {
+          png: 'image/png',
+          jpg: 'image/jpeg',
+          jpeg: 'image/jpeg',
+          webp: 'image/webp',
+          gif: 'image/gif',
+          avif: 'image/avif',
+          svg: 'image/svg+xml',
+        }[ext];
+        if (!mime) fail(`unsupported image type .${ext} (png/jpg/webp/gif/avif/svg)`);
+        const dataBase64 = readFileSync(imgPath).toString('base64');
+        const up = await callApi(
+          {
+            method: 'POST',
+            path: '/api/cli/messages/attachments',
+            body: { channelId: args.channel, filename, mime, dataBase64 },
+          },
+          { token, baseUrl }
+        );
+        attachments = [
+          { storagePath: up.storage_path, kind: 'image', name: filename, mime, size: up.size },
+        ];
+      }
+
+      return ok(
+        await callApi(
+          {
+            method: 'POST',
+            path: '/api/cli/messages',
+            body: {
+              channelId: args.channel,
+              text: args.text,
+              asAgentId: args['as-agent'],
+              ...(verb === 'reply' ? { quotedMessageId: args.to } : {}),
+              ...(attachments ? { attachments } : {}),
+            },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    if (resource === 'message' && verb === 'list') {
+      if (!args.channel) fail('usage: wehandoff message list --channel <id> [--limit <n>]');
+      const qs = `channel=${encodeURIComponent(args.channel)}${args.limit ? `&limit=${encodeURIComponent(args.limit)}` : ''}`;
+      return ok(
+        await callApi({ method: 'GET', path: `/api/cli/messages?${qs}` }, { token, baseUrl })
+      );
+    }
+
+    // message get — fetch one message (the quote / pin target may live outside
+    // the loaded window). Channel-scoped + member-gated server-side. (whf-cli §4)
+    if (resource === 'message' && verb === 'get') {
+      if (!args.channel || !args.msg)
+        fail('usage: wehandoff message get --channel <id> --msg <id>');
+      return ok(
+        await callApi(
+          {
+            method: 'GET',
+            path: `/api/cli/messages/${encodeURIComponent(args.msg)}?channel=${encodeURIComponent(args.channel)}`,
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // message edit — edit your own text message (author-gated server-side via
+    // editOwnMessage; mirrors the web PATCH route). (whf-cli §4)
+    if (resource === 'message' && verb === 'edit') {
+      if (!args.channel || !args.msg || !args.text) {
+        fail('usage: wehandoff message edit --channel <id> --msg <id> --text <t>');
+      }
+      return ok(
+        await callApi(
+          {
+            method: 'PATCH',
+            path: `/api/cli/messages/${encodeURIComponent(args.msg)}`,
+            body: { channel: args.channel, text: args.text },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // message delete — soft-delete your own message (author-gated, tombstone via
+    // softDeleteMessage). (whf-cli §4)
+    if (resource === 'message' && verb === 'delete') {
+      if (!args.channel || !args.msg)
+        fail('usage: wehandoff message delete --channel <id> --msg <id>');
+      return ok(
+        await callApi(
+          {
+            method: 'DELETE',
+            path: `/api/cli/messages/${encodeURIComponent(args.msg)}`,
+            body: { channel: args.channel },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // message forward — relay a message to an L3 session (SPEC §1.5 forward{…} /
+    // §16). The web producer (/api/groups/[id]/messages/[msgId]/forward → persistForward)
+    // inserts a `forward`-type message into the SOURCE room carrying the target
+    // session id; the target owner's daemon soft-interrupts that session. This is
+    // the CLI mirror over the `wh-cli:` token. `--note` = the forwarder's private
+    // interpretation (SPEC-SAMPLE 22 「补私下解读」).
+    if (resource === 'message' && verb === 'forward') {
+      if (!args.channel || !args.msg || !args['to-session']) {
+        fail(
+          'usage: wehandoff message forward --channel <id> --msg <msgId> --to-session <sessionId> [--note <md>]'
+        );
+      }
+      return ok(
+        await callApi(
+          {
+            method: 'POST',
+            path: `/api/cli/messages/${encodeURIComponent(args.msg)}/forward`,
+            body: {
+              channel: args.channel,
+              targetSessionId: args['to-session'],
+              note: args.note,
+            },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // message {merge-forward,download,search} + room search + thread messages —
+    // SPEC §16 says these need NEW/修 backend fns (FTS, merge-forward writer,
+    // attachment-fetch repair, by-root thread query) NOT built this round. Honest
+    // "not yet implemented" rather than a silent no-op.
+    if (
+      resource === 'message' &&
+      (verb === 'merge-forward' || verb === 'download' || verb === 'search')
+    ) {
+      fail(
+        `not yet implemented: \`message ${verb}\` needs a new/repaired backend (SPEC §16, whf-cli design §4). See report.`,
+        2
+      );
+    }
+    if (resource === 'room' && verb === 'search') {
+      fail('not yet implemented: `room search` needs an FTS backend (SPEC §16). See report.', 2);
+    }
+    if (resource === 'thread' && verb === 'messages') {
+      fail(
+        'not yet implemented: `thread messages --root` needs a by-root thread query (SPEC §16). For forum threads use `message list --channel <threadId>`.',
+        2
+      );
+    }
+
+    // reaction add/remove/list — emoji reactions (whf-cli §4 「reaction」). add/
+    // remove are idempotent (route converges via toggleReaction). --as-agent
+    // reacts AS an owned member agent (ownership verified server-side).
+    if (resource === 'reaction' && (verb === 'add' || verb === 'remove')) {
+      if (!args.channel || !args.msg || !args.emoji) {
+        fail(
+          `usage: wehandoff reaction ${verb} --channel <id> --msg <id> --emoji <e> [--as-agent <id>]`
+        );
+      }
+      return ok(
+        await callApi(
+          {
+            method: 'POST',
+            path: `/api/cli/messages/${encodeURIComponent(args.msg)}/reactions`,
+            body: {
+              channel: args.channel,
+              emoji: args.emoji,
+              op: verb,
+              asAgentId: args['as-agent'],
+            },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+    if (resource === 'reaction' && verb === 'list') {
+      if (!args.channel || !args.msg)
+        fail('usage: wehandoff reaction list --channel <id> --msg <id>');
+      return ok(
+        await callApi(
+          {
+            method: 'GET',
+            path: `/api/cli/messages/${encodeURIComponent(args.msg)}/reactions?channel=${encodeURIComponent(args.channel)}`,
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // reaction batch — reactions across many messages at once (lark
+    // reactions.batch_query). --msgs is a comma-separated id list. (whf-cli §4)
+    if (resource === 'reaction' && verb === 'batch') {
+      if (!args.channel || !args.msgs)
+        fail('usage: wehandoff reaction batch --channel <id> --msgs <id,id,...>');
+      const qs = `channel=${encodeURIComponent(args.channel)}&msgs=${encodeURIComponent(args.msgs)}`;
+      return ok(
+        await callApi(
+          { method: 'GET', path: `/api/cli/messages/reactions?${qs}` },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // pin add/remove/list — pin messages (whf-cli §4 「pin」). add/remove are
+    // idempotent (route converges via togglePin). Any channel member may pin.
+    if (resource === 'pin' && (verb === 'add' || verb === 'remove')) {
+      if (!args.channel || !args.msg)
+        fail(`usage: wehandoff pin ${verb} --channel <id> --msg <id>`);
+      return ok(
+        await callApi(
+          {
+            method: 'POST',
+            path: '/api/cli/pins',
+            body: { channel: args.channel, msg: args.msg, op: verb },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+    if (resource === 'pin' && verb === 'list') {
+      if (!args.channel) fail('usage: wehandoff pin list --channel <id>');
+      return ok(
+        await callApi(
+          { method: 'GET', path: `/api/cli/pins?channel=${encodeURIComponent(args.channel)}` },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    if (resource === 'room' && verb === 'create') {
+      if (!args.name) fail('usage: wehandoff room create --name <name> [--type text|forum]');
+      if (args.type && args.type !== 'text' && args.type !== 'forum')
+        fail('channel create: --type must be text or forum');
+      const { conversation_id } = await callApi(
+        {
+          method: 'POST',
+          path: '/api/cli/groups',
+          body: { name: args.name, ...(args.type ? { type: args.type } : {}) },
+        },
+        { token, baseUrl }
+      );
+      return ok({ channel_id: conversation_id });
+    }
+
+    // channel list — channels the caller owns/belongs to (owner/membership-gated
+    // server-side). Read passthrough: prints the route's JSON verbatim. (whf-cli §4)
+    if (resource === 'room' && verb === 'list') {
+      return ok(await callApi({ method: 'GET', path: '/api/cli/groups' }, { token, baseUrl }));
+    }
+
+    // channel get — fetch one channel row (member-gated server-side). (whf-cli §4)
+    if (resource === 'room' && verb === 'get') {
+      if (!args.channel) fail('usage: wehandoff room get --channel <id>');
+      return ok(
+        await callApi(
+          { method: 'GET', path: `/api/cli/groups/${encodeURIComponent(args.channel)}` },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // channel members / agents — list a channel's members (member-gated). `agents`
+    // is the same list filtered to member_type === 'agent' (lark chat.members.bots).
+    if (resource === 'room' && (verb === 'members' || verb === 'agents')) {
+      if (!args.channel) fail(`usage: wehandoff room ${verb} --channel <id>`);
+      const { channel, members } = await callApi(
+        { method: 'GET', path: `/api/cli/groups/${encodeURIComponent(args.channel)}?with=members` },
+        { token, baseUrl }
+      );
+      const filtered =
+        verb === 'agents'
+          ? (members ?? []).filter((m) => m.memberType === 'agent')
+          : (members ?? []);
+      return ok({ channel, members: filtered });
+    }
+
+    // channel update — rename a channel (owner-gated server-side via renameGroup).
+    if (resource === 'room' && verb === 'update') {
+      if (!args.channel || !args.name)
+        fail('usage: wehandoff room update --channel <id> --name <name>');
+      return ok(
+        await callApi(
+          {
+            method: 'PATCH',
+            path: `/api/cli/groups/${encodeURIComponent(args.channel)}`,
+            body: { name: args.name },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // channel delete — archive (default) or hard-delete (--hard) the WHOLE channel
+    // (owner-gated server-side via archiveGroup/deleteGroup). Hits the `/delete`
+    // SUB-route, NOT bare `/groups/<id>` (which is member-kick) — and sends NO body,
+    // so it can never be mistaken for a member removal. (whf-cli §4, B4)
+    if (resource === 'room' && verb === 'delete') {
+      if (!args.channel) fail('usage: wehandoff room delete --channel <id> [--hard]');
+      const qs = args.hard ? '?hard=1' : '';
+      return ok(
+        await callApi(
+          {
+            method: 'DELETE',
+            path: `/api/cli/groups/${encodeURIComponent(args.channel)}/delete${qs}`,
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // channel remove-member — kick a member (owner-gated server-side via kickMember).
+    // --member-type defaults to 'user'; pass 'agent' to remove an agent member.
+    if (resource === 'room' && verb === 'remove-member') {
+      if (!args.channel || !args.member)
+        fail(
+          'usage: wehandoff room remove-member --channel <id> --member <id> [--member-type user|agent]'
+        );
+      return ok(
+        await callApi(
+          {
+            method: 'DELETE',
+            path: `/api/cli/groups/${encodeURIComponent(args.channel)}`,
+            body: { member: args.member, member_type: args['member-type'] ?? 'user' },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    if (resource === 'task' && verb === 'create') {
+      if (!args.title)
+        fail(
+          'usage: wehandoff task create --title <t> [--description <d>] [--domain <科室>] [--as-agent <id>]'
+        );
+      return ok(
+        await callApi(
+          {
+            method: 'POST',
+            path: '/api/cli/tasks',
+            body: {
+              title: args.title,
+              description: args.description,
+              // --domain: 科室 (NO.1847). Optional here — if omitted the server derives from an
+              // area= tag in title/description and rejects the task if it can't (never null).
+              ...(args.domain ? { domain: args.domain } : {}),
+              // --as-agent: open the issue AS an agent the caller owns (NO.348/243,
+              // §0 agent=人). Ownership verified server-side against agent.owner_id.
+              ...(args['as-agent'] ? { creatorType: 'agent', creatorId: args['as-agent'] } : {}),
+            },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // issue get — read one issue (creator-gated server-side: only the issue's
+    // creator may read it via the CLI surface). Returns { issue }. (NO.984 route)
+    if (resource === 'task' && verb === 'get') {
+      if (!args.issue) fail('usage: wehandoff task get --issue <id>');
+      return ok(
+        await callApi({ method: 'GET', path: `/api/cli/tasks/${args.issue}` }, { token, baseUrl })
+      );
+    }
+
+    // issue update — edit title/description ONLY. Status is intentionally NOT
+    // settable here: it has its own free-set path via `issue writeback`, so an
+    // edit never silently moves status (the route's IssueEdit excludes it).
+    // Sends only the fields actually passed. Returns { issue }. (NO.984 route)
+    if (resource === 'task' && verb === 'update') {
+      if (!args.issue || (args.title === undefined && args.description === undefined)) {
+        fail('usage: wehandoff task update --issue <id> [--title <t>] [--description <d>]');
+      }
+      return ok(
+        await callApi(
+          {
+            method: 'PATCH',
+            path: `/api/cli/tasks/${args.issue}`,
+            body: {
+              ...(args.title !== undefined ? { title: args.title } : {}),
+              ...(args.description !== undefined ? { description: args.description } : {}),
+            },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // issue delete — hard-delete the issue (creator-gated server-side via
+    // deleteIssue). Returns { issue_id, deleted:true }. (NO.984 route)
+    if (resource === 'task' && verb === 'delete') {
+      if (!args.issue) fail('usage: wehandoff task delete --issue <id>');
+      return ok(
+        await callApi(
+          { method: 'DELETE', path: `/api/cli/tasks/${args.issue}` },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // task goal — set or show the task's goal field (feat/goal-adversarial-verification).
+    // Show:  whf task goal --issue <id>              → prints kind + text/storyId
+    // Set:   whf task goal --issue <id> --prose "<t>" → kind:prose, text:<t>
+    //        whf task goal --issue <id> --story <id>  → kind:story, storyId:<id>
+    if (resource === 'task' && verb === 'goal') {
+      if (!args.issue)
+        fail('usage: wehandoff task goal --issue <id> [--prose "<text>" | --story <storyId>]');
+      // show — no mutation flag present
+      if (args.prose === undefined && args.story === undefined) {
+        const { task } = await callApi(
+          { method: 'GET', path: `/api/cli/tasks/${args.issue}` },
+          { token, baseUrl }
+        );
+        const g = task?.goal;
+        if (!g) return ok({ goal: null });
+        const summary =
+          g.kind === 'story'
+            ? `kind: story · ${g.storyId ?? '(no storyId)'}`
+            : `kind: prose · ${g.text ?? '(empty)'}`;
+        return ok({ goal: g, summary });
+      }
+      // set — exactly one of --prose / --story
+      if (args.prose !== undefined && args.story !== undefined) {
+        fail('--prose and --story are mutually exclusive');
+      }
+      const goal =
+        args.prose !== undefined
+          ? { kind: 'prose', text: String(args.prose) }
+          : { kind: 'story', storyId: String(args.story) };
+      return ok(
+        await callApi(
+          {
+            method: 'PATCH',
+            path: `/api/cli/tasks/${args.issue}`,
+            body: { goal },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // forum post — author a forum thread (SPEC §1.6 / §16, NO.553). Author defaults
+    // to the CLI caller (user); pass --as-agent <id> to post AS an agent the caller
+    // owns (ownership verified server-side, mirrors `issue create --as-agent`).
+    if (resource === 'forum' && verb === 'post') {
+      if (!args.forum || !args.title || !args.body) {
+        fail('usage: wehandoff forum post --forum <id> --title <t> --body <t> [--as-agent <id>]');
+      }
+      return ok(
+        await callApi(
+          {
+            method: 'POST',
+            path: '/api/cli/forum/posts',
+            body: {
+              forumId: args.forum,
+              title: args.title,
+              body: args.body,
+              asAgentId: args['as-agent'],
+            },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // issue comment — one activity-feed entry (SPEC §6): optional status推进,
+    // 挂 artifact (报告) / preview (证据) / user_story (回归声明). 自由态, 无闸.
+    // --image <path> 上传截图: PNG/JPG bytes → cloud `image` artifact → 挂到 comment,
+    // 让接活 agent 读得到 (NO.1678). 与 --artifact 互斥 (一条 comment 挂一个 artifact).
+    if (resource === 'task' && verb === 'comment') {
+      if (!args.issue)
+        fail(
+          'usage: wehandoff task comment --issue <id> [--body <t>] [--status <s>] [--artifact <id>] [--image <png>] [--preview <id>] [--us <id,id>] [--as-agent <id>]'
+        );
+      const userStoryIds = args.us
+        ? String(args.us)
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean)
+        : undefined;
+
+      // --image: upload the screenshot → create an `image` artifact → hang it on
+      // the comment. Three-step because the artifact id must exist before the
+      // comment references it (mirrors the web sign→PUT→artifact flow, but the
+      // CLI ships bytes to a serviceRole route since it has no Supabase session).
+      let artifactId = args.artifact;
+      if (args.image) {
+        if (args.artifact)
+          fail('--image and --artifact are mutually exclusive (one artifact per comment)');
+        const imgPath = resolvePath(String(args.image));
+        if (!existsSync(imgPath)) fail(`image not found: ${imgPath}`);
+        const filename = imgPath.split(/[/\\]/).pop() || 'screenshot.png';
+        const ext = (filename.split('.').pop() || '').toLowerCase();
+        const mime = {
+          png: 'image/png',
+          jpg: 'image/jpeg',
+          jpeg: 'image/jpeg',
+          webp: 'image/webp',
+          gif: 'image/gif',
+          avif: 'image/avif',
+          svg: 'image/svg+xml',
+        }[ext];
+        if (!mime) fail(`unsupported image type .${ext} (png/jpg/webp/gif/avif/svg)`);
+        const dataBase64 = readFileSync(imgPath).toString('base64');
+        const up = await callApi(
+          {
+            method: 'POST',
+            path: `/api/cli/tasks/${args.issue}/attachments`,
+            body: { filename, mime, dataBase64 },
+          },
+          { token, baseUrl }
+        );
+        const art = await callApi(
+          {
+            method: 'POST',
+            path: '/api/cli/artifacts',
+            body: {
+              kind: 'image',
+              title: filename,
+              storagePath: up.storage_path,
+              authorAgentId: args['as-agent'],
+            },
+          },
+          { token, baseUrl }
+        );
+        artifactId = art.artifact_id;
+      }
+
+      const commentResult = await callApiRaw(
+        {
+          method: 'POST',
+          path: `/api/cli/tasks/${args.issue}/comment`,
+          body: {
+            body: args.body,
+            status: args.status,
+            artifactId,
+            previewId: args.preview,
+            userStoryIds,
+            authorAgentId: args['as-agent'],
+          },
+        },
+        { token, baseUrl }
+      );
+      if (commentResult.status === 422 && commentResult.json?.error === 'verification_failed') {
+        const attacks = Array.isArray(commentResult.json.attacks) ? commentResult.json.attacks : [];
+        process.stdout.write('✗ 验证未通过 (goal 未达成):\n');
+        for (const attack of attacks) {
+          process.stdout.write(`  - ${attack}\n`);
+        }
+        process.exit(1);
+      }
+      if (!commentResult.ok) {
+        fail(
+          commentResult.json?.error ?? String(commentResult.json) ?? `HTTP ${commentResult.status}`
+        );
+      }
+      return ok(commentResult.json);
+    }
+
+    // issue comment-delete — remove one activity-feed comment (SPEC §6). Caller
+    // may only delete a comment they authored (user) or one authored by an agent
+    // they own (server-side authz, mirrors `issue comment --as-agent`). Status
+    // set by the comment is NOT rolled back (free-set state, not derived).
+    if (resource === 'task' && verb === 'comment-delete') {
+      if (!args.issue || !args.comment)
+        fail('usage: wehandoff task comment-delete --issue <id> --comment <commentId>');
+      return ok(
+        await callApi(
+          {
+            method: 'DELETE',
+            path: `/api/cli/tasks/${args.issue}/comment/${args.comment}`,
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // task comments — read the activity feed (chronological task_comment rows) for an
+    // issue, including image artifacts as `artifact.href` (public URL from the
+    // `attachments` bucket, NO.1678). Lets an agent fetch comment images without the
+    // desktop app/daemon. Creator-gated server-side (mirrors `task get`).
+    if (resource === 'task' && verb === 'comments') {
+      if (!args.issue) fail('usage: wehandoff task comments --issue <id>');
+      return ok(
+        await callApi(
+          { method: 'GET', path: `/api/cli/tasks/${args.issue}/comments` },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // issue writeback — §9 执行→通告: the session-completion caller. Push the issue
+    // to a delivered status AND/OR POST an artifact_card back to the issue's ORIGIN
+    // channel (the 提为Issue provenance). `--deploy-url` here = the §9 acceptance
+    // evidence URL (recorded in the activity feed), not a platform deploy URL
+    // (DEC-189 — the platform tracks none). Returns { status, announced }.
+    if (resource === 'task' && verb === 'writeback') {
+      if (!args.issue)
+        fail(
+          'usage: wehandoff task writeback --issue <id> [--status <s>] [--deploy-url <u>] [--commit <sha>]'
+        );
+      const writebackResult = await callApiRaw(
+        {
+          method: 'POST',
+          path: `/api/cli/tasks/${args.issue}/writeback`,
+          body: {
+            status: args.status,
+            deployUrl: args['deploy-url'],
+            commitSha: args.commit,
+          },
+        },
+        { token, baseUrl }
+      );
+      if (writebackResult.status === 422 && writebackResult.json?.error === 'verification_failed') {
+        const attacks = Array.isArray(writebackResult.json.attacks)
+          ? writebackResult.json.attacks
+          : [];
+        process.stdout.write('✗ 验证未通过 (goal 未达成):\n');
+        for (const attack of attacks) {
+          process.stdout.write(`  - ${attack}\n`);
+        }
+        process.exit(1);
+      }
+      if (!writebackResult.ok) {
+        fail(
+          writebackResult.json?.error ??
+            String(writebackResult.json) ??
+            `HTTP ${writebackResult.status}`
+        );
+      }
+      return ok(writebackResult.json);
+    }
+
+    // issue push-card — SPEC §1.5 / DEC-24: push an issue_card into a channel.
+    // NOT a deterministic status-change trigger — the AGENT decides when/which
+    // channel (judgment=agent, execution=code, Karpathy §5). --as-agent posts the
+    // card AS an agent the caller owns; absent → posts as the caller (user).
+    if (resource === 'task' && verb === 'push-card') {
+      if (!args.issue || !args.channel) {
+        fail('usage: wehandoff task push-card --issue <id> --channel <id> [--as-agent <id>]');
+      }
+      return ok(
+        await callApi(
+          {
+            method: 'POST',
+            path: `/api/cli/tasks/${args.issue}/push-card`,
+            body: {
+              channelId: args.channel,
+              asAgentId: args['as-agent'],
+            },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // issue push-verification-card — SPEC §6 activity / NO.496: record a
+    // verification/sign-off card into a channel. Same producer-edge shape as
+    // push-card (judgment=agent, execution=code) plus optional --preview-url
+    // and --note (markdown). --as-agent posts AS an owned agent; absent → user.
+    if (resource === 'task' && verb === 'push-verification-card') {
+      if (!args.issue || !args.channel) {
+        fail(
+          'usage: wehandoff task push-verification-card --issue <id> --channel <id> [--preview-url <u>] [--note <md>] [--as-agent <id>]'
+        );
+      }
+      return ok(
+        await callApi(
+          {
+            method: 'POST',
+            path: `/api/cli/tasks/${args.issue}/push-verification-card`,
+            body: {
+              channelId: args.channel,
+              previewUrl: args['preview-url'],
+              noteMd: args.note,
+              asAgentId: args['as-agent'],
+            },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // artifact create — session 产物 (kind html/md/text). 挂到 comment 用 --artifact.
+    if (resource === 'artifact' && verb === 'create') {
+      if (!args.kind)
+        fail(
+          'usage: wehandoff artifact create --kind html|md|text [--title <t>] [--content <c>|--file <p>] [--project <id>] [--as-agent <id>]'
+        );
+      const content = args.file ? readFileSync(args.file, 'utf8') : args.content;
+      return ok(
+        await callApi(
+          {
+            method: 'POST',
+            path: '/api/cli/artifacts',
+            body: {
+              kind: args.kind,
+              title: args.title,
+              content,
+              projectId: args.project,
+              authorAgentId: args['as-agent'],
+            },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    if (resource === 'room' && verb === 'add-agent') {
+      if (!args.channel || !args.agent) fail('--channel and --agent are required');
+      return ok(
+        await callApi(
+          {
+            method: 'POST',
+            path: `/api/cli/groups/${args.channel}/agents`,
+            body: { agent_id: args.agent },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    if (resource === 'room' && verb === 'add-member') {
+      if (!args.channel || !args.user) fail('--channel and --user are required');
+      return ok(
+        await callApi(
+          {
+            method: 'POST',
+            path: `/api/cli/groups/${args.channel}/members`,
+            body: { user_id: args.user },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    if (resource === 'service' && verb === 'search') {
+      const query = args._.join(' ').trim();
+      if (!query) fail('usage: wehandoff service search <query>');
+      return ok(
+        await callApi(
+          { method: 'GET', path: `/api/cli/services/search?q=${encodeURIComponent(query)}` },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    if (resource === 'service' && verb === 'create') {
+      if (!args.agent || !args.title)
+        fail(
+          'usage: wehandoff service create --agent <id> --title <t> [--description <d>] [--skill <name>]'
+        );
+      const skillSnapshot = args.skill ? readSkillSnapshot(String(args.skill)) : {};
+      return ok(
+        await callApi(
+          {
+            method: 'POST',
+            path: '/api/cli/services',
+            body: {
+              agent_id: args.agent,
+              title: args.title,
+              description: args.description ?? '',
+              ...skillSnapshot,
+            },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    if (resource === 'service' && (verb === 'publish' || verb === 'unpublish')) {
+      if (!args.service) fail(`usage: wehandoff service ${verb} --service <id>`);
+      return ok(
+        await callApi(
+          {
+            method: 'POST',
+            path: `/api/cli/services/${args.service}/publish`,
+            body: { published: verb === 'publish' },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    if (resource === 'service' && verb === 'list') {
+      return ok(await callApi({ method: 'GET', path: '/api/cli/services' }, { token, baseUrl }));
+    }
+
+    // matching start — one-shot matchmaking (NO.1999, KEYSTONE G3). Given a demand
+    // (task id + need text), in ONE step: creates a forum room, sources candidates
+    // via runSourcing (promote + post demand + fan-out), and returns the room id
+    // plus candidateAgentIds. Callers that already have a room: use `matching source`.
+    if (resource === 'matching' && verb === 'start') {
+      if (!args.issue || !args.need) {
+        fail('usage: wehandoff matching start --issue <taskId> --need <text> [--name <roomName>]');
+      }
+      return ok(
+        await callApi(
+          {
+            method: 'POST',
+            path: '/api/cli/matching/start',
+            body: {
+              taskId: args.issue,
+              need: args.need,
+              ...(args.name ? { name: args.name } : {}),
+            },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    if (resource === 'matching' && verb === 'source') {
+      if (!args.issue || !args.room || !args.query) {
+        fail(
+          'usage: wehandoff matching source --issue <id> --room <id> --query <q> [--demand <text>]'
+        );
+      }
+      return ok(
+        await callApi(
+          {
+            method: 'POST',
+            path: '/api/cli/matching/source',
+            // task⊥room (overturns DEC-179): the demand room is passed explicitly,
+            // not derived from a task-side binding.
+            body: {
+              taskId: args.issue,
+              roomId: args.room,
+              query: args.query,
+              demandText: args.demand,
+            },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // matching refresh — the /api/cli/matching/refresh route is NOT wired yet
+    // (NO.2099). Honest exit-2 not-yet-implemented, matching the `stub` manifest,
+    // instead of a raw 404. Use `matching start` / `matching source` meanwhile.
+    if (resource === 'matching' && verb === 'refresh') {
+      fail(
+        'not yet implemented: `matching refresh` route (/api/cli/matching/refresh) is not wired (NO.2099). Use `matching start` / `matching source`.',
+        2
+      );
+    }
+
+    if (resource === 'project' && verb === 'create') {
+      if (!args.name || !args.slug || !args['repo-url']) {
+        fail(
+          'usage: wehandoff project create --name <n> --slug <s> --repo-url <u> [--repo-kind <k>] [--default-branch <b>]'
+        );
+      }
+      return ok(
+        await callApi(
+          {
+            method: 'POST',
+            path: '/api/cli/projects',
+            body: {
+              name: args.name,
+              slug: args.slug,
+              repo_url: args['repo-url'],
+              ...(args['repo-kind'] ? { repo_kind: args['repo-kind'] } : {}),
+              ...(args['default-branch'] ? { default_branch: args['default-branch'] } : {}),
+              // Handoff provenance passthrough (§4.1 / NO.550) — receiver chain threads these.
+              ...(args['source-project'] ? { source_project_id: args['source-project'] } : {}),
+              ...(args['source-issue'] ? { source_issue_id: args['source-issue'] } : {}),
+            },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // user resolve — email → canonical user_id (P0b). The cross-person primitive
+    // that survives DEC-117: L1 add-member takes a bare user_id, so callers need
+    // to turn an email into one. --handle is not supported in v1 (no column).
+    if (resource === 'user' && verb === 'resolve') {
+      if (!args.email) fail('usage: wehandoff user resolve --email <e>');
+      return ok(
+        await callApi(
+          { method: 'GET', path: `/api/cli/users/resolve?email=${encodeURIComponent(args.email)}` },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // workspace list — workspaces the caller belongs to (member-scoped server-side).
+    // Fills the A13 vacuum (NO.2100): SPEC §16 「agent 经 whf 够到全状态」 covers the
+    // workspace container. Read-only — member/role management stays on the web.
+    if (resource === 'workspace' && verb === 'list') {
+      return ok(await callApi({ method: 'GET', path: '/api/cli/workspaces' }, { token, baseUrl }));
+    }
+
+    // workspace members — list a workspace's members (member-gated server-side).
+    if (resource === 'workspace' && verb === 'members') {
+      if (!args.workspace) fail('usage: wehandoff workspace members --workspace <id>');
+      return ok(
+        await callApi(
+          {
+            method: 'GET',
+            path: `/api/cli/workspaces/${encodeURIComponent(args.workspace)}/members`,
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // project list — projects owned by the caller (owner-filtered server-side). (whf-cli §4.1)
+    if (resource === 'project' && verb === 'list') {
+      return ok(await callApi({ method: 'GET', path: '/api/cli/projects' }, { token, baseUrl }));
+    }
+
+    // project get — fetch one project row (owner-gated). (whf-cli §4.1)
+    if (resource === 'project' && verb === 'get') {
+      if (!args.project) fail('usage: wehandoff project get --project <id>');
+      return ok(
+        await callApi(
+          { method: 'GET', path: `/api/cli/projects/${encodeURIComponent(args.project)}` },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // project update — partial update of name / repo_url / default_branch (owner-gated). (whf-cli §4.1)
+    if (resource === 'project' && verb === 'update') {
+      if (!args.project)
+        fail(
+          'usage: wehandoff project update --project <id> [--name <n>] [--repo-url <u>] [--default-branch <b>]'
+        );
+      const body = {
+        ...(args.name ? { name: args.name } : {}),
+        ...(args['repo-url'] ? { repo_url: args['repo-url'] } : {}),
+        ...(args['default-branch'] ? { default_branch: args['default-branch'] } : {}),
+      };
+      if (Object.keys(body).length === 0)
+        fail(
+          'usage: wehandoff project update --project <id> [--name <n>] [--repo-url <u>] [--default-branch <b>]'
+        );
+      return ok(
+        await callApi(
+          {
+            method: 'PATCH',
+            path: `/api/cli/projects/${encodeURIComponent(args.project)}`,
+            body,
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // project delete — archive (soft) by default; --hard goes ?hard=1 (true delete). (whf-cli §4.1/§2.4)
+    if (resource === 'project' && verb === 'delete') {
+      if (!args.project) fail('usage: wehandoff project delete --project <id> [--hard]');
+      const path = `/api/cli/projects/${encodeURIComponent(args.project)}${args.hard ? '?hard=1' : ''}`;
+      return ok(await callApi({ method: 'DELETE', path }, { token, baseUrl }));
+    }
+
+    // story steps — fetch the project's user_story e2e blueprint to run as acceptance regression (§6/§17).
+    if (resource === 'story' && verb === 'steps') {
+      if (!args.issue) fail('usage: wehandoff story steps --issue <id>');
+      return ok(
+        await callApi(
+          { method: 'GET', path: `/api/cli/tasks/${args.issue}/story-steps` },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // userstory list — enumerate all user_story rows for a project (NO.1496).
+    if ((resource === 'userstory' || resource === 'story') && verb === 'list') {
+      if (!args.project) fail('usage: wehandoff userstory list --project <id>');
+      return ok(
+        await callApi(
+          { method: 'GET', path: `/api/cli/projects/${args.project}/stories` },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // story get — fetch a single user_story by id (cloud-restore §4). Owner-gated
+    // server-side (story → project → owner). Top-level id route, no --project.
+    if ((resource === 'userstory' || resource === 'story') && verb === 'get') {
+      if (!args.story) fail('usage: wehandoff story get --story <id>');
+      return ok(
+        await callApi({ method: 'GET', path: `/api/cli/stories/${args.story}` }, { token, baseUrl })
+      );
+    }
+
+    // userstory create — author a project's e2e acceptance blueprint (SPEC §1.2).
+    // `story create` is accepted as an alias (matches the `story steps` verb).
+    // --steps is a JSON array of {action, expect}; the route validates the shape.
+    if ((resource === 'userstory' || resource === 'story') && verb === 'create') {
+      if (!args.project || !args.title || !args.steps) {
+        fail(
+          'usage: wehandoff userstory create --project <id> --title <t> --steps <json [{action,expect}]>'
+        );
+      }
+      let steps;
+      try {
+        steps = JSON.parse(args.steps);
+      } catch {
+        fail('--steps must be valid JSON, e.g. \'[{"action":"open /","expect":"hero loads"}]\'');
+      }
+      return ok(
+        await callApi(
+          {
+            method: 'POST',
+            path: `/api/cli/projects/${args.project}/stories`,
+            body: { title: args.title, steps },
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // userstory update — edit a story's title and/or steps (NO.504). At least one
+    // of --title / --steps is required; --steps is the same JSON shape as create.
+    // Owner-gated server-side. (`story update` alias, matching create.)
+    if ((resource === 'userstory' || resource === 'story') && verb === 'update') {
+      if (!args.project || !args.story || (!args.title && !args.steps)) {
+        fail(
+          'usage: wehandoff userstory update --project <id> --story <id> [--title <t>] [--steps <json [{action,expect}]>]'
+        );
+      }
+      const body = {};
+      if (args.title) body.title = args.title;
+      if (args.steps) {
+        try {
+          body.steps = JSON.parse(args.steps);
+        } catch {
+          fail('--steps must be valid JSON, e.g. \'[{"action":"open /","expect":"hero loads"}]\'');
+        }
+      }
+      return ok(
+        await callApi(
+          {
+            method: 'PATCH',
+            path: `/api/cli/projects/${args.project}/stories/${args.story}`,
+            body,
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // userstory delete — hard-delete a story (NO.504). Owner-gated server-side.
+    // (`story delete` alias, matching create.)
+    if ((resource === 'userstory' || resource === 'story') && verb === 'delete') {
+      if (!args.project || !args.story) {
+        fail('usage: wehandoff userstory delete --project <id> --story <id>');
+      }
+      return ok(
+        await callApi(
+          {
+            method: 'DELETE',
+            path: `/api/cli/projects/${args.project}/stories/${args.story}`,
+          },
+          { token, baseUrl }
+        )
+      );
+    }
+
+    // acceptance report — agent reports a per-criterion verdict after running the
+    // e2e regression on the real product page (§6/§17). The /api/cli/tasks/<id>/
+    // acceptance route is NOT wired yet (NO.2099) — there is no acceptance-write
+    // persistence lib, only a read-overlay. Honest exit-2 not-yet-implemented,
+    // matching the `stub` manifest, instead of a raw 404.
+    if (resource === 'acceptance' && verb === 'report') {
+      fail(
+        'not yet implemented: `acceptance report` route (/api/cli/tasks/<id>/acceptance) is not wired (NO.2099).',
+        2
+      );
+    }
+
+    // asset share/pull/push/grant/revoke — the shared-asset sharing layer
+    // (P1.4 / spec §4/§5). `share` promotes a local issue md into a cloud
+    // `shared_asset`; `pull`/`push` sync a LOCAL working copy under
+    // ~/.wehandoff/shared/<id>/ against the cloud HEAD via server CAS
+    // (expected_rev → 409) + a node-diff3 3-way merge. The client NEVER picks
+    // rev itself; server-side CAS stays in the DB layer (we react to 409).
+    if (resource === 'asset') {
+      // share — POST /api/cli/assets: promote a local asset to a shared_asset,
+      // then seed the local working copy + .meta.json from the route's response
+      // (initial cloud_rev=0, base_body=body just shared). constitution is
+      // rejected server-side (422); --file reads the body from disk.
+      if (verb === 'share') {
+        if (!args.channel || !args.title || (args.body === undefined && !args.file)) {
+          fail(
+            'usage: wehandoff asset share --channel <id> --title <t> (--body <t> | --file <p>) [--kind <k>] [--source-path <p>]'
+          );
+        }
+        const assetBody = args.file ? readFileSync(args.file, 'utf8') : String(args.body);
+        const { asset } = await callApi(
+          {
+            method: 'POST',
+            path: '/api/cli/assets',
+            body: {
+              channel: args.channel,
+              title: args.title,
+              body: assetBody,
+              ...(args.kind ? { kind: args.kind } : {}),
+              ...(args['source-path'] ? { source_path: args['source-path'] } : {}),
+            },
+          },
+          { token, baseUrl }
+        );
+        // Seed the working copy at the freshly-shared body + its cloud_rev so a
+        // later `push` knows the expected_rev and diff3 has a base ancestor.
+        writeWorkingCopy({ assetId: asset.id, body: assetBody, cloudRev: asset.cloud_rev });
+        return ok({ asset, working_copy: assetDirHint(asset.id) });
+      }
+
+      // pull — GET /api/cli/assets/<id>: fetch cloud HEAD body+rev into the
+      // local working copy. clean (working == base, or no copy yet) → fast-
+      // forward to remote + advance base. dirty (un-pushed local edits) → do
+      // NOT clobber: keep the working copy, refresh the base ancestor to remote
+      // so the next push's diff3 is against the latest HEAD (spec §4 触发式 pull).
+      if (verb === 'pull') {
+        if (!args.asset) fail('usage: wehandoff asset pull --asset <id>');
+        const { asset } = await callApi(
+          { method: 'GET', path: `/api/cli/assets/${encodeURIComponent(args.asset)}` },
+          { token, baseUrl }
+        );
+        const dirty = isDirty({ assetId: args.asset });
+        if (!dirty) {
+          // FF: working copy tracks remote exactly.
+          writeWorkingCopy({ assetId: args.asset, body: asset.body, cloudRev: asset.cloud_rev });
+          clearMerged({ assetId: args.asset });
+          return ok({ asset, pulled: 'fast-forward', working_copy: assetDirHint(args.asset) });
+        }
+        // dirty: preserve local edits; advance the merge base to remote HEAD.
+        writeMeta({ assetId: args.asset, cloudRev: asset.cloud_rev, baseBody: asset.body });
+        return ok({
+          asset: { id: asset.id, cloud_rev: asset.cloud_rev, title: asset.title },
+          pulled: 'kept-local',
+          note: 'local working copy has un-pushed edits and was preserved; merge base advanced to cloud HEAD — run `asset push` to merge + upload.',
+          working_copy: assetDirHint(args.asset),
+        });
+      }
+
+      // push — POST /api/cli/assets/<id>/push with expected_rev (CAS). On 200 the
+      // push landed: advance base := pushed body, rev := server rev. On 409 the
+      // cloud HEAD moved: re-pull remote, 3-way merge {base, local, remote} via
+      // node-diff3, and re-push the merged body if clean. A residual conflict is
+      // written to .merged (git-style markers) and surfaced — NOT re-pushed.
+      if (verb === 'push') {
+        if (!args.asset) fail('usage: wehandoff asset push --asset <id>');
+        const meta = readMeta({ assetId: args.asset });
+        const local = readWorkingCopy({ assetId: args.asset });
+        if (meta == null || local == null) {
+          fail(
+            `no local working copy for asset ${args.asset} — run \`asset pull --asset <id>\` first`
+          );
+        }
+
+        // 1st push at the rev our base_body is synced to.
+        const first = await callApiRaw(
+          {
+            method: 'POST',
+            path: `/api/cli/assets/${encodeURIComponent(args.asset)}/push`,
+            body: { expected_rev: meta.cloud_rev, body: local },
+          },
+          { token, baseUrl }
+        );
+
+        if (first.ok) {
+          // clean push: base advances to exactly what we uploaded (spec §4 ①).
+          writeWorkingCopy({ assetId: args.asset, body: local, cloudRev: first.json.cloud_rev });
+          clearMerged({ assetId: args.asset });
+          return ok({ pushed: 'clean', cloud_rev: first.json.cloud_rev, asset_id: args.asset });
+        }
+        if (first.status !== 409) {
+          // a non-CAS error (403/404/400/...) — surface verbatim, don't merge.
+          fail(
+            typeof first.json?.error === 'string' ? first.json.error : JSON.stringify(first.json)
+          );
+        }
+
+        // 409: cloud HEAD moved. Re-pull remote body+rev, 3-way merge.
+        const { asset: remote } = await callApi(
+          { method: 'GET', path: `/api/cli/assets/${encodeURIComponent(args.asset)}` },
+          { token, baseUrl }
+        );
+        const { conflict, body: merged } = threeWayMerge(meta.base_body, local, remote.body);
+        if (conflict) {
+          // Unresolved overlap: write .merged with markers, surface, do NOT push.
+          const path = writeMergedConflict({ assetId: args.asset, body: merged });
+          // Keep the working copy as the user's local edits; advance base to the
+          // remote we just merged against so a hand-resolved re-push is clean.
+          writeMeta({ assetId: args.asset, cloudRev: remote.cloud_rev, baseBody: remote.body });
+          failJson(
+            {
+              status: 'conflict',
+              asset_id: args.asset,
+              cloud_rev: remote.cloud_rev,
+              merged_file: path,
+              note: 'unresolved 3-way conflict — resolve the <<<<<<< markers in .merged, copy into issue.md, then re-run `asset push`.',
+            },
+            1
+          );
+        }
+
+        // clean merge: re-push the merged body at the remote rev we merged against.
+        const second = await callApiRaw(
+          {
+            method: 'POST',
+            path: `/api/cli/assets/${encodeURIComponent(args.asset)}/push`,
+            body: { expected_rev: remote.cloud_rev, body: merged },
+          },
+          { token, baseUrl }
+        );
+        if (!second.ok) {
+          // The HEAD moved again between our re-pull and re-push (rare). Surface
+          // so the caller re-runs push; base stays at the remote we merged on.
+          writeWorkingBody({ assetId: args.asset, body: merged });
+          writeMeta({ assetId: args.asset, cloudRev: remote.cloud_rev, baseBody: remote.body });
+          fail(
+            typeof second.json?.error === 'string'
+              ? `re-push raced (HEAD moved again) — re-run \`asset push\`: ${second.json.error}`
+              : JSON.stringify(second.json)
+          );
+        }
+        // base advances to exactly the merged body we pushed (spec §4 ③).
+        writeWorkingCopy({ assetId: args.asset, body: merged, cloudRev: second.json.cloud_rev });
+        clearMerged({ assetId: args.asset });
+        return ok({ pushed: 'merged', cloud_rev: second.json.cloud_rev, asset_id: args.asset });
+      }
+
+      // grant — POST /api/cli/assets/<id>/grants: owner grants a named account
+      // viewer|editor. owner/role gates live in the DB layer (403 on violation).
+      if (verb === 'grant') {
+        if (!args.asset || !args.grantee || !args.role) {
+          fail('usage: wehandoff asset grant --asset <id> --grantee <userId> --role viewer|editor');
+        }
+        return ok(
+          await callApi(
+            {
+              method: 'POST',
+              path: `/api/cli/assets/${encodeURIComponent(args.asset)}/grants`,
+              body: { grantee: args.grantee, role: args.role },
+            },
+            { token, baseUrl }
+          )
+        );
+      }
+
+      // revoke — DELETE /api/cli/assets/<id>/grants: owner revokes a named grant
+      // (can't revoke the owner). owner/anti-orphan gates live in the DB layer.
+      if (verb === 'revoke') {
+        if (!args.asset || !args.grantee) {
+          fail('usage: wehandoff asset revoke --asset <id> --grantee <userId>');
+        }
+        return ok(
+          await callApi(
+            {
+              method: 'DELETE',
+              path: `/api/cli/assets/${encodeURIComponent(args.asset)}/grants`,
+              body: { grantee: args.grantee },
+            },
+            { token, baseUrl }
+          )
+        );
+      }
+
+      fail(`unknown asset verb: ${verb ?? ''}`);
+    }
+
+    if (resource === 'constitution') {
+      const agentHeaders = args['as-agent'] ? { 'x-wh-agent': args['as-agent'] } : undefined;
+      const q = (obj) =>
+        Object.entries(obj)
+          .filter(([, v]) => v != null && v !== true)
+          .map(([k, v]) => `${k}=${encodeURIComponent(String(v))}`)
+          .join('&');
+
+      if (verb === 'list') {
+        if (!args.project) fail('--project is required');
+        return ok(
+          await callApi(
+            { method: 'GET', path: `/api/cli/constitution/list?${q({ project: args.project })}` },
+            { token, baseUrl }
+          )
+        );
+      }
+      if (verb === 'drift') {
+        if (!args.project) fail('--project is required');
+        return ok(
+          await callApi(
+            {
+              method: 'GET',
+              path: `/api/cli/constitution/drift?${q({ project: args.project })}`,
+              headers: agentHeaders,
+            },
+            { token, baseUrl }
+          )
+        );
+      }
+      if (verb === 'show') {
+        if (!args.project || !args.slug) fail('--project and --slug are required');
+        return ok(
+          await callApi(
+            {
+              method: 'GET',
+              path: `/api/cli/constitution/show?${q({ project: args.project, slug: args.slug, heading: args.heading })}`,
+              headers: agentHeaders,
+            },
+            { token, baseUrl }
+          )
+        );
+      }
+      if (verb === 'add') {
+        if (!args.project || !args.slug || !args.title)
+          fail('--project, --slug and --title are required');
+        const body = {
+          project: args.project,
+          slug: args.slug,
+          kind: args.kind ?? 'other',
+          title: args.title,
+          source_path: args['source-path'],
+        };
+        if (args.file) body.full_text = readFileSync(args.file, 'utf8');
+        if (args['no-gate']) body.drift_gated = false;
+        return ok(
+          await callApi(
+            { method: 'POST', path: '/api/cli/constitution/add', body },
+            { token, baseUrl }
+          )
+        );
+      }
+      if (verb === 'publish') {
+        if (!args.project || !args.slug || !args.file)
+          fail('--project, --slug and --file are required');
+        // 先取当前 head 的 section hashes,作为 base_hashes 传给 publish,防静默覆盖(NO.893)。
+        // 首次 publish(doc 无 head)返回 null,publish 允许 null 跳过冲突检测。
+        const { base_hashes } = await callApi(
+          {
+            method: 'GET',
+            path: `/api/cli/constitution/hashes?${q({ project: args.project, slug: args.slug })}`,
+          },
+          { token, baseUrl }
+        );
+        const body = {
+          project: args.project,
+          slug: args.slug,
+          full_text: readFileSync(args.file, 'utf8'),
+          base_hashes,
+        };
+        return ok(
+          await callApi(
+            { method: 'POST', path: '/api/cli/constitution/publish', body },
+            { token, baseUrl }
+          )
+        );
+      }
+      // sync — 建待审修宪提案(NO.873 spec §2)。
+      // 读本地文件 → 拉当前 head hashes + rev → 推 proposal(不直接 publish);
+      // 路由在 3-way 检测通过后建 proposal 并返回 proposal_id + section_diff。
+      // 人在 web UI 点 [通过] 才 publish;CLI 永远不能直接 publish(guard 在路由)。
+      if (verb === 'sync') {
+        if (!args.project || !args.slug || !args.file)
+          fail('--project, --slug and --file are required');
+        // 1. 拉当前 head hashes + rev
+        const hashesResp = await callApi(
+          {
+            method: 'GET',
+            path: `/api/cli/constitution/hashes?${q({ project: args.project, slug: args.slug })}`,
+          },
+          { token, baseUrl }
+        );
+        const baseHashes = hashesResp.base_hashes ?? null;
+        const baseRev = typeof hashesResp.rev === 'number' ? hashesResp.rev : 0;
+        // 2. 推 proposal
+        const body = {
+          project: args.project,
+          slug: args.slug,
+          full_text: readFileSync(args.file, 'utf8'),
+          base_rev: baseRev,
+          base_hashes: baseHashes,
+        };
+        return ok(
+          await callApi(
+            { method: 'POST', path: '/api/cli/constitution/sync', body },
+            { token, baseUrl }
+          )
+        );
+      }
+      // append — DEC-56 品味沉淀:把人确认后的一行规则追加进 head 文本再走 publish(rev 递增)。
+      // 写入归 CLI(确定性);判断「该不该入宪 / 人同意了吗」归 agent + 人(§0,不自落宪)。
+      if (verb === 'append') {
+        if (!args.project || !args.slug || !args.line)
+          fail('--project, --slug and --line are required');
+        const body = { project: args.project, slug: args.slug, line: args.line };
+        return ok(
+          await callApi(
+            { method: 'POST', path: '/api/cli/constitution/append', body },
+            { token, baseUrl }
+          )
+        );
+      }
+      fail(`unknown constitution verb: ${verb ?? ''}`);
+    }
+
+    fail(`unknown command: ${resource ?? ''} ${verb ?? ''}. Run \`wehandoff --help\`.`);
+  } catch (err) {
+    fail(err instanceof Error ? err.message : String(err));
+  }
+}
+
+main();