@aiwg/cli 2026.10.7 → 2026.10.8

package/dist/src/decision/ledger.js

@@ -21,9 +21,9 @@
  * assumption that the artifact root is owned and written by the SAME local
  * user running `aiwg`. It does not and cannot defend against a HOSTILE
  * process running as that same user: such a process already has read/write
- * access to everything the ledger could protect. There is no cross-process
- * lock and no privilege boundary here, by design — adding one would be the
- * "second subsystem" this feature deliberately avoids. Every filesystem
+ * access to everything the ledger could protect. Appenders, rotation and
+ * readers share the existing cross-process directory-lock helper. There is
+ * no privilege boundary here. Every filesystem
  * check below uses only portable Node primitives (no `/proc`, no handle
  * anchoring): `mkdir`/`lstat` for the directory, `open`+`fstat` for the
  * file, with `O_NOFOLLOW` applied when the platform defines it (POSIX; not
@@ -39,25 +39,26 @@
  * single-write atomicity boundary most platforms also honor for `PIPE_BUF`
  * (4096 bytes on Linux): this makes a single, non-interleaved write the
  * overwhelmingly likely outcome for one record, but it is not a guarantee.
- * There is no cross-process append lock, so two concurrent writers can in
- * rare cases interleave and produce one malformed line; `history`/`stats`
- * detect and skip a malformed line (counted, never silently merged into a
- * neighboring record) rather than assuming it is impossible.
+ * The lock covers opening, checking the trailing newline, writing every
+ * byte and closing. Rotation holds that same lock through live-file
+ * replacement. `history`/`stats` count malformed lines as skipped; retention
+ * preserves their original bytes.
  *
  * Recording — attribution resolution and the write — is bounded by a short
  * deadline (`DECISION_LEDGER_RECORD_TIMEOUT_MS`). On timeout, the in-flight
  * attempt is not cancelled (Node has no way to abort an in-flight `open`),
  * so its outcome is genuinely unknown: the record may or may not eventually
  * land. The warning says exactly that ("completion unknown"), and no
- * further stage of that same attempt starts once the deadline has fired
- * (checked before each later `await`), so a slow attribution lookup cannot
- * itself delay the subsequent write past the deadline.
+ * attribution-to-append stage starts once the deadline has fired. An append
+ * already waiting for the ledger lock can still complete after that deadline.
  */
 import { randomUUID, createHash } from 'node:crypto';
 import { constants as fsConstants, createReadStream, existsSync } from 'node:fs';
-import { lstat, mkdir, open } from 'node:fs/promises';
+import { lstat, mkdir, open, readdir, rename, rm } from 'node:fs/promises';
 import { createInterface } from 'node:readline';
-import { join } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { acquireDirectoryLock } from '../artifacts/prebuilt-build-lock.js';
+import { syncDirectory } from '../storage/protected-files.js';
 import { projectAiwgPath, projectAiwgWritePath } from '../config/project-artifacts.js';
 import { redactText } from '../governance/redaction.js';
 import { CanonicalJsonByteEstimator } from './context-plan.js';
@@ -121,6 +122,7 @@ export const MAX_LEDGER_RECORD_BYTES = 4000;
 export const DECISION_LEDGER_RECORD_TIMEOUT_MS = 250;
 const LEDGER_DIR_MODE = 0o700;
 const LEDGER_FILE_MODE = 0o600;
+const LEDGER_LOCK_TIMEOUT_MS = 30_000;
 const IS_WINDOWS = process.platform === 'win32';
 const HAS_O_NOFOLLOW = typeof fsConstants.O_NOFOLLOW === 'number';
 function errorMessage(error) {
@@ -349,8 +351,8 @@ async function ensurePrivateDecisionDir(projectRoot, warn) {
     return decisionDir;
 }
 /**
- * Open (creating if needed) `ledger.jsonl` for append and verify it is safe
- * to write: a regular file with exactly one hard link (rejects a
+ * Open a private ledger/archive file (append by default, read-only for
+ * retention) and verify it is a regular file with exactly one hard link (rejects a
  * pre-planted hard link to an unrelated file, which `O_NOFOLLOW` alone does
  * not catch), and on POSIX owned by the current user with no group/other
  * permission bits. `O_NOFOLLOW` is applied when the platform defines it
@@ -360,7 +362,7 @@ async function ensurePrivateDecisionDir(projectRoot, warn) {
  * check is closed untouched (no chmod, no write) and recording is skipped
  * with exactly one warning naming the reason.
  */
-async function openLedgerFileForAppend(ledgerPath, warn) {
+async function openPrivateLedgerFile(ledgerPath, warn, flags = fsConstants.O_APPEND | fsConstants.O_CREAT | fsConstants.O_WRONLY) {
     try {
         const pre = await lstat(ledgerPath);
         if (pre.isSymbolicLink()) {
@@ -374,10 +376,9 @@ async function openLedgerFileForAppend(ledgerPath, warn) {
             return null;
         }
     }
-    const flags = fsConstants.O_APPEND | fsConstants.O_CREAT | fsConstants.O_WRONLY | (HAS_O_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
     let handle;
     try {
-        handle = await open(ledgerPath, flags, LEDGER_FILE_MODE);
+        handle = await open(ledgerPath, flags | (HAS_O_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0), LEDGER_FILE_MODE);
     }
     catch (error) {
         warn(`warning: cannot open decision ledger file: ${errorMessage(error)}`);
@@ -466,10 +467,13 @@ export async function appendDecisionLedgerRecord(record, options) {
     if (!decisionDir)
         return false;
     const ledgerPath = join(decisionDir, DECISION_LEDGER_FILE_NAME);
-    const handle = await openLedgerFileForAppend(ledgerPath, warn);
-    if (!handle)
-        return false;
+    let release;
+    let handle = null;
     try {
+        release = await lockDecisionLedger(decisionDir);
+        handle = await openPrivateLedgerFile(ledgerPath, warn);
+        if (!handle)
+            return false;
         const prefix = (await needsLeadingNewline(ledgerPath)) ? '\n' : '';
         await writeFully(handle, Buffer.from(prefix + line, 'utf8'), options.writeChunk);
         return true;
@@ -479,7 +483,162 @@ export async function appendDecisionLedgerRecord(record, options) {
         return false;
     }
     finally {
-        await handle.close().catch(() => { });
+        await handle?.close().catch(() => { });
+        await release?.().catch(error => warn(`warning: cannot release decision ledger lock: ${errorMessage(error)}`));
+    }
+}
+function lockDecisionLedger(decisionDir) {
+    return acquireDirectoryLock(join(decisionDir, 'ledger.lock'), {
+        timeoutMs: LEDGER_LOCK_TIMEOUT_MS, pollMs: 10, reclaimDeadOwner: true,
+    });
+}
+export function parseDecisionLedgerRetention(keepLast, all = false) {
+    if (all) {
+        if (keepLast !== undefined)
+            throw new Error('--all cannot be combined with --keep-last');
+        return {};
+    }
+    const match = /^(\d+)(d?)$/.exec(keepLast ?? '90d');
+    const n = match ? Number(match[1]) : NaN;
+    if (!Number.isSafeInteger(n) || n <= 0 || !Number.isSafeInteger(n * (match?.[2] ? 86_400_000 : 1))) {
+        throw new Error('--keep-last must be a positive count or <N>d; rotating everything requires --all');
+    }
+    return match?.[2] ? { ms: n * 86_400_000 } : { count: n };
+}
+function isBeneath(root, target) {
+    const rel = relative(root, target);
+    return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+/** Walk before mkdir: recursive mkdir alone could write through a symlinked ancestor. */
+async function privateArchiveDirectory(root, target, create) {
+    let current = root;
+    for (const part of relative(root, target).split(sep)) {
+        current = join(current, part);
+        if (create) {
+            try {
+                await mkdir(current, { mode: LEDGER_DIR_MODE });
+                if (!IS_WINDOWS)
+                    await syncDirectory(dirname(current));
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+        }
+        let info;
+        try {
+            info = await lstat(current);
+        }
+        catch (error) {
+            if (!create && error.code === 'ENOENT')
+                return false;
+            throw error;
+        }
+        // archive/ is shared with the activity log and may already be readable.
+        // Its decision/ subtree (and any nested directories) must be private.
+        const modeMask = current === join(root, 'archive') ? 0o022 : 0o077;
+        if (!info.isDirectory() || (!IS_WINDOWS && (info.uid !== currentUid() || (info.mode & modeMask) !== 0))) {
+            throw new Error(`Unsafe decision archive directory (requires a private, owned real directory): ${current}`);
+        }
+    }
+    return true;
+}
+/** Retention preserves each raw line, including invalid UTF-8, CRLF and an unterminated final line. */
+export async function rotateDecisionLedger(options) {
+    const retention = parseDecisionLedgerRetention(options.keepLast, options.all);
+    const now = (options.now ?? Date.now)();
+    const artifactRoot = projectAiwgWritePath(options.projectRoot);
+    const archiveRoot = join(artifactRoot, 'archive', 'decision');
+    const archivePath = resolve(artifactRoot, options.to ?? join('archive', 'decision', `${new Date(now).toISOString().replace(/[-:]/g, '').replace('T', '-').replace(/\.\d{3}Z$/, '')}-${randomUUID()}.jsonl`));
+    if (!isBeneath(artifactRoot, archivePath))
+        throw new Error('Archive path must stay inside the resolved artifact root');
+    if (!isBeneath(archiveRoot, archivePath) || !archivePath.endsWith('.jsonl')) {
+        throw new Error('Archive path must be a .jsonl file beneath archive/decision/ in the resolved artifact root');
+    }
+    const fail = (message) => { throw new Error(message); };
+    const decisionDir = await ensurePrivateDecisionDir(options.projectRoot, fail);
+    if (!decisionDir)
+        throw new Error('Cannot access decision ledger directory');
+    const release = await lockDecisionLedger(decisionDir);
+    const ledgerPath = join(decisionDir, DECISION_LEDGER_FILE_NAME);
+    const tempPath = join(decisionDir, `.ledger-${randomUUID()}.tmp`);
+    let archiveCreated = false;
+    try {
+        const live = await openPrivateLedgerFile(ledgerPath, fail, fsConstants.O_RDONLY | fsConstants.O_CREAT);
+        if (!live)
+            throw new Error('Cannot read decision ledger');
+        let content;
+        try {
+            content = await live.readFile();
+        }
+        finally {
+            await live.close();
+        }
+        const lines = [];
+        for (let start = 0; start < content.length;) {
+            const newline = content.indexOf(0x0a, start);
+            const end = newline < 0 ? content.length : newline + 1;
+            const bytes = content.subarray(start, end);
+            let timestamp = null;
+            try {
+                const record = JSON.parse(bytes.toString('utf8'));
+                if (isDecisionLedgerRecord(record))
+                    timestamp = Date.parse(record.timestamp);
+            }
+            catch { /* preserve malformed bytes */ }
+            lines.push({ bytes, timestamp });
+            start = end;
+        }
+        const valid = lines.filter(line => line.timestamp !== null).sort((a, b) => a.timestamp - b.timestamp);
+        const recent = new Set(retention.count === undefined ? [] : valid.slice(-retention.count));
+        const kept = [], archived = [];
+        for (const line of lines) {
+            const keep = !options.all && (line.timestamp === null || (retention.count !== undefined
+                ? recent.has(line) : line.timestamp >= now - retention.ms));
+            (keep ? kept : archived).push(line.bytes);
+        }
+        const result = { archived: archived.length, retained: kept.length,
+            malformed: lines.length - valid.length, archivePath: archived.length ? archivePath : null };
+        if (!archived.length)
+            return result;
+        await privateArchiveDirectory(artifactRoot, dirname(archivePath), true);
+        const archive = await open(archivePath, 'wx', LEDGER_FILE_MODE);
+        archiveCreated = true;
+        try {
+            await writeFully(archive, Buffer.concat(archived));
+            await archive.sync();
+        }
+        finally {
+            await archive.close();
+        }
+        if (!IS_WINDOWS)
+            await syncDirectory(dirname(archivePath));
+        const replacement = await open(tempPath, 'wx', LEDGER_FILE_MODE);
+        try {
+            await writeFully(replacement, Buffer.concat(kept));
+            await replacement.sync();
+        }
+        finally {
+            await replacement.close();
+        }
+        await rename(tempPath, ledgerPath);
+        archiveCreated = false; // Both files now own their respective records.
+        if (!IS_WINDOWS)
+            await syncDirectory(decisionDir);
+        return result;
+    }
+    catch (error) {
+        if (archiveCreated)
+            await rm(archivePath, { force: true }); // Live file is still intact.
+        throw error;
+    }
+    finally {
+        try {
+            await rm(tempPath, { force: true });
+        }
+        finally {
+            await release();
+        }
     }
 }
 /** Never throws: a provider-detection failure (missing config, unreadable capability matrix, …) degrades to "unknown". */
@@ -723,20 +882,57 @@ async function* streamDecisionLedgerLines(path) {
         rl.close();
     }
 }
-/** Streams parsed-and-validated records one at a time; invalid lines yield `null` so callers can count them as skipped. */
-async function* streamDecisionLedgerRecords(projectRoot) {
-    for await (const line of streamDecisionLedgerLines(ledgerReadPath(projectRoot))) {
-        const trimmed = line.trim();
-        if (!trimmed)
-            continue;
-        try {
-            const parsed = JSON.parse(trimmed);
-            yield isDecisionLedgerRecord(parsed) ? parsed : null;
+async function archiveLedgerPaths(artifactRoot, directory = join(artifactRoot, 'archive', 'decision')) {
+    if (!await privateArchiveDirectory(artifactRoot, directory, false))
+        return [];
+    const paths = [];
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+        const target = join(directory, entry.name);
+        if (entry.isSymbolicLink())
+            throw new Error(`Unsafe decision archive symlink: ${target}`);
+        if (entry.isDirectory())
+            paths.push(...await archiveLedgerPaths(artifactRoot, target));
+        else if (entry.name.endsWith('.jsonl')) {
+            const handle = await openPrivateLedgerFile(target, message => { throw new Error(message); }, fsConstants.O_RDONLY);
+            if (!handle)
+                throw new Error(`Unsafe decision archive: ${target}`);
+            await handle.close();
+            paths.push(target);
         }
-        catch {
-            yield null;
+    }
+    return paths.sort();
+}
+/** Streams validated records under the rotation lock; invalid lines yield null. */
+async function* streamDecisionLedgerRecords(projectRoot, includeArchives = false) {
+    const livePath = ledgerReadPath(projectRoot);
+    const decisionDir = dirname(livePath);
+    if (!existsSync(decisionDir))
+        return;
+    if (!(await lstat(decisionDir)).isDirectory())
+        throw new Error('Decision ledger directory must be a real directory');
+    // A single lock also prevents readers from observing the archive and live
+    // replacement at different points in a rotation (duplicates or omissions).
+    const release = await lockDecisionLedger(decisionDir);
+    try {
+        const paths = includeArchives ? [...await archiveLedgerPaths(projectAiwgPath(projectRoot)), livePath] : [livePath];
+        for (const path of paths) {
+            for await (const line of streamDecisionLedgerLines(path)) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    const parsed = JSON.parse(trimmed);
+                    yield isDecisionLedgerRecord(parsed) ? parsed : null;
+                }
+                catch {
+                    yield null;
+                }
+            }
         }
     }
+    finally {
+        await release();
+    }
 }
 function matchesFilters(record, filters) {
     if (filters.since && new Date(record.timestamp).getTime() < filters.since.getTime())
@@ -765,7 +961,7 @@ export function filterDecisionLedgerRecords(records, filters) {
 export async function decisionLedgerHistory(projectRoot, filters = {}) {
     const records = [];
     let skipped = 0;
-    for await (const record of streamDecisionLedgerRecords(projectRoot)) {
+    for await (const record of streamDecisionLedgerRecords(projectRoot, filters.includeArchives)) {
         if (!record) {
             skipped += 1;
             continue;
@@ -897,7 +1093,7 @@ export async function decisionLedgerStats(projectRoot, filters = {}) {
     const weights = decisionSavingsWeights(config?.decision?.ask);
     const groups = new Map();
     let skipped = 0;
-    for await (const record of streamDecisionLedgerRecords(projectRoot)) {
+    for await (const record of streamDecisionLedgerRecords(projectRoot, filters.includeArchives)) {
         if (!record) {
             skipped += 1;
             continue;

package/dist/src/mcp/cli.mjs

@@ -29,7 +29,7 @@ import {
   prepareClaudePermissions,
   resolveToolFilters,
 } from './tool-filters.mjs';
-import { assertCredentialPolicy, CREDENTIAL_POLICIES, installPolicyCheckedServer, redactCredentialArgs, redactCredentialText, redactCredentialRecord, resolveCredentialPolicy } from './credentials.mjs';
+import { assertCredentialPolicy, CREDENTIAL_POLICIES, credentialReferenceInput, validateCredentialReferences, hasSecretLookingLiterals, installPolicyCheckedServer, redactCredentialArgs, redactCredentialText, redactCredentialRecord, resolveCredentialPolicy } from './credentials.mjs';
 import { getMcpInjectionDefinition } from '../providers/provider-definitions.mjs';
 import { manageOmpMcp } from './omp-config.mjs';
 import { claudeDesktopConfigPath, resolveClaudeInstallTarget, legacyClaudeMigration } from './claude-install.mjs';
@@ -176,13 +176,15 @@ Server Options (for add/update):
   --url <url>          Server URL (for http/sse types)
   --type <type>        Server type: http (default), stdio, sse
   --command <cmd>      Command to run (for stdio type)
-  --args <a1,a2,...>   Command arguments (comma-separated, for stdio)
+  --args <a1,a2,...>   Literal command arguments (visible on argv; prefer env/header references)
   --env <K=V,...>      Environment variables (comma-separated K=V pairs)
   --headers <K=V,...>  HTTP headers (comma-separated K=V pairs)
-  --header-env <K=ENV,...>
-                       Resolve HTTP header values from environment variables
-  --env-from <K=ENV,...>
-                       Resolve stdio server variables from environment variables
+  --header-env <K=SOURCE,...>
+                       HTTP header references: ENV_NAME, file:ABSOLUTE_PATH, store:NAME
+  --env-from <K=SOURCE,...>
+                       Stdio variable references (same sources; repeatable)
+                       File/store require the AIWG runtime client; native configs use ENV_NAME
+                       stdin:STORE_NAME / interactive:STORE_NAME save one value to the OS store
   --description <text> Optional description
 
 Inject Options:
@@ -701,6 +703,83 @@ function parseKVPairs(str) {
   return Object.keys(result).length > 0 ? result : undefined;
 }
 
+function parseHeaderPairs(str) {
+  if (!str) return undefined;
+  const entries = str.split(',').flatMap(pair => {
+    const delimiter = pair.search(/[=:]/);
+    return delimiter < 0 ? [] : [[pair.slice(0, delimiter).trim(), pair.slice(delimiter + 1).trim()]];
+  });
+  return entries.length ? Object.fromEntries(entries) : undefined;
+}
+
+/** Validate every occurrence, retaining the existing comma-separated spelling. */
+function parseCredentialReferences(args, flag) {
+  let result;
+  for (let index = 0; index < args.length; index++) {
+    const token = args[index];
+    if (token === '--') break;
+    if (token !== flag && !token.startsWith(`${flag}=`)) continue;
+    const value = token === flag ? args[++index] : token.slice(flag.length + 1);
+    if (!value || value.startsWith('--')) throw new Error(`${flag} requires KEY=ENV_NAME, KEY=file:ABSOLUTE_PATH, or KEY=store:NAME.`);
+    for (const pair of value.split(',')) {
+      const equals = pair.indexOf('=');
+      const key = pair.slice(0, equals).trim();
+      if (equals < 1 || !key) throw new Error(`${flag} requires KEY=ENV_NAME, KEY=file:ABSOLUTE_PATH, or KEY=store:NAME.`);
+      const reference = pair.slice(equals + 1).trim();
+      credentialReferenceInput(reference.replace(/^(?:stdin|interactive):/, 'store:'), flag);
+      result = { ...result, [key]: reference };
+    }
+  }
+  return result;
+}
+
+/** Transient input is saved by the existing raw-value store; registry receives only its name. */
+export async function persistCredentialInputs(server, dependencies) {
+  const inputs = [];
+  for (const field of ['envFrom', 'headerEnv']) {
+    for (const [key, reference] of Object.entries(server[field] || {})) {
+      const match = /^(stdin|interactive):(.+)$/.exec(reference);
+      if (match) {
+        credentialReferenceInput(`store:${match[2]}`, field === 'envFrom' ? '--env-from' : '--header-env');
+        inputs.push({ field, key, source: match[1], name: match[2] });
+      }
+    }
+  }
+  if (inputs.filter(input => input.source === 'stdin').length > 1) {
+    throw new Error('Only one --env-from/--header-env value may use stdin:STORE_NAME per invocation; use file:PATH or store:NAME for additional values.');
+  }
+  const persistent = Object.fromEntries(['envFrom', 'headerEnv'].map(field => [field,
+    Object.fromEntries(Object.entries(server[field] || {}).map(([key, reference]) => [key, reference.replace(/^(?:stdin|interactive):/, 'store:')]))]));
+  validateCredentialReferences(persistent);
+  if (!inputs.length) return;
+  const { resolveSensitiveInput, namedSensitiveStore } = dependencies
+    ?? await import(pathToFileURL(path.join(findOwnPackageRoot(), 'dist', 'src', 'auth', 'sensitive-input.js')).href);
+  // Read/validate all requested inputs before changing the store.
+  const pending = [];
+  for (const input of inputs) {
+    try {
+      const value = await resolveSensitiveInput({ prefix: 'value', [input.source]: true });
+      pending.push({ ...input, value });
+    } catch (error) {
+      const flag = input.field === 'envFrom' ? '--env-from' : '--header-env';
+      const message = error instanceof Error ? error.message : 'MCP credential input failed';
+      throw new Error(message.replace(/--value-(interactive|stdin|file|store|env)(?: <(?:path|name)>)?/g, (_, source) =>
+        `${flag} KEY=${['interactive', 'stdin'].includes(source) ? `${source}:STORE_NAME` : source === 'env' ? 'ENV_NAME' : source === 'file' ? 'file:ABSOLUTE_PATH' : 'store:NAME'}`));
+    }
+  }
+  for (const { field, key, name, value } of pending) {
+    try { await namedSensitiveStore(name).saveSecret(value); }
+    catch { throw new Error('MCP credential input could not be saved to the native store; use --env-from/--header-env with file:PATH or ENV_NAME instead.'); }
+    server[field][key] = `store:${name}`;
+  }
+}
+
+function warnLiteralCredentials(server) {
+  if (hasSecretLookingLiterals(server)) {
+    console.error('Warning: secret-bearing --env/--headers literals are deprecated; argv and saved config expose their values. Use --env-from/--header-env references. See docs/cli/sensitive-values.md.');
+  }
+}
+
 /**
  * Handle `aiwg mcp add <name> [opts]`
  */
@@ -718,8 +797,8 @@ async function handleAdd(args) {
   const argsStr = parseFlag(args, '--args');
   const envStr = parseFlag(args, '--env');
   const headersStr = parseFlag(args, '--headers');
-  const headerEnvStr = parseFlag(args, '--header-env');
-  const envFromStr = parseFlag(args, '--env-from');
+  const headerEnv = parseCredentialReferences(args, '--header-env');
+  const envFrom = parseCredentialReferences(args, '--env-from');
   const description = parseFlag(args, '--description');
 
   if (type === 'stdio' && !command) {
@@ -732,24 +811,28 @@ async function handleAdd(args) {
   }
 
   const registry = new McpServerRegistry();
-  await registry.add({
+  const definition = {
     name,
     type,
     url,
     command,
     args: argsStr ? argsStr.split(',') : undefined,
     env: parseKVPairs(envStr),
-    headers: parseKVPairs(headersStr),
-    headerEnv: parseKVPairs(headerEnvStr),
-    envFrom: parseKVPairs(envFromStr),
+    headers: parseHeaderPairs(headersStr),
+    headerEnv,
+    envFrom,
     description,
-  });
+  };
+  warnLiteralCredentials(definition);
+  if ([...Object.values(definition.envFrom || {}), ...Object.values(definition.headerEnv || {})].some(ref => /^(?:stdin|interactive):/.test(ref)) && await registry.get(name)) throw new Error(`MCP server "${name}" already exists`);
+  await persistCredentialInputs(definition);
+  await registry.add(definition);
 
   console.log(`Added MCP server: ${name}`);
   if (url) console.log(`  URL: ${redactUrlUserinfo(url)}`);
   if (command) console.log(`  Command: ${redactCredentialText(command)}`);
   console.log(`  Type: ${type}`);
-  for (const [key, values] of [['env', parseKVPairs(envStr)], ['headers', parseKVPairs(headersStr)]]) {
+  for (const [key, values] of [['env', definition.env], ['headers', definition.headers]]) {
     if (values) console.log(`  ${key}: ${Object.keys(values).join(', ')}`);
   }
   console.log(`\nUse "aiwg mcp inject --provider <name>" to inject into a provider config.`);
@@ -790,8 +873,8 @@ async function handleUpdate(args) {
   const argsStr = parseFlag(args, '--args');
   const envStr = parseFlag(args, '--env');
   const headersStr = parseFlag(args, '--headers');
-  const headerEnvStr = parseFlag(args, '--header-env');
-  const envFromStr = parseFlag(args, '--env-from');
+  const headerEnv = parseCredentialReferences(args, '--header-env');
+  const envFrom = parseCredentialReferences(args, '--env-from');
   const description = parseFlag(args, '--description');
 
   if (url !== undefined) updates.url = url;
@@ -799,9 +882,9 @@ async function handleUpdate(args) {
   if (command !== undefined) updates.command = command;
   if (argsStr !== undefined) updates.args = argsStr.split(',');
   if (envStr !== undefined) updates.env = parseKVPairs(envStr);
-  if (headersStr !== undefined) updates.headers = parseKVPairs(headersStr);
-  if (headerEnvStr !== undefined) updates.headerEnv = parseKVPairs(headerEnvStr);
-  if (envFromStr !== undefined) updates.envFrom = parseKVPairs(envFromStr);
+  if (headersStr !== undefined) updates.headers = parseHeaderPairs(headersStr);
+  if (headerEnv !== undefined) updates.headerEnv = headerEnv;
+  if (envFrom !== undefined) updates.envFrom = envFrom;
   if (description !== undefined) updates.description = description;
 
   if (Object.keys(updates).length === 0) {
@@ -810,6 +893,9 @@ async function handleUpdate(args) {
   }
 
   const registry = new McpServerRegistry();
+  warnLiteralCredentials(updates);
+  if ([...Object.values(updates.envFrom || {}), ...Object.values(updates.headerEnv || {})].some(ref => /^(?:stdin|interactive):/.test(ref)) && !(await registry.get(name))) throw new Error(`MCP server "${name}" not found`);
+  await persistCredentialInputs(updates);
   await registry.update(name, updates);
   console.log(`Updated MCP server: ${name}`);
   for (const [key, value] of Object.entries(updates)) {

package/dist/src/mcp/credentials.d.mts

@@ -21,6 +21,10 @@ export function isCredentialReferenceValue(value: unknown): boolean;
 export function credentialLikeArgs(args?: string[], options?: { includeReferences?: boolean }): string[];
 export function redactCredentialArgs(args?: string[]): string[] | undefined;
 export function validateEnvReferenceName(name: string): void;
+export function credentialReferenceInput(reference: string, flag?: string): { env?: string; file?: string; store?: string };
+export function validateCredentialReferences(server: Pick<CredentialBearingServer, 'headerEnv' | 'envFrom'>): void;
+export function assertEnvironmentCredentialReferences(server: CredentialBearingServer, provider: string): void;
+export function hasSecretLookingLiterals(server: CredentialBearingServer): boolean;
 export function renderCredentialMaps(
   server: CredentialBearingServer,
   provider: string,

package/dist/src/mcp/credentials.mjs

@@ -3,9 +3,9 @@
  *
  * A registry entry carries credentials in two ways:
  *   - literal values in `env` / `headers` (and OMP `auth` / `oauth` secrets)
- *   - references: `headerEnv` (header -> variable) and `envFrom`
- *     (server variable -> variable), which name a variable the harness
- *     resolves when it starts the server. Only the variable name is written.
+ *   - references: `headerEnv` and `envFrom` name a variable the harness
+ *     resolves, or a file:/store: locator resolved only by AIWG's runtime
+ *     client. Only the locator is written.
  *
  * Each harness spells a reference differently; ENV_REFERENCE_SYNTAX holds the
  * documented form. `null` means the harness documents no interpolation in its
@@ -48,6 +48,39 @@ export function validateEnvReferenceName(name) {
   }
 }
 
+/** Durable locators only: the CLI saves ephemeral stdin/terminal input to the named store. */
+export function credentialReferenceInput(reference, flag = '--env-from/--header-env') {
+  if (typeof reference === 'string') {
+    if (ENV_REFERENCE_NAME.test(reference)) return { env: reference };
+    if (/^store:[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(reference)) return { store: reference.slice(6) };
+    // Absolute paths keep resolution independent of the consuming process's cwd.
+    if (/^file:(?:\/|[A-Za-z]:[\\/])[^\u0000-\u001f\u007f]+$/.test(reference)) return { file: reference.slice(5) };
+  }
+  throw new Error(`${flag} requires KEY=ENV_NAME, KEY=file:ABSOLUTE_PATH, or KEY=store:NAME.`);
+}
+
+export function validateCredentialReferences(server) {
+  for (const [field, flag] of [['headerEnv', '--header-env'], ['envFrom', '--env-from']]) {
+    for (const [key, reference] of Object.entries(server[field] || {})) {
+      if (field === 'headerEnv' ? !key.trim() : !ENV_REFERENCE_NAME.test(key)) {
+        throw new Error(`${flag} requires a valid ${field === 'headerEnv' ? 'header' : 'variable'} name.`);
+      }
+      credentialReferenceInput(reference, flag);
+    }
+  }
+}
+
+/** Native provider configs cannot call AIWG's private-file/native-store resolver. */
+export function assertEnvironmentCredentialReferences(server, provider) {
+  for (const [field, flag] of [['envFrom', '--env-from'], ['headerEnv', '--header-env']]) {
+    for (const reference of Object.values(server[field] || {})) {
+      if (!credentialReferenceInput(reference, flag).env) {
+        throw new Error(`${provider} cannot resolve MCP file/store references. Use ${flag} KEY=ENV_NAME for provider configs; file/store references require the AIWG runtime client.`);
+      }
+    }
+  }
+}
+
 function hasEntries(value) {
   return value !== null && typeof value === 'object' && Object.keys(value).length > 0;
 }
@@ -62,6 +95,7 @@ function hasReferences(server) {
  * harness has no documented syntax for them.
  */
 export function renderCredentialMaps(server, provider) {
+  assertEnvironmentCredentialReferences(server, provider);
   const env = server.env ? { ...server.env } : undefined;
   const headers = server.headers ? { ...server.headers } : undefined;
   if (!hasReferences(server)) return { env, headers };
@@ -116,6 +150,13 @@ function credentialName(key) {
       || CREDENTIAL_QUERY_NAME.test(part.replace(/[_\s]+/g, '-'))));
 }
 
+/** Reuse policy scanner/name rules for the compatibility CLI warning. Never returns values. */
+export function hasSecretLookingLiterals(server) {
+  return ['env', 'headers'].some(field => Object.entries(server[field] || {}).some(([key, value]) =>
+    typeof value === 'string' && literalValue(value, false)
+      && (credentialName(key) || /^(?:cookie|set-cookie)$/i.test(key) || scanCredentialText(value).some(hit => hit.credential))));
+}
+
 function literalValue(value, includeReferences) {
   return value !== '' && (includeReferences || !isCredentialReferenceValue(value));
 }

package/dist/src/mcp/grok-build-config.mjs

@@ -1,3 +1,4 @@
+import { assertEnvironmentCredentialReferences } from './credentials.mjs';
 import { writeConfigAtomic } from './config-file.mjs';
 import { constants } from 'node:fs';
 import { access, lstat, readFile } from 'node:fs/promises';
@@ -20,6 +21,7 @@ function inline(values = {}) {
 }
 
 export function renderGrokMcpServer(server) {
+  assertEnvironmentCredentialReferences(server, 'grok-build');
   if (!server?.name) throw new Error('Grok MCP server name is required');
   const lines = [`[mcp_servers.${key(server.name)}]`];
   if (server.type === 'stdio') {

package/dist/src/mcp/omp-config.mjs

@@ -1,3 +1,4 @@
+import { assertEnvironmentCredentialReferences } from './credentials.mjs';
 import { assertConfigDestination, assertNoSymlinkParents, writeConfigAtomic } from './config-file.mjs';
 import { readFile, mkdir, lstat, unlink, open } from 'node:fs/promises';
 import { dirname, parse, resolve } from 'node:path';
@@ -50,6 +51,7 @@ async function atomic(file, data, options) {
 }
 
 export function ompServerConfig(server) {
+  assertEnvironmentCredentialReferences(server, 'omp');
   const config = {};
   for (const field of ['command', 'args', 'env', 'cwd', 'url', 'headers', 'enabled', 'timeout', 'requestIdFormat', 'auth', 'oauth', 'type']) {
     if (server[field] !== undefined) config[field] = server[field];