@aiwg/cli 2026.10.0 → 2026.10.3

package/bin/aiwg.mjs

@@ -244,10 +244,81 @@ if (process.argv.slice(2).includes('--dry-run')) {
   process.env['AIWG_CLI_DRY_RUN'] = '1';
 }
 
+// Startup tracing — set AIWG_TRACE_STARTUP=1 to print per-phase timings to
+// stderr. Useful for diagnosing cold-start regressions, and for a test to
+// observe whether the credential-handling skip below actually fired,
+// without needing the update notifier to otherwise be eligible to run (it
+// also needs a real terminal — see `isCredentialHandlingCommand()`'s own
+// tests). No-op by default so it doesn't cost anything on the hot path.
+// Defined ahead of its first use below (moved up from just before
+// `resolveRouterPath()`, where it used to sit) so the notifier gate can use
+// it too.
+const traceStartup = process.env['AIWG_TRACE_STARTUP'] === '1' ||
+  process.env['AIWG_TRACE_STARTUP']?.toLowerCase() === 'true';
+const startHr = process.hrtime.bigint();
+function trace(phase) {
+  if (!traceStartup) return;
+  const ms = Number(process.hrtime.bigint() - startHr) / 1_000_000;
+  process.stderr.write(`[trace] +${ms.toFixed(1)}ms ${phase}\n`);
+}
+trace('bin:entry');
+
+/**
+ * True iff this invocation is a command that reads a secret directly from
+ * the environment or from an argument as part of its own documented
+ * contract (go/no-go review, blocker 1A). Checked from argv alone — no
+ * dist/ import, no router resolution — so it costs nothing on the
+ * `--version`/`--help` fast paths and can run before any bootstrap
+ * subprocess starts.
+ *
+ * No bootstrap subprocess may start before dispatch for one of these,
+ * because a bootstrap child that copies the parent's environment (or is
+ * merely spawned while `NODE_DEBUG=child_process` is set) would otherwise
+ * see whatever the command's own secret-bearing variable holds, before the
+ * command itself ever ran. Scrubbing a specific variable out of every
+ * possible bootstrap child is not attempted here — not starting the
+ * bootstrap at all for these commands is the smaller, certain fix. (The
+ * background update-check child also gets its own environment allow-list,
+ * independent of this list — see `notifierChildEnv()` in
+ * `src/update/notifier.mjs` — so a secret in the parent's environment that
+ * this list does not yet name is still not copied into that one child.)
+ *
+ * Qualifying commands, and why:
+ *   - `mcp profile login` — reads an API key via `--api-key-env`,
+ *     `--api-key-stdin`, or `--api-key-file`.
+ *   - `decision setup jev` — without `--token-stdin`, reads the token
+ *     directly from `JEV_API_KEY`/`AIWG_DECISION_JEV_API_KEY`.
+ *
+ * Checked and left out, with reasons (see the go/no-go review response):
+ *   - `auth login` — an OAuth device/browser flow; it does not read a
+ *     pre-existing secret from the environment or argv at invocation, it
+ *     obtains one over the network after the user authorizes it.
+ *   - `mcp inject` / `mcp add` / `mcp update` (including `--header-env`) —
+ *     `headerEnv`/`envFrom` references only ever carry a variable *name*
+ *     into a provider's config (resolved by that provider later, not by
+ *     this process); a literal `--env NAME=value` on `mcp add` is stored
+ *     to the registry file and never touches `process.env` here.
+ */
+function isCredentialHandlingCommand(args) {
+  const positionals = [];
+  for (const arg of args) {
+    if (arg === '--') break;
+    if (!arg.startsWith('-')) {
+      positionals.push(arg);
+      if (positionals.length >= 3) break;
+    }
+  }
+  if (positionals[0] === 'mcp' && positionals[1] === 'profile' && positionals[2] === 'login') return true;
+  if (positionals[0] === 'decision' && positionals[1] === 'setup' && positionals[2] === 'jev') return true;
+  return false;
+}
+
 // Display a cached notice and schedule its refresh before every eligible CLI
 // path, including fast help/version, channel recovery, and later preflight
