@worca/app 0.0.1

package/src/core/chat/channel-worker-child.mjs

@@ -0,0 +1,211 @@
+// src/core/chat/channel-worker-child.mjs
+// Persistent channel-worker bootstrap (chat-connectivity-design.md §4.4) — the
+// long-lived analog of plugin-shim-child.mjs. Runs with a scrubbed env
+// ({PATH, HOME}), so it imports NOTHING from the worca core graph except the
+// dependency-free channel-protocol module. Protocol: JSON-lines both ways;
+// first host frame is `hello` (config+secrets+state via stdin ONLY, never
+// argv/env); the process stays up until `shutdown`/stdin-EOF or a crash
+// (nonzero exit -> the supervisor restarts with backoff).
+//
+// The plugin module must export:
+//   createChannelWorker(ctx) -> { start(), stop(), send(chatId, msg),
+//                                 handleWebhook?(req), onConfig?(config) }
+//   validateConfig?(config)  -> {ok:true, identity?} | {ok:false, errors:[...]}
+// ctx = { apiVersion, platform, mock, config, state:{get,set}, log,
+//         emitMessage, setStatus, shutdownSignal }
+//
+// `--check` argv mode (doctor / `worca plugin channel --check`): read hello,
+// run validateConfig once, write ONE result line, exit 0.
+
+import { createInterface } from 'node:readline';
+import { pathToFileURL } from 'node:url';
+import { encodeFrame, decodeFrame, isValidIncoming, isValidMessage, CONNECTION_STATES } from './channel-protocol.mjs';
+
+const CHECK_MODE = process.argv.includes('--check');
+const MAX_LOG_CHARS = 8 * 1024;
+
+function writeFrame(frame) {
+  try { process.stdout.write(encodeFrame(frame)); return true; }
+  catch { return false; /* oversize/broken pipe */ }
+}
+
+// stdout is protocol-reserved: any stray console.* from plugin code becomes a
+// log frame instead of corrupting the stream (shim-child rule, made survivable
+// for a persistent process).
+function shimConsole() {
+  const to = (level) => (...args) => {
+    const msg = args.map((a) => (typeof a === 'string' ? a : (() => { try { return JSON.stringify(a); } catch { return String(a); } })())).join(' ');
+    writeFrame({ type: 'log', level, msg: msg.slice(0, MAX_LOG_CHARS) });
+  };
+  console.log = to('info');
+  console.info = to('info');
+  console.warn = to('warn');
+  console.error = to('error');
+}
+
+function errKind(err) {
+  const kinds = ['auth', 'rate-limit', 'network', 'plugin', 'timeout', 'protocol'];
+  return kinds.includes(err?.kind) ? err.kind : 'plugin';
+}
+
+async function main() {
+  process.stdin.setEncoding('utf8');
+  const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+  const iter = lines[Symbol.asyncIterator]();
+
+  const first = await iter.next();
+  if (first.done) process.exit(1);
+  const hello = decodeFrame(first.value);
+  if (!hello || hello.type !== 'hello') {
+    process.stderr.write('channel-worker-child: first frame must be a valid hello\n');
+    process.exit(1);
+  }
+
+  const config = { ...hello.config };
+  const stateSnapshot = { ...hello.state };
+  const shutdownController = new AbortController();
+
+  const ctx = {
+    apiVersion: hello.apiVersion,
+    platform: hello.platform,
+    mock: hello.mock === true,
+    config,
+    state: {
+      // get() prefers writes made this session; set() RECORDS and emits — the
+      // HOST persists via writePluginState (shim stateDelta semantics).
+      get: async (k) => (stateSnapshot[k] ?? null),
+      set: async (k, v) => {
+        stateSnapshot[k] = v;
+        if (!writeFrame({ type: 'state-delta', delta: { [k]: v } })) {
+          writeFrame({ type: 'log', level: 'warn', msg: `state-delta for "${k}" exceeds the 1 MiB frame cap — not persisted` });
+        }
+      },
+    },
+    log: (level, msg) => writeFrame({ type: 'log', level: String(level || 'info'), msg: String(msg).slice(0, MAX_LOG_CHARS) }),
+    emitMessage: (msg) => {
+      if (!isValidIncoming(msg)) { ctx.log('warn', 'emitMessage: invalid IncomingMessage dropped'); return; }
+      writeFrame({ type: 'inbound', msg: { chatId: msg.chatId, userId: msg.userId, text: msg.text, meta: msg.meta ?? {} } });
+    },
+    setStatus: (state, detail) => {
+      if (!CONNECTION_STATES.includes(state)) return;
+      writeFrame({ type: 'status', state, detail: detail == null ? null : String(detail) });
+    },
+    shutdownSignal: shutdownController.signal,
+  };
+
+  shimConsole();
+
+  const mod = await import(pathToFileURL(hello.module).href);
+
+  if (CHECK_MODE) {
+    let result;
+    try {
+      result = typeof mod.validateConfig === 'function'
+        ? await mod.validateConfig(config)
+        : { ok: true, skipped: 'plugin exports no validateConfig' };
+    } catch (err) {
+      result = { ok: false, errors: [{ field: null, message: err?.message || String(err) }] };
+    }
+    process.stdout.write(`${JSON.stringify(result ?? { ok: false, errors: [{ field: null, message: 'validateConfig returned nothing' }] })}\n`, () => process.exit(0));
+    return;
+  }
+
+  if (typeof mod.createChannelWorker !== 'function') {
+    process.stderr.write(`channel module has no createChannelWorker export: ${hello.module}\n`);
+    process.exit(1);
+  }
+  const worker = mod.createChannelWorker(ctx);
+
+  let shuttingDown = false;
+  const shutdown = async () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    shutdownController.abort();
+    try { await worker.stop?.(); } catch { /* best effort */ }
+    process.exit(0);
+  };
+
+  // start() owns the platform connection; ready (with optional identity, e.g.
+  // '@worca_bot' from getMe) is emitted by the CHILD once start resolves.
+  // A start() failure is a crash: nonzero exit -> supervisor backoff, and auth
+  // failures should setStatus('disconnected', ...) + return instead of throwing
+  // when a restart cannot help.
+  let startInfo;
+  try {
+    startInfo = await worker.start?.();
+  } catch (err) {
+    process.stderr.write(`worker start failed: ${err?.message || err}\n`);
+    process.exit(1);
+  }
+  writeFrame({ type: 'ready', identity: startInfo?.identity ?? null });
+
+  for await (const line of lines) {
+    const frame = decodeFrame(line);
+    if (!frame) { ctx.log('warn', 'invalid host frame dropped'); continue; }
+    switch (frame.type) {
+      case 'send': {
+        (async () => {
+          try {
+            if (!isValidMessage(frame.message)) throw Object.assign(new Error('invalid NormalizedMessage'), { kind: 'protocol' });
+            const r = await worker.send(frame.chatId, frame.message);
+            writeFrame({ type: 'send-result', id: frame.id, ok: true, ...(r && typeof r === 'object' ? { detail: r } : {}) });
+          } catch (err) {
+            writeFrame({
+              type: 'send-result', id: frame.id, ok: false,
+              error: {
+                kind: errKind(err), message: err?.message || String(err),
+                ...(Number.isFinite(err?.retryAfterMs) ? { retryAfterMs: err.retryAfterMs } : {}),
+              },
+            });
+          }
+        })();
+        break;
+      }
+      case 'webhook': {
+        (async () => {
+          try {
+            if (typeof worker.handleWebhook !== 'function') {
+              writeFrame({ type: 'webhook-result', id: frame.id, statusCode: 501 });
+              return;
+            }
+            const res = await worker.handleWebhook({ method: frame.method, path: frame.path, headers: frame.headers, bodyB64: frame.bodyB64 });
+            writeFrame({
+              type: 'webhook-result', id: frame.id,
+              statusCode: Number.isInteger(res?.statusCode) ? res.statusCode : 200,
+              ...(res?.headers ? { headers: res.headers } : {}),
+              ...(typeof res?.bodyB64 === 'string' ? { bodyB64: res.bodyB64 } : {}),
+            });
+          } catch (err) {
+            ctx.log('error', `handleWebhook failed: ${err?.message || err}`);
+            writeFrame({ type: 'webhook-result', id: frame.id, statusCode: 500 });
+          }
+        })();
+        break;
+      }
+      case 'config': {
+        Object.keys(config).forEach((k) => { if (!(k in frame.config)) delete config[k]; });
+        Object.assign(config, frame.config);
+        try { await worker.onConfig?.(config); } catch (err) { ctx.log('warn', `onConfig failed: ${err?.message || err}`); }
+        break;
+      }
+      case 'ping':
+        writeFrame({ type: 'pong', id: frame.id });
+        break;
+      case 'shutdown':
+        await shutdown();
+        break;
+      case 'hello':
+        ctx.log('warn', 'duplicate hello ignored');
+        break;
+      default:
+        ctx.log('warn', `unexpected host frame "${frame.type}" ignored`);
+    }
+  }
+  // stdin EOF = host died or closed us: treat as shutdown.
+  await shutdown();
+}
+
+main().catch((err) => {
+  process.stderr.write(`channel-worker-child crashed: ${err?.stack || err}\n`);
+  process.exit(1);
+});

