@aiwg/cli 2026.8.2 → 2026.8.4

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/cli/handlers/subcommands.js

@@ -1062,6 +1062,7 @@ export const installPluginHandler = {
         const runner = createScriptRunner(frameworkRoot);
         return runner.run("tools/plugin/plugin-installer-cli.mjs", ctx.args, {
             cwd: ctx.cwd,
+            env: { AIWG_ROOT: frameworkRoot },
         });
     },
 };

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

@@ -31,7 +31,7 @@ import { PROJECT_LOCAL_TYPE_TO_DIR } from '../../extensions/project-local-paths.
 import { buildUpstreamRegistry } from '../../extensions/upstream-registry.js';
 import { resolveShadows, formatShadowReport, } from '../../extensions/shadow-resolver.js';
 import { appendProjectLocalActivity, emitDiscoverEventsDeduped, } from '../../extensions/project-local-activity.js';
-import { hashBundleArtifacts } from '../../extensions/project-local-remove.js';
+import { hashBundleArtifacts, hashDeployedBundleArtifacts, } from '../../extensions/project-local-remove.js';
 import { installAiwgHooks } from '../../extensions/claude-hooks-installer.js';
 import { detectScope, mirrorToUserScope, rejectOpenClawProjectScope, USER_SCOPE_PATHS, } from '../scope-resolver.js';
 import { maybeWarnProjectIsolation } from '../project-isolation/index.js';
@@ -1185,6 +1185,7 @@ async function deployProjectLocalBundles(opts) {
                 // #1037 — record per-artifact source hashes so `aiwg remove` can
                 // detect pristine vs mutated vs replaced deployed files.
                 const artifactHashes = await hashBundleArtifacts(bundle.artifactPath);
+                const deployedArtifactHashes = await hashDeployedBundleArtifacts(projectDir, provider, artifactHashes);
                 const updated = updateInstalled(config, bundle.id, provider, result.counts, {
                     version: bundle.manifest.version,
                     source: 'project-local',
@@ -1193,6 +1194,7 @@ async function deployProjectLocalBundles(opts) {
                     localType: bundle.type,
                     manifestVersion: bundle.manifest.manifestVersion,
                     artifactHashes,
+                    deployedArtifactHashes,
                 });
                 await writeAiwgConfig(projectDir, updated);
             }

package/dist/src/config/aiwg-config.js

@@ -784,6 +784,10 @@ export function updateInstalled(config, name, provider, counts, opts) {
             existing.manifestVersion = opts.manifestVersion;
         if (opts.artifactHashes)
             existing.artifactHashes = opts.artifactHashes;
+        if (opts.deployedArtifactHashes) {
+            existing.deployedArtifactHashes ??= {};
+            existing.deployedArtifactHashes[provider] = opts.deployedArtifactHashes;
+        }
     }
     else {
         // Clear stale project-local fields if a previously project-local entry is
@@ -792,6 +796,7 @@ export function updateInstalled(config, name, provider, counts, opts) {
         delete existing.localType;
         delete existing.manifestVersion;
         delete existing.artifactHashes;
+        delete existing.deployedArtifactHashes;
     }
     config.installed[name] = existing;
     return config;

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/extensions/project-local-doctor.js

@@ -12,8 +12,7 @@
  * @design @.aiwg/architecture/design-doctor-log-promote.md
  * @implements #1037
  */
-import { join, resolve } from 'path';
-import { homedir } from 'os';
+import { join } from 'path';
 import { discoverProjectLocalBundles } from './project-local-discovery.js';
 import { buildUpstreamRegistry } from './upstream-registry.js';
 import { resolveShadows } from './shadow-resolver.js';
@@ -22,6 +21,7 @@ import { sha256OfFileRawAndNormalized } from './managed-marker.js';
 import { projectAiwgPath } from '../config/project-artifacts.js';
 import { projectRelativePathIfInside } from './project-local-paths.js';
 import { auditProjectQuickref } from './project-quickref.js';
+import { artifactHashesForProvider, candidateDeployedPaths } from './project-local-remove.js';
 /**
  * Hash a deployed file in raw and managed-marker-normalized forms. Returns
  * null on read errors (e.g., file missing — caller treats as
@@ -48,23 +48,6 @@ const TYPE_DIR = {
     plugin: 'plugins',
     provider: 'providers',
 };
-// Per PUW-026 (#1127): home-deploying providers get absolute prefixes so
-// `resolve(projectDir, prefix)` correctly produces the home-rooted path
-// (resolve treats absolute paths as authoritative). Previously these were
-// `null`, which silently skipped lifecycle operations against home-deployed
-// project-local bundles.
-const PROVIDER_PREFIX = {
-    claude: '.claude',
-    cursor: '.cursor',
-    factory: '.factory',
-    opencode: '.opencode',
-    windsurf: '.windsurf',
-    warp: '.warp',
-    codex: '.codex',
-    copilot: '.github',
-    openclaw: resolve(homedir(), '.openclaw'),
-    hermes: resolve(homedir(), '.hermes'),
-};
 export async function buildProjectLocalDoctorSection(opts) {
     const { projectDir, frameworkRoot, config, quiet = false } = opts;
     const discovery = await discoverProjectLocalBundles(projectDir);
@@ -165,18 +148,19 @@ export async function buildProjectLocalDoctorSection(opts) {
             const entry = config.installed[bundle.id];
             if (!entry || entry.source !== 'project-local')
                 continue;
-            const hashes = entry.artifactHashes;
-            if (!hashes) {
+            if (!entry.artifactHashes && !entry.deployedArtifactHashes) {
                 unhashedSeen = true;
                 continue;
             }
             for (const provider of Object.keys(entry.deployedTo)) {
-                const prefix = PROVIDER_PREFIX[provider];
-                if (!prefix)
-                    continue;
+                const hashes = artifactHashesForProvider(entry, provider);
                 for (const [sourceRel, expectedHash] of Object.entries(hashes)) {
-                    const deployedAbs = resolve(projectDir, `${prefix}/${sourceRel}`);
-                    const actualHash = await hashDeployed(deployedAbs);
+                    let actualHash = null;
+                    for (const deployedAbs of candidateDeployedPaths(projectDir, provider, sourceRel)) {
+                        actualHash = await hashDeployed(deployedAbs);
+                        if (actualHash)
+                            break;
+                    }
                     if (actualHash === null) {
                         // Missing — not drift, deploy is just absent
                         continue;