-// failures. This local-only bootstrap never waits on the registry and failures
-// are deliberately ignored so update advice cannot change command behavior.
+// failures — except a credential-handling command (above), which never gets
+// this or any other bootstrap subprocess before dispatch. This local-only
+// bootstrap never waits on the registry and failures are deliberately
+// ignored so update advice cannot change command behavior.
 async function runUpdateNotifierBootstrap() {
   try {
     const notifierPath = path.join(packageRoot, 'dist', 'src', 'update', 'notifier.mjs');
@@ -260,12 +331,18 @@ async function runUpdateNotifierBootstrap() {
   }
 }
 
-await runUpdateNotifierBootstrap();
+const cliArgs = process.argv.slice(2);
+if (isCredentialHandlingCommand(cliArgs)) {
+  trace('notifier:skip (credential-handling command)');
+} else {
+  await runUpdateNotifierBootstrap();
+  trace('notifier:bootstrap-complete');
+}
 
-if (maybeHandleFastVersion(process.argv.slice(2))) {
+if (maybeHandleFastVersion(cliArgs)) {
   process.exit(0);
 }
-if (maybeHandleFastHelp(process.argv.slice(2))) {
+if (maybeHandleFastHelp(cliArgs)) {
   process.exit(0);
 }
 
@@ -286,19 +363,6 @@ function ensureInvocationId() {
 }
 const invocationId = ensureInvocationId();
 
-// Startup tracing — set AIWG_TRACE_STARTUP=1 to print per-phase timings to
-// stderr. Useful for diagnosing cold-start regressions. No-op by default so
-// it doesn't cost anything on the hot path.
-const traceStartup = process.env['AIWG_TRACE_STARTUP'] === '1' ||
-  process.env['AIWG_TRACE_STARTUP']?.toLowerCase() === 'true';
-const startHr = process.hrtime.bigint();
-function trace(phase) {
-  if (!traceStartup) return;
-  const ms = Number(process.hrtime.bigint() - startHr) / 1_000_000;
-  process.stderr.write(`[trace] +${ms.toFixed(1)}ms ${phase}\n`);
-}
-trace('bin:entry');
-
 /**
  * Resolve the path to the compiled router.
  *
@@ -309,10 +373,11 @@ trace('bin:entry');
  * emit a clear error and exit rather than falling back to a tsx fork.
  */
 async function resolveRouterPath() {
-  const { loadConfig } = await import('../dist/src/channel/manager.mjs');
+  const { loadConfig, resolveEffectiveInstallationRoot } = await import('../dist/src/channel/manager.mjs');
   const config = await loadConfig({ createIfMissing: !process.argv.slice(2).includes('--dry-run') });
-  if (config.devMode && config.edgePath && config.edgePath !== packageRoot) {
-    const devRouter = path.join(config.edgePath, 'dist', 'src', 'cli', 'router.js');
+  const effectiveRoot = resolveEffectiveInstallationRoot(packageRoot, config);
+  if (effectiveRoot !== packageRoot) {
+    const devRouter = path.join(effectiveRoot, 'dist', 'src', 'cli', 'router.js');
     if (!existsSync(devRouter)) {
       console.error(`Dev mode: compiled router not found at ${devRouter}`);
       console.error(`  Run: (cd ${config.edgePath} && npm run build)`);

package/dist/src/a2a/codecs.js

@@ -1,3 +1,4 @@
+import { assertMissionWorkerHandoff } from '../mission-protocol/codecs.js';
 export function encodePushNotificationConfig(version, config) {
     assertNonEmptyString(version, '$.url', config.url);
     if (version === '0.3') {
@@ -81,6 +82,7 @@ const V1_TO_STATE = {
 };
 const STATE_TO_V1 = Object.fromEntries(Object.entries(V1_TO_STATE).map(([wire, normalized]) => [normalized, wire]));
 export function encodeMessage(version, message) {
+    assertMissionWorkerHandoff(message, 'a2a');
     assertNonEmptyString(version, '$.messageId', message.messageId);
     if (message.role !== 'user' && message.role !== 'agent') {
         fail(version, '$.role', 'must be user or agent');
@@ -101,6 +103,7 @@ export function encodeMessage(version, message) {
     return out;
 }
 export function decodeMessage(version, input, path = '$') {
+    assertMissionWorkerHandoff(input, 'a2a');
     const obj = objectAt(version, path, input);
     const messageId = stringAt(version, `${path}.messageId`, obj.messageId);
     const role = decodeRole(version, obj.role, `${path}.role`);
@@ -120,6 +123,7 @@ export function decodeMessage(version, input, path = '$') {
     return message;
 }
 export function encodeTask(version, task) {
+    assertMissionWorkerHandoff(task, 'a2a');
     assertNonEmptyString(version, '$.id', task.id);
     const out = {
         id: task.id,
@@ -137,6 +141,7 @@ export function encodeTask(version, task) {
     return out;
 }
 export function decodeTask(version, input, path = '$') {
+    assertMissionWorkerHandoff(input, 'a2a');
     const obj = objectAt(version, path, input);
     if (version === '1.0' && typeof obj.kind === 'string') {
         fail(version, `${path}.kind`, 'legacy kind discriminator is not valid in 1.0');
@@ -219,6 +224,7 @@ export function decodeStatus(version, input, path = '$') {
     return status;
 }
 export function encodeArtifact(version, artifact, path = '$') {
+    assertMissionWorkerHandoff(artifact, 'a2a');
     assertNonEmptyString(version, `${path}.artifactId`, artifact.artifactId);
     if (!Array.isArray(artifact.parts) || artifact.parts.length === 0) {
         fail(version, `${path}.parts`, 'must contain at least one part');
@@ -234,6 +240,7 @@ export function encodeArtifact(version, artifact, path = '$') {
     return out;
 }
 export function decodeArtifact(version, input, path = '$') {
+    assertMissionWorkerHandoff(input, 'a2a');
     const obj = objectAt(version, path, input);
     const partsRaw = arrayAt(version, `${path}.parts`, obj.parts);
     if (partsRaw.length === 0)
@@ -260,6 +267,7 @@ function encodeMessageAt(version, message, path) {
     }
 }
 function encodePart(version, part, path) {
+    assertMissionWorkerHandoff(part, 'a2a');
     const common = {};
     copyJsonObject(version, common, 'metadata', part.metadata, `${path}.metadata`);
     copyOptional(common, version === '0.3' ? 'mimeType' : 'mediaType', part.mediaType);
@@ -288,6 +296,7 @@ function encodePart(version, part, path) {
     };
 }
 function decodePart(version, input, path) {
+    assertMissionWorkerHandoff(input, 'a2a');
     const obj = objectAt(version, path, input);
     if (version === '0.3')
         return decodeLegacyPart(obj, path);

package/dist/src/artifacts/corpus-tools/vision-extract.js

@@ -21,6 +21,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { spawnSync } from 'child_process';
+import { boundedSpawnSync, positiveTimeoutMs } from '../../process/bounded-child-process.mjs';
 /** Strict-transcription prompt. `title` parameterizes the corpus-specific intro. */
 export function buildPrompt(page, title) {
     const subject = title ? `from ${title}` : 'from a scanned document';
@@ -53,7 +54,11 @@ const codexAdapter = {
         try {
             const r = spawnSync(process.env.AIWG_CODEX_BIN || 'codex', args, {
                 input: prompt,
-                timeout: ctx.timeoutSec * 1000,
+                // ctx.timeoutSec is caller-controlled (a CLI flag); clamp it so a
+                // configured 0 (or anything else non-positive) can't disable the
+                // bound entirely (#3062 B/C finding 8). 240s matches this
+                // function's own documented default (see extractPages() below).
+                timeout: positiveTimeoutMs(ctx.timeoutSec * 1000, 240_000),
                 encoding: 'utf8',
             });
             if (r.status === 0 && fs.existsSync(tmp)) {
@@ -70,15 +75,93 @@ const codexAdapter = {
         }
     },
 };
+/** Paths enter the shell as positional arguments, never as shell source. */
+const MAX_VISION_TEMPLATE_LENGTH = 4096;
+function visionCommand(template) {
+    const guidance = 'Use "$1"/"$2"/"$3" as data operands or move complex logic to a wrapper script';
+    const reject = (construct) => {
+        throw new Error(`Vision command rejects ${construct}. ${guidance}`);
+    };
+    // Bound the checks below; a vision command template is a short command line.
+    if (template.length > MAX_VISION_TEMPLATE_LENGTH)
+        reject(`templates longer than ${MAX_VISION_TEMPLATE_LENGTH} characters`);
+    // A vision template is one command line; a backslash-newline continuation can
+    // join an allowed name with following text into a different variable at runtime.
+    if (/\\\r?\n|\\\r/.test(template))
+        reject('line continuations (backslash-newline)');
+    // Recognize literal command names even when quoted or backslash-escaped.
+    const syntax = template.replace(/\\([^\n])/g, '$1').replace(/["']/g, '');
+    if (syntax.includes('$('))
+        reject('command substitution ($(...))');
+    if (template.includes('`'))
+        reject('backticks');
+    if (/\beval\b/.test(syntax))
+        reject('eval');
+    if (syntax.includes('<<'))
+        reject('here-documents and here-strings (<<)');
+    // Conservatively reject a shell word together with any short -c option
+    // cluster, regardless of order, wrappers, redirections or command boundaries.
+    const words = syntax.split(/[\s;&|(){}<>]+/);
+    const shellWords = words.map(word => word.slice(word.lastIndexOf('/') + 1)
+        .match(/^(?:sh|bash|zsh|dash|ksh|ash|mksh|yash|fish|csh|tcsh|rbash|busybox|toybox)(?:$|(-[A-Za-z]*c))/));
+    const hasShell = shellWords.some(Boolean);
+    if (shellWords.some(word => word?.[1]) || (hasShell && words.some(word => /^-[A-Za-z]*c/.test(word))))
+        reject('nested shell invocation (-c)');
+    // Only contract-provided parameters may expand; match at each dollar without
+    // rescanning the remaining template. Braces must contain only the exact name.
+    const parameter = /\$(?:[123](?![0-9])|AIWG_VISION_(?:IMAGE|PROMPT_FILE|OUT)(?![A-Za-z0-9_])|\{(?:[123]|AIWG_VISION_(?:IMAGE|PROMPT_FILE|OUT))\})/y;
+    // Track quotes to reject quoted/escaped placeholders, expansions and comments.
+    let quote = '';
+    return template.replace(/\\?\{(image|prompt_file|out)\}|\\[\s\S]|\$'|[$"'#]/g, (token, name, offset) => {
+        if ((token === '#' || token === '\\#') && quote !== "'")
+            reject('comments (# outside single quotes)');
+        if (name) {
+            if (quote)
+                throw new Error(`Vision command placeholders must be outside shell quotes. ${guidance}`);
+            if (token.startsWith('\\'))
+                throw new Error(`Vision command placeholders must not be escaped. ${guidance}`);
+            return `"$${name === 'image' ? 1 : name === 'prompt_file' ? 2 : 3}"`;
+        }
+        if (token === '#')
+            return token;
+        // Backslashes are literal inside POSIX single quotes, but escape the next
+        // character in double quotes and ANSI-C ($'...') quotes.
+        if (token.startsWith('\\')) {
+            if (quote === "'" && token[1] === "'")
+                quote = '';
+            return token;
+        }
+        if (token.startsWith('$')) {
+            if (quote !== "'") {
+                parameter.lastIndex = offset;
+                if (!parameter.test(template))
+                    reject('parameter expansions other than the provided vision variables');
+            }
+            if (token === '$')
+                return token;
+        }
+        if (!quote)
+            quote = token;
+        else if (quote === token || (quote === "$'" && token === "'") || (quote === "'" && token === "$'"))
+            quote = '';
+        return token;
+    });
+}
 /**
  * Generic command-template adapter (provider-neutral). Runs
  * `AIWG_VISION_COMMAND` (or the `--command` flag) with placeholders:
- *   {image}        absolute image path
- *   {prompt_file}  path to a file containing the prompt
- *   {out}          path the command must write the transcription to
- * e.g.  claude -p "$(cat {prompt_file})" --image {image} > {out}
+ *   {image}        "$1": absolute image path
+ *   {prompt_file}  "$2": path to a file containing the prompt
+ *   {out}          "$3": path the command must write the transcription to
+ * Placeholders must be unquoted and unescaped. AIWG_VISION_IMAGE /
+ * AIWG_VISION_PROMPT_FILE / AIWG_VISION_OUT are also exported.
+ * Only $1/$2/$3 and the exported vision variables (also braced) may expand.
+ * Other $ expansions, command substitution, backticks, eval, nested shells with -c, <<, and #
+ * outside single quotes are rejected; use a wrapper script for complex logic.
+ * e.g.  vision-cli --prompt-file {prompt_file} --image {image} > {out}
  */
 function commandAdapter(template) {
+    const cmd = visionCommand(template);
     return {
         name: 'command',
         transcribe(imagePath, prompt, ctx) {
@@ -86,12 +169,12 @@ function commandAdapter(template) {
             const promptFile = path.join(dir, `.vision-prompt-${ctx.page}.txt`);
             const out = path.join(dir, `.vision-out-${ctx.page}.txt`);
             fs.writeFileSync(promptFile, prompt);
-            const cmd = template
-                .replaceAll('{image}', JSON.stringify(imagePath))
-                .replaceAll('{prompt_file}', JSON.stringify(promptFile))
-                .replaceAll('{out}', JSON.stringify(out));
             try {
-                const r = spawnSync('sh', ['-c', cmd], { timeout: ctx.timeoutSec * 1000, encoding: 'utf8' });
+                // Same caller-controlled-timeout clamp as the codex adapter above.
+                const r = spawnSync('sh', ['-c', cmd, 'aiwg-vision', imagePath, promptFile, out], {
+                    timeout: positiveTimeoutMs(ctx.timeoutSec * 1000, 240_000), encoding: 'utf8',
+                    env: { ...process.env, AIWG_VISION_IMAGE: imagePath, AIWG_VISION_PROMPT_FILE: promptFile, AIWG_VISION_OUT: out },
+                });
                 let text;
                 if (fs.existsSync(out))
                     text = fs.readFileSync(out, 'utf8');
@@ -115,7 +198,7 @@ export function resolveAdapter(opts = {}) {
     const provider = opts.provider ?? process.env.AIWG_VISION_PROVIDER ?? (command ? 'command' : 'codex');
     if (provider === 'command') {
         if (!command)
-            throw new Error("vision provider 'command' requires --command or AIWG_VISION_COMMAND (template with {image}/{prompt_file}/{out})");
+            throw new Error("vision provider 'command' requires --command or AIWG_VISION_COMMAND (template with unquoted, unescaped {image}/{prompt_file}/{out} placeholders)");
         return commandAdapter(command);
     }
     if (provider === 'codex')
@@ -125,7 +208,8 @@ export function resolveAdapter(opts = {}) {
 // ── PDF → PNG rasterization (poppler pdftoppm) ───────────────────────────────
 export function pdftoppmAvailable() {
     try {
-        return spawnSync('pdftoppm', ['-v'], { encoding: 'utf8' }).status === 0 || spawnSync('pdftoppm', ['-h'], { encoding: 'utf8' }).status !== null;
+        return boundedSpawnSync('pdftoppm', ['-v'], 'quick', { encoding: 'utf8' }).status === 0
+            || boundedSpawnSync('pdftoppm', ['-h'], 'quick', { encoding: 'utf8' }).status !== null;
     }
     catch {
         return false;
@@ -144,9 +228,15 @@ export function rasterizePdf(pdfPath, outDir, dpi = 200) {
     fs.mkdirSync(outDir, { recursive: true });
     // pdftoppm writes <prefix>-<n>.png with its own zero-padding based on page count.
     const prefix = path.join(outDir, 'page');
-    const r = spawnSync('pdftoppm', ['-png', '-r', String(dpi), pdfPath, prefix], { encoding: 'utf8' });
-    if (r.status !== 0)
-        throw new Error(`pdftoppm failed: ${r.stderr || r.status}`);
+    // Rasterizing a multi-page PDF can take a while; long tier (#3062).
+    const r = boundedSpawnSync('pdftoppm', ['-png', '-r', String(dpi), pdfPath, prefix], 'long', { encoding: 'utf8' });
+    if (r.status !== 0) {
+        // #3062 finding 14: r.error.message (when present) carries the
+        // enriched timeout explanation (tier/bound/override) that stderr/
+        // status alone do not — put it first, captured stderr after.
+        const detail = r.error ? r.error.message : `pdftoppm failed: ${r.stderr || r.status}`;
+        throw new Error(r.error && r.stderr ? `${detail} (stderr: ${r.stderr})` : detail);
+    }
     // Normalize names to page-NNN.png (3-digit zero-pad).
     let count = 0;
     for (const f of fs.readdirSync(outDir)) {

package/dist/src/artifacts/repair.js

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto';
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { PROJECT_CONTROL_PLANE_FILES, auditProjectArtifactHealth, } from '../config/project-artifacts.js';
+import { PROJECT_CONTROL_PLANE_FILES, auditProjectArtifactHealth, isProjectArtifactRootExternal, } from '../config/project-artifacts.js';
 async function optionalBytes(filePath) {
     try {
         return await readFile(filePath);
@@ -21,14 +21,19 @@ async function writeAndVerify(destination, bytes) {
 }
 export async function repairProjectArtifacts(options) {
     const projectDir = path.resolve(options.projectDir);
+    // Refuse local mode before auditing — the audit's own payload scan is a
+    // no-op in local mode now (#274), but the refusal should not depend on
+    // running the audit first either (repair.ts:45-51 previously audited
+    // before this check existed, so the refusal reason always paid for the
+    // scan it was about to reject).
+    if (!isProjectArtifactRootExternal(projectDir)) {
+        throw new Error('No external AIWG artifact corpus is configured for this project.');
+    }
     const before = auditProjectArtifactHealth(projectDir);
     const copied = [];
     const migrated = [];
     const archivedConflicts = [];
     const removed = [];
-    if (!before.external_configured) {
-        throw new Error('No external AIWG artifact corpus is configured for this project.');
-    }
     if (!before.external_reachable) {
         throw new Error(`External AIWG artifact corpus is unavailable: ${before.artifact_root}`);
     }

package/dist/src/channel/manager.mjs

@@ -13,9 +13,10 @@ import fs from 'fs/promises';
 import { readFileSync, existsSync } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { execFileSync, execSync, spawn } from 'child_process';
+import { spawn } from 'child_process';
 import os from 'os';
 import { resolveUserConfigDir } from '../config/user-config-dir.mjs';
+import { boundedExecFileSync } from '../process/bounded-child-process.mjs';
 import {
   assertCanonicalInstallation,
   createInstallationIdentity,
@@ -135,6 +136,50 @@ export function getPackageRoot() {
   return path.resolve(__dirname, '..', '..');
 }
 
+/**
+ * Resolve the installation root bin/aiwg.mjs actually dispatches to.
+ *
+ * This is the exact decision `resolveRouterPath()` in bin/aiwg.mjs makes
+ * when picking which `dist/` to load the compiled router (and therefore
+ * every compiled-dist module it imports, including the MCP server) from:
+ * the dev-mode edge checkout when configured and present and distinct from
+ * the package root, otherwise the package root itself. Shared so health
+ * checks (doctor) validate the layout the launcher will actually execute
+ * instead of re-deriving — and risking drifting from — the same decision
+ * (#276).
+ *
+ * @param {string} packageRoot - This install's own package root (`getPackageRoot()`).
+ * @param {{devMode?: boolean, edgePath?: string}} config - Channel config (`loadConfig()`).
+ * @returns {string} The effective root whose `dist/src/...` the launcher loads from.
+ */
+export function resolveEffectiveInstallationRoot(packageRoot, config) {
+  if (config?.devMode && config.edgePath && config.edgePath !== packageRoot) {
+    return config.edgePath;
+  }
+  return packageRoot;
+}
+
+/**
+ * Resolve the absolute path to the MCP server entrypoint the production
+ * launcher actually loads: `bin/aiwg.mjs` always dispatches to the
+ * *compiled* router (`resolveRouterPath()`, never an uncompiled `src/`
+ * tree), whose MCP handler imports `../../mcp/cli.mjs` relative to its own
+ * compiled location, which in turn imports `./server.mjs` relative to
+ * itself — i.e. always `<effective root>/dist/src/mcp/server.mjs`, in every
+ * layout (npm install, source checkout, dev-mode edge checkout). There is
+ * no runtime path that falls back to `src/mcp/server.mjs` directly, so a
+ * health check that also accepts that source path can report OK for a
+ * layout where `aiwg mcp serve` will actually fail (#276).
+ *
+ * @param {string} packageRoot - This install's own package root (`getPackageRoot()`).
+ * @param {{devMode?: boolean, edgePath?: string}} config - Channel config (`loadConfig()`).
+ * @returns {string} Absolute path to the compiled MCP server entrypoint.
+ */
+export function resolveMcpServerEntrypointPath(packageRoot, config) {
+  const root = resolveEffectiveInstallationRoot(packageRoot, config);
+  return path.join(root, 'dist', 'src', 'mcp', 'server.mjs');
+}
+
 /**
  * Load channel configuration
  * @returns {Promise<object>} Channel configuration
@@ -237,6 +282,9 @@ export async function getFrameworkRoot(options = {}) {
  */
 export async function switchToEdge() {
   const config = await loadConfig();
+  if (typeof config.edgePath !== 'string' || !path.isAbsolute(config.edgePath)) {
+    throw new Error('Edge installation path must be absolute');
+  }
 
   console.log('Switching to edge channel (bleeding edge from main branch)...');
   console.log('');
@@ -256,8 +304,8 @@ export async function switchToEdge() {
         const sparseConfig = path.join(config.edgePath, '.git', 'info', 'sparse-checkout');
         const hasSparse = await fs.access(sparseConfig).then(() => true).catch(() => false);
         if (!hasSparse) {
-          execSync('git sparse-checkout init --cone', { cwd: config.edgePath, stdio: 'pipe' });
-          execSync('git sparse-checkout set --no-cone "/*" "!/.aiwg"', { cwd: config.edgePath, stdio: 'pipe' });
+          boundedExecFileSync('git', ['sparse-checkout', 'init', '--cone'], 'quick', { cwd: config.edgePath, stdio: 'pipe' });
+          boundedExecFileSync('git', ['sparse-checkout', 'set', '--no-cone', '/*', '!/.aiwg'], 'quick', { cwd: config.edgePath, stdio: 'pipe' });
         }
       } catch {
         // Sparse checkout is optional — older git may not support it
@@ -275,11 +323,12 @@ export async function switchToEdge() {
     console.log(`Cloning repository to ${config.edgePath}...`);
     await fs.mkdir(path.dirname(config.edgePath), { recursive: true });
     try {
-      execSync(`git clone --branch main ${REPO_URL} "${config.edgePath}"`, { stdio: 'inherit' });
+      // Cloning the full repository; long tier (#3062).
+      boundedExecFileSync('git', ['clone', '--branch', 'main', '--', REPO_URL, config.edgePath], 'long', { stdio: 'inherit' });
       // Exclude dogfooding artifacts from edge clones — users want framework source only
       try {
-        execSync('git sparse-checkout init --cone', { cwd: config.edgePath, stdio: 'pipe' });
-        execSync('git sparse-checkout set --no-cone "/*" "!/.aiwg"', { cwd: config.edgePath, stdio: 'pipe' });
+        boundedExecFileSync('git', ['sparse-checkout', 'init', '--cone'], 'quick', { cwd: config.edgePath, stdio: 'pipe' });
+        boundedExecFileSync('git', ['sparse-checkout', 'set', '--no-cone', '/*', '!/.aiwg'], 'quick', { cwd: config.edgePath, stdio: 'pipe' });
       } catch {
         // Sparse checkout is optional — older git versions may not support it
         console.log('Note: sparse checkout not available, .aiwg/ will be present in edge install.');
@@ -375,7 +424,7 @@ export async function switchToNext() {
   console.log('');
 
   try {
-    execFileSync(status.identity.managerExecutable, ['install', '--global', 'aiwg@next'], { stdio: 'inherit' });
+    boundedExecFileSync(status.identity.managerExecutable, ['install', '--global', 'aiwg@next'], 'long', { stdio: 'inherit' });
   } catch (error) {
     console.error('Failed to install aiwg@next:', error.message);
     console.error('Check that npm is available and you have write access to the global prefix.');
@@ -409,7 +458,7 @@ export async function switchToNightly() {
   console.log('');
 
   try {
-    execFileSync(status.identity.managerExecutable, ['install', '--global', 'aiwg@nightly'], { stdio: 'inherit' });
+    boundedExecFileSync(status.identity.managerExecutable, ['install', '--global', 'aiwg@nightly'], 'long', { stdio: 'inherit' });
   } catch (error) {
     console.error('Failed to install aiwg@nightly:', error.message);
     console.error('Check that npm is available and you have write access to the global prefix.');
@@ -526,11 +575,11 @@ export async function getVersionInfo() {
   if (config.channel === 'edge') {
     // Get git info for edge channel
     try {
-      const gitHash = execSync('git rev-parse --short HEAD', {
+      const gitHash = boundedExecFileSync('git', ['rev-parse', '--short', 'HEAD'], 'quick', {
         cwd: config.edgePath,
         encoding: 'utf8',
       }).trim();
-      const gitBranch = execSync('git branch --show-current', {
+      const gitBranch = boundedExecFileSync('git', ['branch', '--show-current'], 'quick', {
         cwd: config.edgePath,
         encoding: 'utf8',
       }).trim();

package/dist/src/cli/child-process-result.js

@@ -0,0 +1,40 @@
+/**
+ * Shared `spawnSync`/`boundedSpawnSync` result-to-exit-code mapping (#3062
+ * review item 7).
+ *
+ * `SpawnSyncReturns.status` is `null` on spawn failure, timeout, or signal
+ * termination — not `0`. Several call sites derived a CLI exit code with
+ * `result.status ?? 0`, which reports *success* for exactly those failure
+ * cases. This helper never does that: a `status` of `null` defaults to a
+ * non-zero exit, and when the bounded helper's `error`/`signal` fields are
+ * present, their message (already enriched with the tier/bound/override
+ * guidance for a timeout) is surfaced instead of being silently dropped.
+ *
+ * Deliberately lives under `src/cli/` rather than `src/process/` so it
+ * composes with, but does not modify, the bounded helper itself.
+ *
+ * @module src/cli/child-process-result
+ */
+/**
+ * Map one spawn result to `{ exitCode, message? }`.
+ *
+ * - `result.error` set (spawn failure, or a bounded-helper timeout with its
+ *   enriched message) → non-zero, `message` is `error.message` (optionally
+ *   prefixed with `context`).
+ * - No `error`, but `result.signal` set (child killed by a signal, with no
+ *   separate error object) → non-zero, `message` names the signal.
+ * - Otherwise → `result.status ?? 1` (a `null`/`undefined` status with
+ *   neither `error` nor `signal` set is still treated as a failure, never
+ *   as success).
+ */
+export function exitCodeForSpawnResult(result, context) {
+    const prefix = context ? `${context}: ` : '';
+    if (result.error) {
+        return { exitCode: 1, message: `${prefix}${result.error.message}` };
+    }
+    if (result.signal) {
+        return { exitCode: 1, message: `${prefix}terminated by signal ${result.signal}` };
+    }
+    return { exitCode: result.status ?? 1 };
+}
+//# sourceMappingURL=child-process-result.js.map