@event4u/agent-config 3.3.0 → 4.2.0

package/dist/server/routes/wizard.js

@@ -18,10 +18,10 @@ const LEGACY_USER_MD_REL = '.agent-user.md';
 const LEGACY_SETTINGS_REL = '.agent-settings.yml';
 // Step count mirrors the UI's `WIZARD_STEPS` array in `src/ui/wizard/steps.ts`
 // and the chat-side `~/.claude/skills/onboard/SKILL.md`. Bump in lockstep.
-// Extended mode (road-to-global-only-install § Phase 1) prepends two
-// steps (ai-tools + packs) to ship the unified 9-step flow.
+// Extended mode (road-to-global-only-install § Phase 1) prepends three
+// steps (ai-tools + packs + modules) to ship the unified 10-step flow.
 const DEFAULT_TOTAL_STEPS = 7;
-const EXTENDED_TOTAL_STEPS = 9;
+const EXTENDED_TOTAL_STEPS = 10;
 /**
  * Discovery-manifest path. Resolved from the package root the server
  * was booted with — same artefact the installer reads (ADR-015 locks
@@ -35,7 +35,7 @@ const wizardStateSchema = z.object({
     startedAt: z.string().nullable().default(null),
 });
 // road-to-global-only-install § Phase 1.5 — WizardApplyPayload shape.
-// Mirrors `schemas/wizard-apply-payload.schema.json`; the discriminator
+// Mirrors `internal/schemas/wizard-apply-payload.schema.json`; the discriminator
 // (`schema_version`) selects the variant. Real schema validation lives
 // in install.py — the route only enforces the outer envelope so the
 // bridge spawn surface stays tight.
@@ -149,9 +149,136 @@ async function spawnInstaller(scriptPath, args) {
         });
     });
 }
+/** SSE frame writer — one event per `data:` line, blank-line terminator. */
+function writeFrame(reply, payload) {
+    reply.raw.write(`data: ${JSON.stringify(payload)}\n\n`);
+}
+function streamInstaller(scriptPath, args, onLine, signal) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('python3', [scriptPath, ...args], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, AGENT_CONFIG_NO_UPDATE_CHECK: '1' },
+        });
+        const onAbort = () => {
+            child.kill('SIGTERM');
+        };
+        if (signal !== undefined) {
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener('abort', onAbort, { once: true });
+        }
+        const stderrChunks = [];
+        let buf = '';
+        const handleLine = (line) => {
+            const trimmed = line.trim();
+            if (trimmed.length === 0)
+                return;
+            try {
+                onLine(JSON.parse(trimmed));
+            }
+            catch {
+                // Non-JSON stdout (defensive — real-apply runs with QUIET so
+                // only NDJSON reaches stdout). Drop it rather than corrupt the
+                // SSE stream.
+            }
+        };
+        child.stdout?.on('data', (chunk) => {
+            buf += chunk.toString('utf8');
+            let nl = buf.indexOf('\n');
+            while (nl !== -1) {
+                handleLine(buf.slice(0, nl));
+                buf = buf.slice(nl + 1);
+                nl = buf.indexOf('\n');
+            }
+        });
+        child.stderr?.on('data', (chunk) => stderrChunks.push(chunk));
+        child.once('error', (err) => {
+            if (signal !== undefined)
+                signal.removeEventListener('abort', onAbort);
+            reject(err);
+        });
+        child.once('close', (code) => {
+            if (buf.trim().length > 0)
+                handleLine(buf);
+            if (signal !== undefined)
+                signal.removeEventListener('abort', onAbort);
+            resolve({ exitCode: code ?? 1, stderr: Buffer.concat(stderrChunks).toString('utf8') });
+        });
+    });
+}
+async function spawnBash(scriptPath, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('bash', [scriptPath, ...args], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, AGENT_CONFIG_NO_UPDATE_CHECK: '1' },
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        child.stdout?.on('data', (chunk) => stdoutChunks.push(chunk));
+        child.stderr?.on('data', (chunk) => stderrChunks.push(chunk));
+        child.once('error', reject);
+        child.once('close', (code) => {
+            resolve({
+                exitCode: code ?? 1,
+                stdout: Buffer.concat(stdoutChunks).toString('utf8'),
+                stderr: Buffer.concat(stderrChunks).toString('utf8'),
+            });
+        });
+    });
+}
+function parseScopeGuardOutput(stdout) {
+    const findings = [];
+    let overall = 'OK';
+    let countOk = 0;
+    let countWarn = 0;
+    let countDrift = 0;
+    for (const line of stdout.split('\n')) {
+        if (!line.trim())
+            continue;
+        const parts = line.split('\t');
+        if (parts[0] === 'SUMMARY') {
+            overall = parts[1] ?? 'OK';
+            countOk = Number.parseInt(parts[2] ?? '0', 10);
+            countWarn = Number.parseInt(parts[3] ?? '0', 10);
+            countDrift = Number.parseInt(parts[4] ?? '0', 10);
+            continue;
+        }
+        const [verdict, tool, otherScopePath, otherVersion, thisVersion] = parts;
+        if (verdict !== 'OK' && verdict !== 'WARN' && verdict !== 'DRIFT')
+            continue;
+        findings.push({
+            verdict: verdict,
+            tool: tool ?? '?',
+            otherScopePath: otherScopePath ?? '-',
+            otherVersion: otherVersion ?? '-',
+            thisVersion: thisVersion ?? '-',
+        });
+    }
+    return { overall, countOk, countWarn, countDrift, findings };
+}
+// road-to-configurable-modules § Phase E — wire shape of the
+// `modulesConfig` field on `POST /api/v1/wizard/finish`. Matches the
+// `proposed_block` JSON emitted by `propose_modules_config.py --json`
+// so the wizard can round-trip the detection output untouched. Extra
+// fields are rejected — the persistence helper has its own coercion
+// for older payload shapes, but the wizard always sends the strict
+// shape.
+const modulesConfigSchema = z.object({
+    enabled: z.boolean(),
+    root_paths: z.array(z.string()),
+    namespace_template: z.string().optional(),
+    agent_folder: z.string().optional(),
+    skip_dirs: z.array(z.string()).optional(),
+}).strict();
 export function wizardRoute(opts) {
     const extended = opts.extendedSteps === true;
     const totalSteps = opts.totalSteps ?? (extended ? EXTENDED_TOTAL_STEPS : DEFAULT_TOTAL_STEPS);
+    // Clamp the CLI-provided initial step to the active step range so a
+    // stale `--initial-step=99` cannot shove the UI past the last screen.
+    const rawInitial = opts.initialStep ?? 0;
+    const initialStep = Math.max(0, Math.min(totalSteps - 1, Math.trunc(rawInitial)));
+    const wizardMode = opts.wizardMode ?? null;
     const dryRun = opts.dryRun === true;
     const legacyReadRoot = opts.legacyReadRoot ?? null;
     const projectScopeRoot = opts.projectScopeRoot ?? null;
@@ -166,9 +293,21 @@ export function wizardRoute(opts) {
             // in-progress real run can be previewed.
             const existing = dryRun ? (memState ?? await readState(opts.writeRoot)) : await readState(opts.writeRoot);
             if (existing === null) {
-                return { step: 0, totalSteps, partial: {}, startedAt: null, extendedSteps: extended };
+                return {
+                    step: initialStep,
+                    totalSteps,
+                    partial: {},
+                    startedAt: null,
+                    extendedSteps: extended,
+                    wizardMode,
+                };
             }
-            return { ...existing, totalSteps: existing.totalSteps ?? totalSteps, extendedSteps: extended };
+            return {
+                ...existing,
+                totalSteps: existing.totalSteps ?? totalSteps,
+                extendedSteps: extended,
+                wizardMode,
+            };
         });
         // road-to-global-only-install § Phase 1.2 — Auto-detect endpoint.
         // Reads package signals from the maintainer's CWD (the consumer
