@aiwg/cli 2026.8.3 → 2026.8.5

package/dist/src/cli/handlers/mc.js

@@ -14,10 +14,11 @@
 import * as ui from '../ui.js';
 import { promises as fs } from 'node:fs';
 import { join } from 'node:path';
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 // ── Constants ────────────────────────────────────────────────
 const MC_ROOT = '.aiwg/ralph-external/mc';
 const SESSIONS_DIR = join(MC_ROOT, 'sessions');
+const CONTROL_ID_RE = /^[a-zA-Z0-9._-]+$/;
 // ── Helpers ──────────────────────────────────────────────────
 function genId(prefix) {
     return `${prefix}-${Date.now().toString(36)}-${randomBytes(3).toString('hex')}`;
@@ -26,6 +27,8 @@ async function ensureDir(dir) {
     await fs.mkdir(dir, { recursive: true });
 }
 async function readSession(sessionId) {
+    if (!CONTROL_ID_RE.test(sessionId))
+        return null;
     const path = join(SESSIONS_DIR, sessionId, 'session.json');
     try {
         const raw = await fs.readFile(path, 'utf-8');
@@ -35,17 +38,88 @@ async function readSession(sessionId) {
         return null;
     }
 }
-async function writeSession(session) {
+async function writeSession(session, { touch = true } = {}) {
     const dir = join(SESSIONS_DIR, session.id);
     await ensureDir(dir);
-    session.updatedAt = new Date().toISOString();
-    await fs.writeFile(join(dir, 'session.json'), JSON.stringify(session, null, 2));
+    if (touch)
+        session.updatedAt = new Date().toISOString();
+    const destination = join(dir, 'session.json');
+    const temporary = join(dir, `.session.${process.pid}.${randomBytes(4).toString('hex')}.tmp`);
+    await fs.writeFile(temporary, JSON.stringify(session, null, 2));
+    await fs.rename(temporary, destination);
 }
 async function appendLog(sessionId, event) {
     const logPath = join(SESSIONS_DIR, sessionId, 'log.jsonl');
     const entry = JSON.stringify({ ...event, ts: new Date().toISOString() });
     await fs.appendFile(logPath, entry + '\n');
 }
+/**
+ * Apply one durable Mission Control mutation under a cross-process lock.
+ * `expectedUpdatedAt` provides optimistic concurrency and `requestId` makes
+ * retries idempotent across CLI/Cockpit reconnects.
+ */
+async function mutateSession(sessionId, action, target, expectedUpdatedAt, requestId, mutate) {
+    if (!CONTROL_ID_RE.test(sessionId) || !CONTROL_ID_RE.test(target)) {
+        return { ok: false, code: 'target_not_found', message: 'invalid Mission control identifier' };
+    }
+    const dir = join(SESSIONS_DIR, sessionId);
+    await ensureDir(dir);
+    const lockPath = join(dir, '.control.lock');
+    let lock;
+    try {
+        lock = await fs.open(lockPath, 'wx', 0o600);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            return { ok: false, code: 'mission_conflict', message: 'another Mission control mutation is in progress' };
+        }
+        throw error;
+    }
+    try {
+        const session = await readSession(sessionId);
+        if (!session)
+            return { ok: false, code: 'session_not_found', message: `Session not found: ${sessionId}` };
+        if (expectedUpdatedAt && session.updatedAt !== expectedUpdatedAt) {
+            return { ok: false, code: 'mission_conflict', message: `expected revision ${expectedUpdatedAt}; current revision is ${session.updatedAt}` };
+        }
+        if (requestId && session.mutationKeys?.[requestId]) {
+            const prior = session.mutationKeys[requestId];
+            if (prior.action !== action || prior.target !== target) {
+                return { ok: false, code: 'mission_conflict', message: `request id '${requestId}' was already used for another mutation` };
+            }
+            return { ok: true, session, replayed: true };
+        }
+        const errorCode = mutate(session);
+        if (errorCode === 'target_not_found')
+            return { ok: false, code: errorCode, message: `Mission not found: ${target}` };
+        if (errorCode === 'invalid_state')
+            return { ok: false, code: errorCode, message: `Mutation '${action}' is invalid from state '${session.state}'` };
+        if (errorCode === 'capacity')
+            return { ok: false, code: errorCode, message: `Session at capacity (${session.maxMissions} missions)` };
+        const nextUpdatedAt = new Date().toISOString();
+        session.updatedAt = nextUpdatedAt;
+        if (requestId) {
+            session.mutationKeys = { ...(session.mutationKeys ?? {}), [requestId]: { action, target, updatedAt: nextUpdatedAt } };
+        }
+        await writeSession(session, { touch: false });
+        await appendLog(session.id, { event: `control_${action}`, target, requestId: requestId ?? null, replayed: false, revision: session.updatedAt });
+        return { ok: true, session, replayed: false };
+    }
+    finally {
+        await lock.close();
+        await fs.unlink(lockPath).catch(() => undefined);
+    }
+}
+function mutationFlags(args) {
+    return {
+        expectedUpdatedAt: parseFlag(args, '--expected-updated-at'),
+        requestId: parseFlag(args, '--request-id'),
+    };
+}
+function mutationFailure(result) {
+    ui.error(`${result.code}: ${result.message}`);
+    return { exitCode: result.code === 'mission_conflict' ? 3 : 1, message: `${result.code}: ${result.message}` };
+}
 async function listSessions() {
     try {
         const entries = await fs.readdir(SESSIONS_DIR, { withFileTypes: true });
@@ -142,7 +216,9 @@ Queue a mission onto a session. Does NOT execute — use 'aiwg mc run' to launch
                                 (off unless declared; no default K)
   --budget-stop-policy P        completion-wins (default) | budget-wins
   --mode pty-orchestrator       PTY-orchestrator mode (requires --target-agent)
-  --target-agent <id>           Required for --mode pty-orchestrator`,
+  --target-agent <id>           Required for --mode pty-orchestrator
+  --expected-updated-at <time>  Reject stale state with exit 3
+  --request-id <id>             Idempotent dispatch key`,
     run: `Usage: aiwg mc run [<session-id>] [--accept-cost]
 
 Drain queued missions in a session by launching each as a ralph loop. Missions
@@ -160,13 +236,22 @@ Show mission status for a session. Auto-syncs from ralph loop state files.
 Live-monitor mission progress (non-interactive context prints status once).`,
     abort: `Usage: aiwg mc abort <session-id> <mission-id>
 
-Mark a specific mission as aborted.`,
+Mark a specific mission as aborted.
+
+  --expected-updated-at <timestamp>  Reject stale state with exit 3
+  --request-id <id>                  Idempotent mutation key`,
     pause: `Usage: aiwg mc pause [<session-id>]
 
-Pause an active session; running missions transition to 'paused' status.`,
+Pause an active session; running missions transition to 'paused' status.
+
+  --expected-updated-at <timestamp>  Reject stale state with exit 3
+  --request-id <id>                  Idempotent mutation key`,
     resume: `Usage: aiwg mc resume [<session-id>]
 
-Resume a paused session; paused missions transition back to 'running'.`,
+Resume a paused session; paused missions transition back to 'running'.
+
+  --expected-updated-at <timestamp>  Reject stale state with exit 3
+  --request-id <id>                  Idempotent mutation key`,
     stop: `Usage: aiwg mc stop [<session-id>] [--drain]
 
 Shut down a session.
@@ -289,15 +374,11 @@ async function mcDispatch(ctx) {
         ui.error('--mode pty-orchestrator requires --target-agent <agent-id>');
         return { exitCode: 1 };
     }
-    const session = await findActiveSession(sessionId);
-    if (!session) {
+    const selected = await findActiveSession(sessionId);
+    if (!selected) {
         ui.error(sessionId ? `Session not found: ${sessionId}` : 'No active session. Run `aiwg mc start` first.');
         return { exitCode: 1 };
     }
-    if (session.missions.length >= session.maxMissions) {
-        ui.error(`Session at capacity (${session.maxMissions} missions). Increase with --max-missions or stop completed missions.`);
-        return { exitCode: 1 };
-    }
     // #1361: Check project-level parallelism cap. Active missions = running or
     // queued; if at cap, warn but still queue (FIFO behavior — the mission goes
     // into the session as 'queued' and will run when a slot frees up).
@@ -307,7 +388,7 @@ async function mcDispatch(ctx) {
         const cfg = await readAiwgConfig(ctx.cwd || process.cwd());
         if (cfg) {
             const resolved = resolveParallelism(cfg.parallelism, cfg.providers[0]);
-            const activeCount = session.missions.filter(m => m.status === 'running' || m.status === 'queued' || m.status === 'paused').length;
+            const activeCount = selected.missions.filter(m => m.status === 'running' || m.status === 'queued' || m.status === 'paused').length;
             if (activeCount >= resolved.max_parallel_mc_missions) {
                 capWarning = `Active missions (${activeCount}) at or above project parallelism cap (${resolved.max_parallel_mc_missions}). Mission will queue; bump via 'aiwg config set --project parallelism.max_parallel_mc_missions N'.`;
             }
@@ -316,8 +397,11 @@ async function mcDispatch(ctx) {
     catch {
         // Non-fatal — config read failure doesn't block dispatch
     }
+    const flags = mutationFlags(ctx.args);
     const mission = {
-        id: genId('m'),
+        id: flags.requestId
+            ? `m-${createHash('sha256').update(flags.requestId).digest('hex').slice(0, 16)}`
+            : genId('m'),
         objective,
         completion,
         status: 'queued',
@@ -334,27 +418,38 @@ async function mcDispatch(ctx) {
         mode,
         targetAgent: targetAgent || undefined,
     };
-    session.missions.push(mission);
-    await writeSession(session);
-    await appendLog(session.id, {
-        event: 'mission_dispatched',
-        missionId: mission.id,
-        objective,
-        priority,
-        mode,
-        targetAgent,
-        lfdBudgets: {
-            maxTotalTokens,
-            maxOutputTokens,
-            maxToolCalls,
-            maxTotalCost,
-            maxWallClockMinutes,
-            explorationQuota,
-        },
+    const result = await mutateSession(selected.id, 'dispatch', mission.id, flags.expectedUpdatedAt, flags.requestId, session => {
+        if (session.state !== 'active')
+            return 'invalid_state';
+        if (session.missions.length >= session.maxMissions)
+            return 'capacity';
+        session.missions.push(mission);
+        return undefined;
     });
+    if (!result.ok)
+        return mutationFailure(result);
+    if (!result.replayed) {
+        await appendLog(selected.id, {
+            event: 'mission_dispatched',
+            missionId: mission.id,
+            objective,
+            priority,
+            mode,
+            targetAgent,
+            requestId: flags.requestId ?? null,
+            lfdBudgets: {
+                maxTotalTokens,
+                maxOutputTokens,
+                maxToolCalls,
+                maxTotalCost,
+                maxWallClockMinutes,
+                explorationQuota,
+            },
+        });
+    }
     if (capWarning)
         ui.warn(capWarning);
-    ui.success(`Dispatched mission ${mission.id}: ${objective}`);
+    ui.success(`${result.replayed ? 'Replayed dispatch for' : 'Dispatched mission'} ${mission.id}: ${objective}`);
     const modeLabel = mode === 'pty-orchestrator' ? ` | Mode: PTY orchestrator → ${targetAgent}` : '';
     ui.info(`Priority: ${priority} | Max iterations: ${maxIterations}${modeLabel}`);
     const lfdLimits = [
@@ -370,7 +465,7 @@ async function mcDispatch(ctx) {
     }
     // #1439: dispatch alone does NOT execute the mission. Surface the next step
     // so the user knows the queue won't drain on its own.
-    ui.info(`Next: run \`aiwg mc run ${session.id}\` to launch queued missions as ralph loops.`);
+    ui.info(`Next: run \`aiwg mc run ${selected.id}\` to launch queued missions as ralph loops.`);
     return { exitCode: 0, message: mission.id };
 }
 /**
@@ -445,6 +540,18 @@ async function mcRun(ctx) {
     let failed = 0;
     const projectRoot = ctx.cwd || process.cwd();
     const frameworkRoot = ctx.frameworkRoot;
+    const { readAiwgConfig, resolveParallelism } = await import('../../config/aiwg-config.js');
+    const { FileAdmissionStore, SharedHostScheduler } = await import('../../serve/shared-host-scheduler.js');
+    const cfg = await readAiwgConfig(projectRoot).catch(() => null);
+    const provider = cfg?.providers[0] ?? 'unknown';
+    const maxConcurrent = resolveParallelism(cfg?.parallelism, provider).max_parallel_mc_missions;
+    const scheduler = new SharedHostScheduler(new FileAdmissionStore(join(projectRoot, MC_ROOT, 'admission.json')), {
+        maxConcurrent,
+        leaseTtlMs: 5 * 60_000,
+        agingIntervalMs: 30_000,
+        allowPreemption: false,
+        defaultHostQuota: maxConcurrent,
+    });
     for (const mission of queued) {
         if (mission.mode === 'pty-orchestrator') {
             ui.warn(`Mission ${mission.id} mode=pty-orchestrator is not yet wired to mc run; skipping. Use 'aiwg ralph' directly for PTY-orchestrator workflows.`);
@@ -456,6 +563,40 @@ async function mcRun(ctx) {
             skipped += 1;
             continue;
         }
+        const admissionRequestId = mission.admissionState === 'released'
+            ? `${session.id}.${mission.id}.${Date.now().toString(36)}`
+            : mission.admissionRequestId ?? `${session.id}.${mission.id}`;
+        const admissionSubmittedAt = mission.admissionState === 'released'
+            ? new Date().toISOString()
+            : mission.admissionSubmittedAt ?? new Date().toISOString();
+        const admission = scheduler.submit({
+            requestId: admissionRequestId,
+            orchestratorId: session.id,
+            environment: process.env.AIWG_ENVIRONMENT ?? 'default',
+            provider,
+            runtimeKind: 'host',
+            priority: mission.priority === 'critical' ? 100 : mission.priority === 'high' ? 50 : mission.priority === 'low' ? 0 : 10,
+            submittedAt: admissionSubmittedAt,
+            queueTimeoutMs: 24 * 60 * 60_000,
+            preemptible: false,
+            metadata: { missionId: mission.id },
+        });
+        mission.admissionRequestId = admissionRequestId;
+        mission.admissionSubmittedAt = admissionSubmittedAt;
+        mission.admissionState = admission.state;
+        mission.admissionLeaseExpiresAt = admission.leaseExpiresAt;
+        await writeSession(session);
+        if (admission.state !== 'admitted') {
+            await appendLog(session.id, {
+                event: 'mission_admission_queued',
+                missionId: mission.id,
+                admissionRequestId,
+                reason: admission.reason,
+            });
+            ui.info(`Queued ${mission.id}: ${admission.reason}`);
+            skipped += 1;
+            continue;
+        }
         try {
             const result = await launchExternalRalph(frameworkRoot, projectRoot, {
                 objective: mission.objective,
@@ -490,6 +631,9 @@ async function mcRun(ctx) {
             mission.status = 'failed';
             mission.error = msg;
             mission.completedAt = new Date().toISOString();
+            scheduler.release(admissionRequestId);
+            mission.admissionState = 'released';
+            mission.admissionLeaseExpiresAt = undefined;
             await writeSession(session);
             await appendLog(session.id, {
                 event: 'mission_launch_failed',
@@ -522,6 +666,12 @@ async function mcRun(ctx) {
  */
 async function syncMissionsFromRalph(session, projectRoot) {
     let mutated = false;
+    const { readAiwgConfig, resolveParallelism } = await import('../../config/aiwg-config.js');
+    const { FileAdmissionStore, SharedHostScheduler } = await import('../../serve/shared-host-scheduler.js');
+    const cfg = await readAiwgConfig(projectRoot).catch(() => null);
+    const provider = cfg?.providers[0] ?? 'unknown';
+    const maxConcurrent = resolveParallelism(cfg?.parallelism, provider).max_parallel_mc_missions;
+    const scheduler = new SharedHostScheduler(new FileAdmissionStore(join(projectRoot, MC_ROOT, 'admission.json')), { maxConcurrent, leaseTtlMs: 5 * 60_000, agingIntervalMs: 30_000, allowPreemption: false, defaultHostQuota: maxConcurrent });
     for (const mission of session.missions) {
         if (mission.status !== 'running')
             continue;
@@ -560,6 +710,25 @@ async function syncMissionsFromRalph(session, projectRoot) {
                     mission.error = state.error;
                 }
                 mutated = true;
+                if (mission.admissionRequestId) {
+                    try {
+                        scheduler.release(mission.admissionRequestId);
+                    }
+                    catch { /* already expired or released */ }
+                    mission.admissionState = 'released';
+                    mission.admissionLeaseExpiresAt = undefined;
+                }
+            }
+            else if (mission.admissionRequestId) {
+                try {
+                    const renewed = scheduler.renew(mission.admissionRequestId);
+                    mission.admissionState = renewed.state;
+                    mission.admissionLeaseExpiresAt = renewed.leaseExpiresAt;
+                    mutated = true;
+                }
+                catch {
+                    // An expired lease is reconciled on the next run; status remains best-effort.
+                }
             }
         }
         catch {
@@ -662,58 +831,85 @@ async function mcAbort(ctx) {
         ui.error('Usage: aiwg mc abort <session-id> <mission-id>');
         return { exitCode: 1 };
     }
-    const session = await readSession(sessionId);
-    if (!session) {
-        ui.error(`Session not found: ${sessionId}`);
-        return { exitCode: 1 };
-    }
-    const mission = session.missions.find(m => m.id === missionId);
-    if (!mission) {
-        ui.error(`Mission not found: ${missionId}`);
-        return { exitCode: 1 };
+    const flags = mutationFlags(ctx.args);
+    const result = await mutateSession(sessionId, 'cancel', missionId, flags.expectedUpdatedAt, flags.requestId, session => {
+        const mission = session.missions.find(m => m.id === missionId);
+        if (!mission)
+            return 'target_not_found';
+        if (mission.status === 'done' || mission.status === 'failed' || mission.status === 'aborted')
+            return 'invalid_state';
+        mission.status = 'aborted';
+        mission.completedAt = new Date().toISOString();
+        return undefined;
+    });
+    if (!result.ok)
+        return mutationFailure(result);
+    if (!result.replayed) {
+        const mission = result.session.missions.find(candidate => candidate.id === missionId);
+        if (mission?.admissionRequestId) {
+            try {
+                const projectRoot = ctx.cwd || process.cwd();
+                const { readAiwgConfig, resolveParallelism } = await import('../../config/aiwg-config.js');
+                const { FileAdmissionStore, SharedHostScheduler } = await import('../../serve/shared-host-scheduler.js');
+                const cfg = await readAiwgConfig(projectRoot).catch(() => null);
+                const provider = cfg?.providers[0] ?? 'unknown';
+                const maxConcurrent = resolveParallelism(cfg?.parallelism, provider).max_parallel_mc_missions;
+                const scheduler = new SharedHostScheduler(new FileAdmissionStore(join(projectRoot, MC_ROOT, 'admission.json')), { maxConcurrent, leaseTtlMs: 5 * 60_000, agingIntervalMs: 30_000, allowPreemption: false, defaultHostQuota: maxConcurrent });
+                scheduler.cancel(mission.admissionRequestId);
+            }
+            catch {
+                // The mission state is authoritative; lease expiry provides recovery.
+            }
+        }
     }
-    mission.status = 'aborted';
-    mission.completedAt = new Date().toISOString();
-    await writeSession(session);
-    await appendLog(session.id, { event: 'mission_aborted', missionId });
-    ui.success(`Aborted mission: ${missionId}`);
-    return { exitCode: 0 };
+    ui.success(`${result.replayed ? 'Replayed' : 'Aborted'} mission: ${missionId}`);
+    return { exitCode: 0, message: JSON.stringify({ ok: true, replayed: result.replayed, updated_at: result.session.updatedAt }) };
 }
 async function mcPause(ctx) {
     const positional = getPositionalArgs(ctx.args);
     const sessionId = positional[0];
-    const session = await findActiveSession(sessionId);
-    if (!session) {
+    const selected = await findActiveSession(sessionId);
+    if (!selected) {
         ui.error('No active session to pause.');
         return { exitCode: 1 };
     }
-    session.state = 'paused';
-    for (const m of session.missions) {
-        if (m.status === 'running')
-            m.status = 'paused';
-    }
-    await writeSession(session);
-    await appendLog(session.id, { event: 'session_paused' });
-    ui.success(`Paused session: ${session.id}`);
-    return { exitCode: 0 };
+    const flags = mutationFlags(ctx.args);
+    const result = await mutateSession(selected.id, 'pause', selected.id, flags.expectedUpdatedAt, flags.requestId, session => {
+        if (session.state !== 'active')
+            return 'invalid_state';
+        session.state = 'paused';
+        for (const mission of session.missions)
+            if (mission.status === 'running')
+                mission.status = 'paused';
+        return undefined;
+    });
+    if (!result.ok)
+        return mutationFailure(result);
+    ui.success(`${result.replayed ? 'Replayed pause for' : 'Paused'} session: ${selected.id}`);
+    return { exitCode: 0, message: JSON.stringify({ ok: true, replayed: result.replayed, updated_at: result.session.updatedAt }) };
 }
 async function mcResume(ctx) {
     const positional = getPositionalArgs(ctx.args);
     const sessionId = positional[0];
-    const session = await findActiveSession(sessionId);
-    if (!session || session.state !== 'paused') {
+    const selected = await findActiveSession(sessionId);
+    if (!selected || selected.state !== 'paused') {
         ui.error('No paused session to resume.');
         return { exitCode: 1 };
     }
-    session.state = 'active';
-    for (const m of session.missions) {
-        if (m.status === 'paused')
-            m.status = 'running';
-    }
-    await writeSession(session);
-    await appendLog(session.id, { event: 'session_resumed' });
-    ui.success(`Resumed session: ${session.id}`);
-    return { exitCode: 0 };
+    const flags = mutationFlags(ctx.args);
+    const result = await mutateSession(selected.id, 'resume', selected.id, flags.expectedUpdatedAt, flags.requestId, session => {
+        if (session.state !== 'paused')
+            return 'invalid_state';
+        session.state = 'active';
+        for (const mission of session.missions)
+            if (mission.status === 'paused')
+                mission.status = 'running';
+        return undefined;
+    });
+    if (!result.ok)
+        return mutationFailure(result);
+    ui.success(`${result.replayed ? 'Replayed resume for' : 'Resumed'} session: ${selected.id}`);
+    return { exitCode: 0, message: JSON.stringify({ ok: true, replayed: result.replayed, updated_at: result.session.updatedAt }) };
 }
 async function mcStop(ctx) {
     const positional = getPositionalArgs(ctx.args);
@@ -912,6 +1108,7 @@ const subcommands = {
     status: mcStatus,
     watch: mcWatch,
     abort: mcAbort,
+    cancel: mcAbort,
     pause: mcPause,
     resume: mcResume,
     stop: mcStop,
@@ -945,7 +1142,7 @@ function showMcHelp() {
                                   Cost gate warns/refuses above ~$5 estimate
     status [<id>] [--json]        View mission status dashboard
     watch [<id>]                  Live monitor (streaming)
-    abort <session> <mission>     Abort a specific mission
+    abort|cancel <session> <mission> Abort a specific mission
     pause [<id>]                  Pause active session
     resume [<id>]                 Resume paused session
     stop [<id>] [--drain]         Shut down session

package/dist/src/extensions/claude-hooks-installer.js

@@ -34,9 +34,12 @@ import * as path from 'node:path';
  * Per the script-source comments at agentic/code/addons/aiwg-hooks/hooks/.
  */
 const HOOK_SCRIPTS = [
-    { file: 'aiwg-permissions.cjs', events: ['PermissionRequest'] },
-    { file: 'aiwg-session.cjs', events: ['SessionStart'] },
-    { file: 'aiwg-trace.cjs', events: ['SubagentStart', 'SubagentStop'] },
+    { file: 'aiwg-permissions.cjs', events: { PermissionRequest: undefined } },
+    { file: 'aiwg-session.cjs', events: { SessionStart: undefined } },
+    {
+        file: 'aiwg-trace.cjs',
+        events: { SubagentStart: 'start', SubagentStop: 'stop' },
+    },
 ];
 /**
  * Migrate a legacy array-shaped `hooks` field to the object form Claude
@@ -185,9 +188,10 @@ export async function installAiwgHooks(opts) {
         // embedded script path POSIX-style on every host: native Windows
         // backslashes are interpreted as escapes and collapse into a nonexistent
         // path such as `.claudehooksaiwg-session.cjs` (#133).
-        const command = `node ${path.posix.join('.claude', 'hooks', file)}`;
+        const script = path.posix.join('.claude', 'hooks', file);
         const hookId = file.replace(/\.(cjs|js)$/, '');
-        for (const event of events) {
+        for (const [event, argument] of Object.entries(events)) {
+            const command = `node ${script}${argument ? ` ${argument}` : ''}`;
             if (!hooksObj[event])
                 hooksObj[event] = [];
             const groups = hooksObj[event];

package/dist/src/mcp/cli.mjs

@@ -47,6 +47,8 @@ Server Options (for add/update):
   --args <a1,a2,...>   Command arguments (comma-separated, for stdio)
   --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
   --description <text> Optional description
 
 Inject Options:
@@ -62,6 +64,8 @@ Serve Options:
 Examples:
   # Define MCP servers
   aiwg mcp add fortemi --url https://memory.s9.internal/mcp --type http
+  aiwg mcp add fortemi-enterprise --url https://memory.example.internal/mcp --type http \
+    --header-env Authorization=AIWG_FORTEMI_TOKEN
   aiwg mcp add gitea --url https://mcp-gitea.integrolabs.net/mcp
   aiwg mcp add mytools --type stdio --command npx --args mcp-server-mytools
 
@@ -498,6 +502,7 @@ 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 description = parseFlag(args, '--description');
 
   if (type === 'stdio' && !command) {
@@ -518,6 +523,7 @@ async function handleAdd(args) {
     args: argsStr ? argsStr.split(',') : undefined,
     env: parseKVPairs(envStr),
     headers: parseKVPairs(headersStr),
+    headerEnv: parseKVPairs(headerEnvStr),
     description,
   });
 
@@ -564,6 +570,7 @@ 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 description = parseFlag(args, '--description');
 
   if (url !== undefined) updates.url = url;
@@ -572,6 +579,7 @@ async function handleUpdate(args) {
   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 (description !== undefined) updates.description = description;
 
   if (Object.keys(updates).length === 0) {
@@ -608,6 +616,10 @@ async function handleList() {
     console.log(`    Type: ${server.type}`);
     if (server.url) console.log(`    URL: ${server.url}`);
     if (server.command) console.log(`    Command: ${server.command}${server.args ? ' ' + server.args.join(' ') : ''}`);
+    if (server.headerEnv) {
+      const refs = Object.entries(server.headerEnv).map(([header, envName]) => `${header}←${envName}`);
+      console.log(`    Credential refs: ${refs.join(', ')}`);
+    }
     if (server.description) console.log(`    Description: ${server.description}`);
     if (server.injectedProviders && server.injectedProviders.length > 0) {
       console.log(`    Injected into: ${server.injectedProviders.join(', ')}`);

package/dist/src/mcp/registry.js

@@ -20,6 +20,16 @@ const DEFAULT_REGISTRY = {
     kind: 'McpServerRegistry',
     servers: {},
 };
+const ENV_REFERENCE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function validateCredentialReferences(def) {
+    for (const [header, envName] of Object.entries(def.headerEnv ?? {})) {
+        if (!header.trim())
+            throw new Error('MCP header-env header name must not be empty');
+        if (!ENV_REFERENCE_NAME.test(envName)) {
+            throw new Error(`Invalid MCP header environment variable reference "${envName}"`);
+        }
+    }
+}
 export class McpServerRegistry {
     configDir;
     cache = null;
@@ -59,6 +69,7 @@ export class McpServerRegistry {
     }
     /** Add a new MCP server definition */
     async add(def) {
+        validateCredentialReferences(def);
         const data = await this.load();
         if (data.servers[def.name]) {
             throw new Error(`Server "${def.name}" already exists. Use "update" to modify it.`);
@@ -86,12 +97,14 @@ export class McpServerRegistry {
         if (!data.servers[name]) {
             throw new Error(`Server "${name}" not found.`);
         }
-        data.servers[name] = {
+        const next = {
             ...data.servers[name],
             ...updates,
             name, // preserve original name
             updatedAt: new Date().toISOString(),
         };
+        validateCredentialReferences(next);
+        data.servers[name] = next;
         await this.save();
     }
     /** Get a specific server definition */