@aiwg/cli 2026.10.1 → 2026.10.4

package/dist/src/smiths/context-pipeline/parallelism-section.js

@@ -13,9 +13,135 @@
  *
  * @implements #1362
  */
-import { readAiwgConfig, resolveParallelism, PROVIDER_PARALLELISM_DEFAULTS } from '../../config/aiwg-config.js';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findPackageRoot } from '../../cli/find-package-root.js';
+import { readAiwgConfigCandidate, validateWorkerConfigCandidate, resolveParallelism, PROVIDER_PARALLELISM_DEFAULTS } from '../../config/aiwg-config.js';
 export const PARALLELISM_BLOCK_START = '<!-- AIWG-PARALLELISM-CAP:START -->';
 export const PARALLELISM_BLOCK_END = '<!-- AIWG-PARALLELISM-CAP:END -->';
+/**
+ * One-line note rendered when the bundled model defaults cannot be loaded.
+ * The orchestration health block is omitted; the rest of the section renders
+ * unchanged so context regeneration never throws for a missing home install.
+ */
+export const PARALLELISM_HEALTH_UNRESOLVED_NOTE = 'Health values could not be resolved from the bundled defaults, so the orchestration health block is omitted.';
+/**
+ * Locate this package's bundled AIWG defaults (`models-v2.json` under
+ * `agentic/...`) from the running code, whether it runs from a source
+ * checkout or an installed package. Uses the canonical package-root walk
+ * shared with the rest of src/ (`findPackageRoot`), never a hand-rolled
+ * relative path and never the user's home install.
+ */
+function resolveBundledAiwgHome() {
+    try {
+        return findPackageRoot(dirname(fileURLToPath(import.meta.url))) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve the AIWG home to pass to `ConfigLoader` for this generator's own
+ * read: an explicit, non-empty `AIWG_HOME` always wins; otherwise fall back
+ * to this package's own bundled defaults so regeneration does not depend on
+ * what (if anything) is installed at the user's home. This function only
+ * ever READS `process.env.AIWG_HOME` — it never sets or deletes it, so
+ * concurrent callers and any spawned children never observe a value this
+ * generator did not itself receive from the real environment.
+ */
+function resolveAiwgHome() {
+    return process.env.AIWG_HOME || resolveBundledAiwgHome();
+}
+function isBundledDefaultsFailure(error) {
+    return error instanceof Error && error.message.includes('Failed to load AIWG default config');
+}
+function oneLine(value, maxLen) {
+    return value.replace(/[\r\n|]+/g, ' ').trim().slice(0, maxLen);
+}
+/** At most this many group summaries render; the rest collapse to "+N more". */
+export const MAX_SHOWN_GROUPS = 8;
+/**
+ * Config-level member exclusions for one group, mirroring the static gates
+ * in `resolveWorkerPlan()` (`src/models/resolver.ts`): a member or its CLI
+ * installation flagged `enabled: false` is statically excluded. This is
+ * NOT the live eligibility verdict — `resolveWorkerPlan()` resolves
+ * eligibility per (group, member, effort) tuple against the current
+ * catalog and request, so a member excluded nowhere here can still be
+ * excluded for a specific role/task/effort, and vice versa is never true
+ * (a statically excluded member is always excluded live too). Only the
+ * per-member reasons render; the group itself is never labeled
+ * "eligible"/"not eligible" — see the request-scoped resolve guidance
+ * below the group list.
+ *
+ * A `requiredRoles` entry with no enabled covering member is a config
+ * error `validateParallelismConfig()` (and `resolveParallelism()` /
+ * `ConfigLoader.load()`, both called earlier in `buildParallelismSection()`)
+ * already rejects outright — a config reaching this function can never
+ * have one, so that case is not re-rendered here.
+ */
+function excludedMembers(parallelism, group) {
+    const excluded = [];
+    for (const member of group.members) {
+        if (member.enabled === false)
+            excluded.push(`${member.id} (member disabled)`);
+        else if (parallelism?.clis?.[member.cli]?.enabled === false)
+            excluded.push(`${member.id} (installation ${member.cli} disabled)`);
+    }
+    return excluded;
+}
+function groupSummaries(entries, parallelism) {
+    return entries.map(([id, group]) => {
+        const roles = [...new Set(group.members.flatMap(m => m.roles ?? []))].join('/');
+        const clis = [...new Set(group.members.map(m => m.cli))].join('/');
+        const parts = [`${oneLine(id, 64)} (members: ${group.members.length}`];
+        if (clis)
+            parts.push(`clis: ${oneLine(clis, 96)}`);
+        if (roles)
+            parts.push(`roles: ${oneLine(roles, 96)}`);
+        if (group.maxParallel !== undefined)
+            parts.push(`maxParallel: ${group.maxParallel}`);
+        if (group.requiredRoles?.length)
+            parts.push(`requiredRoles: ${group.requiredRoles.join('/')}`);
+        parts.push('configured');
+        const excluded = excludedMembers(parallelism, group);
+        if (excluded.length)
+            parts.push(`excluded members: ${oneLine(excluded.join(', '), 160)}`);
+        return parts.join('; ') + ')';
+    });
+}
+/**
+ * One configured health window with its origin. The origin mirrors
+ * `resolveWorkerEffectiveHealth()` (`src/serve/worker-invocation.ts`): a
+ * field the project config leaves unset resolves from the built-in defaults.
+ */
+function healthValue(health, field, fallback) {
+    const value = health?.[field] ?? fallback;
+    return { value, origin: health?.[field] === undefined ? 'default' : 'project config' };
+}
+/**
+ * Plain-language dispatch state line (#3050 item 5). Agents must not assume
+ * other worker CLIs are unavailable just because dispatch is off — they
+ * should detect them and offer the opt-in, not silently work around it.
+ */
+function workerDispatchStateLine(parallelism, setup) {
+    if (parallelism?.worker_dispatch === true) {
+        return '**Direct worker dispatch**: on (`parallelism.worker_dispatch`).';
+    }
+    // A recorded decline (#3050 review item 3) means a person already said no
+    // to this offer — render the plain off state without repeating the
+    // detect-and-offer instruction, so agents stop re-litigating a settled
+    // decision every session. The decline is a setup/onboarding preference,
+    // not worker policy, so it lives in `setup`, not in the frozen
+    // `parallelism` contract fragment (B-OG-29).
+    if (setup?.worker_dispatch_offer === 'declined') {
+        return '**Direct worker dispatch**: off (`parallelism.worker_dispatch`); a prior offer was declined '
+            + '(`setup.worker_dispatch_offer`). Do not re-offer it. It can still be turned on with '
+            + '`aiwg config set --project parallelism.worker_dispatch true` if the user asks for it directly.';
+    }
+    return '**Direct worker dispatch**: off (`parallelism.worker_dispatch`). Do not assume other worker CLIs '
+        + 'are unavailable — detect them yourself and offer `aiwg config set --project parallelism.worker_dispatch true` '
+        + 'to the user if it would help.';
+}
 function delegationSupport(provider) {
     switch (provider) {
         case 'antigravity':
@@ -45,12 +171,34 @@ function delegationSupport(provider) {
  *   - `AIWG_HIDE_PARALLELISM_IN_CONTEXT=1` is set
  *   - No `.aiwg/aiwg.config` exists at the project path
  */
-export async function buildParallelismSection(projectPath) {
+export async function buildParallelismSection(projectPath, deps = {}) {
     if (process.env.AIWG_HIDE_PARALLELISM_IN_CONTEXT === '1')
         return '';
-    const cfg = await readAiwgConfig(projectPath);
+    // Step 1: the project config, independently validated except for the
+    // worker-model defaults (never throws solely because bundled defaults are
+    // unreachable — any error here is a genuine config problem and stays fatal).
+    const cfg = deps.readConfig
+        ? await deps.readConfig(projectPath)
+        : await readAiwgConfigCandidate(projectPath);
     if (!cfg)
         return '';
+    // Step 2: worker-model defaults validation, attempted only when dispatch
+    // is enabled. A bundled-defaults failure degrades (health/group details
+    // are omitted below with a one-line note); every other error stays fatal.
+    let healthUnresolved = false;
+    if (cfg.parallelism?.worker_dispatch === true) {
+        try {
+            if (deps.validateWorkerConfig)
+                await deps.validateWorkerConfig(projectPath, cfg);
+            else
+                await validateWorkerConfigCandidate(projectPath, cfg, { aiwgHome: resolveAiwgHome() });
+        }
+        catch (error) {
+            if (!isBundledDefaultsFailure(error))
+                throw error;
+            healthUnresolved = true;
+        }
+    }
     const primary = cfg.providers[0];
     const resolved = resolveParallelism(cfg.parallelism, primary);
     const providerDefaults = primary && PROVIDER_PARALLELISM_DEFAULTS[primary];
@@ -84,20 +232,53 @@ export async function buildParallelismSection(projectPath) {
         lines.push(`*Rationale*: ${resolved.rationale}`);
     }
     lines.push('');
-    lines.push('### Model-selected delegation rubric');
-    lines.push('');
-    lines.push('For each non-trivial task, assess whether it contains independent, bounded subtasks that can run concurrently. When delegation is supported, prefer the deployed model-pinned wrappers by task characteristics and consequence:');
-    lines.push('');
-    lines.push('- `aiwg-model-efficiency-worker`: discovery, inventory, focused edits, and other bounded low-cost work.');
-    lines.push('- `aiwg-model-coding-worker`: implementation, tests, debugging, and routine technical delivery.');
-    lines.push('- `aiwg-model-reasoning-worker`: architecture, synthesis, difficult analysis, and high-consequence review.');
-    lines.push('');
-    lines.push('Do not delegate trivial work, tightly coupled changes, serial dependencies, or tasks likely to collide in shared state; also keep work local when coordination costs exceed the expected benefit. Parallelize only independent work, and take the MIN of provider limits, `max_parallel_subagents`, `AIWG_CONTEXT_WINDOW` budget, framework-specific caps (including the RLM 7-agent hard cap for RLM dispatches), and natural task decomposition. Bump the project cap via `aiwg config set --project parallelism.max_parallel_subagents N`.');
-    lines.push('');
-    lines.push('The primary agent retains orchestration, final integration, conflict resolution, validation, and user-facing accountability.');
+    lines.push('Delegation policy and model-worker selection: `aiwg show rule subagent-scoping`.');
+    lines.push('After changing project parallelism with `aiwg config set/reset --project`, follow the emitted provider-specific regeneration commands and run `aiwg workspace-context doctor`.');
     lines.push('');
     lines.push(delegationSupport(primary));
     lines.push('');
+    lines.push(workerDispatchStateLine(cfg.parallelism, cfg.setup));
+    lines.push('');
+    // Group dispatch disabled (worker_dispatch unset/false): the resolver reports
+    // `disabled`, so no group block renders — the subagent-scoping pointer above
+    // remains available.
+    if (cfg.parallelism?.worker_dispatch === true && healthUnresolved) {
+        lines.push(PARALLELISM_HEALTH_UNRESOLVED_NOTE);
+        lines.push('');
+    }
+    else if (cfg.parallelism?.worker_dispatch === true) {
+        const health = cfg.parallelism?.health;
+        const check = healthValue(health, 'checkSeconds', 15);
+        const startup = healthValue(health, 'startupSeconds', 60);
+        const quiet = healthValue(health, 'quietSeconds', 90);
+        const stall = healthValue(health, 'stallSeconds', 300);
+        const hard = healthValue(health, 'hardTimeoutSeconds', 1800);
+        lines.push('### Orchestration groups (group dispatch enabled)');
+        lines.push('');
+        const entries = Object.entries(cfg.parallelism?.groups ?? {});
+        if (entries.length > 0) {
+            // Slice before summarizing so at most MAX_SHOWN_GROUPS summaries are built.
+            const shown = groupSummaries(entries.slice(0, MAX_SHOWN_GROUPS), cfg.parallelism).join(' | ');
+            const hidden = entries.length - MAX_SHOWN_GROUPS;
+            lines.push(`Configured groups: ${shown}${hidden > 0 ? ` (+${hidden} more)` : ''}`);
+        }
+        else {
+            lines.push('Configured groups: none — group dispatch is enabled but no groups are configured; the subagent-scoping rule applies.');
+        }
+        lines.push('');
+        lines.push('A group above shown as configured, with excluded members or an uncovered required role listed, is a static config read — not a live eligibility verdict. Eligibility is resolved per (group, member, effort) tuple against the current catalog and request; see `aiwg models resolve` below to check a specific role/task/group.');
+        lines.push('');
+        lines.push('Tier 0 direct handoff is the default: use your own shell or a qualified MCP worker tool. No Mission/MC session, scheduler, daemon, or activation marker is needed. Self-count active native + CLI + MCP workers, take the minimum of the project, group, CLI, model, and context caps, and launch each writing task once.');
+        lines.push('');
+        lines.push('Before resolving, qualify the installed CLIs and configured model roles with `aiwg doctor --probe-workers --qualify` (`--yes` for headless confirmation).');
+        lines.push('Agents pass `--authorize-premium` to `aiwg models resolve` only after the human explicitly confirmed the premium escalation (escalation-discipline rule); authorization applies to that resolution only.');
+        lines.push('Resolve each bounded brief with `aiwg models resolve --role <role> --task <class> --group <group> --brief <file> --workdir <tree> --final-output <file> --transport shell --format shell`. Copy the exact rendered command or the MCP server/tool/arguments byte-for-byte; never assemble vendor flags from memory. Re-resolve after any brief, profile, model, or workspace change. `--format shell` prints only the launch command: to see the resolved health windows for an attempt, use `--format json` (the default) and read `invocation.health` with its per-field `origins`.');
+        lines.push('');
+        lines.push(`Configured health windows (each followed by its origin — \`default\` or \`project config\`): check every ${check.value}s (${check.origin}); confirm startup within ${startup.value}s (${startup.origin}); quiet limit ${quiet.value}s (${quiet.origin}); stall limit ${stall.value}s (${stall.origin}); hard stop ${hard.value}s (${hard.origin}). Per-attempt windows scale quiet and stall by the single largest applicable role/effort/model factor, never their product (for example, reasoning at \`xhigh\` effort resolves 180s/600s from the 90s/300s defaults; an effective 1.25 scale gives 112.5s/375s). Only the hard deadline and its diagnostic/termination grace periods are capped by the remaining wall-clock and transport ceilings; startup, quiet, and stall keep their configured or scaled values, and \`truncatedWindows\` instead records when one of them would exceed that capped deadline (\`resolveWorkerEffectiveHealth()\` in \`src/serve/worker-invocation.ts\`). Resolved values win over these configured values.`);
+        lines.push('');
+        lines.push('Supervise by observer state, never by suspicion. `quiet` (no observed activity for the quiet window, reported with confidence `suspected`) is not a stop: read the status (`aiwg ralph-external --status --workers --runs-root <dir> --json` is read-only and never kills or retries), check owned-worktree progress, and keep waiting — the observer’s `shouldStop()` stays false. `stalled` (no progress for the stall window) opens diagnosis through the diagnostic grace period; only `hung` (still no progress after grace, with the process live and connected) authorizes a no-progress stop — and only a worker this conductor owns. The launcher also stops independently of progress state on `failed-to-start`, the hard wall-clock deadline (`HARD_DEADLINE`), the step-count limit (`STEP_LIMIT`), and a fatal observer-record failure (`tools/ralph-external/session-launcher.mjs`). Confirm the stop (a sent signal, lease expiry, or final-file presence is not proof — only a confirmed exit is), preserve partial work for independent verification, then re-resolve within remaining attempts and budgets. Observer loss (`OBSERVER_GAP`, `DISCONNECTED`, degraded or unobserved coverage, opaque MCP output) is unknown, never worker failure: keep polling owned run files and processes from the shell at the same cadence. Heartbeats and log bytes are not progress. On correlated failure across workers sharing one account, quota, or host, pause further launches there and report cause and scope.');
+        lines.push('');
+    }
     lines.push(PARALLELISM_BLOCK_END);
     lines.push('');
     return lines.join('\n');

package/dist/src/smiths/context-pipeline/workspace-context.js

@@ -7,7 +7,8 @@
  * an operator runs the explicit migration workflow.
  */
 import { createHash } from 'node:crypto';
-import { promises as fs } from 'node:fs';
+import { promises as fs, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
 import * as path from 'node:path';
 import { buildAiwgMdContent } from './aiwg-md.js';
 import { buildNormalizedAiwgMd } from './finalization.js';
@@ -592,11 +593,106 @@ function sensitiveEvidence(content) {
     }
     return findings;
 }
+// Directory names the context-graph walk always skips, regardless of where
+// the walk root is: VCS/build output that is never hand-authored project
+// content (#277, pre-existing) plus two reserved, self-identifying names
+// that are never legitimately a real project directory.
+const CONTEXT_WALK_ALWAYS_IGNORED_DIR_NAMES = new Set([
+    '.git', 'node_modules', 'dist', 'build', 'coverage', '.aiwg',
+]);
+// Cache/registry directory names that are only skipped when the walk root
+// is the home directory itself (#277 fix-round). A project subtree that
+// happens to be named `.cache`, `target`, `.gradle`, etc. is NOT generated
+// data and must still be scanned — these names are only reliably "cache,
+// not project" when they sit directly under $HOME. `Library/Caches` and
+// `.local/share` are two-segment (parent + name) patterns, handled
+// separately below.
+const HOME_LEVEL_CACHE_DIR_NAMES = new Set([
+    '.cache', '.cargo', '.rustup', '.npm', '.nvm', '.pnpm-store',
+    '.gradle', '.m2', 'Trash',
+]);
+/** True when `dirPath` contains `markerFile` — a cheap, synchronous, read-only check. */
+function hasMarkerFile(dirPath, markerFile) {
+    return existsSync(path.join(dirPath, markerFile));
+}
+/** A `target` directory is Cargo/build output only when it carries the
+ * standard `CACHEDIR.TAG` marker, or sits next to a `Cargo.toml` — not
+ * merely because it is named `target` (#277 fix-round). */
+function isGeneratedTargetDir(dirPath) {
+    if (hasMarkerFile(dirPath, 'CACHEDIR.TAG'))
+        return true;
+    return existsSync(path.join(path.dirname(dirPath), 'Cargo.toml'));
+}
+/** A `venv`/`.venv` directory is a Python virtualenv only when it carries
+ * `pyvenv.cfg` — not merely because of its name (#277 fix-round). */
+function isPythonVenvDir(dirPath) {
+    return hasMarkerFile(dirPath, 'pyvenv.cfg');
+}
+/**
+ * Whether the context-graph walk should skip `entryName` (a directory
+ * directly under `directory`) without descending into it.
+ *
+ * `isHomeRoot` gates the home-level cache list and the `Library/Caches` /
+ * `.local/share` two-segment patterns — they apply only when the overall
+ * walk root is $HOME, never for an arbitrary project subtree that happens
+ * to share one of those names (#277 fix-round).
+ */
+export function shouldSkipContextWalkDir(directory, entryName, isHomeRoot) {
+    if (CONTEXT_WALK_ALWAYS_IGNORED_DIR_NAMES.has(entryName))
+        return true;
+    if (entryName.startsWith('.context-migration-'))
+        return true;
+    const childPath = path.join(directory, entryName);
+    if (entryName === 'target' && isGeneratedTargetDir(childPath))
+        return true;
+    if ((entryName === 'venv' || entryName === '.venv') && isPythonVenvDir(childPath))
+        return true;
+    // Codex's own plugin/temp scratch — a known, specific noise source named
+    // in the original report, not a broad `.tmp` exclusion (#277 fix-round).
+    if (entryName === '.tmp' && path.basename(directory) === '.codex')
+        return true;
+    if (isHomeRoot) {
+        if (HOME_LEVEL_CACHE_DIR_NAMES.has(entryName))
+            return true;
+        if (entryName === 'Caches' && path.basename(directory) === 'Library')
+            return true;
+        if (entryName === 'share' && path.basename(directory) === '.local')
+            return true;
+    }
+    return false;
+}
+/** Walk depth/entry bounds for the context-graph walk (#277). A hit sets
+ * `truncated: true` on the result instead of silently stopping. Overridable
+ * via environment for tests that need to exercise the bound without
+ * building a correspondingly large fixture tree. */
+function readPositiveIntEnv(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+const CONTEXT_WALK_MAX_DEPTH = readPositiveIntEnv('AIWG_CONTEXT_WALK_MAX_DEPTH', 10);
+const CONTEXT_WALK_MAX_DIRECTORIES = readPositiveIntEnv('AIWG_CONTEXT_WALK_MAX_DIRECTORIES', 20_000);
 async function nestedInstructionFiles(projectPath) {
     const found = [];
-    const ignored = new Set(['.git', 'node_modules', 'dist', 'build', 'coverage', '.aiwg']);
     const artifactRoot = path.resolve(resolveProjectAiwgDir(projectPath));
-    async function walk(directory) {
+    // Running from $HOME is the exact shape of #277: bound the walk to the
+    // top level and apply the home-level cache exclusions instead of
+    // recursing into every cache/registry/venv underneath it. A markerless
+    // but otherwise ordinary (non-home) project root keeps the full bounded
+    // walk — "no project marker" is not evidence the directory is generated
+    // data (#277 fix-round).
+    const isHomeDirectory = path.resolve(projectPath) === path.resolve(homedir());
+    const maxDepth = isHomeDirectory ? 1 : CONTEXT_WALK_MAX_DEPTH;
+    let visitedDirectories = 0;
+    let truncated = false;
+    async function walk(directory, depth) {
+        if (depth > maxDepth || visitedDirectories >= CONTEXT_WALK_MAX_DIRECTORIES) {
+            truncated = true;
+            return;
+        }
+        visitedDirectories += 1;
         let entries;
         try {
             entries = await fs.readdir(directory, { withFileTypes: true });
@@ -605,12 +701,14 @@ async function nestedInstructionFiles(projectPath) {
             return;
         }
         for (const entry of entries) {
+            // Dirent.isDirectory() is false for symlinks (it reflects the entry
+            // itself, not its target), so symlinked directories are never
+            // followed out of the root by this walk.
             if (entry.isDirectory()) {
                 const child = path.join(directory, entry.name);
-                if (!ignored.has(entry.name)
-                    && !entry.name.startsWith('.context-migration-')
+                if (!shouldSkipContextWalkDir(directory, entry.name, isHomeDirectory)
                     && path.resolve(child) !== artifactRoot)
-                    await walk(child);
+                    await walk(child, depth + 1);
             }
             else if (['AGENTS.md', 'CLAUDE.md', 'WARP.md'].includes(entry.name)) {
                 const relative = path.relative(projectPath, path.join(directory, entry.name)).replace(/\\/g, '/');
@@ -621,8 +719,8 @@ async function nestedInstructionFiles(projectPath) {
             }
         }
     }
-    await walk(projectPath);
-    return found.sort((a, b) => a.localeCompare(b));
+    await walk(projectPath, 1);
+    return { files: found.sort((a, b) => a.localeCompare(b)), truncated };
 }
 async function migratedProviderFiles(projectPath) {
     const directory = projectAiwgPath(projectPath, 'context', 'providers');
@@ -638,10 +736,11 @@ async function migratedProviderFiles(projectPath) {
 }
 export async function auditWorkspaceContext(projectPath) {
     const extractedProject = await extractExistingProjectContext(projectPath);
+    const nested = await nestedInstructionFiles(projectPath);
     const candidates = new Set([
         'WORKSPACE.md',
         ...LEGACY_ROOT_FILES,
-        ...await nestedInstructionFiles(projectPath),
+        ...nested.files,
         ...await migratedProviderFiles(projectPath),
     ]);
     const sources = [];
@@ -740,6 +839,7 @@ export async function auditWorkspaceContext(projectPath) {
         overlaps,
         conflicts,
         sensitiveFindings,
+        contextWalkTruncated: nested.truncated,
         plan: {
             routing,
             scopeReview,
@@ -1039,6 +1139,13 @@ export async function workspaceLinkedFiles(projectPath) {
 export async function diagnoseWorkspaceContext(projectPath) {
     const diagnostics = [];
     const audit = await auditWorkspaceContext(projectPath);
+    if (audit.contextWalkTruncated) {
+        diagnostics.push({
+            severity: 'info',
+            code: 'context-walk-truncated',
+            message: 'Nested-instruction-file walk stopped early (depth/entry bound reached, or the root looks like $HOME or has no project markers); the context graph may be incomplete.',
+        });
+    }
     const workspacePath = path.join(projectPath, 'WORKSPACE.md');
     const workspace = await readOptional(workspacePath);
     if (!workspace) {

package/dist/src/smiths/hook-bridge/codex-translator.js

@@ -13,6 +13,7 @@ import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { homedir } from 'node:os';
 import { substituteEnvVars } from './shim.js';
+import { tomlString } from '../../mcp/toml-string.mjs';
 /** Codex-native event names (subset; extend when verified against codex-rs). */
 const CODEX_EVENT_MAP = {
     PreToolUse: 'before_tool',
@@ -44,16 +45,16 @@ export function renderCodexHookToml(source) {
         const subCommand = substituteEnvVars(source.command, 'codex');
         const subArgs = (source.args || []).map((a) => substituteEnvVars(a, 'codex'));
         lines.push(`[[hooks.${codexEvent}]]`);
-        lines.push(`# AIWG-managed hook: ${source.id} — ${source.description}`);
-        lines.push(`command = "${subCommand.replace(/"/g, '\\"')}"`);
+        lines.push(`# AIWG-managed hook: ${`${source.id} — ${source.description}`.replace(/[\x00-\x1f\x7f]/g, ' ')}`);
+        lines.push(`command = ${tomlString(subCommand)}`);
         if (subArgs.length > 0) {
-            lines.push(`args = [${subArgs.map((a) => `"${a.replace(/"/g, '\\"')}"`).join(', ')}]`);
+            lines.push(`args = [${subArgs.map(tomlString).join(', ')}]`);
         }
         if (source.safetyCritical) {
             lines.push(`# safety-critical: cannot be auto-removed without --allow-unsafe-shadow`);
         }
         lines.push(`_aiwg_managed = true`);
-        lines.push(`_aiwg_id = "${source.id}"`);
+        lines.push(`_aiwg_id = ${tomlString(source.id)}`);
         lines.push('');
     }
     return lines.join('\n');
@@ -95,7 +96,7 @@ export async function translateForCodex(source, options) {
         result.skipReason = 'degrade-on declared codex';
         return result;
     }
-    const configPath = path.join(homedir(), '.codex', 'config.toml');
+    const configPath = path.join(process.env.CODEX_HOME || path.join(homedir(), '.codex'), 'config.toml');
     const block = renderCodexHookToml(source);
     if (block.trim().length === 0) {
         result.skipped = true;

package/dist/src/smiths/mcpsmith/example.js

@@ -99,7 +99,7 @@ async function main() {
     console.log(`  node ${generatedServer.files.server}`);
     console.log();
     console.log('  To register with Claude Code:');
-    console.log('  Add to .claude/settings.local.json:');
+    console.log('  Add to .mcp.json:');
     console.log('  {');
     console.log('    "mcpServers": {');
     console.log('      "git": {');

package/dist/src/smiths/mcpsmith/generator.js

@@ -161,7 +161,7 @@ function createManifest(serverId, serverName, analyzerResult, config) {
         resources: [],
         prompts: [],
         dependencies: {
-            runtime: ['node >= 18.0.0'],
+            runtime: ['node >= 24'],
             external: [
                 `${analyzerResult.metadata.sourceName}${analyzerResult.metadata.sourceVersion ? ' >= ' + analyzerResult.metadata.sourceVersion : ''}`
             ]

package/dist/src/smiths/toolsmith/runtime-discovery.d.mts

@@ -0,0 +1,10 @@
+export class RuntimeDiscovery {
+  basePath: string;
+  constructor(basePath?: string | null, options?: { cwd?: string; quiet?: boolean });
+  discover(options?: { force?: boolean }): Promise<any>;
+  verify(): Promise<any>;
+  getCatalog(): Promise<any>;
+  generateDefinition(): Promise<any>;
+  checkTool(toolName: string): Promise<any>;
+  getSummary(): Promise<any>;
+}