flowviant 0.103.0 → 0.104.0

package/bin/lib/runTurn.mjs

@@ -0,0 +1,324 @@
+/**
+ * ONE HEADLESS CLI TURN — the argv the runtime's adapter builds, the child it
+ * spawns (its own process group, the daemon's environment minus the machine
+ * credential), and the supervision of its output until it closes.
+ *
+ * Split out of claude.mjs (SOLID 2026-09-26) because process lifetime — spawn,
+ * decode, error, close — changes for its own reasons. The posture it hands the
+ * adapter comes from claudePosture.mjs by the profile's name; Claude's stream
+ * is read by claudeStream.mjs; every other runtime brings its own `parse`
+ * (runtimeEvents.mjs).
+ */
+
+import { spawn } from 'node:child_process';
+import { runtimeById } from './runtimes.mjs';
+import { withoutMachineCredentials } from './machineEnv.mjs';
+import { resolveTurnProfile } from './turnProfile.mjs';
+import { claudePermFor } from './claudePosture.mjs';
+import { handleStreamLine } from './claudeStream.mjs';
+import { never, workLanesStopped } from './standDownGate.mjs';
+
+/**
+ * THE ENVIRONMENT A CLI TURN IS SPAWNED WITH — the daemon's own, plus the
+ * turn's MCP token, MINUS the machine credential (2026-09-24, the audit).
+ *
+ * A turn cannot be handed a curated environment the way `childEnv` builds one
+ * for a deploy: the CLI's own sign-in lives in this environment, and stripping
+ * it signs the CLI out. But on a headless box started as
+ * `FLOWVIANT_MACHINE_TOKEN=… npx flowviant` the MACHINE CREDENTIAL lives here
+ * too, and every turn — and every dev server and script a turn starts, which
+ * inherit it — could read it with one `env`. Nothing a CLI or its children do
+ * needs it: the daemon authenticates to the server itself, and a turn that
+ * needs the project's tools gets its own per-turn token through `mcpEnv` or
+ * the MCP config file. So those two names, and only those, are removed —
+ * by the one rule in machineEnv.mjs, which the project check obeys too.
+ */
+export function cliEnv(mcpEnv) {
+  // After the merge, so an mcpEnv can never smuggle one back in.
+  return withoutMachineCredentials({ ...process.env, ...(mcpEnv ?? {}) });
+}
+
+// One Claude Code turn. Output is captured (for sentinel detection) and streamed
+// through, line-prefixed with the worker label so a fleet stays legible.
+//
+// `streamJson` switches to `--output-format stream-json` and parses the event
+// stream: only the humanized tool activity reaches the console (a legible
+// stream of `read …`, `grep …`, `+ node …`), assistant text is folded into the
+// returned string for sentinel detection, and each activity is handed to
+// `onActivity` so the caller can forward progress. Build-agent turns leave it
+// off and keep the raw text passthrough + line sentinels.
+export function runTurn(opts) {
+  const { prompt, resume, system, cwd, mcpConfig, mcpArgs, mcpEnv, agentTools, runtime = 'claude', label, onSpawn, streamJson, answerFromResult, onActivity, onToolEvent, onInit, onUsage, onThreadId, onAnswer, vaultDir, knowledgeDir, resultSchemaArgs, model, effort, adoptResumeId, resumeThreadId, resumeConversationId } = opts;
+  /**
+   * AFTER THE TEARDOWN, NO TURN STARTS AND NO TURN ENDS (standDownGate.mjs).
+   * A stand-down that drains a deploy keeps this process alive; without this
+   * a turn the teardown killed would hand its empty output back to its lane,
+   * which would settle it as `nothing` or spawn a fresh retry nobody kills.
+   * Both answers stay pending instead, as `process.exit` left them.
+   */
+  if (workLanesStopped()) return never();
+  return new Promise((resolveTurn) => {
+    const resolve = (v) => {
+      if (!workLanesStopped()) resolveTurn(v);
+    };
+    const rt = runtimeById(runtime);
+    // AN UNKNOWN RUNTIME IS REFUSED, NEVER RUN AS CLAUDE (2026-09-26). Asked
+    // before anything is spawned. This is the belt, not the relay: the words
+    // a person sees come from the callers' own gates, asked earlier (the agent
+    // lane's `canRun` answers "this machine cannot run <id>", the session
+    // lane's `unsupported` check). Here the daemon log names the id and the
+    // turn answers nothing — never Claude wearing the other runtime's name.
+    if (!rt) {
+      console.error(`\nerror: cannot run '${runtime}' — this daemon does not know that runtime; update flowviant`);
+      resolve('');
+      return;
+    }
+    /**
+     * ONE PROFILE, NAMED BY THE CALLER (turnProfile.mjs). An unknown name or a
+     * retired posture switch fails the turn in words — never the build
+     * posture by fall-through.
+     */
+    const turnProfile = resolveTurnProfile(opts);
+    if (turnProfile.error) {
+      console.error(`\nerror: ${turnProfile.error}`);
+      resolve('');
+      return;
+    }
+    // A PROFILE SOME RUNTIMES CANNOT EXPRESS FAILS THE TURN — plan mode off
+    // Claude, a design or research posture on a runtime that does not declare
+    // it. The callers refuse first, in words (the tab lane; the agent lane's
+    // `canRun`); this is the belt no caller can skip. The other adapters build
+    // argv from the profile name and never read `perm`, so the only
+    // alternative is their build branch — for codex `--sandbox
+    // danger-full-access`: a research card's words with the whole machine to
+    // act on. Asked against the runtime's own declared profiles, so the day an
+    // adapter learns to express one this opens by itself.
+    const offRuntime = turnProfile.onlyOn?.(rt);
+    if (offRuntime) {
+      console.error(`\nerror: ${offRuntime}`);
+      resolve('');
+      return;
+    }
+    if (!rt.args) {
+      // Reached only if a brief names a runtime this daemon declares but cannot
+      // drive. Fail as a turn with no sentinel — the loop already treats that as
+      // "the protocol did not complete" and retries, rather than inventing a
+      // completion for work that never started.
+      console.error(`\nerror: cannot run '${rt.label}' — ${rt.blocked}`);
+      resolve('');
+      return;
+    }
+    // Pin the model — never inherit the user's global default (which for Claude
+    // may be a 1M/long-context tier their subscription can't bill autonomous
+    // work on). A per-task override (chosen in the app, validated server-side
+    // against a fixed list before it ever reaches this argv) wins over the
+    // machine pin; absent, the pin stands. Effort has no machine-level pin at
+    // all: unset means the CLI's own default, the honest resting state.
+    //
+    // TWO FORMS OF THE SAME DECISION, and the redundancy is deliberate rather
+    // than sloppy. `profile` is the NAME of the posture — a promise about what
+    // must be impossible during the turn — and every runtime expresses it in its
+    // own vocabulary: Claude as an `--allowedTools` verb list, Codex as a kernel
+    // sandbox mode plus feature toggles. `perm` is Claude's expression, looked
+    // up by the SAME name (`claudePermFor`), so the two cannot disagree about
+    // which posture a turn is running under. There is no precedence chain left
+    // to get wrong: the caller named one profile (turnProfile.mjs).
+    const args = rt.args({
+      prompt,
+      system,
+      model,
+      effort,
+      resume,
+      streamJson,
+      profile: turnProfile.adapterProfile,
+      agentTools,
+      // Adopting a terminal session (workSessionTurns.mjs): Claude turns it into
+      // `--resume <id> --fork-session` (a FORK — the original is untouched);
+      // agy turns it into `--conversation <id>` (a MOVE — agy has no fork, the
+      // tab continues the terminal conversation itself). Codex THROWS on it,
+      // so a mis-wired adoption fails as a loud turn error rather than a
+      // silent fresh conversation wearing an adopted session's name.
+      adoptResumeId,
+      // Only the wiki profile uses it, but it is passed unconditionally: a
+      // runtime that can path-scope its writes needs to know WHERE the vault is,
+      // and Claude — which cannot — simply ignores it.
+      vaultDir,
+      // THE PROJECT'S KNOWLEDGE LIBRARY (0.94.0), when this box holds one. It
+      // lives in the CHECKOUT and a turn usually runs in a worktree, so the
+      // prompt hands an absolute path OUTSIDE the cwd — and a curated Claude
+      // profile (the capture chat's read-only list, `FLOWVIANT_SAFE=1`) may
+      // refuse a read there. `--add-dir` says the directory is one it may read.
+      // Only Claude's adapter uses it; codex's sandboxes read the filesystem
+      // already, and agy's `--add-dir` is spent on the wiki vault.
+      knowledgeDir,
+      // Structured-output flags for the MEDIATED path. Handed to the adapter
+      // rather than appended here for the same reason `mcp` is: Codex takes its
+      // prompt as a trailing positional, so a flag after it is in the wrong
+      // place.
+      resultSchemaArgs,
+      // PLAN MODE REPLACES THE POSTURE, never joins it: beside
+      // `--dangerously-skip-permissions` the bypass wins silently (measured —
+      // see PLAN_MODE_PERM).
+      perm: claudePermFor(turnProfile.name, knowledgeDir),
+      // Handed to the adapter rather than appended here, because WHERE these go
+      // is a property of the CLI: Codex reads its prompt as a trailing
+      // positional, so a flag after it is a flag in the wrong place.
+      // Wiki-vault turns are pure file work and pass neither — no MCP at all.
+      mcp: turnProfile.strictMcp ? ['--strict-mcp-config'] : mcpConfig ? ['--mcp-config', mcpConfig] : (mcpArgs ?? []),
+      // Resuming a SPECIFIC held conversation by its own id (workSessionTurns.mjs, codex
+      // sessions). Runtimes without a by-id resume ignore it and keep their
+      // `resume` behavior unchanged.
+      resumeThreadId,
+      // agy's by-id resume (workSessionTurns.mjs, antigravity sessions): the conversation
+      // id learned from the adopt hint or the cwd registry after a turn.
+      resumeConversationId,
+    });
+    // Whatever this machine is signed in with, we use. We do NOT pick.
+    //
+    // This used to delete ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN to force
+    // the subscription path, which was right when the daemon ran on a
+    // developer's laptop: a key left in their shell would silently bill every
+    // turn as raw API usage instead of the plan they were already paying for.
+    // On a machine the project leaves running, an inherited org key is the
+    // POINT — deleting it is the daemon overriding the credential its operator
+    // deliberately configured.
+    //
+    // Which credential is correct, and whether an account may be shared, is
+    // between the operator and the vendor. Flowviant does not detect it and does
+    // not enforce it; it runs the CLI the ordinary way and relays what happens.
+    const child = spawn(rt.bin, args, {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      /**
+       * ITS OWN PROCESS GROUP, so what the agent starts stays attributable.
+       *
+       * Everything the CLI spawns inherits this pgid and KEEPS it through
+       * `nohup` and `setsid` — which is exactly when attribution by descendancy
+       * fails, because reparenting to init breaks the ppid chain the moment a
+       * process becomes long-running. `processes.mjs` reads the group; the
+       * Workbench renders it.
+       *
+       * TEARDOWN IS DELIBERATELY UNCHANGED: `shutdownWork` still SIGTERMs this
+       * CHILD and never the group. Signalling the group would kill the dev
+       * server the driver started every time the daemon restarts — including
+       * on an ordinary auto-update, unattended — which is the outcome the
+       * deleted dev-run supervisor spent a whole registry avoiding. Flowviant
+       * does not manage those processes; it reports them.
+       *
+       * Not `unref`'d: the daemon must still wait on this turn.
+       */
+      detached: true,
+      // Only ADDS to the environment (the worker token, for runtimes that read
+      // it from there). Never replaces it: the CLI's own credentials live in
+      // this environment, and handing it a curated one signs it out. The one
+      // thing it REMOVES is this daemon's machine credential — see `cliEnv`.
+      env: cliEnv(mcpEnv),
+    });
+    onSpawn?.(child);
+    let out = '';
+    const pfx = label ? `${label} ` : '';
+    const emit = (s) => process.stdout.write(pfx ? s.replace(/\n/g, `\n${pfx}`) : s);
+
+    // A runtime with its own parser is ALWAYS line-parsed — for Codex the JSONL
+    // stream is the only output there is, so treating it as raw text would print
+    // event objects at the operator and, worse, hand the sentinel matcher a
+    // string containing every word the model reasoned about.
+    const lineParsed = streamJson || Boolean(rt.parse);
+    if (lineParsed) {
+      let buf = '';
+      const appendText = (t) => {
+        out += t;
+      };
+      /** One line of the child's stdout, in whichever dialect it speaks. */
+      const onLine = (line) => {
+        if (!rt.parse)
+          return handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, appendText, answerFromResult, onInit, onUsage });
+        const ev = rt.parse(line, cwd);
+        if (!ev) return;
+        // The conversation id, when the runtime announces one (codex's
+        // thread.started). Purely additive: callers that pass no onThreadId —
+        // every dispatch path — see zero behavior change.
+        if (ev.threadId) onThreadId?.(ev.threadId);
+        // The runtime's own token count (codex's `turn.completed`) — the same
+        // `onUsage` Claude's result event feeds, so a caller charges a turn
+        // identically whichever CLI ran it.
+        if (ev.usage) onUsage?.(ev.usage);
+        // One agent MESSAGE, alone — see parseCodexLine's `answer`. Last call
+        // wins at the caller, which is what "the final answer" means.
+        if (typeof ev.answer === 'string') onAnswer?.(ev.answer);
+        if (ev.text) appendText(ev.text);
+        if (ev.activity) {
+          emit(`${ev.activity.label}\n`);
+          onActivity?.(ev.activity);
+        }
+      };
+      // DECODED AS A STREAM, never chunk by chunk (2026-09-24, the audit): a
+      // pipe read can end inside a multi-byte character — the em dash models
+      // write constantly — and `d.toString()` per chunk turned each half into
+      // U+FFFD, which JSON.parse accepts and the reply then carried verbatim.
+      // `setEncoding` holds the partial bytes over to the next chunk.
+      child.stdout.setEncoding('utf8');
+      child.stderr.setEncoding('utf8');
+      child.stdout.on('data', (d) => {
+        buf += d;
+        let nl;
+        while ((nl = buf.indexOf('\n')) >= 0) {
+          const line = buf.slice(0, nl);
+          buf = buf.slice(nl + 1);
+          if (line.trim()) onLine(line);
+        }
+      });
+      // stderr is not JSON (warnings/errors) — pass through and keep for sentinels.
+      child.stderr.on('data', (s) => {
+        out += s;
+        emit(s);
+      });
+      child.on('error', (e) => {
+        if (e.code === 'ENOENT') {
+          // A MISSING CLI FAILS THE TURN, NOT THE DAEMON. This called
+          // process.exit(1), which was defensible while `claude` was the only
+          // runtime and preflight refused to start without it — the process
+          // could not reach here. Both halves of that are gone: preflight is now
+          // fatal only when NOTHING is drivable, so a Codex-only machine starts
+          // legitimately, and the wiki/plan-check/consult turns still ask for
+          // Claude by default. On such a machine the first wiki sweep would have
+          // killed the whole daemon, taking every in-flight build with it,
+          // because one background job could not find one binary.
+          console.error(`\nerror: '${rt.bin}' CLI not found on PATH. Install ${rt.label} first: ${rt.install}`);
+          resolve('');
+          return;
+        }
+        console.error(e);
+        resolve(out);
+      });
+      child.on('close', () => {
+        if (buf.trim()) onLine(buf);
+        resolve(out);
+      });
+      return;
+    }
+
+    const onChunk = (s) => {
+      out += s;
+      emit(s);
+    };
+    // Stream-decoded for the same reason as the line-parsed path above.
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', onChunk);
+    child.stderr.on('data', onChunk);
+    child.on('error', (e) => {
+      if (e.code === 'ENOENT') {
+        // A MISSING CLI FAILS THE TURN, NOT THE DAEMON — same fix as the
+        // line-parsed path above; this raw-output duplicate used to
+        // process.exit(1) and take every in-flight worker down with it.
+        console.error(`\nerror: '${rt.bin}' CLI not found on PATH. Install ${rt.label} first: ${rt.install}`);
+        resolve('');
+        return;
+      }
+      console.error(e);
+      resolve(out);
+    });
+    child.on('close', () => resolve(out));
+  });
+}