@@ -183,6 +322,44 @@ export function wizardRoute(opts) {
             const signals = detectProjectSignals(root);
             return { root, signals };
         });
+        // road-to-configurable-modules § Phase E — Modules detect endpoint.
+        // Read-only scan: spawns `scripts/propose_modules_config.py --json`
+        // against the consumer project so the wizard's modules step can
+        // surface candidate root_paths + a prefilled `modules:` block.
+        // Same root-resolution rule as `/auto-detect` (legacyReadRoot ??
+        // cwd) — the consumer repo the maintainer is running the wizard
+        // against. Gated by extended-mode so the canonical 7-step flow
+        // stays clean.
+        app.get('/api/v1/modules/detect', async (_request, reply) => {
+            if (!extended) {
+                await reply.code(404).send({ error: { code: 'NOT_FOUND', message: 'extended-mode endpoint disabled' } });
+                return reply;
+            }
+            const root = legacyReadRoot ?? process.cwd();
+            const scriptPath = join(opts.packageRoot, 'scripts', 'propose_modules_config.py');
+            try {
+                const result = await spawnInstaller(scriptPath, ['--json', '--project', root]);
+                if (result.exitCode !== 0) {
+                    await reply.code(500).send({
+                        error: { code: 'DETECT_FAILED', message: result.stderr || 'module detect bridge exited non-zero', exitCode: result.exitCode },
+                    });
+                    return reply;
+                }
+                try {
+                    return JSON.parse(result.stdout);
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : 'invalid JSON from module detect bridge';
+                    await reply.code(500).send({ error: { code: 'DETECT_PARSE_FAILED', message } });
+                    return reply;
+                }
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : 'module detect bridge failed';
+                await reply.code(500).send({ error: { code: 'DETECT_FAILED', message } });
+                return reply;
+            }
+        });
         // road-to-global-only-install § Phase 1.3 — Manifest endpoint.
         // Surfaces the locked discovery-manifest (ADR-015) so the UI can
         // render the supported AI IDs + every pack the manifest exposes.
