@worca/app 0.0.1

package/src/core/plugin-repo.mjs

@@ -0,0 +1,303 @@
+// src/core/plugin-repo.mjs
+// Git plumbing for the plugin store (spec §4.1, §4.3, §6.1-6.2): bare fetch
+// cache, manifest discovery (a root worca-cc-marketplace.json when present, else
+// tree depth 0/1), update candidate preview, and git-archive export of a pinned
+// SHA. All git/tar via execFile — injectable as opts.exec for tests:
+// async (cmd, args, opts?) => { stdout, stderr }.
+// The cache lives at <pluginsRoot>/.cache/<slug>.git — NEVER on any execution
+// path; exports contain no .git, so repo hooks are inert (spec §8).
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { createHash } from 'node:crypto';
+import { mkdirSync, existsSync, rmSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { pluginsRoot, pluginDir, readPluginsLock } from './plugins-lock.mjs';
+import { normalizeManifest, findEscapingSymlinks } from './plugin-manifest.mjs';
+
+const execFileP = promisify(execFile);
+const defaultExec = (cmd, args, opts = {}) =>
+  execFileP(cmd, args, {
+    maxBuffer: 16 * 1024 * 1024,
+    timeout: 120_000,
+    killSignal: 'SIGKILL',
+    env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    ...opts,
+  });
+
+/** Filesystem slug for a repo URL — shared by the bare-cache dir and marketplace
+ *  ids. Injective: a readable prefix plus an 8-hex digest of the EXACT input, so
+ *  distinct urls (http vs https, /a/b vs /a-b, unicode, .git.git) never collide
+ *  onto one id/cache dir. */
+export function repoSlug(repoUrl) {
+  const s = String(repoUrl);
+  const readable = s
+    .replace(/^[a-z+]+:\/\//i, '').replace(/\.git$/i, '')
+    .replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '')
+    .slice(0, 80) || 'repo';
+  return `${readable}-${createHash('sha1').update(s).digest('hex').slice(0, 8)}`;
+}
+
+/** Bare-cache path for a repo URL: <pluginsRoot>/.cache/<slug>.git. */
+export function repoCacheDir(repoUrl) {
+  return join(pluginsRoot(), '.cache', `${repoSlug(repoUrl)}.git`);
+}
+
+/** Validate a raw worca-cc-marketplace.json (spec §4.1). Paths are repo-relative
+ *  dirs, any depth: no absolute, no '..'/'.' segments, no backslashes, no empties. */
+export function parseMarketplaceManifest(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { ok: false, errors: ['not a JSON object'] };
+  }
+  const structural = []; // whole-file problems -> ok:false (caller falls back to the scan)
+  if (typeof raw.name !== 'string' || !raw.name.trim()) structural.push('"name" is required');
+  if (!Array.isArray(raw.plugins)) structural.push('"plugins" must be an array of repo-relative dirs');
+  if (structural.length) return { ok: false, errors: structural };
+  const warnings = []; // per-entry problems -> skipped entries, manifest still authoritative
+  const plugins = [];
+  for (const d of raw.plugins) {
+    // Segment charset is deliberately strict: it blocks '..'/absolute paths AND
+    // any segment beginning with '-', which would otherwise be parsed as a git
+    // option when the subdir is passed as a positional to `git archive`/`ls-tree`
+    // (see the `--` pathspec guards in fetchCandidate/exportVersion). '=' is
+    // outside the class, so `--output=/x` is rejected on both counts.
+    if (typeof d !== 'string' || !d.trim() || d.includes('\\') || d.startsWith('/')
+        || d.split('/').some((seg) =>
+          !/^[A-Za-z0-9._-]+$/.test(seg) || seg === '.' || seg === '..' || seg.startsWith('-'))) {
+      warnings.push(`invalid plugin path ${JSON.stringify(d)} — skipped`);
+      continue;
+    }
+    plugins.push(d.replace(/\/+$/, ''));
+  }
+  return {
+    ok: true,
+    name: raw.name.trim(),
+    description: typeof raw.description === 'string' ? raw.description.trim() : '',
+    plugins,
+    warnings,
+  };
+}
+
+async function gitDir(cache, args, exec) {
+  const { stdout } = await exec('git', ['--git-dir', cache, ...args]);
+  return stdout;
+}
+
+/** Clone the bare cache if absent, else fetch all heads (explicit refspec —
+ *  clone --bare configures no fetch refspec). */
+async function ensureCache(repoUrl, exec) {
+  const cache = repoCacheDir(repoUrl);
+  if (!existsSync(cache)) {
+    mkdirSync(dirname(cache), { recursive: true });
+    await exec('git', ['clone', '--quiet', '--bare', repoUrl, cache]);
+  } else {
+    await gitDir(cache, ['fetch', '--quiet', 'origin', '+refs/heads/*:refs/heads/*', '--prune'], exec);
+  }
+  return cache;
+}
+
+/**
+ * `worca plugin add`: clone/refresh the bare cache, then discover plugins in the
+ * HEAD tree. A root worca-cc-marketplace.json (spec §4.1), when present and
+ * structurally valid, is AUTHORITATIVE — its listed dirs (any depth) are the only
+ * candidates, even when the list is empty. Without one, the depth 0/1 scan of
+ * spec §4.3 applies unchanged.
+ * @returns {{repoUrl:string, sha:string, discovered:Array<{name,subdir,manifest}>,
+ *   warnings:string[], marketplace:{name:string, description:string}|null}}
+ */
+export async function addPluginRepo(repoUrl, { exec = defaultExec } = {}) {
+  // `owner/repo` shorthand -> GitHub URL (spec §4.3) — only when it is not a
+  // real local path (local fixture repos in tests stay untouched).
+  if (/^[\w.-]+\/[\w.-]+$/.test(repoUrl) && !existsSync(repoUrl)) {
+    repoUrl = `https://github.com/${repoUrl}`;
+  }
+  const cache = await ensureCache(repoUrl, exec);
+  const sha = (await gitDir(cache, ['rev-parse', 'HEAD'], exec)).trim();
+  const allPaths = (await gitDir(cache, ['ls-tree', '-r', '--name-only', sha], exec))
+    .split('\n').map((s) => s.trim()).filter(Boolean);
+  const warnings = [];
+  let marketplace = null;
+  let manifestPaths = null; // null -> fall back to the depth 0-1 scan
+  if (allPaths.includes('worca-cc-marketplace.json')) {
+    let mp = null;
+    try {
+      mp = parseMarketplaceManifest(JSON.parse(await gitDir(cache, ['show', `${sha}:worca-cc-marketplace.json`], exec)));
+    } catch {
+      mp = { ok: false, errors: ['invalid JSON'] };
+    }
+    if (mp.ok) {
+      marketplace = { name: mp.name, description: mp.description };
+      warnings.push(...(mp.warnings || []).map((w) => `worca-cc-marketplace.json: ${w}`));
+      manifestPaths = [];
+      for (const dir of mp.plugins) {
+        const p = `${dir}/worca-cc-plugin.json`;
+        if (!allPaths.includes(p)) {
+          warnings.push(`worca-cc-marketplace.json: ${dir}/worca-cc-plugin.json not found in repo — skipped`);
+          continue;
+        }
+        manifestPaths.push(p);
+      }
+    } else {
+      warnings.push(`worca-cc-marketplace.json: ${mp.errors.join('; ')} — falling back to depth 0-1 scan`);
+    }
+  }
+  if (manifestPaths === null) {
+    manifestPaths = allPaths
+      .filter((p) => p === 'worca-cc-plugin.json' || /^[^/]+\/worca-cc-plugin\.json$/.test(p));
+  }
+  const discovered = [];
+  const seenNames = new Set();
+  for (const p of manifestPaths) {
+    const subdir = p === 'worca-cc-plugin.json' ? '' : p.slice(0, -'/worca-cc-plugin.json'.length);
+    let raw;
+    try {
+      raw = JSON.parse(await gitDir(cache, ['show', `${sha}:${p}`], exec));
+    } catch {
+      warnings.push(`${p}: invalid JSON — skipped`);
+      continue;
+    }
+    const res = normalizeManifest(raw, { dir: subdir || '.' });
+    if (!res.ok) { warnings.push(...res.errors); continue; }
+    if (seenNames.has(res.manifest.name)) {
+      warnings.push(`${p}: duplicate plugin name "${res.manifest.name}" — first entry wins, skipped`);
+      continue;
+    }
+    seenNames.add(res.manifest.name);
+    discovered.push({ name: res.manifest.name, subdir, manifest: res.manifest });
+  }
+  return { repoUrl, sha, discovered, warnings, marketplace };
+}
+
+/** `<sourceId>.<key>` for every secret configSchema field of a manifest. */
+function manifestSecretKeys(manifest) {
+  return (manifest?.taskSources || []).flatMap((s) =>
+    (s.configSchema || []).filter((f) => f && f.secret === true).map((f) => `${s.id}.${f.key}`));
+}
+
+/** Normalized models/modelSecrets view of a RAW manifest ({} on any failure —
+ *  a manifest invalid to THIS host contributes no models here either). */
+function manifestModels(raw) {
+  if (!raw) return { models: [], modelSecrets: [] };
+  const r = normalizeManifest(raw);
+  return r.ok ? { models: r.manifest.models, modelSecrets: r.manifest.modelSecrets } : { models: [], modelSecrets: [] };
+}
+
+async function showManifest(cache, sha, subdir, exec) {
+  const p = subdir ? `${subdir}/worca-cc-plugin.json` : 'worca-cc-plugin.json';
+  try { return JSON.parse(await gitDir(cache, ['show', `${sha}:${p}`], exec)); } catch { return null; }
+}
+
+/**
+ * Update-review manifest delta (spec §6.2): newly requested secrets, new task
+ * sources, new agents (added agents/<key>.meta.json files), setup changes —
+ * the red-highlight inputs that turn a malicious update into a human review event.
+ */
+async function computeManifestDelta(cache, entry, pinnedSha, candidateSha, exec) {
+  const pin = await showManifest(cache, pinnedSha, entry.subdir, exec);
+  const cand = await showManifest(cache, candidateSha, entry.subdir, exec);
+  const pinSecrets = manifestSecretKeys(pin);
+  const candSecrets = manifestSecretKeys(cand);
+  const pinIds = (pin?.taskSources || []).map((s) => s.id);
+  const candIds = (cand?.taskSources || []).map((s) => s.id);
+  const scope = entry.subdir ? `${entry.subdir}/agents` : 'agents';
+  let newAgents = [];
+  try {
+    const status = await gitDir(cache, ['diff', '--name-status', pinnedSha, candidateSha, '--', scope], exec);
+    newAgents = status.split('\n')
+      .filter((l) => l.startsWith('A') && l.endsWith('.meta.json'))
+      .map((l) => l.split('\t').pop().split('/').pop().replace(/\.meta\.json$/, ''));
+  } catch { newAgents = []; }
+  // Model delta (design §9.4): env changes — a base-URL swap redirects ALL API
+  // traffic for that model — are the red-highlight review inputs.
+  const pinM = manifestModels(pin);
+  const candM = manifestModels(cand);
+  const byLc = (list) => new Map(list.map((m) => [m.id.toLowerCase(), m]));
+  const pinModels = byLc(pinM.models);
+  const candModels = byLc(candM.models);
+  const envOf = (m) => JSON.stringify(m.env ?? {});
+  return {
+    newSecrets: candSecrets.filter((k) => !pinSecrets.includes(k)),
+    newTaskSources: candIds.filter((id) => !pinIds.includes(id)),
+    newAgents,
+    setupChanged: JSON.stringify(pin?.setup ?? null) !== JSON.stringify(cand?.setup ?? null),
+    newModels: [...candModels.values()].filter((m) => !pinModels.has(m.id.toLowerCase())).map((m) => m.id),
+    removedModels: [...pinModels.values()].filter((m) => !candModels.has(m.id.toLowerCase())).map((m) => m.id),
+    envChangedModels: [...candModels.values()]
+      .filter((m) => pinModels.has(m.id.toLowerCase()) && envOf(pinModels.get(m.id.toLowerCase())) !== envOf(m))
+      .map((m) => m.id),
+    newModelSecrets: candM.modelSecrets.map((f) => f.key)
+      .filter((k) => !pinM.modelSecrets.some((f) => f.key === k)),
+  };
+}
+
+/**
+ * Update preview (spec §6.2): fetch, then report commits + diffstat + the
+ * manifest delta between the pinned SHA and the new HEAD; { fullDiff: true }
+ * additionally returns the complete diff text ("full diff on demand").
+ * Read-only; performing the update is Task 5's updatePlugin.
+ */
+export async function fetchCandidate(name, { exec = defaultExec, fullDiff = false } = {}) {
+  const entry = readPluginsLock()[name];
+  if (!entry || !entry.repo) throw new Error(`plugin "${name}" is not installed from a repo`);
+  const cache = await ensureCache(entry.repo, exec);
+  const candidateSha = (await gitDir(cache, ['rev-parse', 'HEAD'], exec)).trim();
+  const pinnedSha = entry.pinnedSha;
+  let commits = [];
+  let diffstat = '';
+  let diffFull = '';
+  let manifestDelta = {
+    newSecrets: [], newTaskSources: [], newAgents: [], setupChanged: false,
+    newModels: [], removedModels: [], envChangedModels: [], newModelSecrets: [],
+  };
+  if (candidateSha !== pinnedSha) {
+    const log = await gitDir(cache, ['log', '--format=%H%x09%s', `${pinnedSha}..${candidateSha}`], exec);
+    commits = log.split('\n').filter(Boolean).map((l) => {
+      const i = l.indexOf('\t');
+      return { sha: l.slice(0, i), subject: l.slice(i + 1) };
+    });
+    const scope = entry.subdir ? ['--', entry.subdir] : [];
+    diffstat = (await gitDir(cache, ['diff', '--stat', pinnedSha, candidateSha, ...scope], exec)).trim();
+    if (fullDiff) diffFull = (await gitDir(cache, ['diff', pinnedSha, candidateSha, ...scope], exec)).trim();
+    manifestDelta = await computeManifestDelta(cache, entry, pinnedSha, candidateSha, exec);
+  }
+  return { pinnedSha, candidateSha, commits, diffstat, diffFull, manifestDelta };
+}
+
+/**
+ * Export a pinned SHA to `${pluginDir(name)}/versions/<sha7>` via git archive ->
+ * tar extraction (no .git inside, spec §6.1). Symlinks escaping the export dir
+ * are DELETED post-extraction (git archive preserves symlinks) and reported.
+ * opts.repoUrl/opts.subdir override the lock entry — required on FIRST install,
+ * when no lock entry exists yet (Task 5 passes them explicitly).
+ * @returns {Promise<{versionDir:string, warnings:string[]}>}
+ */
+export async function exportVersion(name, sha, { exec = defaultExec, repoUrl, subdir } = {}) {
+  const entry = readPluginsLock()[name] || {};
+  const repo = repoUrl ?? entry.repo;
+  const sub = subdir ?? entry.subdir ?? '';
+  if (!repo) throw new Error(`plugin "${name}": no repo known (pass { repoUrl } on first install)`);
+  const cache = existsSync(repoCacheDir(repo)) ? repoCacheDir(repo) : await ensureCache(repo, exec);
+  const versionDir = join(pluginDir(name), 'versions', sha.slice(0, 7));
+  rmSync(versionDir, { recursive: true, force: true }); // re-export = fresh dir
+  mkdirSync(versionDir, { recursive: true });
+  const scratch = await mkdtemp(join(tmpdir(), 'worca-cc-export-'));
+  const tarFile = join(scratch, 'export.tar');
+  try {
+    await gitDir(cache, ['archive', '--format=tar', '-o', tarFile, ...(sub ? [sha, '--', sub] : [sha])], exec);
+    const strip = sub ? ['--strip-components', String(sub.split('/').length)] : [];
+    await exec('tar', ['-xf', tarFile, '-C', versionDir, ...strip]);
+  } catch (err) {
+    rmSync(versionDir, { recursive: true, force: true });
+    throw err;
+  } finally {
+    await rm(scratch, { recursive: true, force: true });
+  }
+  const warnings = [];
+  for (const rel of findEscapingSymlinks(versionDir)) {
+    rmSync(join(versionDir, rel), { force: true });
+    warnings.push(`removed symlink escaping the export dir: ${rel}`);
+  }
+  return { versionDir, warnings };
+}