package/bin/lib/runtimeAntigravity.mjs

@@ -0,0 +1,230 @@
+/**
+ * ANTIGRAVITY, AS A RUNTIME — its registry row, and the measured record of why
+ * it cannot be handed a per-lane MCP config.
+ *
+ * Split out of runtimes.mjs (2026-09-26, SOLID F045). Each vendor's argv moves
+ * on its own vendor's release schedule; the registry (runtimes.mjs) assembles
+ * the rows and owns the rule that reads them (`canRun`, `mediated`), and the
+ * stream-json parser this row hands out as `parse` lives with the other stream
+ * parsers in runtimeEvents.mjs.
+ */
+
+import { parseAgyLine } from './runtimeEvents.mjs';
+
+/**
+ * DECLARED, NOT DRIVABLE — and this is now MEASURED rather than argued.
+ *
+ * The reason went wrong twice before it went right, so the evidence is written
+ * down here in full. First it cited upstream antigravity-cli#60, which is about
+ * `.antigravitycli/mcp_config.json` — the project-DISCOVERY folder — while
+ * claiming it was about `.agents/`, the workspace-CUSTOMIZATION folder. Then,
+ * on reading the docs (antigravity.google/docs/mcp describes `.agents/`, and
+ * Google's own codelab creates it), this comment swung the other way and said
+ * the blocker looked wrong. Both were reasoning from paperwork.
+ *
+ * THE TEST, run against agy 1.1.12, signed in, in a real git repo:
+ * the SAME minimal stdio MCP server, declared two ways.
+ *   • workspace `<worktree>/.agents/mcp_config.json` → the server process is
+ *     NEVER SPAWNED. Not connected-and-failed: never launched. The model
+ *     answers "NO_MCP".
+ *   • global `~/.gemini/config/mcp_config.json` → spawns immediately and
+ *     handshakes: server/discover, initialize, notifications/initialized,
+ *     tools/list.
+ * stdio deliberately, to remove every confound — no bearer token to reject,
+ * no network, no TLS. The difference is the config LOCATION and nothing else.
+ *
+ * AND IT SURVIVES THE TRUST VARIABLE, which was the obvious objection: agy
+ * keeps a `trustedWorkspaces` list in settings.json, a fresh per-task worktree
+ * is not on it, and an untrusted folder demonstrably changes behaviour (the
+ * model stops treating cwd as its workspace and works out of its own scratch
+ * dir). Adding the worktree to `trustedWorkspaces` and re-running changed
+ * nothing: the server still never spawned, the model still answered NO_MCP.
+ * So the workspace config is not trust-gated, it is simply not read.
+ *
+ * So Antigravity's MCP config is machine-wide IN PRACTICE, and the original
+ * blocker's conclusion stands even though its cited reason never did: every
+ * lane on the box would share one worker token, which is exactly the blast
+ * radius the per-lane token exists to prevent. That is why this stays
+ * undrivable, and it is a property of the CLI rather than something we can
+ * work around from here.
+ *
+ * A TRAP FOR WHOEVER RE-TESTS THIS: agy exposes MCP through a single generic
+ * `call_mcp_tool` dispatcher, so per-server tools NEVER appear in the `init`
+ * event's tools array even when a server is loaded correctly. Reading that
+ * array tells you nothing. Watch the server process instead, or ask the model.
+ *
+ * FOUR MORE FACTS from the same session, each an independent obstacle:
+ *   1. AUTH IS INTERACTIVE OAUTH (bubbletea TUI; needs a real /dev/tty), with
+ *      no headless credential path. A signed-out `agy -p` prints a consent URL
+ *      and then SITS until `--print-timeout` (default 5m) before erroring — so
+ *      a lane on a signed-out agy burns five minutes per turn looking like a
+ *      hang. Preflight cannot see it: `--version` succeeds while signed out.
+ *   2. `--sandbox` IS A BOOLEAN ("terminal restrictions enabled"), not a mode
+ *      selector — but a CONSULT POSTURE IS STILL EXPRESSIBLE, and this was
+ *      recorded backwards here for a while. It does not come from `--sandbox`
+ *      at all; it comes from headless mode's default. Any tool needing a
+ *      permission that cannot be prompted for is AUTO-DENIED:
+ *        "User denied permission to run command: <cmd>"
+ *        "a tool required the 'command' permission that headless mode cannot
+ *         prompt for, so it was auto-denied."
+ *      Observed repeatedly, including for an entirely benign `pwd && ls -la`,
+ *      and a local listener confirmed no egress in any run. Reads (list_dir,
+ *      file reads) work throughout. So: NOT passing
+ *      `--dangerously-skip-permissions` IS the consult posture, and passing it
+ *      is the build posture — both per invocation, both harness-enforced
+ *      rather than model-instructed. `--mode plan` is a separate, WEAKER thing:
+ *      it steers behaviour and blocks workspace writes, but it is not what
+ *      stops command execution.
+ *      RESIDUAL RISK, and it has no fix from here: `permissions.allow` in the
+ *      machine-wide settings.json is inherited, so a user who has allowed
+ *      `command(...)` widens every consult on that box. Codex has
+ *      `--ignore-user-config` for exactly this; agy has no equivalent.
+ *   3. No `mcp` subcommand; `/mcp` is interactive-only.
+ *   4. It attempts to INSTALL PLAYWRIGHT at startup (observed failing 404
+ *      against playwright.azureedge.net). A daemon runtime that downloads and
+ *      runs a browser driver is worth knowing before it goes on a machine the
+ *      project leaves running.
+ *
+ * There is no npm package. `antigravity-cli` (0.0.1, "placeholder") and `agy`
+ * (0.0.0, empty) on npm are SQUATS by unrelated accounts; the real channel is
+ * the install script at antigravity.google, which is why `install` below says
+ * to see the docs rather than naming an npm command.
+ *
+ * WHAT WOULD UNBLOCK IT: a per-invocation MCP flag or env var, or workspace
+ * configs actually being honoured. Re-test with the two-location stdio probe
+ * above — it is five minutes and it answers the question outright. Pin any
+ * wiring to >= 1.1.10 (`--model`/`--effort` were ignored in headless before it;
+ * `--output-format` arrived in 1.1.8).
+ */
+export const ANTIGRAVITY_RUNTIME = {
+  id: 'antigravity',
+  label: 'Antigravity',
+  vendor: 'Google',
+  bin: 'agy',
+  install: 'see antigravity.google/docs/cli',
+  login: 'agy',
+  live: false,
+  /** None, because it cannot reach the MCP server at all — see `blocked`. */
+  /**
+   * WIKI AND CONSULT, BUT NOT BUILD — and the split is the whole point of
+   * making drivability per-profile rather than one verdict.
+   *
+   * Only a BUILD needs the MCP control plane: claiming, reporting a blocker,
+   * attaching a PR, completing. A wiki turn writes markdown files that the
+   * daemon syncs afterwards, and a consult answers a question in prose; BOTH
+   * already run with no MCP at all on every runtime, Claude included. Gating
+   * them on an MCP capability they never use was a test of the wrong thing,
+   * and it is what kept Antigravity at zero for months.
+   *
+   * Build returns here when the mediated adapter lands (the daemon holds the
+   * MCP connection and the CLI just returns schema-enforced JSON via
+   * `--json-schema`), which needs no per-invocation MCP config from the vendor
+   * at all.
+   *
+   * PLAN IS ABSENT ON PURPOSE, and NOT because a planning turn is beyond it —
+   * it reads code as well as anything here. A plan session is a conversation
+   * that makes many control-plane calls as it goes (spawn a slice, re-shape
+   * it, drop it, rewrite the spec), and mediation turns a turn into ONE
+   * schema-enforced form the daemon then applies. That shape fits a build,
+   * whose outcome is a single structured result; it does not yet fit an
+   * argument. Note that `canRun` would otherwise say yes via `mediated()` and
+   * hand this runtime a job it cannot finish — declaring the profile is the
+   * only thing standing between here and that. Mediated planning is a real
+   * design (the session returns its writes as a batch), just not a built one.
+   */
+  profiles: ['build', 'wiki', 'consult'],
+  /** No measured ladder, and ignorance never refuses: the full list, as the
+   *  server's `RUNTIME_EFFORTS.antigravity` keeps it. */
+  efforts: ['low', 'medium', 'high', 'xhigh', 'max'],
+  mcp: null,
+  args({ prompt, system, model, effort, resume, resumeConversationId, profile = 'build', vaultDir, resultSchemaArgs = [], adoptResumeId }) {
+    const a = [];
+    // WHICH CONVERSATION IS THIS — one decision, answered one way (the same
+    // rule as Claude's --resume/--continue). By id when the caller knows:
+    // `--conversation <id>` resumes globally, any cwd (measured on 1.1.12).
+    // Adoption is the SAME argv because agy has no fork — the id in the db
+    // is the identity (a renamed copy fails "trajectory not found",
+    // measured), so adopting MOVES the conversation: the tab continues the
+    // terminal session itself, appending to its one store. `--continue` is
+    // the cwd-keyed fallback for a session whose id was never learned.
+    if (adoptResumeId || resumeConversationId) a.push('--conversation', adoptResumeId || resumeConversationId);
+    else if (resume) a.push('--continue');
+    // No system-prompt flag, same weakening as Codex: the contract rides in
+    // the prompt, fenced and first.
+    a.push('-p', `${system}\n\n---\n\n${prompt}`);
+    a.push('--output-format', 'stream-json');
+    if (model) a.push('--model', model);
+    if (effort) a.push('--effort', effort);
+    a.push(...resultSchemaArgs);
+
+    if (profile === 'wiki') {
+      // THE CARTOGRAPHER, at the same bar WIKI_PERM sets for Claude — writes
+      // allowed, network shut. Both halves measured on 1.1.12:
+      //   • headless cannot prompt, so anything needing approval is
+      //     auto-denied — including the file writes a wiki turn exists to
+      //     make. `--dangerously-skip-permissions` is what grants them.
+      //   • `--sandbox` blocks egress: with it, curl returned 400 and a local
+      //     listener saw nothing; without it, 200 and the request arrived.
+      // Upstream #36 warns these two cancel out (skip-permissions
+      // auto-approving the sandbox-bypass prompt). It does NOT reproduce on
+      // 1.1.12 — tested together, the write landed and the network stayed
+      // shut. Re-check on upgrade: if it ever does cancel, this posture
+      // silently becomes "wiki turn with internet", which is the one line
+      // WIKI_PERM draws ("Command execution is the line: it enables network
+      // exfil").
+      if (vaultDir) a.push('--add-dir', vaultDir);
+      a.push('--sandbox', '--dangerously-skip-permissions');
+      // A sweep reads a whole repository; the 5m default would guillotine it.
+      a.push('--print-timeout', '60m');
+    } else if (profile === 'build') {
+      // A BUILD WRITES, and headless auto-denies anything needing approval —
+      // so without this every edit comes back "User denied permission" and the
+      // turn reports failure having touched nothing. Caught only because an
+      // end-to-end test had to add the flag by hand to work.
+      //
+      // NOT `--sandbox` here, unlike wiki: a build has to `git push`, so it
+      // needs the network by definition.
+      //
+      // AND NOTHING ELSE CONTAINS IT EITHER. This comment used to end "the
+      // containment is the worktree, as it is for every runtime", which was
+      // false and is the kind of false that stops people looking: `cwd` is a
+      // starting directory, not a jail. A build turn runs with the operator's
+      // full user permissions — it can write outside the worktree, to their
+      // home directory, to their other checkouts. Claude gets
+      // --dangerously-skip-permissions, codex gets --sandbox
+      // danger-full-access, and agy gets no sandbox flag at all. The only
+      // real boundary today is that the person driving the tab is trusted.
+      //
+      // FLOWVIANT_SAFE HAS NO EXPRESSION ON THIS RUNTIME. Claude narrows to an
+      // allowlist and Codex to `workspace-write`; agy's only per-invocation
+      // control is this boolean, and its allow/deny engine is machine-wide.
+      // So a SAFE-mode operator gets an agy build that is not actually
+      // narrowed — which is why `mediatedSafeGap` is surfaced rather than
+      // quietly ignored.
+      a.push('--dangerously-skip-permissions');
+      a.push('--print-timeout', '60m');
+    } else if (profile === 'consult') {
+      // NOTHING GRANTED, deliberately. The headless default IS the consult
+      // posture: `run_command` comes back "User denied permission… headless
+      // mode cannot prompt for it, so it was auto-denied", observed even for a
+      // benign `pwd && ls -la`, with no egress in any run. Reads keep working,
+      // which is all a consult needs. Passing --dangerously-skip-permissions
+      // here would hand a question ANY project editor can type a shell.
+      a.push('--print-timeout', '10m');
+    }
+    return a;
+  },
+  parse: parseAgyLine,
+  /**
+   * `--json-schema` enforces the shape of the final result — verified against
+   * 1.1.12, which returned exactly the object asked for. This is what makes a
+   * BUILD possible on a runtime that cannot be handed an MCP config: the CLI
+   * stops needing to CALL anything and just returns a filled-in form, and the
+   * daemon makes the control-plane calls on its behalf with the lane's own
+   * per-lane token. Strictly better than parsing markers out of prose, which a
+   * model can wrap in a code fence, truncate or hallucinate.
+   */
+  resultSchema: (path) => ['--json-schema', path],
+  blocked:
+    'its MCP config is machine-wide — a workspace .agents/mcp_config.json is never loaded (measured), so every lane would share one token',
+};