@@ -202,6 +379,123 @@ export function wizardRoute(opts) {
                 return reply;
             }
         });
+        // road-to-clean-skill-distribution-channels § Phase D Step 3 —
+        // harness-expectations endpoint. Returns the three classes the
+        // wizard's final review step renders after install completes.
+        // Content is static + sourced from docs/contracts/harness-expectations.md
+        // (the doc is the long form; this endpoint is the wizard-shaped
+        // short form so the UI does not have to parse markdown).
+        app.get('/api/v1/wizard/harness-expectations', async (_request, reply) => {
+            if (!extended) {
+                await reply.code(404).send({ error: { code: 'NOT_FOUND', message: 'extended-mode endpoint disabled' } });
+                return reply;
+            }
+            return {
+                contractPath: 'docs/contracts/harness-expectations.md',
+                classes: [
+                    {
+                        id: 'sibling-plugins',
+                        title: 'Plugin-namespaced peer skills',
+                        symptom: 'Skills appear under namespaces like codex:* or cc-gemini-plugin:*.',
+                        cause: 'Sibling AI-tool plugins loaded by the harness; not owned by this package.',
+                        action: 'Use the harness’s plugin-list command to identify the source.',
+                    },
+                    {
+                        id: 'deferred-tools',
+                        title: 'Tools deferred behind ToolSearch',
+                        symptom: 'system-reminder mentions “deferred tools … available via ToolSearch”.',
+                        cause: 'Harness defers schema load until needed to protect context budget.',
+                        action: 'Run ToolSearch with select:<name> to load the schema before calling.',
+                    },
+                    {
+                        id: 'duplicate-registration',
+                        title: 'Duplicate skill registration',
+                        symptom: 'Same skill name appears twice in the available-skills list.',
+                        cause: 'Cross-scope install drift (~/.claude/skills/ + ./.claude/skills/ at different versions).',
+                        action: 'Run `task probe:skills` — if findings show DUPLICATE/DRIFT, clean with `bash scripts/cleanup_other_scope.sh --confirm`.',
+                    },
+                ],
+                triage: [
+                    'Run `task probe:skills` first — confirms or rules out class 3.',
+                    'If a vendor: prefix shows, check the harness’s plugin list.',
+                    'deferred-tools reminder = expected; the skill must call ToolSearch.',
+                ],
+            };
+        });
+        // road-to-clean-skill-distribution-channels § Phase C Step 6 —
+        // probe endpoint. Spawns scripts/probe_skill_registration.py with
+        // --format=json so the wizard's final step can surface DUPLICATE /
+        // DRIFT findings before the operator closes the install. Read-only.
+        app.get('/api/v1/wizard/probe', async (_request, reply) => {
+            if (!extended) {
+                await reply.code(404).send({ error: { code: 'NOT_FOUND', message: 'extended-mode endpoint disabled' } });
+                return reply;
+            }
+            const probePath = join(opts.packageRoot, 'scripts', 'probe_skill_registration.py');
+            if (!existsSync(probePath)) {
+                await reply.code(500).send({ error: { code: 'PROBE_MISSING', message: `probe script not found at ${probePath}` } });
+                return reply;
+            }
+            const projectRoot = legacyReadRoot ?? process.cwd();
+            try {
+                const result = await spawnInstaller(probePath, ['--project', projectRoot, '--format=json']);
+                // Default mode exits 0 regardless of findings; --strict (not
+                // passed here) is the only path with a non-zero exit.
+                if (result.exitCode !== 0) {
+                    await reply.code(500).send({
+                        error: { code: 'PROBE_FAILED', message: result.stderr || `probe exited ${result.exitCode}`, exitCode: result.exitCode },
+                    });
+                    return reply;
+                }
+                try {
+                    return JSON.parse(result.stdout);
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : 'invalid JSON from probe';
+                    await reply.code(500).send({ error: { code: 'PROBE_PARSE_FAILED', message } });
+                    return reply;
+                }
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : 'probe failed to spawn';
+                await reply.code(500).send({ error: { code: 'PROBE_FAILED', message } });
+                return reply;
+            }
+        });
+        // road-to-clean-skill-distribution-channels § Phase B Step 4 —
+        // scope-guard endpoint. Spawns scripts/_lib/scope_guard.sh against
+        // the target project root and the user's $HOME, returns a
+        // structured verdict the wizard's first step renders before the
+        // operator picks an install scope. Read-only — no file writes.
+        app.get('/api/v1/wizard/scope-guard', async (_request, reply) => {
+            if (!extended) {
+                await reply.code(404).send({ error: { code: 'NOT_FOUND', message: 'extended-mode endpoint disabled' } });
+                return reply;
+            }
+            const guardPath = join(opts.packageRoot, 'scripts', '_lib', 'scope_guard.sh');
+            if (!existsSync(guardPath)) {
+                await reply.code(500).send({ error: { code: 'GUARD_MISSING', message: `scope_guard.sh not found at ${guardPath}` } });
+                return reply;
+            }
+            const projectRoot = legacyReadRoot ?? process.cwd();
+            try {
+                const result = await spawnBash(guardPath, ['project', opts.packageRoot, projectRoot]);
+                // The script always exits 0; we still pass through stderr
+                // on a non-zero so the UI can surface platform issues.
+                if (result.exitCode !== 0) {
+                    await reply.code(500).send({
+                        error: { code: 'GUARD_FAILED', message: result.stderr || `scope_guard.sh exited ${result.exitCode}`, exitCode: result.exitCode },
+                    });
+                    return reply;
+                }
+                return parseScopeGuardOutput(result.stdout);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : 'scope_guard.sh failed to spawn';
+                await reply.code(500).send({ error: { code: 'GUARD_FAILED', message } });
+                return reply;
+            }
+        });
         app.post('/api/v1/wizard/state', async (request, reply) => {
             const body = (request.body ?? {});
             const parsed = wizardStateSchema.safeParse({
@@ -223,13 +517,17 @@ export function wizardRoute(opts) {
             await writeState(opts.writeRoot, parsed.data);
             return { ok: true };
         });
-        // road-to-global-only-install § Phase 1.5 — Wizard Apply bridge.
-        // Validates the WizardApplyPayload envelope, spills it to a temp
-        // file, and spawns `python3 scripts/install.py --apply-payload
-        // <tmp> --dry-run`. Returns the installer's plan-summary stdout
-        // so the UI can render the preview before the maintainer commits.
-        // Real-apply (non-dry-run) is gated until Phase 1.9 minor release
-        // (kill-switch per D7 — no dual code paths).
+        // road-to-single-install-source-of-truth § Phase 2 — Wizard Apply bridge.
+        // Validates the WizardApplyPayload envelope and spills it to a temp file,
+        // then dispatches `scripts/install.py --apply-payload <tmp>` — the single
+        // installer (D12 / ADR-020). Two modes on the SAME endpoint:
+        //   • dry_run:true  → buffered plan-summary preview (JSON), used by the
+        //     Review step. Adds `--dry-run`.
+        //   • dry_run:false → REAL apply, streamed as SSE. install.py emits NDJSON
+        //     (`{type:"file"|"done"|"error"}`); we map each line to the SSE frame
+        //     vocabulary the UI consumes (`progress`/`done`/`error`) and abort the
+        //     child on client disconnect (Finding #24). CSRF + Host/Origin
+        //     allow-list are enforced by the app-level onRequest hooks.
         app.post('/api/v1/wizard/apply', async (request, reply) => {
             if (!extended) {
                 await reply.code(404).send({ error: { code: 'NOT_FOUND', message: 'extended-mode endpoint disabled' } });
@@ -242,35 +540,114 @@ export function wizardRoute(opts) {
                 });
                 return reply;
             }
-            // Force dry-run on the bridge until Phase 1.9 — protects
-            // against accidental real writes during the rollout window.
-            const payload = { ...parsed.data, dry_run: true };
+            const isDryRun = parsed.data.dry_run === true;
+            const payload = parsed.data;
             const tmpPath = join(tmpdir(), `agent-config-apply-${randomBytes(8).toString('hex')}.json`);
+            const scriptPath = join(opts.packageRoot, 'scripts', 'install.py');
+            if (isDryRun) {
+                // Plan-summary preview — buffered JSON (Review step).
+                try {
+                    await fs.writeFile(tmpPath, JSON.stringify(payload), { mode: 0o600 });
+                    const result = await spawnInstaller(scriptPath, ['--apply-payload', tmpPath, '--dry-run']);
+                    if (result.exitCode !== 0) {
+                        await reply.code(500).send({
+                            error: { code: 'BRIDGE_FAILED', message: result.stderr || 'installer bridge exited non-zero', exitCode: result.exitCode },
+                        });
+                        return reply;
+                    }
+                    return {
+                        ok: true,
+                        dryRun: true,
+                        schemaVersion: payload.schema_version,
+                        preview: result.stdout,
+                    };
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : 'apply bridge failed';
+                    await reply.code(500).send({ error: { code: 'BRIDGE_FAILED', message } });
+                    return reply;
+                }
+                finally {
+                    await fs.unlink(tmpPath).catch(() => undefined);
+                }
+            }
+            // Real apply — SSE stream. Flush headers so the browser opens the
+            // channel immediately.
+            reply.raw.writeHead(200, {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache, no-transform',
+                Connection: 'keep-alive',
+                'X-Accel-Buffering': 'no',
+            });
+            reply.raw.flushHeaders?.();
+            const controller = new AbortController();
+            const onClose = () => {
+                if (!reply.raw.writableEnded)
+                    controller.abort();
+            };
+            reply.raw.on('close', onClose);
+            let written = 0;
+            let total = 0;
+            let sawTerminal = false;
             try {
                 await fs.writeFile(tmpPath, JSON.stringify(payload), { mode: 0o600 });
-                const scriptPath = join(opts.packageRoot, 'scripts', 'install.py');
-                const result = await spawnInstaller(scriptPath, ['--apply-payload', tmpPath, '--dry-run']);
-                if (result.exitCode !== 0) {
-                    await reply.code(500).send({
-                        error: { code: 'BRIDGE_FAILED', message: result.stderr || 'installer bridge exited non-zero', exitCode: result.exitCode },
-                    });
-                    return reply;
+                const result = await streamInstaller(scriptPath, ['--apply-payload', tmpPath], (obj) => {
+                    const t = obj.type;
+                    if (t === 'file') {
+                        written = typeof obj.written === 'number' ? obj.written : written;
+                        total = typeof obj.total === 'number' ? obj.total : total;
+                        writeFrame(reply, {
+                            type: 'progress',
+                            file: obj.file,
+                            status: obj.status,
+                            written,
+                            total,
+                        });
+                    }
+                    else if (t === 'done') {
+                        sawTerminal = true;
+                        writeFrame(reply, { type: 'done', summary: { written, total } });
+                    }
+                    else if (t === 'error') {
+                        sawTerminal = true;
+                        writeFrame(reply, {
+                            type: 'error',
+                            code: typeof obj.code === 'string' ? obj.code : 'E_INSTALL',
+                            message: typeof obj.message === 'string' ? obj.message : 'install failed',
+                            recoverable: false,
+                        });
+                    }
+                }, controller.signal);
+                // install.py exited without a terminal frame (crash / kill): emit
+                // one so the UI never hangs waiting for `done`/`error`.
+                if (!sawTerminal) {
+                    if (result.exitCode === 0) {
+                        writeFrame(reply, { type: 'done', summary: { written, total } });
+                    }
+                    else {
+                        writeFrame(reply, {
+                            type: 'error',
+                            code: 'BRIDGE_FAILED',
+                            message: result.stderr.trim() || `installer exited ${result.exitCode}`,
+                            recoverable: false,
+                        });
+                    }
                 }
-                return {
-                    ok: true,
-                    dryRun: true,
-                    schemaVersion: payload.schema_version,
-                    preview: result.stdout,
-                };
             }
             catch (err) {
-                const message = err instanceof Error ? err.message : 'apply bridge failed';
-                await reply.code(500).send({ error: { code: 'BRIDGE_FAILED', message } });
-                return reply;
+                writeFrame(reply, {
+                    type: 'error',
+                    code: 'E_CRASH',
+                    message: err instanceof Error ? err.message : String(err),
+                    recoverable: false,
+                });
             }
             finally {
+                reply.raw.off('close', onClose);
+                reply.raw.end();
                 await fs.unlink(tmpPath).catch(() => undefined);
             }
+            return reply;
         });
         app.post('/api/v1/wizard/finish', async (request, reply) => {
             const body = (request.body ?? {});
@@ -293,6 +670,28 @@ export function wizardRoute(opts) {
                 });
                 return reply;
             }
+            // road-to-configurable-modules § Phase E — parse the modules
+            // payload. Extended-mode only; legacy 7-step flow never sends
+            // this field. Omitted / null → skip persistence (the team
+            // file stays untouched).
+            const rawModulesConfig = body.modulesConfig;
+            let modulesConfigData = null;
+            if (rawModulesConfig !== undefined && rawModulesConfig !== null) {
+                if (!extended) {
+                    await reply.code(422).send({
+                        error: { code: 'VALIDATION', message: 'modulesConfig requires extended mode', fields: [{ path: 'modulesConfig', message: 'extended-mode only' }] },
+                    });
+                    return reply;
+                }
+                const modulesParsed = modulesConfigSchema.safeParse(rawModulesConfig);
+                if (!modulesParsed.success) {
+                    await reply.code(422).send({
+                        error: { code: 'VALIDATION', message: 'invalid modulesConfig', fields: zodIssuesToFields(modulesParsed.error.issues) },
+                    });
+                    return reply;
+                }
+                modulesConfigData = modulesParsed.data;
+            }
             // road-to-global-only-install § Phase 2.3 — explicit scope opt-in.
             // `'global'` (default) lands writes under the resolved writeRoot
             // (typically `~/.event4u/agent-config/`). `'project'` routes
@@ -332,6 +731,7 @@ export function wizardRoute(opts) {
                             settingsYaml: settingsBody,
                             identity: identityParsed && identityParsed.success ? identityParsed.data : null,
                             userIdentityYaml: identityBody,
+                            modulesConfig: modulesConfigData,
                         },
                     };
                 }
@@ -355,11 +755,47 @@ export function wizardRoute(opts) {
                 // and the flat-root files are independent legacy artefacts
                 // that should still be cleaned. The helper handles that.
                 const migratedFrom = await deleteLegacyArtefacts(legacyReadRoot, effectiveWriteRoot).catch(() => []);
+                // road-to-configurable-modules § Phase E — invoke the
+                // persistence helper after the 2PC commit so a failed
+                // settings write never leaves a half-applied
+                // `.agent-project-settings.yml` behind. Best-effort: a
+                // bridge failure surfaces in `modulesApply.error` but
+                // does NOT roll back the settings commit (the team file
+                // is a separate artefact and the user can re-apply).
+                // Same root rule as `/auto-detect`: legacyReadRoot ??
+                // process.cwd() — that's the consumer repo, not the
+                // server's writeRoot.
+                let modulesAppliedTo = null;
+                let modulesApplyError = null;
+                if (modulesConfigData !== null) {
+                    const projectRoot = legacyReadRoot ?? process.cwd();
+                    const scriptPath = join(opts.packageRoot, 'scripts', 'apply_modules_config.py');
+                    const tmpPath = join(tmpdir(), `agent-config-modules-${randomBytes(8).toString('hex')}.json`);
+                    try {
+                        await fs.writeFile(tmpPath, JSON.stringify(modulesConfigData), { mode: 0o600 });
+                        const result = await spawnInstaller(scriptPath, ['--project', projectRoot, '--input-file', tmpPath]);
+                        if (result.exitCode !== 0) {
+                            modulesApplyError = { code: 'MODULES_APPLY_FAILED', message: result.stderr || 'modules apply bridge exited non-zero', exitCode: result.exitCode };
+                        }
+                        else {
+                            modulesAppliedTo = result.stdout.trim() || null;
+                        }
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : 'modules apply bridge failed';
+                        modulesApplyError = { code: 'MODULES_APPLY_FAILED', message };
+                    }
+                    finally {
+                        await fs.unlink(tmpPath).catch(() => undefined);
+                    }
+                }
                 return {
                     writtenPaths: payloads.map((p) => p.target),
                     txnId,
                     scope,
                     ...(migratedFrom.length > 0 ? { migratedFrom } : {}),
+                    ...(modulesAppliedTo !== null ? { modulesAppliedTo } : {}),
+                    ...(modulesApplyError !== null ? { modulesApplyError } : {}),
                 };
             }
             catch (err) {