package/src/core/plugin-shim-child.mjs

@@ -0,0 +1,76 @@
+// src/core/plugin-shim-child.mjs
+// Ephemeral connector runner (spec §7.2). Deliberately imports NOTHING from
+// worca: it runs with a scrubbed env (PATH+HOME only, no WORCA_HOME), so any
+// store/db import here would resolve wrong paths. Protocol: read ONE JSON doc
+// from stdin, run ONE op, write ONE JSON frame to stdout, exit 0. The child
+// ALWAYS exits 0 after writing a frame — a nonzero exit means "crashed before
+// the frame" and the parent maps it to PluginOpError('protocol').
+import { pathToFileURL } from 'node:url';
+
+const logs = [];
+
+async function main() {
+  process.stdin.setEncoding('utf8');
+  let raw = '';
+  for await (const chunk of process.stdin) raw += chunk;
+  const msg = JSON.parse(raw);
+
+  // ctx.state: plain-object snapshot + mutation collection. get() prefers the
+  // delta so a connector reads back its own writes within the op; set() only
+  // RECORDS — the HOST applies the delta via writePluginState after the frame.
+  const snapshot = msg.state && typeof msg.state === 'object' ? msg.state : {};
+  const stateDelta = {};
+  const ctx = {
+    apiVersion: msg.apiVersion ?? 1,
+    config: msg.config && typeof msg.config === 'object' ? msg.config : {},
+    state: {
+      get: async (k) => (k in stateDelta ? stateDelta[k] : (snapshot[k] ?? null)),
+      set: async (k, v) => { stateDelta[k] = v; },
+    },
+    log: (level, text) => { logs.push({ level, msg: String(text) }); }, // stdout is protocol-reserved
+  };
+
+  const mod = await import(pathToFileURL(msg.module).href);
+  if (typeof mod.default !== 'function') {
+    throw Object.assign(new Error(`connector module has no default-export factory: ${msg.module}`), { kind: 'plugin' });
+  }
+  const source = mod.default(ctx);
+  const fn = source?.[msg.op];
+  if (typeof fn !== 'function') {
+    // Optional ops (e.g. capabilities) land here; the host treats this kind +
+    // message as "op not implemented" (Task 13 defaults writeBack:true on it).
+    throw Object.assign(new Error(`connector does not implement op "${msg.op}"`), { kind: 'plugin' });
+  }
+
+  // §7.1 signatures: getTask(id) and reportResult(id, r) are positional; every
+  // other op takes the single args object (listTasks(q), validateConfig(), …).
+  const args = msg.args && typeof msg.args === 'object' ? msg.args : {};
+  let result;
+  if (msg.op === 'getTask') {
+    result = await fn.call(source, args.id);
+  } else if (msg.op === 'reportResult') {
+    const { id, ...r } = args;
+    result = await fn.call(source, id, r);
+  } else {
+    result = await fn.call(source, args);
+  }
+  return { ok: true, result: result === undefined ? null : result, stateDelta, logs };
+}
+
+// A pending op promise alone does not keep the event loop alive: a hung
+// connector with no live handles would exit 0 with NO frame (parent would see
+// 'protocol', not 'timeout'). Hold the loop open so a hung op stays hung and
+// the parent's timeout SIGKILL is the only way out; process.exit(0) after the
+// frame ends the process regardless.
+setInterval(() => {}, 1 << 30);
+
+main()
+  .catch((err) => ({
+    ok: false,
+    error: { kind: err?.kind || 'plugin', message: err?.message || String(err) },
+    logs,
+  }))
+  .then((frame) => {
+    // Write-callback before exit so a piped stdout is fully flushed.
+    process.stdout.write(JSON.stringify(frame), () => process.exit(0));
+  });

