create-principles-disciple 1.101.0 → 1.102.0

package/console/dist/server/index.js

@@ -17,6 +17,7 @@ import { handleGovernanceRoute, disposeGovernanceModels } from './routes/governa
 import { handleEvidenceChainRoute, disposeEvidenceChainModels } from './routes/evidence-chain.js';
 import { handleIntentRoute, disposeIntentModels } from './routes/intent.js';
 import { handleIntentDecisionsRoute, disposeIntentDecisionModels } from './routes/intent-decisions.js';
+import { handleOnboardingRoute, disposeOnboardingModels } from './routes/onboarding.js';
 import { createWorkspacesRoutes } from './routes/workspaces.js';
 import { handleUpdateRoute } from './routes/update.js';
 import { handleUpdateHistoryRoute } from './routes/update-history.js';
@@ -229,6 +230,7 @@ async function closeServices() {
     disposeEvidenceChainModels();
     disposeIntentModels();
     disposeIntentDecisionModels();
+    disposeOnboardingModels();
 }
 // ── Route handler ───────────────────────────────────────────────────────────
 function handleRequest(services) {
@@ -340,6 +342,13 @@ function handleRequest(services) {
                 asyncHandler(() => handleIntentDecisionsRoute(req, res, services.workspaceDir, subPath))(req, res);
                 return;
             }
+            // Onboarding wizard: POST /api/v1/onboarding/run-demo — spawns `pd demo story-a`
+            // (spec 2026-06-30-new-user-onboarding-design.md §6.3 改动 5)
+            if (urlPath === '/api/v1/onboarding' || urlPath.startsWith('/api/v1/onboarding/')) {
+                const subPath = urlPath === '/api/v1/onboarding' ? '' : urlPath.slice('/api/v1/onboarding'.length);
+                asyncHandler(() => handleOnboardingRoute(req, res, { workspaceDir: services.workspaceDir, subPath }))(req, res);
+                return;
+            }
             // PRI-331: GET /api/v1/evidence-chain
             if (urlPath === '/api/v1/evidence-chain') {
                 asyncHandler(() => handleEvidenceChainRoute(req, res, services.workspaceDir))(req, res);

package/console/dist/server/models/ActivationsConsoleModel.d.ts

@@ -1,3 +1,12 @@
+/**
+ * PRI-491 — owner-observable activation record.
+ *
+ * Mirrors the CLI's `AnnotatedActivation` so the Console surfaces the same
+ * mode / status / contextVersion / evidenceRefs / nextAction fields the owner
+ * sees in `pd activation list`. Without this enrichment the Console would
+ * hide suspended-by-flag state, silently showing v2 activations as "active"
+ * even when the rulecode_context_v2 flag is off.
+ */
 export interface ActivationRecord {
     id: string;
     artifactId: string;
@@ -6,7 +15,34 @@ export interface ActivationRecord {
     action: string;
     targetRef: string;
     activatedAt: string | null;
-    status: 'active' | 'inactive';
+    /** When this activation was promoted from shadow to live (null for never-promoted). */
+    promotedAt: string | null;
+    /** When this activation was deactivated (null for active). */
+    deactivatedAt: string | null;
+    /**
+     * Lifecycle mode derived from action.
+     * - 'shadow' for code_tool_hook_shadow_activate
+     * - 'live'   for code_tool_hook_live_activate
+     * - undefined for unrecognized actions (cannot be safely mode-tagged).
+     */
+    mode?: 'shadow' | 'live';
+    /**
+     * Owner-visible status. Precedence: deactivated > suspended_by_flag > active.
+     * - 'deactivated'      — deactivatedAt is non-null.
+     * - 'suspended_by_flag' — v2 artifact but rulecode_context_v2 flag is off.
+     * - 'active'           — loaded and (for v2) flag is on.
+     */
+    status: 'active' | 'deactivated' | 'suspended_by_flag';
+    /** Artifact context version derived from requiresContextVersion field. */
+    contextVersion?: 'v1' | 'v2';
+    /** Owner-labelled evidence refs preserved from the artifact (PRI-490). */
+    evidenceRefs?: string[];
+    /** Human-readable summary of evidenceRefs for display. */
+    evidenceSummary?: string;
+    /** Next CLI command the owner should run to act on this activation. */
+    nextAction?: string;
+    /** Present when the activation references a non-existent artifact. */
+    warning?: string;
 }
 export interface ActivationsResponse {
     activations: ActivationRecord[];

package/console/dist/server/models/ActivationsConsoleModel.js

@@ -1,6 +1,14 @@
-import { SqliteConnection, SqliteActivationStateStore, SqlitePIArtifactStore, extractPrincipleId, } from '@principles/core/runtime-v2';
+import { SqliteConnection, SqliteActivationStateStore, SqlitePIArtifactStore, extractPrincipleId, extractEvidenceRefs, } from '@principles/core/runtime-v2';
+import { loadPdConfig, computeFlagsFromLoadResult } from '../config/pd-config-store.js';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+/**
+ * Type guard for parsed JSON objects (rc-2-no-as-bypass).
+ * Replaces `as Record<string, unknown>` casts on untrusted contentJson.
+ */
+function isRecord(value) {
+    return value !== null && value !== undefined && typeof value === 'object' && !Array.isArray(value);
+}
 function isMissingTableError(err) {
     if (!(err instanceof Error))
         return false;
@@ -56,13 +64,45 @@ export class ActivationsConsoleModel {
             // Without this, dreamer artifacts whose sourcePrincipleId was stripped
             // (non-core-principle case) would show 'unlinked' even when contentJson
             // carries a resolvable principleId.
+            //
+            // PRI-491: also collect contextVersion + evidenceRefs from contentJson so
+            // the Console can show whether a rule will block and why. rc-1/rc-2:
+            // contentJson is parsed as unknown and type-narrowed with typeof; never
+            // `as`-cast without a prior typeof check.
             const artifactPrincipleMap = new Map();
+            const artifactMetadata = new Map();
+            const danglingArtifactIds = new Set();
             for (const activation of allActivations) {
                 if (!artifactPrincipleMap.has(activation.artifactId)) {
                     try {
                         const artifact = await artifactStore.getArtifactById(activation.artifactId);
-                        const principleId = artifact ? extractPrincipleId(toSnapshot(artifact)) : null;
-                        artifactPrincipleMap.set(activation.artifactId, principleId);
+                        if (!artifact) {
+                            danglingArtifactIds.add(activation.artifactId);
+                            artifactPrincipleMap.set(activation.artifactId, null);
+                        }
+                        else {
+                            const principleId = extractPrincipleId(toSnapshot(artifact));
+                            artifactPrincipleMap.set(activation.artifactId, principleId);
+                            // PRI-491: extract contextVersion + evidenceRefs from contentJson.
+                            // rc-1: treat parsed JSON as unknown; rc-2: narrow with typeof.
+                            let parsedContent = null;
+                            try {
+                                const parsed = JSON.parse(artifact.contentJson);
+                                if (isRecord(parsed)) {
+                                    parsedContent = parsed;
+                                }
+                            }
+                            catch {
+                                // Malformed contentJson — treat as no metadata. Not dangling,
+                                // just unreadable; the principleId may still resolve via column.
+                            }
+                            const requiresCtxV2 = parsedContent !== null
+                                && Object.hasOwn(parsedContent, 'requiresContextVersion')
+                                && parsedContent.requiresContextVersion === 2;
+                            const contextVersion = requiresCtxV2 ? 'v2' : 'v1';
+                            const evidenceRefs = parsedContent !== null ? extractEvidenceRefs(parsedContent) : null;
+                            artifactMetadata.set(activation.artifactId, { contextVersion, evidenceRefs });
+                        }
                     }
                     catch (err) {
                         if (isMissingTableError(err)) {
@@ -74,16 +114,77 @@ export class ActivationsConsoleModel {
                     }
                 }
             }
-            const facts = allActivations.map((record) => ({
-                id: record.activationId,
-                artifactId: record.artifactId,
-                principleId: artifactPrincipleMap.get(record.artifactId) ?? 'unlinked',
-                channel: record.channel,
-                action: record.action,
-                targetRef: record.targetRef,
-                activatedAt: record.activatedAt,
-                status: record.deactivatedAt === null ? 'active' : 'inactive',
-            }));
+            // PRI-491: Probe rulecode_context_v2 flag to determine suspended_by_flag
+            // status for v2 activations. When the flag is off, v2 activations are
+            // suspended (not executing) even though they remain active in the DB.
+            const featureFlags = computeFlagsFromLoadResult(loadPdConfig(this.workspaceDir));
+            const v2FlagEnabled = featureFlags.flags.rulecode_context_v2?.enabled === true;
+            const facts = allActivations.map((record) => {
+                const meta = artifactMetadata.get(record.artifactId);
+                const contextVersion = meta?.contextVersion;
+                const evidenceRefs = meta?.evidenceRefs ?? undefined;
+                const evidenceSummary = evidenceRefs && evidenceRefs.length > 0
+                    ? `${evidenceRefs.length} evidence ref(s): ${evidenceRefs.slice(0, 3).join(', ')}${evidenceRefs.length > 3 ? '...' : ''}`
+                    : undefined;
+                // Derive mode from action (shadow_activate -> shadow, live_activate -> live).
+                const mode = record.action === 'code_tool_hook_shadow_activate'
+                    ? 'shadow'
+                    : record.action === 'code_tool_hook_live_activate'
+                        ? 'live'
+                        : undefined;
+                // Derive status: deactivated > suspended_by_flag > active (matches CLI).
+                let status;
+                let nextAction;
+                if (record.deactivatedAt) {
+                    status = 'deactivated';
+                    nextAction = undefined;
+                }
+                else if (contextVersion === 'v2' && !v2FlagEnabled) {
+                    status = 'suspended_by_flag';
+                    nextAction = `Enable rulecode_context_v2 flag or deactivate: pd activation deactivate --activation-id ${record.activationId} --confirm`;
+                }
+                else {
+                    status = 'active';
+                    if (mode === 'shadow') {
+                        nextAction = `pd activation promote --activation-id ${record.activationId} --confirm`;
+                    }
+                    else if (mode === 'live') {
+                        nextAction = `pd activation deactivate --activation-id ${record.activationId} --confirm`;
+                    }
+                    else {
+                        nextAction = undefined;
+                    }
+                }
+                const enriched = {
+                    id: record.activationId,
+                    artifactId: record.artifactId,
+                    principleId: artifactPrincipleMap.get(record.artifactId) ?? 'unlinked',
+                    channel: record.channel,
+                    action: record.action,
+                    targetRef: record.targetRef,
+                    activatedAt: record.activatedAt,
+                    promotedAt: record.promotedAt ?? null,
+                    deactivatedAt: record.deactivatedAt,
+                    mode,
+                    status,
+                    contextVersion,
+                    evidenceRefs,
+                    evidenceSummary,
+                    nextAction,
+                };
+                if (danglingArtifactIds.has(record.artifactId)) {
+                    enriched.warning = `artifact_id "${record.artifactId}" does not exist in pi_artifacts - activation is orphaned`;
+                }
+                return enriched;
+            });
+            // rc-9: surface dangling references instead of silently returning a degraded list.
+            if (danglingArtifactIds.size > 0) {
+                return {
+                    activations: facts,
+                    generatedAt: new Date().toISOString(),
+                    note: `${danglingArtifactIds.size} activation(s) reference non-existent artifact_id(s): ${Array.from(danglingArtifactIds).join(', ')}`,
+                };
+            }
             return {
                 activations: facts,
                 generatedAt: new Date().toISOString(),

package/console/dist/server/routes/onboarding.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Onboarding route - POST /api/v1/onboarding/run-demo
+ *
+ * Spec: docs/superpowers/specs/2026-06-30-new-user-onboarding-design.md 6.3 change 5
+ *
+ * Spawns `pd demo story-a --workspace <path> --json` as a subprocess, waits for
+ * it to complete, validates the JSON stdout, and returns 200 with the demo
+ * result. The console backend NEVER writes SQLite directly - all DB I/O happens
+ * inside the pd-cli subprocess (EP-06 Source of Truth).
+ *
+ * Feature flag gate: `new_user_onboarding` (default true, registered in
+ * packages/principles-core/src/runtime-v2/feature-flags/feature-flag-contract.ts).
+ *
+ * ERR entries considered:
+ * - EP-02 (Production Path Wiring): registered in server/index.ts handleRequest
+ * - EP-03 (Fail Loud): spawn failure -> 500 with reason + nextAction;
+ *   flag disabled -> 403 with reason + nextAction (rc-9-no-silent-fallback)
+ * - EP-06 (Source of Truth): reuses pd-cli demo command, no direct DB writes
+ * - EP-08 (Security Boundary): no shell:true — argv passed directly to OS,
+ *   eliminating command-injection risk; demo runs in a temp workspace so no
+ *   user-controlled path enters the command at all
+ * - rc-1-treat-as-unknown / rc-2-no-as-bypass / rc-4-validate-array-elements:
+ *   parsed stdout is validated by parseDemoStdout before use
+ * - rc-9-no-silent-fallback: timeout, error, and invalid-stdout paths each
+ *   return a structured error with reason + nextAction
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export interface OnboardingRouteContext {
+    workspaceDir: string;
+    subPath: string;
+}
+export declare function handleOnboardingRoute(req: IncomingMessage, res: ServerResponse, ctx: OnboardingRouteContext): Promise<void>;
+/** No persistent resources to dispose - included for parity with other routes. */
+export declare function disposeOnboardingModels(): void;

package/console/dist/server/routes/onboarding.js

@@ -0,0 +1,324 @@
+/**
+ * Onboarding route - POST /api/v1/onboarding/run-demo
+ *
+ * Spec: docs/superpowers/specs/2026-06-30-new-user-onboarding-design.md 6.3 change 5
+ *
+ * Spawns `pd demo story-a --workspace <path> --json` as a subprocess, waits for
+ * it to complete, validates the JSON stdout, and returns 200 with the demo
+ * result. The console backend NEVER writes SQLite directly - all DB I/O happens
+ * inside the pd-cli subprocess (EP-06 Source of Truth).
+ *
+ * Feature flag gate: `new_user_onboarding` (default true, registered in
+ * packages/principles-core/src/runtime-v2/feature-flags/feature-flag-contract.ts).
+ *
+ * ERR entries considered:
+ * - EP-02 (Production Path Wiring): registered in server/index.ts handleRequest
+ * - EP-03 (Fail Loud): spawn failure -> 500 with reason + nextAction;
+ *   flag disabled -> 403 with reason + nextAction (rc-9-no-silent-fallback)
+ * - EP-06 (Source of Truth): reuses pd-cli demo command, no direct DB writes
+ * - EP-08 (Security Boundary): no shell:true — argv passed directly to OS,
+ *   eliminating command-injection risk; demo runs in a temp workspace so no
+ *   user-controlled path enters the command at all
+ * - rc-1-treat-as-unknown / rc-2-no-as-bypass / rc-4-validate-array-elements:
+ *   parsed stdout is validated by parseDemoStdout before use
+ * - rc-9-no-silent-fallback: timeout, error, and invalid-stdout paths each
+ *   return a structured error with reason + nextAction
+ */
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { loadPdConfig, computeFlagsFromLoadResult } from '../config/pd-config-store.js';
+import { sendError, sendJson } from '../utils/response.js';
+/** Demo subprocess timeout in milliseconds (60s). */
+const DEMO_TIMEOUT_MS = 60_000;
+// P1-1: Best-effort removal of the temp demo workspace.
+function cleanupTempWorkspace(dir) {
+    try {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+    catch {
+        // Best-effort cleanup — temp dir will be cleaned by OS eventually.
+    }
+}
+/** Send a structured error with reason + nextAction (Runtime Contract rc-9). */
+function sendStructuredError(res, payload) {
+    sendError(res, payload.statusCode, payload.error, payload.reason, {
+        reason: payload.reason,
+        nextAction: payload.nextAction,
+    });
+}
+/** Load the new_user_onboarding flag state from .pd/config.yaml. */
+function loadOnboardingFlagEnabled(workspaceDir) {
+    const configResult = loadPdConfig(workspaceDir);
+    const flagsResult = computeFlagsFromLoadResult(configResult);
+    return flagsResult.flags.new_user_onboarding?.enabled === true;
+}
+/**
+ * Resolve the pd CLI invocation: spawn `process.execPath` (Node itself) with
+ * the absolute path to the pd-cli `dist/index.js` entry, instead of spawning
+ * the bare `pd` binary.
+ *
+ * P1-A (Windows .cmd resolution): `spawn('pd', args, { shell: false })` fails
+ * on Windows with ENOENT because Node's CreateProcess cannot resolve npm's
+ * `.cmd` shims (pd.cmd) without a shell. Spawning `process.execPath` with the
+ * JS entry path sidesteps this entirely — there is no `.cmd` involved. This is
+ * the same pattern used in installer.ts:autoLaunchConsole and
+ * pd-cli's runtime-uat.ts `findPdCliPath`.
+ *
+ * P1-2 (command injection): this approach also keeps `shell: false` — argv is
+ * passed directly to the OS, so no user-controlled value is ever interpreted
+ * by a shell (EP-08 Security Boundary).
+ *
+ * Returns `{ cmd, extraArgs }`:
+ *   - On success: `{ cmd: process.execPath, extraArgs: [pdCliEntryPath] }`
+ *   - On failure (pd-cli not resolvable / entry missing): falls back to
+ *     `{ cmd: 'pd', extraArgs: [] }`. This works on Linux/macOS via PATH; on
+ *     Windows the spawn will emit 'error', which the caller handles with a
+ *     clear nextAction (rc-9-no-silent-fallback).
+ */
+function findPdCli() {
+    // Both the monorepo and installed extension place pd-cli beside console.
+    // source: pd-console/src/server/routes -> packages/pd-cli
+    // install: console/dist/server/routes -> principles-disciple/pd-cli
+    const entryPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../pd-cli/dist/index.js');
+    // Do not preflight with existsSync: the Console test job intentionally runs
+    // before pd-cli is built, while production installation guarantees this
+    // sibling layout. Node will exit non-zero with a structured error if the
+    // delivered entry is unexpectedly missing.
+    return { cmd: process.execPath, extraArgs: [entryPath] };
+}
+/**
+ * Validate the parsed JSON stdout from `pd demo story-a --json`.
+ *
+ * rc-1-treat-as-unknown: parsed JSON is treated as unknown until validated.
+ * rc-2-no-as-bypass: no `as` cast is used to bypass validation - all fields
+ *   are checked with typeof / Array.isArray before the value is accepted.
+ * rc-4-validate-array-elements: the `stages` array is type-checked as an array
+ *   (element-level shape validation happens downstream in the UI validator).
+ *
+ * Required fields: status (string), generatedAt (string), narrative (string),
+ * stages (array). Returns the validated object or null if invalid.
+ */
+function parseDemoStdout(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const status = Object.hasOwn(parsed, 'status') ? Reflect.get(parsed, 'status') : undefined;
+    const generatedAt = Object.hasOwn(parsed, 'generatedAt') ? Reflect.get(parsed, 'generatedAt') : undefined;
+    const narrative = Object.hasOwn(parsed, 'narrative') ? Reflect.get(parsed, 'narrative') : undefined;
+    const stages = Object.hasOwn(parsed, 'stages') ? Reflect.get(parsed, 'stages') : undefined;
+    if (typeof status !== 'string' || typeof generatedAt !== 'string' || typeof narrative !== 'string')
+        return null;
+    if (!Array.isArray(stages) || !stages.every((stage) => {
+        if (typeof stage !== 'object' || stage === null)
+            return false;
+        const name = Object.hasOwn(stage, 'name') ? Reflect.get(stage, 'name') : undefined;
+        const stageStatus = Object.hasOwn(stage, 'status') ? Reflect.get(stage, 'status') : undefined;
+        return typeof name === 'string' &&
+            (stageStatus === 'passed' || stageStatus === 'failed' || stageStatus === 'degraded' || stageStatus === 'skipped');
+    }))
+        return null;
+    return parsed;
+}
+/**
+ * Spawn `pd demo story-a --json`, wait for it to complete, validate stdout,
+ * and return 200 with { success: true, data: { simulated: true, demo: ... } }.
+ *
+ * The demo typically completes in < 30s. We block on the subprocess so the
+ * response carries the validated demo result in a single round-trip - the
+ * frontend does not need to poll for the demo itself (it still polls
+ * /api/v1/evidence-chain in step 3 for live evidence detection).
+ *
+ * Failure modes (rc-9-no-silent-fallback - every path returns a structured
+ * error with reason + nextAction):
+ *   - spawn throws synchronously (e.g. ENOENT) -> 500 demo_spawn_failed
+ *   - child emits 'error' after spawn -> 500 demo_subprocess_error
+ *   - subprocess exceeds DEMO_TIMEOUT_MS -> 504 demo_timeout (subprocess killed)
+ *   - subprocess exits with non-zero code -> 500 demo_exit_nonzero
+ *   - stdout cannot be parsed/validated -> 500 demo_invalid_stdout
+ */
+async function handleRunDemo(res, _workspaceDir) {
+    // P1-1: Use a temporary workspace so the demo's simulated DB writes
+    // (tasks, artifacts, approvals, activations) do NOT pollute the user's
+    // real workspace state.db.
+    const tempWorkspace = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-onboarding-demo-'));
+    let child;
+    try {
+        const { cmd, extraArgs } = findPdCli();
+        // P1-A: spawn process.execPath (Node) with the pd-cli entry JS path to
+        // avoid the Windows .cmd resolution problem. P1-2: no shell:true — argv is
+        // passed directly to the OS, eliminating command-injection risk from
+        // user-controlled paths (the temp workspace path is the only variable
+        // here, and it is a mkdtemp result, not user input).
+        child = spawn(cmd, [...extraArgs, 'demo', 'story-a', '--workspace', tempWorkspace, '--json'], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            // No shell:true — argv is passed directly to the OS.
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        cleanupTempWorkspace(tempWorkspace);
+        sendStructuredError(res, {
+            statusCode: 500,
+            error: 'demo_spawn_failed',
+            reason: `spawn failed: ${message}`,
+            nextAction: 'Check that the pd CLI is installed (npm i -g @principles/pd-cli) and that its dist/index.js entry exists, or that pd is on PATH.',
+        });
+        return;
+    }
+    // P2-D: declared outside the try so the finally block can clear it. Captures
+    // the 60s timeout handle to prevent the timer from leaking after demo ends.
+    let timeoutHandle;
+    try {
+        // Capture stdout into a buffer. stderr is logged for observability (rc-9).
+        const stdoutChunks = [];
+        let stderrText = '';
+        child.stdout?.on('data', (data) => {
+            stdoutChunks.push(data);
+        });
+        child.stderr?.on('data', (data) => {
+            const chunk = data.toString();
+            stderrText += chunk;
+            console.error('[pd-console] onboarding demo stderr:', chunk.trim());
+        });
+        // Wrap the subprocess lifecycle in a Promise that resolves with the exit code
+        // or rejects on 'error'. A timeout is enforced via a separate Promise that
+        // resolves with a sentinel value - Promise.race is used below.
+        const settled = new Promise((resolve) => {
+            let done = false;
+            const finish = (code, error) => {
+                if (done)
+                    return;
+                done = true;
+                resolve({ code, error });
+            };
+            child.on('error', (err) => {
+                finish(null, err);
+            });
+            child.on('close', (code) => {
+                finish(code, null);
+            });
+        });
+        const timeout = new Promise((resolve) => {
+            timeoutHandle = setTimeout(() => resolve('timeout'), DEMO_TIMEOUT_MS);
+        });
+        const outcome = await Promise.race([settled, timeout]);
+        // -- Timeout: kill the subprocess and return 504 --
+        if (outcome === 'timeout') {
+            try {
+                child.kill();
+            }
+            catch {
+                // Best-effort kill; ignore failures (rc-9: the 504 response still carries
+                // the reason + nextAction so the operator is not left in the dark).
+            }
+            sendStructuredError(res, {
+                statusCode: 504,
+                error: 'demo_timeout',
+                reason: `demo subprocess exceeded ${DEMO_TIMEOUT_MS}ms timeout`,
+                nextAction: 'Retry the demo; if it persists, check pd CLI health (pd doctor).',
+            });
+            return;
+        }
+        // -- 'error' event after spawn (e.g. EACCES, broken pipe) -> 500 --
+        if (outcome.error !== null) {
+            sendStructuredError(res, {
+                statusCode: 500,
+                error: 'demo_subprocess_error',
+                reason: `subprocess error: ${outcome.error.message}`,
+                nextAction: 'Check pd CLI installation and permissions; see server logs for stderr.',
+            });
+            return;
+        }
+        // -- Non-zero exit code -> 500 --
+        if (outcome.code !== 0) {
+            sendStructuredError(res, {
+                statusCode: 500,
+                error: 'demo_exit_nonzero',
+                reason: `demo exited with code ${outcome.code}`,
+                nextAction: stderrText.trim()
+                    ? `pd stderr: ${stderrText.trim()}`
+                    : 'Run `pd demo story-a --json` manually for diagnostics.',
+            });
+            return;
+        }
+        // -- Validate stdout (rc-1/rc-2/rc-4) --
+        const stdout = Buffer.concat(stdoutChunks).toString('utf8');
+        const validated = parseDemoStdout(stdout);
+        if (validated === null) {
+            sendStructuredError(res, {
+                statusCode: 500,
+                error: 'demo_invalid_stdout',
+                reason: 'demo stdout did not match the expected JSON schema',
+                nextAction: 'Run `pd demo story-a --json` manually and inspect the output.',
+            });
+            return;
+        }
+        // -- 200 OK with validated demo result --
+        sendJson(res, 200, {
+            success: true,
+            data: {
+                simulated: true,
+                demo: validated,
+            },
+        });
+    }
+    finally {
+        // P2-D: clear the 60s timeout timer so it doesn't leak after the demo
+        // completes. The guard handles the case where an error was thrown before
+        // the timeout Promise executor assigned the handle.
+        if (timeoutHandle)
+            clearTimeout(timeoutHandle);
+        // P1-1: always clean up the temp workspace, whether the demo succeeded,
+        // failed, timed out, or threw. Best-effort — OS will reap temp dirs eventually.
+        cleanupTempWorkspace(tempWorkspace);
+    }
+}
+export async function handleOnboardingRoute(req, res, ctx) {
+    const { workspaceDir, subPath } = ctx;
+    // -- Feature flag gate (spec 6.3 change 5) --
+    // Checked BEFORE method/sub-path dispatch so a disabled flag cannot be probed
+    // via 405/404 side-channels (rc-9-no-silent-fallback: explicit 403 + reason).
+    if (!loadOnboardingFlagEnabled(workspaceDir)) {
+        sendStructuredError(res, {
+            statusCode: 403,
+            error: 'flag_disabled',
+            reason: 'flag_disabled',
+            nextAction: 'Enable the new_user_onboarding feature flag in .pd/config.yaml or the Settings page.',
+        });
+        return;
+    }
+    // -- POST /api/v1/onboarding/run-demo --
+    if (subPath === '/run-demo') {
+        if (req.method !== 'POST') {
+            sendStructuredError(res, {
+                statusCode: 405,
+                error: 'method_not_allowed',
+                reason: 'method_not_allowed',
+                nextAction: 'Use POST to trigger the demo.',
+            });
+            return;
+        }
+        await handleRunDemo(res, workspaceDir);
+        return;
+    }
+    // -- Unknown sub-path --
+    sendStructuredError(res, {
+        statusCode: 404,
+        error: 'not_found',
+        reason: 'not_found',
+        nextAction: `Route /api/v1/onboarding${subPath} not found. Use POST /api/v1/onboarding/run-demo.`,
+    });
+}
+/** No persistent resources to dispose - included for parity with other routes. */
+export function disposeOnboardingModels() {
+    // No-op: handleRunDemo holds no cached models or open handles.
+}