@aiwg/cli 2026.10.6 → 2026.10.8

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

@@ -37,6 +37,7 @@
  * @issue #972
  */
 import { createHash } from 'node:crypto';
+import { debuglog } from 'node:util';
 const FORTEMI_QUERY_LIMIT = 50;
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 function schemaProperties(tool) {
@@ -371,8 +372,8 @@ export class FortemiAdapter {
  * Implemented as a lazy import so tests that inject a stub never load
  * the SDK or touch the registry.
  */
-export const createDefaultMcpClient = async (serverName, registryOverride, environment = process.env) => {
-    const { McpServerRegistry } = await import('../../mcp/registry.js');
+export const createDefaultMcpClient = async (serverName, registryOverride, environment = process.env, sensitiveInput = {}) => {
+    const { McpServerRegistry, resolveMcpCredentialMaps } = await import('../../mcp/registry.js');
     const registry = registryOverride ?? new McpServerRegistry();
     const server = await registry.get(serverName);
     if (!server) {
@@ -381,60 +382,117 @@ export const createDefaultMcpClient = async (serverName, registryOverride, envir
     }
     // Lazy imports keep unit tests that inject a stub isolated from transports.
     const { Client } = await import('@modelcontextprotocol/sdk/client/index.js');
-    let transport;
-    if (server.type === 'stdio') {
-        const { StdioClientTransport } = await import('@modelcontextprotocol/sdk/client/stdio.js');
-        transport = new StdioClientTransport({
-            command: server.command ?? '',
-            args: server.args ?? [],
-            env: server.env,
-        });
+    const hasNewReferences = [...Object.values(server.headerEnv ?? {}), ...Object.values(server.envFrom ?? {})]
+        .some(reference => /^(?:file|store):/.test(reference));
+    // Keep legacy header/environment behavior unchanged. New locators are resolved
+    // only at connection time and never fed back to the registry or config writers.
+    if (hasNewReferences && server.type === 'stdio' && debuglog('child_process').enabled) {
+        throw new Error('MCP file/store stdio credentials require NODE_DEBUG child_process logging to be disabled.');
     }
-    else {
-        if (!server.url) {
-            throw new Error(`storage(fortemi): MCP server "${serverName}" has no URL`);
+    const resolved = hasNewReferences
+        ? await resolveMcpCredentialMaps(server, { ...sensitiveInput, environment })
+        : undefined;
+    const secrets = resolved ? [
+        ...Object.keys(server.envFrom ?? {}).map(key => resolved.env?.[key]),
+        ...Object.keys(server.headerEnv ?? {}).map(key => resolved.headers?.[key]),
+    ].filter((value) => Boolean(value)).sort((a, b) => b.length - a.length) : [];
+    const redact = (text) => secrets.reduce((text, secret) => text.split(secret).join('[REDACTED]'), text);
+    const protect = async (operation) => {
+        try {
+            return await operation();
         }
-        const url = validateRemoteMcpUrl(server.url);
-        const headers = resolveMcpRequestHeaders(server, environment);
-        if (server.type === 'http') {
-            const { StreamableHTTPClientTransport } = await import('@modelcontextprotocol/sdk/client/streamableHttp.js');
-            transport = new StreamableHTTPClientTransport(url, {
-                requestInit: { headers },
-            });
+        catch (error) {
+            throw new Error(redact(error instanceof Error ? error.message : 'MCP transport failed'));
         }
-        else if (server.type === 'sse') {
-            const { SSEClientTransport } = await import('@modelcontextprotocol/sdk/client/sse.js');
-            transport = new SSEClientTransport(url, {
-                requestInit: { headers },
-                eventSourceInit: {
-                    fetch: async (input, init) => {
-                        const merged = new Headers(init?.headers);
-                        for (const [name, value] of Object.entries(headers))
-                            merged.set(name, value);
-                        return fetch(input, { ...init, headers: merged });
-                    },
-                },
+    };
+    const protectResult = (value) => {
+        if (typeof value === 'string')
+            return redact(value);
+        if (Array.isArray(value))
+            return value.map(protectResult);
+        if (value && typeof value === 'object')
+            return Object.fromEntries(Object.entries(value).map(([key, value]) => [redact(key), protectResult(value)]));
+        return value;
+    };
+    try {
+        let transport;
+        if (server.type === 'stdio') {
+            const { StdioClientTransport } = await import('@modelcontextprotocol/sdk/client/stdio.js');
+            transport = new StdioClientTransport({
+                command: server.command ?? '',
+                args: server.args ?? [],
+                env: resolved?.env ?? server.env,
+                ...(hasNewReferences ? { stderr: 'pipe' } : {}),
             });
         }
         else {
-            throw new Error(`storage(fortemi): unsupported MCP transport "${String(server.type)}"`);
+            if (!server.url) {
+                throw new Error(`storage(fortemi): MCP server "${serverName}" has no URL`);
+            }
+            const url = validateRemoteMcpUrl(server.url);
+            const headers = resolved?.headers ?? resolveMcpRequestHeaders(server, environment);
+            if (resolved) {
+                for (const header of Object.keys(server.headerEnv ?? {})) {
+                    if (header.toLowerCase() === 'authorization')
+                        headers[header] = `Bearer ${headers[header]}`;
+                }
+            }
+            if (server.type === 'http') {
+                const { StreamableHTTPClientTransport } = await import('@modelcontextprotocol/sdk/client/streamableHttp.js');
+                transport = new StreamableHTTPClientTransport(url, {
+                    requestInit: { headers },
+                });
+            }
+            else if (server.type === 'sse') {
+                const { SSEClientTransport } = await import('@modelcontextprotocol/sdk/client/sse.js');
+                transport = new SSEClientTransport(url, {
+                    requestInit: { headers },
+                    eventSourceInit: {
+                        fetch: async (input, init) => {
+                            const merged = new Headers(init?.headers);
+                            for (const [name, value] of Object.entries(headers))
+                                merged.set(name, value);
+                            return fetch(input, { ...init, headers: merged });
+                        },
+                    },
+                });
+            }
+            else {
+                throw new Error(`storage(fortemi): unsupported MCP transport "${String(server.type)}"`);
+            }
         }
+        const client = new Client({ name: 'aiwg-storage-fortemi-adapter', version: '1.0.0' }, { capabilities: {} });
+        if (hasNewReferences && server.type === 'stdio') {
+            // The recipient's stderr can contain credentials. Drain without forwarding.
+            transport.stderr?.on('data', () => { });
+        }
+        if (hasNewReferences)
+            await protect(() => client.connect(transport));
+        else
+            await client.connect(transport);
+        return {
+            async callTool(name, args) {
+                const call = async () => unwrapMcpToolResult(await client.callTool({ name, arguments: args }));
+                return hasNewReferences ? protectResult(await protect(call)) : call();
+            },
+            async listTools() {
+                return hasNewReferences ? protectResult(await protect(() => client.listTools())) : client.listTools();
+            },
+            serverVersion() {
+                return hasNewReferences ? protectResult(client.getServerVersion()) : client.getServerVersion();
+            },
+            async close() {
+                if (hasNewReferences)
+                    await protect(() => client.close());
+                else
+                    await client.close();
+            },
+        };
+    }
+    catch (error) {
+        if (!hasNewReferences)
+            throw error;
+        throw new Error(redact(error instanceof Error ? error.message : 'MCP transport failed'));
     }
-    const client = new Client({ name: 'aiwg-storage-fortemi-adapter', version: '1.0.0' }, { capabilities: {} });
-    await client.connect(transport);
-    return {
-        async callTool(name, args) {
-            return unwrapMcpToolResult(await client.callTool({ name, arguments: args }));
-        },
-        async listTools() {
-            return client.listTools();
-        },
-        serverVersion() {
-            return client.getServerVersion();
-        },
-        async close() {
-            await client.close();
-        },
-    };
 };
 //# sourceMappingURL=fortemi.js.map

package/dist/src/tracker/project-inputs.js

@@ -5,6 +5,7 @@
  */
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { helperEnvironment } from '../process/cli-command.mjs';
 import { readAiwgConfig } from '../config/aiwg-config.js';
 const execFileAsync = promisify(execFile);
 /** The project config, or `null` when it is missing or unreadable. */
@@ -20,6 +21,7 @@ export async function readConfig(projectPath) {
 export async function readGitRemoteUrls(projectPath) {
     try {
         const { stdout } = await execFileAsync('git', ['-C', projectPath, 'remote', '-v'], {
+            env: helperEnvironment(),
             maxBuffer: 1024 * 1024,
             timeout: 10_000,
         });

package/dist/src/update/notifier.mjs

@@ -36,6 +36,7 @@ import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { resolveUserConfigDir } from '../config/user-config-dir.mjs';
 import { loadInstallationIdentity } from '../installation/manager.mjs';
+import { helperEnvironment } from '../process/cli-command.mjs';
 
 const CACHE_DIR = resolveUserConfigDir();
 const CACHE_FILE = path.join(CACHE_DIR, 'update-notifier.json');
@@ -261,10 +262,7 @@ const NOTIFIER_CHILD_ENV_ALLOWLIST = Object.freeze([
  * secret-shaped variable" (go/no-go review, blocker 1 tests).
  */
 export function notifierChildEnv(parentEnv = process.env) {
-  const env = {};
-  for (const name of NOTIFIER_CHILD_ENV_ALLOWLIST) {
-    if (parentEnv[name] !== undefined) env[name] = parentEnv[name];
-  }
+  const env = helperEnvironment(parentEnv, NOTIFIER_CHILD_ENV_ALLOWLIST);
   env.AIWG_UPDATE_NOTIFIER_CHILD = '1';
   return env;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.10.6",
+  "version": "2026.10.8",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",

package/tools/agents/providers/base.mjs

@@ -17,10 +17,13 @@ import { createHash } from 'crypto';
 import { createRequire } from 'module';
 import { importImpl } from '../../_resolve-impl.mjs';
 
+import { writeContextFileSync } from './context-write.mjs';
+
 const { parseRuleFrontmatter, inferRuleActivation } = await importImpl(import.meta.url, 'rules/activation.mjs');
 const { resolveRulesInlineBudget, DEFAULT_RULES_INLINE_BUDGET_TOKENS } = await importImpl(import.meta.url, 'rules/inline-budget.mjs');
 export { DEFAULT_RULES_INLINE_BUDGET_TOKENS, parseRuleFrontmatter as parseRuleActivation };
 const { boundedExecFileSync } = await importImpl(import.meta.url, 'process/bounded-child-process.mjs');
+const { helperEnvironment } = await importImpl(import.meta.url, 'process/cli-command.mjs');
 const { extractFrameworkSlug, sameSkillOwner, canDeploySkill, pruneRecordedSkillFiles, releaseSkillOwnership } =
   await importImpl(import.meta.url, 'providers/skill-ownership.mjs');
 export { extractFrameworkSlug, sameSkillOwner, pruneRecordedSkillFiles, releaseSkillOwnership };
@@ -1840,6 +1843,7 @@ export function buildRemotesTopologyBlock(targetDir) {
   function getUrl(remote) {
     try {
       return boundedExecFileSync('git', ['-C', targetDir, 'remote', 'get-url', '--', remote], 'quick', {
+        env: helperEnvironment(),
         stdio: ['ignore', 'pipe', 'ignore'],
         encoding: 'utf8',
       }).trim();
@@ -1949,7 +1953,7 @@ export function createManagedMdFromTemplate(target, destFilename, srcRoot, templ
     if (dryRun) {
       console.log(`[dry-run] Would ${verb} ${destFilename} AIWG-managed section`);
     } else {
-      fs.writeFileSync(destPath, content, 'utf8');
+      writeContextFileSync(destPath, content, 'utf8');
       console.log(`${verb[0].toUpperCase()}${verb.slice(1)} ${destFilename} AIWG-managed section`);
     }
   };

package/tools/agents/providers/claude.mjs

@@ -1,3 +1,4 @@
+import { importImpl } from '../../_resolve-impl.mjs';
 /**
  * Claude Code Provider
  *
@@ -61,6 +62,8 @@ import {
   interpolateContextTokens
 } from './base.mjs';
 
+import { writeContextFileSync } from './context-write.mjs';
+
 // ============================================================================
 // Provider Configuration
 // ============================================================================
@@ -472,7 +475,7 @@ function deployHookFile(targetDir, opts) {
   } else {
     let content = fs.readFileSync(templatePath, 'utf8');
     content = interpolateHookTokens(content, effectiveCounts, targetDir);
-    fs.writeFileSync(hookDest, content, 'utf8');
+    writeContextFileSync(hookDest, content, 'utf8');
     console.log('Created AIWG.md (hook file)');
   }
 
@@ -496,7 +499,7 @@ function deployHookFile(targetDir, opts) {
           }
         }
         lines.splice(insertAt, 0, '', directive, '');
-        fs.writeFileSync(claudeDest, lines.join('\n'), 'utf8');
+        writeContextFileSync(claudeDest, lines.join('\n'), 'utf8');
         console.log('Added @AIWG.md directive to CLAUDE.md');
       }
     }

package/tools/agents/providers/codex.mjs

@@ -1,3 +1,4 @@
+import { importImpl } from '../../_resolve-impl.mjs';
 /**
  * OpenAI Codex Provider
  *
@@ -68,6 +69,8 @@ import {
   resolveAiwgRoot
 } from './base.mjs';
 
+import { writeContextFileSync } from './context-write.mjs';
+
 function resolveCodexHelperRoot(srcRoot) {
   const resolved = resolveAiwgRoot(srcRoot);
   if (resolved) return resolved;
@@ -403,7 +406,7 @@ export function aggregateToAgentsMd(agentFiles, destPath, opts) {
   }
   const out = `${lines.join('\n')}\n`;
   if (opts.dryRun) console.log(`[dry-run] write ${destPath}`);
-  else fs.writeFileSync(destPath, out, 'utf8');
+  else writeContextFileSync(destPath, out, 'utf8');
 
 }
 

package/tools/agents/providers/context-write.mjs

@@ -0,0 +1,28 @@
+/**
+ * Context-file writes for deployment providers (#3037).
+ *
+ * The journaled writer lives in compiled TypeScript. In source-resolution
+ * mode (AIWG_RESOLVE_IMPL_FROM=src without a TS loader) it cannot load, and
+ * read-only consumers of provider modules (for example the remotes topology
+ * block) must still import cleanly. Writes then fail closed with the original
+ * load error, so nothing ever writes context files without the safety layer.
+ */
+import { importImpl } from '../../_resolve-impl.mjs';
+
+// Mirrors CONTEXT_STAGE_ENV in src/smiths/context-pipeline/context-file-safety.ts.
+export const CONTEXT_STAGE_ENV = 'AIWG_CONTEXT_STAGE_LOG';
+
+let loadError = null;
+let writer = null;
+try {
+  writer = await importImpl(import.meta.url, 'smiths/context-pipeline/context-file-safety.js');
+} catch (error) {
+  loadError = error;
+}
+
+export function writeContextFileSync(file, content, encoding) {
+  if (!writer) {
+    throw new Error(`Context-file safety layer is unavailable; refusing to write ${file}`, { cause: loadError });
+  }
+  return writer.writeContextFileSync(file, content, encoding);
+}

package/tools/agents/providers/copilot.mjs

@@ -1,3 +1,4 @@
+import { importImpl } from '../../_resolve-impl.mjs';
 /**
  * GitHub Copilot Provider
  *
@@ -54,6 +55,8 @@ import {
   deploySoulCompanions,
   loadRuntimeModelCatalog
 } from './base.mjs';
+
+import { writeContextFileSync } from './context-write.mjs';
 const modelCatalog = loadRuntimeModelCatalog(staticModelCatalog);
 
 // ============================================================================
@@ -477,14 +480,14 @@ export function createCopilotInstructions(target, srcRoot, dryRun) {
     if (dryRun) {
       console.log(`[dry-run] Would update existing copilot-instructions.md with AIWG section`);
     } else {
-      fs.writeFileSync(destPath, combined, 'utf8');
+      writeContextFileSync(destPath, combined, 'utf8');
       console.log('Updated copilot-instructions.md with AIWG SDLC framework section');
     }
   } else {
     if (dryRun) {
       console.log(`[dry-run] Would create copilot-instructions.md from template`);
     } else {
-      fs.writeFileSync(destPath, template, 'utf8');
+      writeContextFileSync(destPath, template, 'utf8');
       console.log('Created copilot-instructions.md from template');
     }
   }

package/tools/agents/providers/hermes.mjs

@@ -1,3 +1,4 @@
+import { importImpl } from '../../_resolve-impl.mjs';
 /**
  * Hermes Agent Provider
  *
@@ -41,6 +42,8 @@ import {
   stripPlatformsFromContent,
 } from './base.mjs';
 
+import { writeContextFileSync } from './context-write.mjs';
+
 // ============================================================================
 // Hermes home resolution (HERMES_HOME) — #2119
 // ============================================================================
@@ -355,7 +358,7 @@ MCP is optional; \`mcp_aiwg_rule_show\` exposes the same rule catalog.
   if (dryRun) {
     console.log(`[dry-run] Would write AGENTS.md (${output.length} chars, ${Math.round(output.length / 4)} tokens estimated)`);
   } else {
-    fs.writeFileSync(destPath, output, 'utf8');
+    writeContextFileSync(destPath, output, 'utf8');
     const charCount = output.length;
     const tokenEstimate = Math.round(charCount / 4);
     let budgetNote;
@@ -397,7 +400,7 @@ when the full AIWG project context is needed.
   if (dryRun) {
     console.log(`[dry-run] Would write .hermes.md (${body.length} chars)`);
   } else {
-    fs.writeFileSync(destPath, mergeHermesContext(destPath, body, 'routing'), 'utf8');
+    writeContextFileSync(destPath, mergeHermesContext(destPath, body, 'routing'), 'utf8');
     console.log(`  Created .hermes.md (${body.length} chars)`);
   }
   return 1;

package/tools/agents/providers/omp.mjs

@@ -5,6 +5,8 @@ import { createHash } from 'node:crypto';
 import YAML from 'yaml';
 import { importImpl } from '../../_resolve-impl.mjs';
 import { withRuleDeployment, collectFrameworkArtifacts, getAddonFiles, isKernelSkill, listMdFiles, listSkillDirs, normalizeDeploymentMode, resolveAiwgRoot } from './base.mjs';
+
+import { writeContextFileSync } from './context-write.mjs';
 export const name = 'omp';
 export const aliases = ['oh-my-pi'];
 export const paths = { agents: '.omp/agents', commands: '.omp/prompts', skills: '.agents/skills', rules: '.omp/rules' };
@@ -168,7 +170,7 @@ export function createAgentsMd(target, srcRoot, dryRun = false) {
   const content = current.includes(start) && current.includes(end) ? current.slice(0, current.indexOf(start)) + block + current.slice(current.indexOf(end) + end.length) : `${current}${current ? '\n\n' : ''}${block}\n`;
   if (!dryRun) {
     fs.mkdirSync(path.dirname(dest), { recursive: true });
-    if (content !== current) fs.writeFileSync(dest, content);
+    if (content !== current) writeContextFileSync(dest, content);
     const receiptPath = path.join(path.dirname(dest), '.aiwg-manifest.json');
     // Block ownership must never claim the operator's complete context file.
     receipt.managed['AGENTS.md'] = { blockHash: `sha256:${hash(block)}`, source: 'omp-bootstrap', provider: 'omp', transformation: 'managed-block' };

package/tools/agents/providers/rule-delivery.mjs

@@ -19,6 +19,7 @@ const { loadRulePinConfigs, installedRuleCapabilities, resolveRulePins } = await
 const { guardRulesInlineBudget } = await importImpl(import.meta.url, 'rules/inline-budget.mjs');
 const { userConfigFile } = await importImpl(import.meta.url, 'config/user-config-dir.mjs');
 const { resolveProjectAiwgDir } = await importImpl(import.meta.url, 'config/project-artifacts-runtime.mjs');
+import { writeContextFileSync, CONTEXT_STAGE_ENV } from './context-write.mjs';
 const PREPARATION_HOOK = Symbol.for('aiwg.provider-preparation-hook.v1');
 
 export function installRuleDeploymentPreparationHook(hook) {
@@ -190,14 +191,17 @@ export async function prepareRuleDelivery(opts) {
       const key = `${anchor}\0${entry.path}`;
       if (!entryPaths.has(key)) entryPaths.set(key, path.resolve(anchor, entry.path));
       const resolvedPath = entryPaths.get(key);
-      return { ...entry, path: opts.mapInputPath ? opts.mapInputPath(resolvedPath) : resolvedPath };
+      // Canonical IDs hash the indexed package-relative path. Keep it through
+      // resolution; the selected target is anchored to root below.
+      return { ...entry, path: entry.path.startsWith('agentic/code/') ? entry.path
+        : opts.mapInputPath ? opts.mapInputPath(resolvedPath) : resolvedPath };
     });
     let rebuilt = false;
     const cacheDir = process.env.AIWG_RULE_BINDING_INDEX_CACHE;
     const cacheFile = cacheDir && path.join(cacheDir, `${contentHash(opts.logicalInputPath ? opts.logicalInputPath(root) : root)}.json`);
     const buildSourceEntries = async (refresh = false) => {
       if (!refresh && cacheFile) {
-        try { return JSON.parse(fs.readFileSync(cacheFile, 'utf8')).map(entry => ({ ...entry, path: opts.mapInputPath ? opts.mapInputPath(entry.path) : entry.path })); }
+        try { return JSON.parse(fs.readFileSync(cacheFile, 'utf8')).map(entry => ({ ...entry, path: path.isAbsolute(entry.path) && opts.mapInputPath ? opts.mapInputPath(entry.path) : entry.path })); }
         catch (error) {
           if (error.code !== 'ENOENT' && !(error instanceof SyntaxError)) throw error;
         }
@@ -206,7 +210,8 @@ export async function prepareRuleDelivery(opts) {
       const sourceEntries = await collectRuleBindingEntries(root,
         root === opts.srcRoot && !fs.existsSync(path.join(root, 'agentic')) ? '.' : 'agentic/code');
       rebuilt = true;
-      const entries = sourceEntries.map(entry => ({ ...entry, path: path.resolve(root, entry.path) }));
+      const entries = sourceEntries.map(entry => ({ ...entry, path: entry.path.startsWith('agentic/code/')
+        ? entry.path : path.resolve(root, entry.path) }));
       if (cacheFile) {
         fs.mkdirSync(cacheDir, { recursive: true });
         // Workers may publish the same immutable source snapshot concurrently.
@@ -324,7 +329,7 @@ function block(content, body) {
 
 function putStartup(file, body) {
   const content = fs.existsSync(file) ? read(file) : '<!-- aiwg-managed -->\n';
-  put(file, block(content, body));
+  writeContextFileSync(file, block(content, body));
 }
 
 /** Tagged rules bypass legacy aggregate writers. Untagged projections retain their tier policy. */
@@ -337,7 +342,7 @@ function projectRules(opts, provider) {
     const content = read(file);
     const clean = content.replace(/(<!-- AIWG:hermes-context:start -->)([\s\S]*?)(<!-- AIWG:hermes-context:end -->)/g,
       (_, start, body, end) => start + body.replace(/^### Rule: [\s\S]*?(?=^#{1,3} |(?![\s\S]))/gm, '') + end);
-    if (clean !== content) put(file, clean);
+    if (clean !== content) writeContextFileSync(file, clean);
   }
   const nativePaths = ['claude', 'cursor'].includes(provider.name);
   const rulesDir = path.isAbsolute(provider.paths.rules || '') ? provider.paths.rules : path.join(opts.target, provider.paths.rules || `.${provider.name}/rules`);
@@ -487,14 +492,14 @@ function projectRules(opts, provider) {
         if (!fs.existsSync(file)) continue;
         const content = read(file);
         const clean = block(content, '');
-        if (clean !== content) put(file, clean);
+        if (clean !== content) writeContextFileSync(file, clean);
       }
       return;
     }
     if (inlineStartup[provider.name]) {
       // Retire the B1 indirect startup block when migrating to the actual loader.
       const former = path.join(opts.target, 'AIWG.md');
-      if (fs.existsSync(former)) put(former, block(read(former), ''));
+      if (fs.existsSync(former)) writeContextFileSync(former, block(read(former), ''));
       putStartup(path.join(opts.target, inlineStartup[provider.name]), body);
     } else if (provider.name === 'hermes') {
       const dest = path.join(opts.target, 'AGENTS.md');
@@ -916,12 +921,12 @@ function expectedAnchorPaths(paths) {
 /** Adopt a detached worker plan into the coordinator's process-local lease. */
 export function adoptRuleDeploymentPlan(detached, { scratch, target, inputPool, cleanup }) {
   const invalid = () => { throw new Error('Invalid transferred rule deployment plan'); };
-  if (!exactObjectKeys(detached, ['version', 'lease', 'temp', 'target', 'stage', 'rootNames', 'workspaceDirs', 'preimages', 'poolSeal', 'anchors', 'snapshotRoot', 'corpusRoot', 'sourceMappings', 'staged', 'report', 'mappings']) ||
+  if (!exactObjectKeys(detached, ['version', 'lease', 'temp', 'target', 'stage', 'rootNames', 'workspaceDirs', 'preimages', 'poolSeal', 'anchors', 'snapshotRoot', 'corpusRoot', 'sourceMappings', 'staged', 'report', 'mappings', 'contextWrites']) ||
       detached.version !== 1 || typeof detached.lease !== 'string' || !(detached.poolSeal === null || typeof detached.poolSeal === 'string') ||
       !detached.report || typeof detached.report !== 'object' || Array.isArray(detached.report) || typeof scratch !== 'string' || typeof target !== 'string' || typeof cleanup !== 'function') invalid();
   const root = path.resolve(scratch), expectedTarget = path.resolve(target);
   if (path.resolve(detached.temp || '') !== root || path.resolve(detached.stage || '') !== path.join(root, 'project') || path.resolve(detached.target || '') !== expectedTarget) invalid();
-  if (!Array.isArray(detached.staged) || !Array.isArray(detached.mappings) || !Array.isArray(detached.rootNames) || !Array.isArray(detached.preimages) ||
+  if (!Array.isArray(detached.contextWrites) || detached.contextWrites.some(file => typeof file !== 'string' || !within(root, file)) || !Array.isArray(detached.staged) || !Array.isArray(detached.mappings) || !Array.isArray(detached.rootNames) || !Array.isArray(detached.preimages) ||
       !Array.isArray(detached.workspaceDirs) || !Array.isArray(detached.anchors) || !Array.isArray(detached.sourceMappings) ||
       typeof detached.snapshotRoot !== 'string' || !path.isAbsolute(detached.snapshotRoot) || typeof detached.corpusRoot !== 'string' || !path.isAbsolute(detached.corpusRoot)) invalid();
   if (detached.rootNames.some(name => !safeRelative(expectedTarget, name))) invalid();
@@ -1011,6 +1016,10 @@ export async function prepareRuleDeployment(original, provider, deploy) {
   const removeTemp = () => { removeStage(); if (pool) releaseInputPool(pool); };
   const lease = randomUUID();
   stagedCleanups.set(lease, { temp, cleanup: removeTemp, detach: () => { if (pool) releaseInputPool(pool); }, pool, seal: null, transferable });
+  const priorContextStage = process.env[CONTEXT_STAGE_ENV];
+  const contextStageLog = path.join(temp, 'context-writes.jsonl');
+  fs.writeFileSync(contextStageLog, '');
+  process.env[CONTEXT_STAGE_ENV] = contextStageLog;
   const mappings = [];
   const preimages = [...initialPreimages];
   let retained = false;
@@ -1338,7 +1347,8 @@ export async function prepareRuleDeployment(original, provider, deploy) {
       }
     };
     collectDirs(path.join(stage, '.aiwg'), '.aiwg');
-    const plan = { version: 1, lease, temp, target, stage, rootNames, workspaceDirs, preimages, poolSeal: pool?.inventorySeal || null,
+    const contextWrites = [...new Set(fs.readFileSync(contextStageLog, 'utf8').split('\n').filter(Boolean).map(line => JSON.parse(line)))];
+    const plan = { version: 1, lease, temp, target, stage, contextWrites, rootNames, workspaceDirs, preimages, poolSeal: pool?.inventorySeal || null,
       anchors: captureAnchors([target, ...mappings.map(mapping => mapping.from), ...workspaceDirs.map(dir => path.join(target, dir))]),
       snapshotRoot, corpusRoot, sourceMappings, staged: snapshotPreimages([stage, ...mappings.map(mapping => mapping.to)]), report: guarded.report,
       mappings: mappings.map(({ from, to, before }) => ({ from, to, before: [...before] })) };
@@ -1346,6 +1356,7 @@ export async function prepareRuleDeployment(original, provider, deploy) {
     retained = true;
     return plan;
   } finally {
+    if (priorContextStage === undefined) delete process.env[CONTEXT_STAGE_ENV]; else process.env[CONTEXT_STAGE_ENV] = priorContextStage;
     Object.assign(provider.paths, originals);
     if (priorAiwgRoot === undefined) delete process.env.AIWG_ROOT; else process.env.AIWG_ROOT = priorAiwgRoot;
     if (priorRegistry === undefined) delete process.env.AIWG_USER_REGISTRY_PATH; else process.env.AIWG_USER_REGISTRY_PATH = priorRegistry;
@@ -1418,10 +1429,16 @@ export function commitRuleDeploymentPlan(plan) {
           output = Buffer.from(`${JSON.stringify(receipt, null, 2)}\n`);
         }
         fs.mkdirSync(path.dirname(path.join(from, rel)), { recursive: true });
-        fs.writeFileSync(path.join(from, rel), output);
+        if (plan.contextWrites.includes(file)) writeContextFileSync(path.join(from, rel), output);
+        else fs.writeFileSync(path.join(from, rel), output);
       }
     }
-    for (const name of rootNames) if (fs.existsSync(path.join(stage, name))) put(path.join(target, name), normalize(read(path.join(stage, name))));
+    for (const name of rootNames) if (fs.existsSync(path.join(stage, name))) {
+      const output = normalize(read(path.join(stage, name)));
+      if (output === read(path.join(target, name))) continue;
+      const write = plan.contextWrites.includes(path.join(stage, name)) ? writeContextFileSync : put;
+      write(path.join(target, name), output);
+    }
     return plan.report;
   } finally {
     disposeRuleDeploymentPlan(plan);

package/tools/agents/providers/warp.mjs

@@ -1,3 +1,4 @@
+import { importImpl } from '../../_resolve-impl.mjs';
 /**
  * Warp Terminal Provider
  *
@@ -48,6 +49,8 @@ import {
   collectFrameworkArtifacts
 } from './base.mjs';
 
+import { writeContextFileSync } from './context-write.mjs';
+
 // ============================================================================
 // Provider Configuration
 // ============================================================================
@@ -206,7 +209,7 @@ export async function deployWarp(targetDir, srcRoot, opts) {
   // Preserve operator sections even for a forced artifact refresh.
   const output = mergeWarpMd(existing, content, false);
   ensureDir(targetDir, opts.dryRun);
-  if (!opts.dryRun) fs.writeFileSync(dest, output);
+  if (!opts.dryRun) writeContextFileSync(dest, output);
 
 }
 

package/tools/agents/providers/windsurf.mjs

@@ -1,3 +1,4 @@
+import { importImpl } from '../../_resolve-impl.mjs';
 /**
  * Devin Desktop Provider (Windsurf compatibility adapter)
  *
@@ -55,6 +56,8 @@ import {
   deploySoulCompanions
 } from './base.mjs';
 
+import { writeContextFileSync } from './context-write.mjs';
+
 // ============================================================================
 // Provider Configuration
 // ============================================================================
@@ -285,7 +288,7 @@ export function generateAgentsMd(files, destPath, opts) {
   if (dryRun) {
     console.log(`[dry-run] Would write AGENTS.md with ${agents.length} agents`);
   } else {
-    fs.writeFileSync(destPath, output, 'utf8');
+    writeContextFileSync(destPath, output, 'utf8');
     console.log(`Created AGENTS.md with ${agents.length} agents at ${path.relative(process.cwd(), destPath)}`);
   }
 
@@ -409,7 +412,7 @@ export function generateWindsurfRules(srcRoot, target, opts) {
     console.log(`[dry-run] Would write .windsurf/rules/aiwg-orchestration.md (trigger: always_on)`);
   } else {
     ensureDir(rulesDir);
-    fs.writeFileSync(orchestrationPath, output, 'utf8');
+    writeContextFileSync(orchestrationPath, output, 'utf8');
     console.log(`Created .windsurf/rules/aiwg-orchestration.md (trigger: always_on)`);
   }
 
@@ -430,7 +433,7 @@ export function generateWindsurfRules(srcRoot, target, opts) {
   if (dryRun) {
     console.log(`[dry-run] Would write .windsurfrules (deprecated stub)`);
   } else {
-    fs.writeFileSync(stubPath, stubLines.join('\n'), 'utf8');
+    writeContextFileSync(stubPath, stubLines.join('\n'), 'utf8');
     console.log(`Created .windsurfrules (deprecated stub → .windsurf/rules/aiwg-orchestration.md)`);
   }
 }