package/src/core/plugin-shim.mjs

@@ -0,0 +1,197 @@
+// src/core/plugin-shim.mjs
+// Ephemeral child-process shim for task-source connector operations (spec §7.2).
+// One spawn per op: the child (plugin-shim-child.mjs) imports the connector
+// through <plugin>/current/, runs ONE op, writes ONE JSON frame to stdout, exits.
+//   stdin  : { apiVersion, module, op, config, state, args }
+//   stdout : { ok:true, result, stateDelta, logs }
+//          | { ok:false, error:{ kind, message }, logs }
+// Config+secrets+state travel via STDIN — never argv (visible in `ps`), never env
+// (inherited by grandchildren). The child env is scrubbed to {PATH, HOME} only, so
+// plugin X can never read plugin Y's secrets or the host environment. stateDelta
+// is applied HOST-side via writePluginState (the child has no WORCA_HOME and
+// never touches the store). WORCA_MOCK=1 short-circuits the spawn with canned
+// per-op responses so smoke/tests run offline with zero plugins installed.
+
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { WORCA_PLUGIN_API } from './plugin-api.mjs';
+import { normalizeManifest, negotiatedApi } from './plugin-manifest.mjs';
+import { readPluginsLock, pluginCurrentDir } from './plugins-lock.mjs';
+import { readPluginConfig, readPluginState, writePluginState } from './plugin-config.mjs';
+
+const CHILD_PATH = fileURLToPath(new URL('./plugin-shim-child.mjs', import.meta.url));
+
+/** Error kinds an op can surface (spec §11); anything else normalizes to 'plugin'. */
+const KINDS = new Set(['auth', 'rate-limit', 'network', 'plugin', 'timeout', 'protocol']);
+
+export class PluginOpError extends Error {
+  /**
+   * @param {'auth'|'rate-limit'|'network'|'plugin'|'timeout'|'protocol'} kind
+   * @param {string} message
+   */
+  constructor(kind, message) {
+    super(message);
+    this.name = 'PluginOpError';
+    this.kind = KINDS.has(kind) ? kind : 'plugin';
+  }
+}
+
+// ── WORCA_MOCK=1: canned responses, never spawns ─────────────────────────────
+
+let _mockResponses = null; // op -> value | (args) => value; null = defaults only
+
+/** Tests: override/extend the canned per-op responses. Pass null to reset. */
+export function setMockSourceResponses(map) {
+  _mockResponses = map && typeof map === 'object' ? map : null;
+}
+
+const MOCK_TASKS = [
+  { id: 'MOCK-1', title: 'Fix the login redirect', url: 'https://mock.test/MOCK-1', state: 'open', labels: ['bug'], updatedAt: '2026-07-12T00:00:00.000Z' },
+  { id: 'MOCK-2', title: 'Add CSV export to reports', url: 'https://mock.test/MOCK-2', state: 'open', labels: ['feature'], updatedAt: '2026-07-12T00:00:00.000Z' },
+];
+const MOCK_DEFAULTS = {
+  listTasks: () => ({ tasks: MOCK_TASKS.map((t) => ({ ...t })) }),
+  getTask: (args) => ({
+    ...MOCK_TASKS[0],
+    id: args?.id || MOCK_TASKS[0].id,
+    body: 'Mock task body.\n\n1. reproduce\n2. fix\n3. verify',
+    meta: { mock: true },
+  }),
+  reportResult: () => ({ ok: true }),
+  validateConfig: () => ({ ok: true }),
+};
+
+/** Same env-flag semantics as claude-runner.mjs#mockEnabled (claude-runner.mjs:100-104). */
+function mockMode() {
+  const v = process.env.WORCA_MOCK ?? process.env.ORCH_MOCK;
+  return !!v && v !== '0' && v.toLowerCase() !== 'false';
+}
+
+async function mockCall(op, args) {
+  const entry = _mockResponses && op in _mockResponses ? _mockResponses[op] : MOCK_DEFAULTS[op];
+  if (entry === undefined) {
+    // Mirror the real child's answer for an unimplemented op — Task 13's
+    // capabilities tolerant-default keys on exactly this kind.
+    throw new PluginOpError('plugin', `mock: no canned response for op "${op}"`);
+  }
+  try {
+    return await (typeof entry === 'function' ? entry(args) : entry);
+  } catch (err) {
+    if (err instanceof PluginOpError) throw err;
+    throw new PluginOpError(err?.kind || 'plugin', err?.message || String(err));
+  }
+}
+
+// ── real path ──────────────────────────────────────────────────────────────────
+
+/** Resolve lock entry + manifest task-source, mapping every failure to kind 'plugin'. */
+function loadSource(plugin, sourceId) {
+  const lock = readPluginsLock();
+  const entry = lock[plugin];
+  if (!entry) throw new PluginOpError('plugin', `plugin "${plugin}" is not installed`);
+  if (entry.enabled === false) throw new PluginOpError('plugin', `plugin "${plugin}" is disabled — enable it in the Plugins view`);
+  const dir = pluginCurrentDir(plugin);
+  let manifest;
+  try {
+    const norm = normalizeManifest(JSON.parse(readFileSync(join(dir, 'worca-cc-plugin.json'), 'utf8')), { dir });
+    if (!norm.ok) throw new Error(norm.errors.join('; '));
+    manifest = norm.manifest;
+  } catch (err) {
+    throw new PluginOpError('plugin', `plugin "${plugin}": cannot read manifest — ${err.message}`);
+  }
+  const source = (manifest.taskSources || []).find((s) => s.id === sourceId);
+  if (!source) throw new PluginOpError('plugin', `plugin "${plugin}" has no task source "${sourceId}"`);
+  // Highest host API the manifest's range allows: an API-1 connector keeps
+  // receiving apiVersion 1 after a host API bump (design §4.3).
+  const apiVersion = negotiatedApi(manifest.engines?.worcaApi) ?? WORCA_PLUGIN_API;
+  return { dir, source, apiVersion };
+}
+
+/** Child env: PATH + HOME ONLY (spec §7.2). Notably NOT WORCA_*, tokens, npm_*.
+ *  Exported for the channel-worker supervisor (chat/channel-host.mjs), which
+ *  spawns persistent children under the same rule. */
+export function scrubbedEnv() {
+  const env = {};
+  if (process.env.PATH) env.PATH = process.env.PATH;
+  if (process.env.HOME) env.HOME = process.env.HOME;
+  return env;
+}
+
+/**
+ * Run ONE connector op in an ephemeral child. Resolves with the op result;
+ * rejects with PluginOpError. `logger(level, msg)` is optional — connector
+ * ctx.log lines route there (default: console.error, since stdout is the UI's).
+ * @returns {Promise<any>}
+ */
+export async function callSource({ plugin, sourceId, op, args = {}, timeoutMs = 30000, logger } = {}) {
+  const log = typeof logger === 'function'
+    ? logger
+    : (level, msg) => console.error(`[plugin:${plugin}] ${level}: ${msg}`);
+
+  if (mockMode()) {
+    // Canned responses, no spawn, no plugin needed. reportResult additionally
+    // records its args into the plugin state — mirroring the real-child
+    // stateDelta path — so the offline smoke (Task 19) can assert write-back ran.
+    const r = await mockCall(op, args);
+    if (op === 'reportResult') writePluginState(plugin, { lastReport: JSON.stringify(args) });
+    return r;
+  }
+
+  const { dir, source, apiVersion } = loadSource(plugin, sourceId);
+  const payload = JSON.stringify({
+    apiVersion,
+    module: resolve(dir, source.module), // './'-relative, '..'-free (normalizeManifest)
+    op,
+    config: readPluginConfig(plugin, source.configSchema),
+    state: readPluginState(plugin),
+    args,
+  });
+
+  const frame = await new Promise((resolveFrame, rejectFrame) => {
+    // WORCA_PLUGIN_INSPECT=1 attaches the debugger to the connector child
+    // (`worca plugin exec --inspect` sets it; spec §7.2 debuggability).
+    const child = spawn(process.execPath,
+      [...(process.env.WORCA_PLUGIN_INSPECT ? ['--inspect-brk'] : []), CHILD_PATH], {
+      env: scrubbedEnv(),
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    let settled = false;
+    const killTimer = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, timeoutMs);
+    const settle = (fn, v) => { if (!settled) { settled = true; clearTimeout(killTimer); fn(v); } };
+    child.stdout.setEncoding('utf8').on('data', (c) => { stdout += c; });
+    child.stderr.setEncoding('utf8').on('data', (c) => { stderr += c; });
+    child.on('error', (err) => settle(rejectFrame, new PluginOpError('protocol', `plugin "${plugin}": spawn failed — ${err.message}`)));
+    child.on('close', (code) => {
+      if (timedOut) {
+        return settle(rejectFrame, new PluginOpError('timeout', `plugin "${plugin}" op "${op}" exceeded ${timeoutMs}ms (child killed)`));
+      }
+      if (code !== 0) {
+        return settle(rejectFrame, new PluginOpError('protocol',
+          `plugin "${plugin}" op "${op}": child exited ${code}${stderr ? ` — ${stderr.slice(0, 400)}` : ''}`));
+      }
+      try {
+        settle(resolveFrame, JSON.parse(stdout));
+      } catch {
+        settle(rejectFrame, new PluginOpError('protocol',
+          `plugin "${plugin}" op "${op}": non-JSON on stdout (stdout is protocol-reserved; use ctx.log) — got: ${stdout.slice(0, 200)}`));
+      }
+    });
+    child.stdin.end(payload); // config/secrets/state via stdin only
+  });
+
+  for (const l of Array.isArray(frame.logs) ? frame.logs : []) {
+    log(l?.level || 'info', String(l?.msg ?? ''));
+  }
+  if (!frame.ok) {
+    throw new PluginOpError(frame.error?.kind || 'plugin', frame.error?.message || `plugin "${plugin}" op "${op}" failed`);
+  }
+  if (frame.stateDelta && typeof frame.stateDelta === 'object' && Object.keys(frame.stateDelta).length) {
+    writePluginState(plugin, frame.stateDelta); // host-side persist; child never touches the store
+  }
+  return frame.result;
+}