@aiwg/cli 2026.10.1 → 2026.10.3

package/dist/src/skills/adapters/openclaw.js

@@ -8,7 +8,8 @@
  * @implements #539
  * @see https://docs.openclaw.ai
  */
-import { execSync } from 'child_process';
+import { boundedExecFileSync } from '../../process/bounded-child-process.mjs';
+import { cliCommand } from '../../process/cli-command.mjs';
 import fs from 'fs';
 import path from 'path';
 import { getProviderDefinition, resolveProviderPathValue, } from '../../providers/provider-definitions.js';
@@ -26,7 +27,8 @@ function resolveSkillFallbackPath(target, projectDir, name) {
  */
 function runOpenClaw(args) {
     try {
-        return execSync(`openclaw ${args}`, {
+        const [file, argv] = cliCommand('openclaw', args);
+        return boundedExecFileSync(file, argv, 'quick', {
             encoding: 'utf-8',
             timeout: 30000,
             stdio: ['pipe', 'pipe', 'pipe'],
@@ -142,7 +144,8 @@ export class OpenClawAdapter {
         if (fs.existsSync(openclawDir))
             return true;
         try {
-            execSync('openclaw --version 2>/dev/null', { encoding: 'utf-8' });
+            const [file, args] = cliCommand('openclaw', ['--version']);
+            boundedExecFileSync(file, args, 'quick', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'] });
             return true;
         }
         catch {
@@ -153,7 +156,7 @@ export class OpenClawAdapter {
         if (this.cachedSkills)
             return this.cachedSkills;
         // Try openclaw CLI with JSON output first
-        const jsonOutput = runOpenClaw('skills list --json 2>/dev/null');
+        const jsonOutput = runOpenClaw(['skills', 'list', '--json']);
         if (jsonOutput) {
             try {
                 const parsed = JSON.parse(jsonOutput);
@@ -178,7 +181,7 @@ export class OpenClawAdapter {
     }
     async search(query) {
         // Try CLI delegation first
-        const cliOutput = runOpenClaw(`skills search "${query}" --json 2>/dev/null`);
+        const cliOutput = runOpenClaw(['skills', 'search', query, '--json']);
         if (cliOutput) {
             try {
                 const parsed = JSON.parse(cliOutput);
@@ -207,7 +210,7 @@ export class OpenClawAdapter {
         const skillMdPath = skillDir ? path.join(skillDir, 'SKILL.md') : '';
         if (!skillMdPath || !fs.existsSync(skillMdPath)) {
             // Try CLI
-            const cliOutput = runOpenClaw(`skills info "${name}" --json 2>/dev/null`);
+            const cliOutput = runOpenClaw(['skills', 'info', name, '--json']);
             if (cliOutput) {
                 try {
                     const parsed = JSON.parse(cliOutput);
@@ -268,7 +271,7 @@ export class OpenClawAdapter {
     }
     async install(name, options) {
         // Try openclaw CLI install first
-        const cliResult = runOpenClaw(`skills install "${name}" 2>/dev/null`);
+        const cliResult = runOpenClaw(['skills', 'install', name]);
         if (cliResult !== null) {
             // CLI handled it — if target is different from openclaw, copy to target
             if (options.target && options.target !== 'openclaw') {

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];
@@ -98,6 +246,47 @@ export async function buildParallelismSection(projectPath) {
     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 native-delegation rubric above
+    // applies unchanged and the output stays byte-identical to the pre-dispatch
+    // rendering.
+    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 native delegation rubric above applies unchanged.');
+        }
+        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('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/toolsmith/runtime-discovery.mjs

@@ -7,7 +7,7 @@
  * @architecture @.aiwg/architecture/toolsmith-implementation-spec.md
  */
 
-import { execSync } from 'child_process';
+import { boundedExecFileSync, boundedExecSync } from '../../process/bounded-child-process.mjs';
 import { readFile, writeFile, mkdir, access } from 'fs/promises';
 import { existsSync, constants } from 'fs';
 import { resolve, join, dirname } from 'path';
@@ -140,10 +140,10 @@ export class RuntimeDiscovery {
           }
         }
       } else if (os === 'darwin') {
-        const version = execSync('sw_vers -productVersion', { encoding: 'utf-8' }).trim();
+        const version = boundedExecFileSync('sw_vers', ['-productVersion'], 'quick', { encoding: 'utf-8' }).trim();
         osVersion = `macOS ${version}`;
       } else if (os === 'win32') {
-        osVersion = execSync('ver', { encoding: 'utf-8' }).trim();
+        osVersion = boundedExecSync('ver', 'quick', { encoding: 'utf-8' }).trim();
       }
     } catch (error) {
       console.warn('Could not detect OS version:', error.message);
@@ -172,7 +172,7 @@ export class RuntimeDiscovery {
       // Disk space
       if (platform() === 'win32') {
         // Windows: use wmic
-        const output = execSync('wmic logicaldisk get size,freespace', { encoding: 'utf-8' });
+        const output = boundedExecFileSync('wmic', ['logicaldisk', 'get', 'size,freespace'], 'quick', { encoding: 'utf-8' });
         const lines = output.trim().split('\n').slice(1);
         let totalFree = 0;
         for (const line of lines) {
@@ -184,7 +184,7 @@ export class RuntimeDiscovery {
         diskFreeGb = Math.round((totalFree / (1024 ** 3)) * 10) / 10;
       } else {
         // Unix: use df
-        const output = execSync('df -k .', { encoding: 'utf-8' });
+        const output = boundedExecFileSync('df', ['-k', '.'], 'quick', { encoding: 'utf-8' });
         const lines = output.trim().split('\n');
         if (lines.length > 1) {
           const parts = lines[1].trim().split(/\s+/);
@@ -365,7 +365,7 @@ export class RuntimeDiscovery {
   async #findToolPath(toolName) {
     try {
       const cmd = platform() === 'win32' ? 'where' : 'which';
-      const path = execSync(`${cmd} ${toolName}`, { encoding: 'utf-8' })
+      const path = boundedExecFileSync(cmd, [toolName], 'quick', { encoding: 'utf-8' })
         .trim()
         .split('\n')[0];
       return path;
@@ -393,15 +393,11 @@ export class RuntimeDiscovery {
     // Bare `version` (positional) is intentionally excluded: it caused
     // BPF tools to attach tracepoints, input-leapc to connect to
     // hostname "version", and cs2cs to open a file named "version".
-    const versionCommands = [
-      `${toolPath} --version`,
-      `${toolPath} -v`,
-      `${toolPath} -V`
-    ];
+    const versionArgs = ['--version', '-v', '-V'];
 
-    for (const cmd of versionCommands) {
+    for (const arg of versionArgs) {
       try {
-        const output = execSync(cmd, {
+        const output = boundedExecFileSync(toolPath, [arg], 'quick', {
           encoding: 'utf-8',
           timeout: 3000,
           killSignal: 'SIGKILL',
@@ -503,7 +499,7 @@ export class RuntimeDiscovery {
     if (platform() === 'win32') return undefined;
 
     try {
-      const manPath = execSync(`man -w ${toolName}`, {
+      const manPath = boundedExecFileSync('man', ['-w', toolName], 'quick', {
         encoding: 'utf-8',
         stdio: ['ignore', 'pipe', 'ignore']
       }).trim();