agy-crew 0.0.0-stage → 0.9.2

package/companion/stream-worker.mjs

@@ -0,0 +1,361 @@
+import fs from 'node:fs';
+import { spawn, spawnSync } from 'node:child_process';
+import { PRODUCT } from './identity.mjs';
+import { createParser, createProjection, excerpt, boundSnapshot } from './observation.mjs';
+import { replaceFile } from './state-lock.mjs';
+
+export function atomicJSON(file, value) {
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(value) + '\n');
+  replaceFile(tmp, file);
+}
+
+export function signalGroup(pid, signal, runner = spawnSync, platform = process.platform) {
+  if (!Number.isInteger(pid) || pid <= 1) return;
+  if (platform === 'win32') {
+    try {
+      // Never /T here: taskkill's own tree walk follows stale ParentProcessId
+      // links (a dead parent's PID reused by this root) into unrelated orphans.
+      // Descendants are terminated one by one by stopExecution after each has
+      // passed the identity and birth-order checks in tree().
+      const res = runner('taskkill', ['/PID', String(pid), '/F'], { windowsHide: true, stdio: 'ignore' });
+      if (res?.error || (res?.status != null && res.status !== 0)) {
+        try { process.kill(pid); } catch { /* already exited */ }
+      }
+    } catch {
+      try { process.kill(pid); } catch { /* already exited */ }
+    }
+    return;
+  }
+  try { process.kill(-pid, signal); } catch { /* already exited */ }
+}
+export const terminateProcessGroup = signalGroup;
+
+export function parseWindowsProcessTable(stdout) {
+  if (!stdout || typeof stdout !== 'string') return [];
+  const lines = stdout.trim().split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  if (lines.length === 0) return [];
+
+  let format = 'powershell';
+  const firstLine = lines[0];
+  if (/^CreationDate/i.test(firstLine)) {
+    format = 'wmic';
+  }
+
+  const rows = [];
+  for (const line of lines) {
+    if (/^(ProcessId|ParentProcessId|CreationDate|--+)/i.test(line)) continue;
+    if (format === 'wmic') {
+      const match = /^(\S+)\s+(\d+)\s+(\d+)$/.exec(line);
+      if (match) {
+        const born = match[1];
+        const parent = Number(match[2]);
+        const pid = Number(match[3]);
+        rows.push({ pid, parent, group: pid, born });
+      }
+    } else {
+      const match = /^(\d+)\s+(\d+)\s*(.*)$/.exec(line);
+      if (match) {
+        const pid = Number(match[1]);
+        const parent = Number(match[2]);
+        const born = match[3].trim() || 'unknown';
+        rows.push({ pid, parent, group: pid, born });
+      }
+    }
+  }
+  return rows;
+}
+
+export function windowsProcessTable(runner = spawnSync) {
+  let res;
+  try {
+    res = runner('powershell', [
+      '-NoLogo',
+      '-NoProfile',
+      '-NonInteractive',
+      '-Command',
+      // -Property limits the WMI fetch to the three columns we parse. The
+      // round-trip ("o") format keeps the 100 ns precision of CreationDate;
+      // the default locale rendering is second-granular, too coarse to order a
+      // process against one that reused its parent's PID in the same second.
+      "Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,CreationDate | Select-Object ProcessId,ParentProcessId,@{Name='CreationDate';Expression={if ($_.CreationDate) { $_.CreationDate.ToString('o') } else { '' }}}",
+    // A cold PowerShell start plus the CIM query can take several seconds on
+    // a busy host; a timeout here would make cleanup skip the tree entirely.
+    ], { encoding: 'utf8', timeout: 15000, windowsHide: true });
+  } catch (err) {
+    res = { error: err };
+  }
+
+  if (res?.error || res?.status !== 0) {
+    try {
+      res = runner('wmic', [
+        'process',
+        'get',
+        'ProcessId,ParentProcessId,CreationDate',
+      ], { encoding: 'utf8', timeout: 15000, windowsHide: true });
+    } catch (err) {
+      res = { error: err };
+    }
+  }
+
+  if (res?.error || res?.status !== 0 || !res?.stdout) {
+    return null;
+  }
+  return parseWindowsProcessTable(res.stdout);
+}
+
+// Track process birth stamps so a previously observed PID cannot cause cleanup
+// to kill an unrelated process after PID reuse. Tool shells may create groups.
+let inspectionUnavailable = false;
+// No caching, even though the Windows query is slow: callers rely on a
+// process spawned a moment ago being visible (identity capture, hard stop).
+export function processTable() {
+  if (process.platform === 'win32') {
+    const table = windowsProcessTable();
+    if (!table) {
+      if (!inspectionUnavailable) process.stderr.write(PRODUCT + ' warning: process-tree inspection unavailable; run unsandboxed to verify descendant cleanup.\n');
+      inspectionUnavailable = true;
+      return null;
+    }
+    return table;
+  }
+  const ps = spawnSync('ps', ['-axo', 'pid=,ppid=,pgid=,lstart='], {
+    encoding: 'utf8',
+    timeout: 1000,
+    windowsHide: true,
+    env: { ...process.env, LC_ALL: 'C', TZ: 'UTC' },
+  });
+  if (ps.error || ps.status !== 0) {
+    if (!inspectionUnavailable) process.stderr.write(PRODUCT + ' warning: process-tree inspection unavailable; run unsandboxed to verify descendant cleanup.\n');
+    inspectionUnavailable = true;
+    return null;
+  }
+  return (ps.stdout || '').trim().split('\n').flatMap((line) => {
+    const match = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(.+)$/.exec(line);
+    return match ? [{ pid: Number(match[1]), parent: Number(match[2]), group: Number(match[3]), born: match[4].trim() }] : [];
+  });
+}
+/** Birth stamp as 100 ns ticks since the epoch (BigInt, so PowerShell's
+ *  seven fractional digits survive), or null when the format is unknown.
+ *  Accepts ISO-8601 (PowerShell "o"), WMIC (yyyyMMddHHmmss.ffffff+ZZZ) and
+ *  any legacy rendering Date.parse understands. */
+export function parseBorn(born) {
+  if (typeof born !== 'string' || !born || born === 'unknown') return null;
+  const iso = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,7}))?(Z|[+-]\d{2}:\d{2})?$/.exec(born);
+  if (iso) {
+    const seconds = BigInt(Date.UTC(+iso[1], +iso[2] - 1, +iso[3], +iso[4], +iso[5], +iso[6])) / 1000n;
+    const ticks = BigInt((iso[7] || '').padEnd(7, '0'));
+    const zoneMinutes = iso[8] && iso[8] !== 'Z' ? (iso[8].startsWith('-') ? -1n : 1n) * (BigInt(iso[8].slice(1, 3)) * 60n + BigInt(iso[8].slice(4, 6))) : 0n;
+    return (seconds - zoneMinutes * 60n) * 10_000_000n + ticks;
+  }
+  const wmic = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})\.(\d{6})([+-]\d{3})$/.exec(born);
+  if (wmic) {
+    const seconds = BigInt(Date.UTC(+wmic[1], +wmic[2] - 1, +wmic[3], +wmic[4], +wmic[5], +wmic[6])) / 1000n;
+    return (seconds - BigInt(wmic[8]) * 60n) * 10_000_000n + BigInt(wmic[7]) * 10n;
+  }
+  const legacy = Date.parse(born);
+  return Number.isNaN(legacy) ? null : BigInt(legacy) * 10_000n;
+}
+
+/** A process cannot be older than its parent. A row whose recorded parent was
+ *  born after it is an orphan whose dead parent's PID has been reused: Windows
+ *  keeps the stale ParentProcessId, and the reuser is not its ancestor. When
+ *  either stamp is unreadable the edge is kept; POSIX reparents orphans to
+ *  init, so the stale-link case does not arise there. */
+export function bornAfterParent(child, parent) {
+  const c = parseBorn(child?.born), p = parseBorn(parent?.born);
+  if (c === null || p === null) return true;
+  return c >= p;
+}
+
+export function tree(pid, rows = processTable()) {
+  if (!rows || !pid) return [];
+  const root = rows.find((row) => row.pid === pid);
+  if (!root) return [];
+  const found = new Map([[pid, root]]);
+  for (let changed = true; changed;) {
+    changed = false;
+    for (const row of rows) {
+      if (found.has(row.pid) || !found.has(row.parent)) continue;
+      if (!bornAfterParent(row, found.get(row.parent))) continue;
+      found.set(row.pid, row); changed = true;
+    }
+  }
+  return rows.filter((row) => row.pid !== pid && found.has(row.pid));
+}
+export function descendants(pid) { return tree(pid).map((row) => row.pid); }
+
+export function processIdentity(pid) {
+  if (!Number.isInteger(pid) || pid <= 1) return null;
+  return processTable()?.find((row) => row.pid === pid) || null;
+}
+const matches = (rows, identity) => !!identity && !!rows?.some((row) => row.pid === identity.pid && row.born === identity.born);
+
+export async function stopExecution(root, known = [], table = processTable) {
+  if (!root) return;
+  const current = table();
+  if (!current) return;
+  const children = new Map(known.filter((old) => matches(current, old)).map((row) => [row.pid, row]));
+  if (matches(current, root)) {
+    children.set(root.pid, root);
+    for (const row of tree(root.pid, current)) children.set(row.pid, row);
+  }
+  // This process is never a member of the execution group it is stopping.
+  children.delete(process.pid);
+  // Nothing of ours is left: skip the grace wait and the second table query.
+  if (children.size === 0) return;
+  // A member spawned after the last snapshot (a tool started during the grace
+  // period) is adopted from a still-live, identity-matched member under the
+  // same birth-order rule as tree(); a dead member's PID proves nothing.
+  const adopt = (rows) => {
+    if (!rows) return;
+    for (let changed = true; changed;) {
+      changed = false;
+      for (const row of rows) {
+        if (children.has(row.pid) || row.pid === process.pid) continue;
+        const parent = children.get(row.parent);
+        if (!parent || !matches(rows, parent) || !bornAfterParent(row, parent)) continue;
+        children.set(row.pid, row); changed = true;
+      }
+    }
+  };
+  const signal = (rows, kind) => {
+    adopt(rows);
+    // A surviving, identified member proves this is still our execution group.
+    const reusedLeader = rows?.some((row) => row.pid === root.pid && row.born !== root.born);
+    const ownedMember = rows?.some((row) => row.group === root.pid && children.get(row.pid)?.born === row.born);
+    if (!reusedLeader && ownedMember) signalGroup(root.pid, kind);
+    for (const child of [...children.values()].reverse()) {
+      if (matches(rows, child)) { try { process.kill(child.pid, kind); } catch {} }
+    }
+  };
+  signal(current, 'SIGTERM');
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  signal(table(), 'SIGKILL');
+}
+
+export async function runStreaming({ binary, args, job, budget, signal, update, conversation, env }) {
+  const hardDeadline = Date.now() + Math.max(0, budget);
+  const rawFd = fs.openSync(job.events_file, 'a');
+  const projection = createProjection(conversation);
+  let payload = null, stderr = '', stdoutTail = '', lastPublish = 0, child, root, deadline, publishTimer, trackingTimer;
+  let stopping = null, reason = null, spawnError = null, streamError = null;
+  const tracked = new Map();
+  const track = () => {
+    const rows = processTable();
+    if (!rows) return; // An unavailable inspection is not evidence of exit.
+    for (const [pid, old] of tracked) if (!rows.some((row) => row.pid === pid && row.born === old.born)) tracked.delete(pid);
+    if (!root) root = rows.find((row) => row.pid === child?.pid);
+    if (matches(rows, root)) for (const row of tree(root.pid, rows)) tracked.set(row.pid, row);
+    // A detached child owns its group until exit; collect orphaned members at
+    // the exit/result boundary too, unless the leader PID has been reused.
+    if (root && !rows.some((row) => row.pid === root.pid && row.born !== root.born)) {
+      for (const row of rows) if (row.pid !== root.pid && row.group === root.pid) tracked.set(row.pid, row);
+    }
+  };
+  const publish = () => {
+    lastPublish = Date.now();
+    atomicJSON(job.progress_file, boundSnapshot({ job_id: job.id, ...projection.snapshot() }));
+  };
+  const stop = (why) => {
+    if (why === 'canceled') reason = why;
+    if (stopping) return;
+    reason = why;
+    // Latch the stop reason before cleanup. The terminal record is published
+    // only after the report is durable; canceled records stay canceled.
+    clearInterval(trackingTimer);
+    track();
+    stopping = cleanup();
+  };
+  const cleanup = async () => {
+    // ChildProcess.kill only targets our still-running direct child. Stored
+    // numeric PIDs are never sufficient authority for a signal.
+    if (!root && child?.exitCode === null && child.signalCode === null) child.kill('SIGTERM');
+    await stopExecution(root, [...tracked.values()]);
+    if (child?.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
+  };
+  const abort = () => stop('canceled');
+  const safely = (action) => {
+    try { action(); } catch (error) { streamError ||= error; stop('stream_error'); }
+  };
+  try {
+    publish();
+    // On Windows, detached: true creates a new console window; piped stdio keeps the
+    // process stream connected. On POSIX, detached: true creates a new process group.
+    child = spawn(binary, args, {
+      detached: process.platform !== 'win32',
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      // undefined inherits the process environment; pool accounts pass a private HOME
+      env,
+    });
+    const exited = new Promise((resolve) => {
+      child.once('error', (error) => { spawnError = error; resolve({ exit: null, killedSignal: null }); });
+      child.once('exit', (exit, killedSignal) => resolve({ exit, killedSignal }));
+    });
+    const closed = new Promise((resolve) => child.once('close', resolve));
+    track();
+    // ps is cheap; the PowerShell CIM query on Windows takes 1-3 s and runs
+    // synchronously, so sample less often there to keep the event loop free.
+    trackingTimer = setInterval(track, process.platform === 'win32' ? 5000 : 1000);
+    update({ agy_pid: child.pid, execution_started_at: new Date().toISOString(), hard_deadline_at: new Date(hardDeadline).toISOString() });
+    signal.addEventListener('abort', abort, { once: true });
+    if (signal.aborted) abort();
+    deadline = setTimeout(() => stop('hard_timeout'), Math.max(0, hardDeadline - Date.now()));
+    const parser = createParser((event) => {
+      projection.accept(event);
+      if (event.event === 'result' && event.result && typeof event.result === 'object') { payload = event.result; track(); }
+      if (Date.now() - lastPublish >= 100) publish();
+      else if (!publishTimer) publishTimer = setTimeout(() => { publishTimer = null; safely(publish); }, 100);
+    }, projection.warn, 64 * 1024 * 1024);
+    child.stdout.on('data', (chunk) => safely(() => {
+      fs.writeSync(rawFd, chunk);
+      stdoutTail = excerpt(stdoutTail + chunk.toString('utf8'), 8192, true).text;
+      parser.write(chunk);
+    }));
+    child.stderr.on('data', (chunk) => safely(() => {
+      process.stderr.write(chunk);
+      stderr = excerpt(stderr + chunk.toString('utf8'), 8192, true).text;
+    }));
+    const outcome = await exited;
+    clearTimeout(deadline); clearInterval(trackingTimer);
+    if (stopping) await stopping;
+    // Kill remaining members even if the CLI itself already exited.
+    else { track(); stopping = cleanup(); await stopping; }
+    // Drain buffered result bytes, but do not wait indefinitely for a tool
+    // process that inherited stdout/stderr and escaped cleanup.
+    let drainTimer;
+    const drained = await Promise.race([closed.then(() => true), new Promise((resolve) => { drainTimer = setTimeout(() => resolve(false), 500); })]);
+    clearTimeout(drainTimer);
+    if (!drained) {
+      projection.warn('AGY exited but inherited output pipes did not close; output drain was bounded.');
+      child.stdout.destroy(); child.stderr.destroy();
+    }
+    safely(() => parser.end());
+    clearTimeout(publishTimer);
+    if (inspectionUnavailable) projection.warn('Process-tree inspection unavailable; verify descendant cleanup from the original unsandboxed context.');
+    publish();
+    if (streamError) throw Object.assign(streamError, { reason: 'stream_error' });
+    if (reason === 'hard_timeout' && typeof payload?.response === 'string' && payload.response.trim()) {
+      const warning = 'Worker hard execution limit reached after a response was received; delivering the response with a cleanup warning.';
+      projection.warn(warning);
+      stderr = `${stderr}\n${warning}`.trim();
+      process.stderr.write(`${PRODUCT} warning: ${warning}\n`);
+    } else if (reason) throw Object.assign(new Error(reason === 'hard_timeout' ? 'Worker hard execution limit reached.' : 'Execution canceled.'), { reason });
+    if (spawnError) throw Object.assign(new Error(`failed to launch agy (${binary}): ${spawnError.message}`), { reason: 'launch_error' });
+    if (!payload) {
+      let message = `agy did not return parseable JSON result (exit ${outcome.exit}, signal ${outcome.killedSignal || 'none'}). stdout: see ${job.events_file}\nstderr: ${stderr || '(empty)'}`;
+      if (/operation not permitted/i.test(stderr)) message += '\nThis looks like a harness command sandbox blocking agy. Run this companion command unsandboxed (escalated permissions).';
+      throw Object.assign(new Error(message), { reason: 'missing_result', diagnosticText: `${stdoutTail}\n${stderr}` });
+    }
+    return { payload, stderr, exit: outcome.exit ?? 1, observationWarnings: projection.snapshot().warnings };
+  } catch (error) {
+    if (!stopping && child?.pid) await cleanup();
+    throw error;
+  } finally {
+    clearInterval(trackingTimer);
+    clearTimeout(deadline); clearTimeout(publishTimer);
+    signal.removeEventListener('abort', abort);
+    fs.closeSync(rawFd);
+  }
+}

package/docs/INSTALL_FOR_AGENTS.md

@@ -0,0 +1,213 @@
+# Installing agy-crew — a guide for coding agents
+
+You are a coding agent that has been asked to install and verify the **agy-crew** plugin. Follow this file top to bottom. When you finish (or get blocked), report the outcome to the user **in the user's own language** — the language they have been using with you, not necessarily English.
+
+> [!IMPORTANT]
+> If you reached this file through a URL, read its **raw** text — `curl -fsSL https://raw.githubusercontent.com/pStrikeZ/agy-crew/master/docs/INSTALL_FOR_AGENTS.md` — or clone the repo. Fetching the rendered page through a web tool that summarises before handing you the content can return a paraphrase, and a paraphrased install command is a broken install command. If all you have is a summary, stop and fetch the raw file.
+
+## 0. Prerequisites
+
+1. **`agy` binary** — run `agy --version`. Use a version supporting `stream-json` (lifecycle smoke tests use v1.1.27). If it is missing, do **not** install it yourself: give the user the official install page <https://antigravity.google/docs/cli/install> (macOS/Linux: `curl -fsSL https://antigravity.google/cli/install.sh | bash`) and wait for them to install and authenticate (`agy` run interactively once handles login).
+2. **Node.js** — run `node --version` (20 or newer). The companion script uses only the Node standard library.
+3. **No agy-staff on this machine.** agy-crew is a fork of the upstream agy-staff, and the two must not be installed together: the skills would appear twice and both companions would write the same per-repository state. `agy-crew install` refuses to run when it finds agy-staff. If you find agy-staff (the `agy@agy-staff` Claude Code plugin, an agy-staff plugin in Codex, an `agy-staff@…` entry in `opencode.json`, an agy-staff Pi package, or upstream flat skills such as `agy-ask` and `agy-jobs` in a harness skills directory), **stop and ask the user before removing anything**. Never remove it silently. With the user's agreement, the removal is: Claude Code `claude plugin uninstall agy@agy-staff`; Codex remove the agy-staff plugin and restart; OpenCode remove the `agy-staff@…` entry from `opencode.json`; Pi uninstall the agy-staff package; and delete any upstream flat skills.
+
+## 1. Detect which harness you are running in
+
+You normally know which product you are. If unsure, check:
+
+- **Claude Code** — you have `/plugin` slash commands, project instructions arrive via `CLAUDE.md`, and your Bash tool typically has `CLAUDECODE=1` in the environment. → Follow section 2a.
+- **Codex** — you invoke skills with `$name` syntax, follow `AGENTS.md`, and plugins are managed through the `codex` CLI. → Follow section 2b.
+- **Pi** — you invoke skills with `/skill:name` and manage packages with `pi install`. → Follow section 2c.
+- **OpenCode V1** — you use `opencode`, its `plugin` config or `opencode plugin` installer, and native `/agy-crew-*` commands. Verified with OpenCode 1.18.34; V2 is not covered. → Follow section 2d.
+- **Oh My Pi / DeepSeek Harness** — supported through route A only (`--hosts omp`, `--hosts dsh`).
+- **Anything else** — this package documents Claude Code, Codex, Pi, OpenCode V1, Oh My Pi and DeepSeek Harness. Report the unsupported harness and stop.
+
+### Route A (preferred): the `agy-crew` terminal command
+
+If `node` and `npm` are available, install the command and let it put the skills into the harness you are running in. It supports Claude Code (`claude`), Codex (`codex`), Oh My Pi (`omp`), OpenCode (`opencode`) and DeepSeek Harness (`dsh`); it does not cover Pi, which uses section 2c.
+
+```bash
+npm install -g agy-crew
+agy-crew install --dry-run --hosts <this harness>   # optional: print the plan, write nothing
+agy-crew install --hosts <this harness>             # e.g. --hosts claude
+agy-crew install --status --json                    # verify per-host link state and bundle
+```
+
+For a local checkout the user gave you, run `npm link` inside it instead of `npm install -g`; the skills then run from the checkout, and `agy-crew install` must be re-run after a `git pull`. The installer renders the skills once into `~/.agy-crew/bundles/<version>-<digest>/` and links `agy-crew-<persona>` directories into the harness skills directory. It never overwrites anything it did not create; on any conflict it aborts before writing and prints the paths and a remedy, which you should relay verbatim and not work around. If route A succeeds, skip to section 3.
+
+### Route A′ (fallback): no npm, git clone + node
+
+If `node` is available but `npm` is not (or the user does not want a global npm package), and `git` is available, clone the repo and run the companion directly. Pick a stable location (for example `~/agy-crew`); the bundle stores the absolute path of the companion inside the clone, so the clone must not move or be deleted afterwards.
+
+```bash
+git clone https://github.com/pStrikeZ/agy-crew <clone>
+node <clone>/companion/agy-companion.mjs install --dry-run --hosts <this harness>   # optional
+node <clone>/companion/agy-companion.mjs install --hosts <this harness>
+node <clone>/companion/agy-companion.mjs install --status --json
+```
+
+The skills behave exactly as in route A, but there is **no `agy-crew` command on PATH**: wherever this guide says `agy-crew <command>`, run `node <clone>/companion/agy-companion.mjs <command>` instead (a shell alias is optional and the user's call). To update, `git -C <clone> pull`, then re-run the install command. To uninstall, run `node <clone>/companion/agy-companion.mjs uninstall --all`, then delete the clone; `~/.agy-crew` (pool accounts) is removed only manually and only if the user asks. If route A′ succeeds, skip to section 3.
+
+### Route B: the harness plugin manager
+
+Use this when route A and A′ are not possible (no node-based install, Pi, or the user prefers the plugin manager). Note the trade-off for the user: there is no terminal command, and the account pool commands are awkward because the companion lives in the plugin cache. Follow exactly one of the four sections below.
+
+## 2a. Claude Code — plugin route (B) install / upgrade
+
+Use the `claude` CLI. The `/plugin …` forms you may have seen are TUI slash commands typed by a human — you cannot execute them from your Bash tool, and there is no shell equivalent of "typing a slash command".
+
+Install (use the local checkout path instead of the slug if the user gave you one):
+
+```bash
+claude plugin marketplace add pStrikeZ/agy-crew   # human types: /plugin marketplace add pStrikeZ/agy-crew
+claude plugin install agy-crew@agy-crew                # human types: /plugin install agy-crew@agy-crew
+```
+
+Upgrade an existing install — note this is `update`, not `install`:
+
+```bash
+claude plugin marketplace update agy-crew
+claude plugin update agy-crew@agy-crew
+```
+
+> [!IMPORTANT]
+> `install` never upgrades: on an already-installed plugin it answers "already installed" and does nothing, whatever the version. And `update` is keyed on the **version string**, not the commit — if the published version is unchanged it answers "already at the latest version", so the user keeps running the old commit while the marketplace clone has moved on. Check by comparing `gitCommitSha` in `~/.claude/plugins/installed_plugins.json` against `git -C ~/.claude/plugins/marketplaces/agy-crew log -1`. When they differ but the version does not, force the current commit in: `claude plugin uninstall agy-crew@agy-crew && claude plugin install agy-crew@agy-crew`.
+
+Then verify what actually landed: `claude plugin list` should show `agy-crew@agy-crew` enabled, at the version you expected. If the user is a contributor, watch for an install whose marketplace source is a **local directory** rather than the GitHub slug — that install tracks their working tree, not a release, which is fine for development but is not what "install the plugin" usually means. Say so, and offer the clean path: `claude plugin uninstall agy-crew@agy-crew`, `claude plugin marketplace remove agy-crew`, then add the slug again.
+
+**A restart is required before the plugin is usable.** A freshly installed plugin is not in the current session's skill registry, so `/agy-crew:…` either does not resolve or — if an older copy was loaded when the session started — silently resolves to that stale copy. Tell the user to restart Claude Code, or verify without a restart using the shell fallback in section 3.
+
+## 2b. Codex — plugin route (B) install / upgrade
+
+Install (use the local checkout path instead of the URL if the user gave you one):
+
+```bash
+codex plugin marketplace add https://github.com/pStrikeZ/agy-crew
+codex plugin add agy-crew@agy-crew
+```
+
+Then the user must restart the app — Codex caches plugins per version. Upgrades reach the app only after the plugin version is bumped **and** `codex plugin marketplace upgrade` is run, followed by a restart.
+
+> [!IMPORTANT]
+> Codex's command sandbox cannot run agy. agy binds a localhost port for its internal language server and reads its OAuth token file; the workspace-write sandbox blocks the bind and hides the token (secret protection — no `writable_roots`/`network_access` config opens it). Every companion command (both job dispatch and management commands such as `wait`, `status`, `result`) must run **unsandboxed**: the workspace needs full access, or each companion command needs escalated approval. The failure signature is `operation not permitted` on `~/.gemini/antigravity-cli/...` followed by empty output or a bogus "authentication failed".
+
+## 2c. Pi — package route (B) install / upgrade / local development
+
+Install (use the local checkout path if provided):
+
+```bash
+pi install git:github.com/pStrikeZ/agy-crew
+```
+
+For local development checkouts, use `pi install /absolute/path/to/checkout` (or `pi -e /absolute/path/to/checkout` for a temporary session). Run `npm run generate:pi` in the checkout if canonical skills were modified.
+
+To upgrade an existing Git install:
+
+```bash
+pi update --extension git:github.com/pStrikeZ/agy-crew
+```
+
+Restart Pi or run `/reload` afterwards. Use `pi list` to verify the package is registered, then check Pi's skill picker for `agy-crew-lead`, `agy-crew-ask`, `agy-crewer`, `agy-crew-researcher`, `agy-crew-reviewer`, `agy-crew-implementer`, and `agy-crew-jobs`.
+
+## 2d. OpenCode V1 — plugin route (B) install / upgrade / local development
+
+Use the native plugin installer (verified with OpenCode 1.18.34):
+
+```bash
+opencode plugin 'agy-crew@git+https://github.com/pStrikeZ/agy-crew.git' --global
+```
+
+This installs the full package and adds it to the `plugin` array in OpenCode's config, preserving other settings. Do not replace the user's config file. The plugin registers its bundled skills automatically; do not manually clone the repository or add `skills.paths` as an installation workaround. For an explicitly provided local checkout, use `opencode plugin /absolute/path/to/checkout --global`. Regenerate modified canonical skills with `npm run generate:skills` in that checkout.
+
+Restart OpenCode, then verify with `opencode debug skill`: expect `agy-crew-ask`, `agy-crewer`, `agy-crew-researcher`, `agy-crew-reviewer`, `agy-crew-implementer`, `agy-crew-jobs`, and `agy-crew-lead` alongside any other installed skills. OpenCode exposes these directly as `/agy-crew-*` commands. Existing skill permissions remain in effect. Install the entire package, since its companion, templates and references are relative resources.
+
+OpenCode 1.18.34 caches the full package spec. Restarting or reinstalling the same Git spec does not guarantee an update, even with `--force`. Select a newer tag or commit containing the adapter, replace the placeholder below, then restart:
+
+```bash
+opencode plugin 'agy-crew@git+https://github.com/pStrikeZ/agy-crew.git#<tag-or-commit>' --global --force
+```
+
+Changing the ref creates a fresh cache key; `--force` replaces the configured plugin entry. Do not clear unrelated caches. This adapter covers V1, not V2.
+
+## 3. Smoke test
+
+Run the zero-setup ask mode — it needs no allowlist and answers in ~3 seconds:
+
+- Installed with route A or A′ (any harness): `/agy-crew-ask reply with OK` (Codex shows it as `$agy-crew-ask`) — after the restart
+- Claude Code plugin route: `/agy-crew:ask "reply with OK"` — **after the restart**, otherwise you are testing the old copy or nothing at all
+- Codex: `$agy-crew:ask reply with OK`
+- Pi: `/skill:agy-crew-ask reply with OK` — after restart or `/reload`
+- OpenCode: `/agy-crew-ask reply with OK` — after restart
+
+If you cannot restart the session, call the companion of the freshly installed copy directly from the shell. After route A the `agy-crew` command is the companion: `agy-crew ask --prompt "reply with OK"`; after route A′ run `node <clone>/companion/agy-companion.mjs ask --prompt "reply with OK"`. It is the same code path the skill takes, so a pass here means the install is sound:
+
+For Claude Code, resolve its installed copy with:
+
+```bash
+AGY_ROOT=$(node -p 'require(process.env.HOME+"/.claude/plugins/installed_plugins.json").plugins["agy-crew@agy-crew"][0].installPath')
+node "$AGY_ROOT/companion/agy-companion.mjs" ask --prompt "reply with OK"
+```
+
+Resolve the root that way rather than globbing `cache/agy-crew/agy-crew/*/`: superseded version directories are left behind after an upgrade, so the glob expands to several paths and the command fails with `unknown subcommand`. `installPath` is always the copy in use. (Codex's equivalent root is printed by `codex plugin list`.) For OpenCode, `opencode debug skill` reports each skill location; resolve `../../companion/agy-companion.mjs` from the installed `agy-crew-ask` skill directory and invoke it with `node` from the user’s project directory. For Pi, use the registered package root from `pi list`. A fallback pass still leaves the restart outstanding — report it as "installed and verified, restart the current harness to use it".
+
+Expect a short answer on stdout with no telemetry mixed in, plus an `[agy-crew]` telemetry line on stderr (mode, profile, model, duration, tokens, conversation id — for you, not for the user). If it errors, relay the error verbatim; the usual causes are expired agy auth (user runs `agy` interactively once to re-login) or an invalid model id (`agy models` lists valid ids). Do not improvise flags to work around errors.
+
+> [!IMPORTANT]
+> A passing `ask` smoke means the install is done. `staffer`, `researcher`, `reviewer` and `implementer` all default to the **unrestricted** profile, so they gather evidence and edit files without any allowlist — nothing else is required to use them. Section 4 (`setup`) is **optional hardening**: it only matters if the user wants to run with `--restricted`, where headless agy fail-closes on every tool call that is not on the allowlist. Do not run setup unprompted; offer it, and apply it only if the user asks for the hardened path.
+
+## 4. Optional hardening — setup, dry run first
+
+Skip this section unless the user wants it. Every tool-using mode already works unrestricted; setup exists so that the opt-in `--restricted` profile is usable, because a restricted run needs an **evidence-gathering command allowlist** in agy's settings or it comes back empty. Mention it to security-sensitive users (shared machines, reviewing untrusted PRs) and let them decide. Setup can also record a per-repo policy (`setup --restrict review,research` makes those modes default to restricted in the current repository; `--restrict none` clears it) — offer that only in the same opt-in conversation.
+
+If they opt in, global install is the normal path. Run the setup **dry run** first — never apply directly:
+
+```bash
+agy-crew setup   # dry run; only add --apply after user confirmation (without the command on PATH: node <plugin-root>/companion/agy-companion.mjs setup)
+```
+
+The full guided flow lives in the jobs skill (`skills/jobs/references/setup.md`).
+
+Show the user the full dry-run output and state these four things plainly before asking for confirmation:
+
+1. Which command rules would be added, and that they exist so `--restricted` runs can gather evidence unattended.
+2. The target file is the **global** `~/.gemini/antigravity-cli/settings.json`, so the rules apply to every `agy` run on this machine — not only to agy-crew jobs.
+3. Setup keeps broad git/gh grants and adds five native deny prefixes: `git push`, `git reset --hard`, `git clean`, `gh pr merge`, and `gh release delete`. AGY evaluates deny > ask > allow. Existing rules are preserved, and the dry run shows any additions. This prevents common mistakes, not every irreversible action: alternate command forms, scripts and APIs are not comprehensively covered. Task authorization does not override deny.
+4. The existing file is backed up before writing.
+
+Apply only after the user explicitly agrees. If they decline, nothing is lost from the default experience — all four modes keep working; they simply cannot harden a run with `--restricted` until the allowlist exists.
+
+If the user is security-sensitive and the machine-wide scope is unacceptable, tell them agy also supports project-scoped permission rules (highest priority) tied to its `--project` system — but that **the project-settings file path is undocumented and unverified against the current agy release**. Do not guess a path and do not write one; point them at [REFERENCE.md → Advanced: project-scoped permissions](REFERENCE.md#advanced-project-scoped-permissions) and let them verify it interactively with `agy`.
+
+## 5. Optional — the account pool
+
+Skip this section unless the user wants concurrent jobs on several agy accounts. Without it everything runs on the user's own agy login (**live**), exactly as before; live is never part of the pool.
+
+Never run `accounts login` yourself. It opens a browser sign-in and waits for the user to exit agy, so only the user can complete it. Offer it, and if they agree give them the command to run in their own terminal:
+
+```bash
+agy-crew accounts login work1     # choose any name: lowercase letters, digits, . _ -
+```
+
+Without the command on PATH (route A′ or B), use `node <clone-or-plugin-root>/companion/agy-companion.mjs accounts login work1`. Repeat with another name for each account (each must be a different Google account). If the user already has agy homes from agy-cli-manager, `agy-crew accounts import <name> --home <dir>` copies the token without a browser; ask before importing. Afterwards you can verify without side effects:
+
+```bash
+agy-crew accounts list            # each account should show "ready"
+```
+
+Runs then choose an account automatically (`--account auto`). New accounts copy their permission settings from the live settings file on login, and a later `setup --apply` updates every pool account. Details: [REFERENCE.md → Accounts](REFERENCE.md#accounts).
+
+## 6. The execution model
+
+`ask` returns its answer synchronously. `staffer`, `research`, `review` and `implement` return a job id, and the job-start output prints the exact collect command (`wait <id> --timeout 10m`). Run that as a background command — one background wait per job — and deliver the result when it exits; exit code 2 means still running, so run the same `wait` again (`cancel <id>` stops the job). Do not leave a started job unreported.
+
+Exit 5 signals a timeout with a resumable conversation. Inspect the retained workspace changes and ask whether to continue with the suggested timeout or stop; recover only after explicit user confirmation. The continuation command preserves the original persona/model/profile. This also applies to synchronous `ask`; no run automatically retries or continues.
+
+Per-repo state lives in `<repo>/.agy-crew/`; the companion git-ignores it automatically on first use (via `.git/info/exclude` — the tracked `.gitignore` is never touched).
+
+## 7. Report back
+
+Tell the user, in **their** language: whether install succeeded (name the version and whether it came from the GitHub slug or a local checkout, and whether you used route A, A′ or B; for A′ also the clone path, which must stay put), the smoke-test result, whether a restart is still needed before the skills load, and whether the optional setup rules were applied, declined, or never offered (the default unrestricted profile does not need it), and whether any pool accounts were added (and that the user, not you, ran the login).
+
+Default: prepare the prompt, dispatch, wait for the final result, then validate as needed. On wait exit 2, wait again for the same job without extra progress checks. While running, do not proactively observe, read logs or inspect intermediate artifacts, including for routine updates. Observe only when the user explicitly asks for progress; diagnose after a failure or a result requiring intervention. Host collection of a pending wait command is necessary result collection, not active observation. Prefer background completion delivery or the longest practical blocking wait the host supports; avoid short empty polls and sleep/observe loops. The worker's hard limit and explicit recovery protocol remain separate from wait soft expiry.
+
+`observe <id>` always returns bounded JSON, including after completion. Its exit 0 means the job finished; collect the existing wait session or use `result <id>` to obtain the full report. Observation does not consume the waiting command’s output.