@aiwg/cli 2026.10.3 → 2026.10.5

package/dist/src/smiths/context-pipeline/aiwg-md.js

@@ -17,6 +17,8 @@
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { projectControlPath } from '../../config/project-artifacts.js';
+import { buildClaudeHookBlock, CLAUDE_HOOK_START, CLAUDE_HOOK_END } from './claude-hook.js';
+import { dominantLineEnding, withLineEnding } from './line-endings.js';
 import { buildParallelismSection, replaceOrAppendParallelismBlock } from './parallelism-section.js';
 import { buildContextFinalizationBlock, replaceOrAppendFinalizationBlock } from './finalization.js';
 import { buildExternalLinksSection, replaceOrAppendExternalLinksBlock, } from './external-links-section.js';
@@ -55,6 +57,15 @@ export async function buildAiwgMdContent(projectPath, stagedClaudeMdContent) {
     if (claudeMdContent) {
         // Insert the AIWG signature comment as the second line.
         // Top line is typically `# AIWG` or `# Project` heading; preserve it.
+        // Regenerate may mirror CLAUDE.md before its hook updater runs. Normalize
+        // that managed block here too so legacy duplicate policy never reaches
+        // AIWG.md, even on the first refresh. Operator content stays untouched.
+        const start = claudeMdContent.indexOf(CLAUDE_HOOK_START);
+        const end = claudeMdContent.indexOf(CLAUDE_HOOK_END, start);
+        if (start >= 0 && end >= start) {
+            const hook = withLineEnding(buildClaudeHookBlock(), dominantLineEnding(claudeMdContent));
+            claudeMdContent = claudeMdContent.slice(0, start) + hook + claudeMdContent.slice(end + CLAUDE_HOOK_END.length);
+        }
         const lines = claudeMdContent.split('\n');
         // #1268: strip `@AIWG.md` self-include directives. CLAUDE.md uses
         // `@AIWG.md` to pull in the framework context; AIWG.md IS that framework

package/dist/src/smiths/context-pipeline/claude-hook.js

@@ -26,29 +26,14 @@ import { dominantLineEnding, withLineEnding } from './line-endings.js';
 import { assertSafeContextFile } from './context-file-safety.js';
 export const CLAUDE_HOOK_START = '<!-- AIWG:claude-md-hook:start -->';
 export const CLAUDE_HOOK_END = '<!-- AIWG:claude-md-hook:end -->';
-function buildClaudeArtifactOutputPolicy(policy = {}) {
-    const providerNative = policy.provider_native ?? 'explicit-only';
-    const design = policy.destinations?.['claude-code.design'];
-    const designEnabled = design?.enabled !== false && design?.use_when !== 'disabled';
-    return [
-        '## AIWG artifact output policy',
-        '',
-        `- Canonical durable artifacts: AIWG artifact store (policy: ${policy.canonical ?? 'aiwg'}).`,
-        `- Provider-native presentation/export: ${providerNative}.`,
-        `- Claude Design: ${designEnabled ? 'available only when explicitly selected by the resolved policy or requested by the user' : 'disabled by project policy'}.`,
-        '- Never substitute, relocate, or omit the canonical AIWG plan/review artifact because Claude adds or changes a provider default.',
-        '- When both canonical and presentation outputs are selected, write the canonical artifact first; treat Design as a derived export and record provenance linking it to the canonical source of truth.',
-        '- Unknown provider-native destinations fail safe with a diagnostic. Higher-authority project policy overrides user preferences; explicit task selection overrides provider defaults only within the project policy ceiling.',
-    ];
-}
-export function buildClaudeHookBlock(policy = {}) {
+export function buildClaudeHookBlock(_policy = {}) {
     return [
         CLAUDE_HOOK_START,
         '',
         buildProviderBootstrapBlock('claude'),
         '@.aiwg/aiwg.config',
         '',
-        ...buildClaudeArtifactOutputPolicy(policy),
+        'Artifact destination authority: `aiwg show rule artifact-output-policy` (kernel).',
         '',
         '<!--',
         '  This block is managed by `aiwg regenerate` and `aiwg use`.',
@@ -72,15 +57,7 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
         action: 'skipped',
         warnings: [],
     };
-    let policy = {};
-    try {
-        const config = JSON.parse(await fs.readFile(path.join(projectPath, '.aiwg', 'aiwg.config'), 'utf8'));
-        policy = config.artifact_outputs ?? {};
-    }
-    catch {
-        // Missing/legacy/temporarily malformed config receives the safe default.
-    }
-    let block = buildClaudeHookBlock(policy);
+    let block = buildClaudeHookBlock();
     // Case 1: CLAUDE.md does not exist — create a minimal one with just the block.
     let existing;
     try {

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

@@ -2,7 +2,7 @@
  * Context-finalization pass for generated provider context files.
  *
  * Templates provide the stable structure; this pass stitches in current
- * workspace facts from `.aiwg/aiwg.config` and the discover-first protocol so
+ * workspace facts from `.aiwg/aiwg.config` and rule authority pointers so
  * provider context files do not remain template-only (#1365).
  */
 import { promises as fs } from 'node:fs';
@@ -10,6 +10,7 @@ import * as path from 'node:path';
 import { projectAiwgPath, projectControlPath, resolveProjectAiwgDir, } from '../../config/project-artifacts.js';
 import { renderTrackerProtocol, resolveTrackerAuthority } from '../../tracker/capability-protocol.js';
 import { readConfig, readGitRemoteUrls } from '../../tracker/project-inputs.js';
+import { DECISION_COMPACT_ANCHOR, inspectDecisionOffloadActivation } from '../../decision/offload-activation.js';
 import { buildExternalLinksSection, replaceOrAppendExternalLinksBlock, } from './external-links-section.js';
 export const FINALIZATION_START = '<!-- aiwg-context-finalization:START -->';
 export const FINALIZATION_END = '<!-- aiwg-context-finalization:END -->';
@@ -52,6 +53,7 @@ export async function buildContextFinalizationBlock(projectPath, documentPath =
         }
     }
     const trackerAuthority = resolveTrackerAuthority(config, remoteUrls);
+    const decision = await inspectDecisionOffloadActivation({ cwd: projectPath });
     const lines = [
         FINALIZATION_START,
         '## Context Finalization',
@@ -65,11 +67,9 @@ export async function buildContextFinalizationBlock(projectPath, documentPath =
         `- Recorded deployments: ${formatList([...providerDeployments].sort())}`,
         `- Normalized project context: \`${normalizedAiwgMdPath}\``,
         '',
-        '### Discover-First Protocol',
+        '### Capability Routing',
         '',
-        'Classify every user turn FIRST: is it a **new directive** or a continuation? When a message names or references an AIWG command/capability — even as pasted content like an `address-issues` tracker table, an issue list, or a `flow-*` name — treat it as a new directive and ACT: run `aiwg discover "<the need>"`, fetch with `aiwg show <type> <name>`, and invoke it. Do NOT ask "what would you like me to do with these?" when the action is implied — a pasted `address-issues #1234` table means run the address-issues workflow on those issues.',
-        '',
-        'Also run `aiwg discover` before declining an AIWG request as out of scope or inventing a workflow from memory. The CLI ranks AIWG capabilities across the installed corpus and rebuilds the index from `$AIWG_ROOT` automatically, so a "no matches" for a command you know is deployed is a bug — not a signal it is absent. Commands AIWG deploys to your provider command directory (`.opencode/command/`, `.claude/commands/`, `~/.codex/prompts/`, …) ARE discoverable this way; fetch them with `aiwg show command <name>`. This prevents decline-without-search failures, ask-instead-of-act on new directives, and hallucinated skill or agent names. Full rule: `agentic/code/addons/aiwg-utils/rules/skill-discovery.md`.',
+        'Routing authority: `aiwg show rule skill-discovery` (kernel); capability phrases: `aiwg show skill aiwg-utils-quickref`.',
         '',
         '### Engagement Verification',
         '',
@@ -84,6 +84,7 @@ export async function buildContextFinalizationBlock(projectPath, documentPath =
         `- ${normalizedAiwgMdLabel} is the normalized project-local context entry point.`,
         '- Root `AIWG.md` is the generated cross-provider companion loaded through `AGENTS.md` and provider twins.',
         `- \`AGENTS.md\`, \`WARP.md\`, \`.hermes.md\`, and \`.github/copilot-instructions.md\` are provider-facing bridges, not replacements for ${normalizedAiwgMdLabel}.`,
+        ...(decision.shouldAnchor ? ['', '## Compact Instructions', '', DECISION_COMPACT_ANCHOR] : []),
         FINALIZATION_END,
         '',
     ];

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

@@ -199,7 +199,24 @@ export async function isOverwriteSafe(filePath) {
  *
  * Per ADR-4 §4 atomic write requirement; on failure no partial state is persisted.
  */
-async function atomicWrite(filePath, content) {
+async function atomicWrite(filePath, content, provider) {
+    // Rule delivery owns this block. Context regeneration runs after deployment
+    // and must retain the selected kernel even when rebuilding the adapter.
+    const existing = await fs.readFile(filePath, 'utf8').catch(() => '');
+    for (const owner of ['rule-startup', 'hermes-context', 'hermes-routing', 'warp-context']) {
+        if (content.includes(`<!-- AIWG:${owner}:start -->`))
+            continue;
+        const managed = existing.match(new RegExp(`<!-- AIWG:${owner}:start -->[\\s\\S]*?<!-- AIWG:${owner}:end -->`));
+        if (managed)
+            content = `${content.trimEnd()}\n\n${managed[0]}\n`;
+    }
+    const bytes = Buffer.byteLength(content, 'utf8');
+    if (provider === 'codex' && path.basename(filePath) === 'AGENTS.md' && bytes >= 32768) {
+        throw new Error('Codex AGENTS.md exceeds its 32 KB hard cap');
+    }
+    if (provider === 'hermes' && ['AGENTS.md', '.hermes.md'].includes(path.basename(filePath)) && content.length > 19000) {
+        throw new Error(`Hermes ${path.basename(filePath)} exceeds hard cap of 19000 characters`);
+    }
     const dir = path.dirname(filePath);
     const tmp = path.join(dir, `.${path.basename(filePath)}.tmp.${process.pid}`);
     await fs.mkdir(dir, { recursive: true });
@@ -212,6 +229,7 @@ async function atomicWrite(filePath, content) {
         await fs.unlink(tmp).catch(() => undefined);
         throw err;
     }
+    return bytes;
 }
 /**
  * Per-provider twin-file names for AGENTS.md emission per ADR-1 §4.
@@ -303,7 +321,7 @@ async function writeTwinFiles(provider, projectPath, agentsMdContent, opts, resu
                     throw err;
             }
         }
-        await atomicWrite(twinPath, twinContent);
+        await atomicWrite(twinPath, twinContent, provider);
         result.twinPaths.push(twinPath);
     }
 }
@@ -408,9 +426,8 @@ export async function generate(opts) {
         // write, and as the twin content downstream.
         const built = await buildAgentsMd(opts);
         if (canWrite) {
-            await atomicWrite(agentsMdPath, built.content);
+            result.agentsMdBytes = await atomicWrite(agentsMdPath, built.content, opts.provider);
             result.agentsMdPath = agentsMdPath;
-            result.agentsMdBytes = Buffer.byteLength(built.content, 'utf8');
             result.warnings.push(...built.warnings);
             if (built.splitOccurred) {
                 await writeSpilloverBlock(opts.projectPath, built.spilloverContent, result);

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

@@ -232,26 +232,16 @@ export async function buildParallelismSection(projectPath, deps = {}) {
         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 native-delegation rubric above
-    // applies unchanged and the output stays byte-identical to the pre-dispatch
-    // rendering.
+    // `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('');
@@ -273,13 +263,15 @@ export async function buildParallelismSection(projectPath, deps = {}) {
             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('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.`);

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>;
+}

package/dist/src/smiths/toolsmith/runtime-discovery.mjs

@@ -8,8 +8,9 @@
  */
 
 import { boundedExecFileSync, boundedExecSync } from '../../process/bounded-child-process.mjs';
-import { readFile, writeFile, mkdir, access } from 'fs/promises';
+import { readFile, writeFile, mkdir, access, stat } from 'fs/promises';
 import { existsSync, constants } from 'fs';
+import { createHash } from 'node:crypto';
 import { resolve, join, dirname } from 'path';
 import { platform, arch, homedir, tmpdir, cpus, totalmem, freemem } from 'os';
 import { fileURLToPath } from 'url';
@@ -22,26 +23,59 @@ const __dirname = dirname(__filename);
  * RuntimeDiscovery - Discovers and catalogs installed system tools
  */
 export class RuntimeDiscovery {
-  constructor(basePath = null) {
-    this.basePath = basePath || projectAiwgPath(process.cwd(), 'smiths', 'toolsmith');
+  constructor(basePath = null, { cwd = process.cwd(), quiet = false } = {}) {
+    this.cwd = cwd;
+    this.quiet = quiet;
+    this.basePath = basePath || projectAiwgPath(this.cwd, 'smiths', 'toolsmith');
     this.knownTools = this.#loadKnownTools();
   }
 
   /**
-   * Perform full discovery scan
+   * Refresh discovery, skipping version probes when inputs are unchanged.
    * @returns {Promise<Object>} RuntimeCatalog
    */
-  async discover() {
-    console.log('Starting runtime discovery...');
+  async discover({ force = false } = {}) {
+    if (!this.quiet) console.log('Starting runtime discovery...');
+
+    const loaded = await this.#loadCatalog().catch(error => {
+      if (error instanceof SyntaxError) return null;
+      throw error;
+    });
+    const previous = Array.isArray(loaded?.tools) ? loaded : null;
+    const paths = new Map();
+    const inputs = [];
+    for (const name of this.#safeTools()) {
+      const toolPath = await this.#findToolPath(name);
+      paths.set(name, toolPath);
+      const metadata = toolPath ? await stat(toolPath).catch(() => null) : null;
+      inputs.push([name, toolPath, metadata && [metadata.mtimeMs, metadata.ctimeMs, metadata.size, metadata.mode]]);
+    }
+    const inputFingerprint = createHash('sha256').update(JSON.stringify([
+      1, this.knownTools, inputs, platform(), arch(), homedir(), this.cwd,
+      process.env.PATH, process.env.PATHEXT, process.env.SHELL, process.env.ComSpec,
+    ])).digest('hex');
+    if (!force && previous?.inputFingerprint === inputFingerprint
+      && existsSync(join(this.basePath, 'runtime-info.md'))) {
+      if (!this.quiet) console.log(`Discovery skipped: unchanged (${previous.tools.length} tools)`);
+      return previous;
+    }
 
     const environment = await this.getEnvironment();
     const resources = await this.getResources();
-    const tools = await this.#discoverTools();
+    const tools = await this.#discoverTools(paths);
+    const previousIds = new Set((previous?.tools || []).map(tool => tool.id));
+    const currentIds = new Set(tools.available.map(tool => tool.id));
+    const delta = {
+      added: [...currentIds].filter(id => !previousIds.has(id)),
+      removed: [...previousIds].filter(id => !currentIds.has(id)),
+    };
 
     const catalog = {
       $schema: 'https://aiwg.io/schemas/toolsmith/runtime-catalog-v1.json',
       version: '1.0',
       generated: new Date().toISOString(),
+      inputFingerprint,
+      delta,
       environment,
       resources,
       tools: tools.available,
@@ -52,7 +86,11 @@ export class RuntimeDiscovery {
     await this.#writeCatalog(catalog);
     await this.#writeRuntimeInfo(catalog);
 
-    console.log(`Discovery complete: ${catalog.tools.length} tools found`);
+    if (!this.quiet) console.log(`Discovery complete: ${catalog.tools.length} tools found`);
+    if (!this.quiet) console.log(`Tool delta: +${delta.added.length} added, -${delta.removed.length} removed`);
+    if (delta.removed.length) {
+      if (!this.quiet) console.warn(`Previously cataloged tools no longer available: ${delta.removed.join(', ')}`);
+    }
     return catalog;
   }
 
@@ -146,7 +184,7 @@ export class RuntimeDiscovery {
         osVersion = boundedExecSync('ver', 'quick', { encoding: 'utf-8' }).trim();
       }
     } catch (error) {
-      console.warn('Could not detect OS version:', error.message);
+      if (!this.quiet) console.warn('Could not detect OS version:', error.message);
     }
 
     return {
@@ -155,7 +193,7 @@ export class RuntimeDiscovery {
       arch: arch(),
       shell: process.env.SHELL || process.env.ComSpec || '/bin/sh',
       homeDir: homedir(),
-      workingDir: process.cwd()
+      workingDir: this.cwd
     };
   }
 
@@ -184,7 +222,7 @@ export class RuntimeDiscovery {
         diskFreeGb = Math.round((totalFree / (1024 ** 3)) * 10) / 10;
       } else {
         // Unix: use df
-        const output = boundedExecFileSync('df', ['-k', '.'], 'quick', { encoding: 'utf-8' });
+        const output = boundedExecFileSync('df', ['-k', '.'], 'quick', { encoding: 'utf-8', cwd: this.cwd });
         const lines = output.trim().split('\n');
         if (lines.length > 1) {
           const parts = lines[1].trim().split(/\s+/);
@@ -199,7 +237,7 @@ export class RuntimeDiscovery {
       memoryTotalGb = Math.round((totalMem / (1024 ** 3)) * 10) / 10;
       memoryAvailableGb = Math.round((freeMem / (1024 ** 3)) * 10) / 10;
     } catch (error) {
-      console.warn('Could not get resource info:', error.message);
+      if (!this.quiet) console.warn('Could not get resource info:', error.message);
     }
 
     return {
@@ -298,9 +336,9 @@ export class RuntimeDiscovery {
    * @see https://git.integrolabs.net/roctinam/aiwg/issues/820
    * @private
    */
-  async #discoverTools() {
+  #safeTools() {
     // Curated list: knownTools database + common dev tools safe to probe
-    const safeToProbe = new Set([
+    return new Set([
       // From knownTools database
       ...Object.keys(this.knownTools),
       // Aliases from knownTools
@@ -328,12 +366,13 @@ export class RuntimeDiscovery {
       'yq', 'fx', 'miller',
       'htop', 'ncdu', 'dust', 'procs', 'tokei',
     ]);
+  }
 
+  async #discoverTools(paths) {
     const available = [];
     const unavailable = [];
 
-    for (const name of safeToProbe) {
-      const toolPath = await this.#findToolPath(name);
+    for (const [name, toolPath] of paths) {
       if (!toolPath) {
         // Not installed — skip silently (not an error)
         continue;
@@ -359,7 +398,7 @@ export class RuntimeDiscovery {
   }
 
   /**
-   * Find tool path using which/where
+   * Search PATH first, then common user installation directories on Unix.
    * @private
    */
   async #findToolPath(toolName) {
@@ -370,8 +409,27 @@ export class RuntimeDiscovery {
         .split('\n')[0];
       return path;
     } catch {
-      return null;
+      // Scheduled jobs often omit user installation directories from PATH.
+    }
+    if (platform() !== 'win32' && !toolName.includes('/') && !toolName.includes('\\')) {
+      const home = homedir();
+      const directories = new Set([
+        join(process.env.CARGO_HOME || join(home, '.cargo'), 'bin'),
+        join(home, '.local', 'bin'), join(home, 'bin'),
+        join(home, '.npm-global', 'bin'), join(home, 'go', 'bin'),
+        join(home, '.bun', 'bin'), join(home, '.deno', 'bin'),
+      ]);
+      for (const directory of directories) {
+        const candidate = join(directory, toolName);
+        try {
+          await access(candidate, constants.X_OK);
+          if ((await stat(candidate)).isFile()) return candidate;
+        } catch {
+          // Continue to the next user directory.
+        }
+      }
     }
+    return null;
   }
 
   /**

package/dist/src/storage/backends/fs.js

@@ -9,14 +9,17 @@
  * @issue #934
  * @issue #956
  */
-import { existsSync } from 'fs';
-import { appendFile, mkdir, readFile, readdir, rm, stat, writeFile } from 'fs/promises';
-import { dirname, join, relative, resolve, sep } from 'path';
+import { resolve, sep } from 'path';
+import { pinContainedRoot, readContainedFile, writeContainedFile, appendContainedFile, deleteContainedFile, listContainedFiles } from '../../utils/contained-filesystem.mjs';
 export class FilesystemAdapter {
     /** Absolute path where this subsystem's content lives. */
     root;
+    store;
     constructor(root) {
         this.root = resolve(root);
+        this.store = pinContainedRoot(this.root, undefined, {
+            createMissing: true, protectLocationPointer: false, rejectLinkedWrites: true,
+        });
     }
     /**
      * Path traversal guard. Rejects `..`, leading `/`, leading `~`, and
@@ -46,89 +49,28 @@ export class FilesystemAdapter {
         return abs;
     }
     async read(path) {
-        const abs = this.resolveSafe(path);
-        if (!existsSync(abs))
-            return null;
-        return readFile(abs, 'utf-8');
+        this.resolveSafe(path);
+        return readContainedFile(await this.store, path);
     }
     async write(path, content, _meta) {
-        const abs = this.resolveSafe(path);
-        await mkdir(dirname(abs), { recursive: true });
-        await writeFile(abs, content, 'utf-8');
+        this.resolveSafe(path);
+        await writeContainedFile(await this.store, path, content);
     }
-    /**
-     * Atomic append. Uses fs.appendFile, which opens with O_APPEND so the
-     * kernel guarantees atomicity for writes ≤ PIPE_BUF (4096 bytes on
-     * Linux). Concurrent appenders interleave at line granularity rather
-     * than racing read-then-write. See #976.
-     */
+    /** Append through a verified O_APPEND handle, without read/replace races. */
     async append(path, content) {
-        const abs = this.resolveSafe(path);
-        await mkdir(dirname(abs), { recursive: true });
-        await appendFile(abs, content, 'utf-8');
+        this.resolveSafe(path);
+        await appendContainedFile(await this.store, path, content);
     }
     async list(prefix) {
-        // Empty prefix = list everything under root. A non-empty prefix
-        // restricts to entries whose subsystem-relative path starts with it
-        // (after path-normalizing the prefix itself).
-        if (typeof prefix !== 'string') {
+        if (typeof prefix !== 'string')
             throw new Error('storage(fs): list prefix must be a string');
-        }
-        if (prefix.length > 0) {
-            // resolveSafe also validates the prefix shape
+        if (prefix)
             this.resolveSafe(prefix);
-        }
-        if (!existsSync(this.root))
-            return [];
-        const out = [];
-        await walkInto(this.root, this.root, prefix, out);
-        return out;
+        return listContainedFiles(await this.store, prefix);
     }
     async delete(path) {
-        const abs = this.resolveSafe(path);
-        if (!existsSync(abs))
-            return;
-        await rm(abs, { force: true });
-    }
-}
-async function walkInto(root, dir, prefix, out) {
-    let entries;
-    try {
-        entries = await readdir(dir, { withFileTypes: true });
-    }
-    catch {
-        return;
-    }
-    for (const e of entries) {
-        const full = join(dir, e.name);
-        const rel = relative(root, full).split(sep).join('/');
-        if (e.isDirectory()) {
-            // Descend if the dir could contain matches
-            if (prefix === '' || rel.startsWith(prefix) || prefix.startsWith(rel + '/')) {
-                await walkInto(root, full, prefix, out);
-            }
-            continue;
-        }
-        if (!e.isFile())
-            continue;
-        if (prefix !== '' && !rel.startsWith(prefix))
-            continue;
-        let size;
-        let modifiedAt;
-        try {
-            const s = await stat(full);
-            size = s.size;
-            modifiedAt = s.mtime;
-        }
-        catch {
-            // ignore stat failures
-        }
-        const entry = { path: rel };
-        if (size !== undefined)
-            entry.size = size;
-        if (modifiedAt !== undefined)
-            entry.modifiedAt = modifiedAt;
-        out.push(entry);
+        this.resolveSafe(path);
+        await deleteContainedFile(await this.store, path);
     }
 }
 //# sourceMappingURL=fs.js.map

package/dist/src/storage/backends/obsidian.js

@@ -96,6 +96,7 @@ export class ObsidianAdapter {
             execSync('obsidian --version', {
                 stdio: ['ignore', 'pipe', 'pipe'],
                 timeout: 2000,
+                killSignal: 'SIGKILL',
             });
         }
         catch {

package/dist/src/tracker/forge-http.js

@@ -13,6 +13,7 @@
  * `code`. Access material stays inside the transport: it is never part of an
  * error, a result or a log line.
  */
+import { signalChild } from '../process/signal-child.mjs';
 import { spawn } from 'node:child_process';
 export class ForgeReadError extends Error {
     code;
@@ -115,7 +116,7 @@ function spawnCliRunner(binary, maxBytes) {
             size += chunk.length;
             if (size > maxBytes + 65_536) {
                 oversized = true;
-                child.kill();
+                signalChild(child);
             }
             else
                 chunks.push(chunk);

package/dist/src/update/checker.d.mts

@@ -0,0 +1,2 @@
+export function checkForUpdates(): Promise<void>;
+export function forceUpdateCheck(): Promise<void>;

package/dist/src/update/service.d.mts

@@ -0,0 +1,22 @@
+export type InstallMode = 'npm' | 'web' | 'source';
+
+export interface UpdateResult {
+  mode: InstallMode;
+  packageRoot: string;
+  packageName: string | null;
+  channel: string;
+  status: 'updated' | 'current' | 'manual' | 'dry-run' | 'unsupported-offline';
+  changed: boolean;
+  version?: string;
+  command?: string;
+  message: string;
+  identity?: import('../installation/manager.mjs').InstallationIdentity;
+  identityPersistent?: boolean;
+}
+
+export function detectInstallMode(options?: Record<string, unknown>): Promise<{
+  mode: InstallMode;
+  packageRoot: string;
+  packageName: string | null;
+}>;
+export function updateInstallation(options?: Record<string, unknown>): Promise<UpdateResult>;

package/dist/src/utils/contained-filesystem.d.mts

@@ -0,0 +1,37 @@
+import type { BigIntStats } from 'node:fs';
+import type { FileHandle } from 'node:fs/promises';
+
+/** Opaque pinned filesystem boundary; configuration is captured only once. */
+export interface ContainedRoot {
+  readonly configured: string;
+  readonly root: string;
+  readonly identity?: BigIntStats | null;
+  readonly error?: Error;
+}
+export interface ContainmentOptions {
+  /** Storage may create missing configured roots through a pinned ancestor. */
+  createMissing?: boolean;
+  /** Artifacts protect location pointers; ordinary storage metadata may opt out. */
+  protectLocationPointer?: boolean;
+  /** Storage refuses replacement of hardlinks; artifact atomic writes retain compatibility. */
+  rejectLinkedWrites?: boolean;
+}
+export interface ContainedFile {
+  handle: FileHandle;
+  fullPath: string;
+  close(): Promise<void>;
+  commit(): Promise<void>;
+}
+export interface ContainedEntry {
+  path: string;
+  size: number;
+  modifiedAt: Date;
+}
+export function validateContainedPath(relative: string): void;
+export function pinContainedRoot(configured: string, projectRoot?: string, options?: ContainmentOptions): Promise<ContainedRoot>;
+export function openContainedFile(store: ContainedRoot, relative: string, options?: { write?: boolean }): Promise<ContainedFile>;
+export function readContainedFile(store: ContainedRoot, relative: string): Promise<string | null>;
+export function writeContainedFile(store: ContainedRoot, relative: string, content: string): Promise<void>;
+export function appendContainedFile(store: ContainedRoot, relative: string, content: string): Promise<void>;
+export function deleteContainedFile(store: ContainedRoot, relative: string): Promise<void>;
+export function listContainedFiles(store: ContainedRoot, prefix?: string): Promise<ContainedEntry[]>;