package/src/core/chat/chat-context.mjs

@@ -0,0 +1,66 @@
+// src/core/chat/chat-context.mjs
+// Per-chat persisted state, ported from pre-1.0 integrations/chat_context.js.
+// Keys are "platform:chatId"; state is {active_project, mute_until,
+// muted_messages}. Atomic tmp+rename writes. Default storage lives at
+// worcaHome()/chat-context.json (callers may inject a path for tests).
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { worcaHome } from '../projects.mjs';
+
+const SCHEMA_VERSION = 1;
+
+const DEFAULT_CHAT_STATE = {
+  active_project: null,
+  mute_until: null,
+  muted_messages: 0,
+};
+
+export function chatContextFile() {
+  return join(worcaHome(), 'chat-context.json');
+}
+
+/**
+ * @param {string} [filePath] absolute path (defaults to worcaHome()/chat-context.json)
+ * @returns {{ get, set, isMuted, incrementMuted }}
+ */
+export function createChatContext(filePath = chatContextFile()) {
+  const data = load(filePath);
+
+  function get(chatKey) {
+    return { ...DEFAULT_CHAT_STATE, ...data.chats[chatKey] };
+  }
+
+  function set(chatKey, patch) {
+    data.chats[chatKey] = { ...DEFAULT_CHAT_STATE, ...data.chats[chatKey], ...patch };
+    save(filePath, data);
+  }
+
+  function isMuted(chatKey) {
+    const { mute_until } = get(chatKey);
+    if (!mute_until) return false;
+    return new Date(mute_until) > new Date();
+  }
+
+  function incrementMuted(chatKey) {
+    const current = get(chatKey);
+    set(chatKey, { muted_messages: current.muted_messages + 1 });
+  }
+
+  return { get, set, isMuted, incrementMuted };
+}
+
+function load(filePath) {
+  try {
+    const raw = JSON.parse(readFileSync(filePath, 'utf8'));
+    if (raw && typeof raw === 'object' && raw.chats && typeof raw.chats === 'object') return raw;
+  } catch { /* missing or invalid — start fresh */ }
+  return { schema_version: SCHEMA_VERSION, chats: {} };
+}
+
+function save(filePath, data) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.tmp`;
+  writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf8');
+  renameSync(tmp, filePath);
+}

package/src/core/chat/command-router.mjs

@@ -0,0 +1,343 @@
+// src/core/chat/command-router.mjs
+// Inbound chat commands -> worca actions (chat-connectivity-design.md §4.6).
+// Command surface ported from the pre-1.0 commands/{global,project,control}.js
+// re-targeted to 1.0 (live runs Map + pipelines DB), plus the NEW approval
+// surface (/approve, /retry, /abort, /answer) the old code lacked. Fleet and
+// workspace command families are not ported (no 1.0 counterpart).
+//
+// Everything with policy weight happens HERE, host-side: allowlist
+// (deny-by-default), parsing, run resolution, answer-payload mapping. The
+// `actions` capability object is injected by ui/server.mjs over its runs Map;
+// this module never imports Express or the orchestrator.
+
+import { parseCommand } from './parser.mjs';
+import { createAllowlistGuard, parseIdList } from './allowlist.mjs';
+import { runRef, fmtUsd, fmtMs } from './renderers.mjs';
+
+const md = (value) => ({ kind: 'markdown', value });
+const reply = (text, severity = 'info') => ({ title: null, body: [md(text)], severity });
+
+/** 1.0 pipeline statuses -> emoji (statusEmoji port, re-keyed). */
+export function statusEmoji(status) {
+  switch (String(status || '')) {
+    case 'running': case 'starting': return '🟢';
+    case 'done': return '✅';
+    case 'error': return '🔴';
+    case 'stopped': return '⏹';
+    case 'paused': case 'pausing': case 'interrupted': return '⏸';
+    default: return '⚪';
+  }
+}
+
+/** "30m" | "2h" | "1d" -> ms (parseDuration port). null on anything else. */
+export function parseDuration(str) {
+  const m = /^(\d+)([mhd])$/.exec(String(str || '').trim());
+  if (!m) return null;
+  const n = Number(m[1]);
+  return m[2] === 'm' ? n * 60000 : m[2] === 'h' ? n * 3600000 : n * 86400000;
+}
+
+const HELP_TEXT = [
+  '**worca-cc chat commands**',
+  '`/runs` — live runs · `/last` — latest finished pipeline',
+  '`/status [*ref]` — run detail · `/cost [*ref]` — run cost',
+  '`/pause [*ref]` · `/stop [*ref]` · `/resume [*ref]`',
+  '`/approve [*ref]` — continue past a gate · `/retry [*ref]` — another cycle',
+  '`/abort [*ref]` — abort a recovery prompt',
+  '`/answer [*ref] <n|text> [| …]` — answer clarify questions (option number, or text for free-text)',
+  '`/projects` · `/use <name>` — scope commands to one project',
+  '`/mute 30m|2h|1d` · `/unmute` — silence notifications for this chat',
+  '`/whoami` · `/help`',
+  '_`*ref` is a run-id suffix, e.g. `*2951`; omit it when only one run is live._',
+].join('\n');
+
+const LIVE = new Set(['running', 'starting', 'pausing']);
+
+/**
+ * Resolve which run a command targets (resolveRunId port: wildcard suffix,
+ * disambiguation, no-arg single-active default).
+ * @returns {{run?:object, row?:object, error?:object}} run = live entry summary,
+ *          row = history row (when not live); error = NormalizedMessage reply
+ */
+function resolveTarget(arg, live, rows, { wantLive = false } = {}) {
+  // wantLive commands (/pause /stop /approve /answer…) must never bind to a
+  // finished entry still parked in the runs Map.
+  if (wantLive) live = live.filter((r) => LIVE.has(String(r.status || '')));
+  const suffix = String(arg || '').replace(/^\*/, '').trim();
+  if (!suffix) {
+    const active = live.filter((r) => LIVE.has(String(r.status || '')));
+    const pool = active.length ? active : live;
+    if (pool.length === 1) return { run: pool[0] };
+    if (pool.length === 0) return { error: reply('No live runs. `/runs` lists them, `/last` shows the latest finished one.', 'warning') };
+    return { error: disambiguate(pool.map((r) => ({ id: r.runId, title: r.title, status: r.status }))) };
+  }
+  const liveHits = live.filter((r) => String(r.runId).endsWith(suffix) || String(r.pipelineId || '').endsWith(suffix));
+  if (liveHits.length === 1) return { run: liveHits[0] };
+  if (liveHits.length > 1) return { error: disambiguate(liveHits.map((r) => ({ id: r.runId, title: r.title, status: r.status }))) };
+  if (wantLive) return { error: reply(`No live run matches \`*${suffix}\`.`, 'warning') };
+  const rowHits = (rows || []).filter((r) => String(r.id).endsWith(suffix));
+  if (rowHits.length === 1) return { row: rowHits[0] };
+  if (rowHits.length > 1) return { error: disambiguate(rowHits.map((r) => ({ id: r.id, title: r.title, status: r.status }))) };
+  return { error: reply(`No run matches \`*${suffix}\`.`, 'warning') };
+}
+
+function disambiguate(candidates) {
+  const lines = ['Ambiguous — use a longer suffix:'];
+  for (const c of candidates.slice(0, 6)) {
+    lines.push(`• ${statusEmoji(c.status)} \`${runRef(c.id)}\` ${String(c.title || '').slice(0, 50)}`);
+  }
+  return reply(lines.join('\n'), 'warning');
+}
+
+function runLine(r) {
+  const title = String(r.title || '(untitled)').slice(0, 60);
+  return `${statusEmoji(r.status)} \`${runRef(r.runId || r.id)}\` ${r.status} — ${title}`;
+}
+
+/**
+ * @param {{actions:object, chatContext:object, logger?:(l:string,m:string)=>void}} deps
+ * actions: listRuns(), runState(runId), pendingQuestion(runId),
+ *          answer(runId, id, payload), stop(runId), pause(runId),
+ *          resume(pipelineId), history({limit}), listProjects()
+ */
+export function createCommandRouter({ actions, chatContext, logger = () => {} }) {
+  const projectOf = (chatKey) => chatContext.get(chatKey).active_project;
+
+  const scopedRuns = (chatKey) => {
+    const all = actions.listRuns().filter((r) => (r.kind || 'run') === 'run' || r.kind === 'workspace-run');
+    const scope = projectOf(chatKey);
+    if (!scope) return all;
+    return all.filter((r) => String(r.projectDir || '').split('/').pop() === scope
+      || (r.projectNames || []).includes(scope));
+  };
+
+  const handlers = {
+    start: async () => reply(HELP_TEXT),
+    help: async () => reply(HELP_TEXT),
+
+    whoami: async ({ chatKey, platform, msg }) =>
+      reply(`platform: **${platform}** · chat: \`${msg.chatId}\` · key: \`${chatKey}\`\nThis chat is allow-listed for commands.`),
+
+    projects: async () => {
+      const projects = await actions.listProjects();
+      if (!projects.length) return reply('No projects onboarded.');
+      return reply(['**Projects:**', ...projects.map((p) => `• ${p.name}`)].join('\n'));
+    },
+
+    use: async ({ chatKey, args }) => {
+      if (!args[0]) {
+        const cur = projectOf(chatKey);
+        return reply(cur ? `Active project: **${cur}** (\`/use -\` to clear)` : 'No active project — commands see all runs. `/use <name>` to scope.');
+      }
+      if (args[0] === '-') {
+        chatContext.set(chatKey, { active_project: null });
+        return reply('Cleared — commands see all runs.');
+      }
+      const projects = await actions.listProjects();
+      const hit = projects.find((p) => p.name === args[0]);
+      if (!hit) return reply(`Unknown project "${args[0]}". \`/projects\` lists them.`, 'warning');
+      chatContext.set(chatKey, { active_project: hit.name });
+      return reply(`Active project: **${hit.name}** — /runs, /status now scope to it.`);
+    },
+
+    runs: async ({ chatKey }) => {
+      const live = scopedRuns(chatKey);
+      if (!live.length) return reply('No live runs. `/last` shows the latest finished pipeline.');
+      return reply(['**Live runs:**', ...live.map(runLine)].join('\n'));
+    },
+
+    last: async () => {
+      const rows = await actions.history({ limit: 1 });
+      if (!rows.length) return reply('No pipelines yet.');
+      const r = rows[0];
+      const bits = [runLine({ ...r, runId: r.id })];
+      const cost = fmtUsd(r.totalCostUsd);
+      if (cost) bits.push(`   **Cost:** ${cost}`);
+      const dur = fmtMs(r.totalActiveMs);
+      if (dur) bits.push(`   **Active:** ${dur}`);
+      return reply(bits.join('\n'));
+    },
+
+    status: async ({ chatKey, args }) => {
+      const t = resolveTarget(args[0], scopedRuns(chatKey), await actions.history({ limit: 50 }));
+      if (t.error) return t.error;
+      if (t.row) {
+        const r = t.row;
+        return reply([runLine({ ...r, runId: r.id }),
+          ...(fmtUsd(r.totalCostUsd) ? [`   **Cost:** ${fmtUsd(r.totalCostUsd)}`] : []),
+          ...(r.pauseReason ? [`   **Pause reason:** ${r.pauseReason}`] : []),
+        ].join('\n'));
+      }
+      const r = t.run;
+      const lines = [runLine(r)];
+      const state = actions.runState(r.runId);
+      if (state) {
+        const doneSteps = (state.steps || []).filter((s) => s.status === 'done').length;
+        lines.push(`   **Steps:** ${doneSteps}/${(state.steps || []).length} done · **Phase:** ${state.phase || '—'}`);
+        const cost = fmtUsd(state.totalCostUsd);
+        if (cost) lines.push(`   **Cost:** ${cost}`);
+      }
+      const pq = actions.pendingQuestion(r.runId);
+      if (pq) lines.push(`   ❓ waiting on you — \`/approve ${runRef(r.runId)}\` or \`/answer ${runRef(r.runId)} <n>\``);
+      return reply(lines.join('\n'));
+    },
+
+    cost: async ({ chatKey, args }) => {
+      const t = resolveTarget(args[0], scopedRuns(chatKey), await actions.history({ limit: 50 }));
+      if (t.error) return t.error;
+      if (t.row) return reply(`\`${runRef(t.row.id)}\` cost: ${fmtUsd(t.row.totalCostUsd) || '$0.00'}`);
+      const state = actions.runState(t.run.runId);
+      return reply(`\`${runRef(t.run.runId)}\` cost so far: ${fmtUsd(state?.totalCostUsd) || '$0.00'}`);
+    },
+
+    pause: async ({ chatKey, args }) => {
+      const t = resolveTarget(args[0], scopedRuns(chatKey), [], { wantLive: true });
+      if (t.error) return t.error;
+      await actions.pause(t.run.runId);
+      return reply(`⏸ Pausing \`${runRef(t.run.runId)}\` — resume from the UI or \`/resume ${runRef(t.run.runId)}\`.`, 'warning');
+    },
+
+    stop: async ({ chatKey, args }) => {
+      const t = resolveTarget(args[0], scopedRuns(chatKey), [], { wantLive: true });
+      if (t.error) return t.error;
+      await actions.stop(t.run.runId);
+      return reply(`⏹ Stopping \`${runRef(t.run.runId)}\` (${String(t.run.title || '').slice(0, 50)}).`, 'warning');
+    },
+
+    resume: async ({ args }) => {
+      // Resolve against PAUSED/INTERRUPTED history rows (resume works across
+      // restarts); a live match means it's already running.
+      const rows = (await actions.history({ limit: 50 })).filter((r) => r.status === 'paused' || r.status === 'interrupted');
+      let t = resolveTarget(args[0], [], rows);
+      if (t.error) {
+        if (!args[0] && rows.length > 1) {
+          return disambiguate(rows.map((r) => ({ id: r.id, title: r.title, status: r.status })));
+        }
+        if (!args[0] && !rows.length) return reply('Nothing is paused.', 'warning');
+        if (args[0] || rows.length !== 1) return t.error;
+        t = { row: rows[0] };            // exactly one paused row, bare /resume: take it
+      }
+      const out = await actions.resume(t.row.id);
+      if (out?.ok) return reply(`▶️ Resuming \`${runRef(t.row.id)}\` — ${String(t.row.title || '').slice(0, 50)}`);
+      return reply(`Could not resume \`${runRef(t.row.id)}\`: ${out?.error || 'unknown error'}`, 'error');
+    },
+
+    approve: async (env) => answerDecision(env, 'approve'),
+    retry: async (env) => answerDecision(env, 'retry'),
+    abort: async (env) => answerDecision(env, 'abort'),
+
+    answer: async ({ chatKey, args }) => {
+      const t = resolveTarget(args[0] && args[0].startsWith('*') ? args[0] : '', scopedRuns(chatKey), [], { wantLive: true });
+      if (t.error) return t.error;
+      const pq = actions.pendingQuestion(t.run.runId);
+      if (!pq) return reply(`\`${runRef(t.run.runId)}\` is not waiting on a question.`, 'warning');
+      if (pq.kind !== 'clarify' && pq.kind !== 'questions') {
+        return reply(`\`${runRef(t.run.runId)}\` is waiting on ${pq.kind} — use \`/approve\` or \`/retry\`.`, 'warning');
+      }
+      const questions = Array.isArray(pq.questions) ? pq.questions : [];
+      const hasRef = !!(args[0] && args[0].startsWith('*'));
+      const rest = (hasRef ? args.slice(1) : args).join(' ').trim();
+      const ref = runRef(t.run.runId);
+      const usage = () => reply(
+        `Need ${questions.length} answer${questions.length === 1 ? '' : 's'} — option numbers, or text for free-text questions, separated by \`|\`.\nExample: \`/answer ${ref} ${questions.map((q) => (q.options?.length ? '1' : '<your answer>')).join(' | ')}\``,
+        'warning');
+      if (!rest) return usage();
+      // Parsing spec:
+      // 1-question: the whole rest IS the answer — never split (pipes are data).
+      // Pure-ordinal back-compat: "1 2 3" iff every question has options and no '|'.
+      // Otherwise: pipe-separated, one part per question, in order.
+      let parts;
+      if (questions.length === 1) {
+        parts = [rest];
+      } else {
+        const tokens = rest.split(/\s+/);
+        const allOrdinals = tokens.every((tk) => /^\d+$/.test(tk));
+        const everyHasOptions = questions.every((q) => (q.options || []).length > 0);
+        parts = allOrdinals && everyHasOptions && !rest.includes('|')
+          ? tokens
+          : rest.split('|').map((s) => s.trim());
+      }
+      if (parts.length !== questions.length) return usage();
+      const answers = [];
+      for (let i = 0; i < questions.length; i++) {
+        const q = questions[i];
+        const opts = Array.isArray(q.options) ? q.options : [];
+        const part = parts[i];
+        const n = /^\d+$/.test(part) ? Number(part) : null;
+        if (opts.length && n !== null) {
+          if (n < 1 || n > opts.length) return reply(`Q${i + 1} has options 1–${opts.length}; got ${n}.`, 'warning');
+          answers.push({ id: q.id, choice: opts[n - 1] });
+        } else if (q.allowFreeText !== false && part) {
+          answers.push({ id: q.id, choice: part });   // free text is a choice string (app.js:3717)
+        } else if (!opts.length) {
+          return reply(`Q${i + 1} needs a written answer — got nothing.`, 'warning');
+        } else {
+          return reply(`Q${i + 1} takes an option number (1–${opts.length}), not text.`, 'warning');
+        }
+      }
+      await actions.answer(t.run.runId, pq.id, { answers });
+      return reply(`✅ Answered ${questions.length} question${questions.length === 1 ? '' : 's'} on \`${ref}\`.`, 'success');
+    },
+
+    mute: async ({ chatKey, args }) => {
+      const ms = parseDuration(args[0]);
+      if (!ms) return reply('Usage: `/mute 30m` · `/mute 2h` · `/mute 1d`', 'warning');
+      const until = new Date(Date.now() + ms).toISOString();
+      chatContext.set(chatKey, { mute_until: until });
+      return reply(`🔇 Notifications muted for ${args[0]} (commands still work). \`/unmute\` to lift.`);
+    },
+
+    unmute: async ({ chatKey }) => {
+      const { muted_messages: muted } = chatContext.get(chatKey);
+      chatContext.set(chatKey, { mute_until: null, muted_messages: 0 });
+      return reply(`🔔 Notifications back on${muted ? ` (${muted} suppressed while muted)` : ''}.`);
+    },
+  };
+
+  async function answerDecision({ chatKey, args }, verb) {
+    const t = resolveTarget(args[0], scopedRuns(chatKey), [], { wantLive: true });
+    if (t.error) return t.error;
+    const pq = actions.pendingQuestion(t.run.runId);
+    if (!pq) return reply(`\`${runRef(t.run.runId)}\` is not waiting on a decision.`, 'warning');
+    const ref = runRef(t.run.runId);
+    let payload;
+    if (pq.kind === 'gate') {
+      if (verb === 'abort') return reply(`Gates have no abort — \`/approve ${ref}\`, \`/retry ${ref}\`, or \`/stop ${ref}\`.`, 'warning');
+      payload = { decision: verb === 'approve' ? 'continue' : 'another' };
+    } else if (pq.kind === 'recovery') {
+      payload = { decision: verb === 'abort' ? 'abort' : 'retry' };
+    } else {
+      return reply(`\`${ref}\` is waiting on ${pq.kind} — use \`/answer ${ref} <n>\`.`, 'warning');
+    }
+    await actions.answer(t.run.runId, pq.id, payload);
+    const what = pq.kind === 'gate'
+      ? (payload.decision === 'continue' ? 'approved — continuing' : 'sent back for another cycle')
+      : (payload.decision === 'retry' ? 'retrying' : 'aborting');
+    return reply(`✅ \`${ref}\` ${what}.`, 'success');
+  }
+
+  return {
+    /**
+     * @param {{plugin:string, channelId:string, platform:string,
+     *          channelConfig:object, msg:{chatId:string,userId:string,text:string,meta?:object}}} ev
+     * @returns {Promise<object|null>} NormalizedMessage reply or null (ignore)
+     */
+    async handleIncoming({ plugin, channelId, platform, channelConfig, msg }) {
+      const guard = createAllowlistGuard(parseIdList(channelConfig?.allowedChatIds), {
+        debug: (m) => logger('info', m),
+      });
+      if (!guard.isAllowed({ platform, chatId: msg.chatId })) return null; // silent, fail closed
+      const parsed = parseCommand(msg.text);
+      if (!parsed) return null; // non-commands are never interpreted
+      const handler = Object.hasOwn(handlers, parsed.command) ? handlers[parsed.command] : null;
+      const chatKey = `${platform}:${msg.chatId}`;
+      if (!handler) return reply(`Unknown command \`/${parsed.command}\` — \`/help\` lists commands.`, 'warning');
+      try {
+        return await handler({ chatKey, platform, plugin, channelId, msg, args: parsed.args });
+      } catch (err) {
+        logger('error', `chat command /${parsed.command} failed: ${err?.message || err}`);
+        return reply(`Command failed: ${String(err?.message || err).slice(0, 200)}`, 'error');
+      }
+    },
+  };
+}