create-principles-disciple 1.103.0 → 1.104.1

package/README.md

@@ -52,8 +52,8 @@ npx create-principles-disciple --yes --workspace "/path/to/workspace" --json
 
 The installer automatically verifies the installation during setup:
 
-1. **Feature flags** — `.pd/config.yaml` is generated and validated (ADR-0016: replaces the legacy `.pd/feature-flags.yaml`)
-2. **Story A demo** — `pd demo story-a` is executed to confirm runtime integration
+1. **Configuration** — `.pd/config.yaml` is generated and validated (ADR-0016: replaces the legacy `.pd/feature-flags.yaml`)
+2. **Demo verification** — `pd demo first-principle` is executed to confirm runtime integration
 3. **Console health** — `/api/health` is checked on the local console instance
 
 After a successful install, you can re-verify at any time:

package/console/dist/server/config/pd-config-store.d.ts

@@ -112,7 +112,7 @@ export interface DefaultRuntimeUpdateResultErr {
 export type DefaultRuntimeUpdateResult = DefaultRuntimeUpdateResultOk | DefaultRuntimeUpdateResultErr;
 export declare function updateDefaultRuntime(workspaceDir: string, payload: unknown): DefaultRuntimeUpdateResult;
 /** Valid values for principles.outputLanguage in config.yaml */
-export declare const VALID_OUTPUT_LANGUAGES: readonly ["zh-CN", "en"];
+export declare const VALID_OUTPUT_LANGUAGES: readonly ['zh-CN', 'en'];
 export type OutputLanguage = typeof VALID_OUTPUT_LANGUAGES[number];
 export interface OutputLanguageResultOk {
     ok: true;
@@ -133,6 +133,13 @@ export type OutputLanguageResult = OutputLanguageResultOk | OutputLanguageResult
  * Fail loud if set to an invalid value (ERR-009).
  */
 export declare function getPrinciplesOutputLanguage(workspaceDir: string): OutputLanguageResult;
+/**
+ * Read `feedback.maintainer_email` from .pd/config.yaml.
+ * Returns the default when the field is absent, empty, or the config is
+ * missing/malformed. Treats parsed YAML as unknown (ERR-001/005): no `as`
+ * bypasses; uses Object.hasOwn for untrusted key checks (ERR-013).
+ */
+export declare function getFeedbackMaintainerEmail(workspaceDir: string): string;
 /**
  * Update principles.outputLanguage in config.yaml.
  * Safe partial write: preserves unknown sections, validates before write.

package/console/dist/server/config/pd-config-store.js

@@ -529,6 +529,56 @@ export function getPrinciplesOutputLanguage(workspaceDir) {
     }
     return { ok: true, outputLanguage: outputLangRaw, source: 'user_config' };
 }
+// ── Feedback Maintainer Email ───────────────────────────────────────────────
+/**
+ * Default maintainer email placeholder when .pd/config.yaml does not set
+ * feedback.maintainer_email. Callers MUST surface a clear warning when this
+ * default is used instead of silently emitting a mailto link — a real-looking
+ * default would leak a placeholder into feedback reports.
+ */
+const DEFAULT_FEEDBACK_MAINTAINER_EMAIL = 'maintainer@example.com';
+/**
+ * Read `feedback.maintainer_email` from .pd/config.yaml.
+ * Returns the default when the field is absent, empty, or the config is
+ * missing/malformed. Treats parsed YAML as unknown (ERR-001/005): no `as`
+ * bypasses; uses Object.hasOwn for untrusted key checks (ERR-013).
+ */
+export function getFeedbackMaintainerEmail(workspaceDir) {
+    const configPath = getPdConfigPath(workspaceDir);
+    if (!fs.existsSync(configPath)) {
+        return DEFAULT_FEEDBACK_MAINTAINER_EMAIL;
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(configPath, 'utf8');
+    }
+    catch {
+        return DEFAULT_FEEDBACK_MAINTAINER_EMAIL;
+    }
+    let parsed;
+    try {
+        parsed = yaml.load(raw, { schema: yaml.JSON_SCHEMA });
+    }
+    catch {
+        return DEFAULT_FEEDBACK_MAINTAINER_EMAIL;
+    }
+    if (!isRecord(parsed)) {
+        return DEFAULT_FEEDBACK_MAINTAINER_EMAIL;
+    }
+    // Extract feedback section — unknown-first, no `as` bypass (ERR-001)
+    const feedbackRaw = Object.hasOwn(parsed, 'feedback') ? parsed.feedback : undefined;
+    if (feedbackRaw === undefined) {
+        return DEFAULT_FEEDBACK_MAINTAINER_EMAIL;
+    }
+    if (!isRecord(feedbackRaw)) {
+        return DEFAULT_FEEDBACK_MAINTAINER_EMAIL;
+    }
+    const emailRaw = Object.hasOwn(feedbackRaw, 'maintainer_email') ? feedbackRaw.maintainer_email : undefined;
+    if (typeof emailRaw !== 'string' || emailRaw.length === 0) {
+        return DEFAULT_FEEDBACK_MAINTAINER_EMAIL;
+    }
+    return emailRaw;
+}
 /**
  * Update principles.outputLanguage in config.yaml.
  * Safe partial write: preserves unknown sections, validates before write.

package/console/dist/server/index.js

@@ -2,11 +2,12 @@ import * as http from 'http';
 import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
-import { loadPdConfig, computeFlagsFromLoadResult } from './config/pd-config-store.js';
+import { loadPdConfig, computeFlagsFromLoadResult, getFeedbackMaintainerEmail } from './config/pd-config-store.js';
 import { AuthConfig } from './config/AuthConfig.js';
 import { WorkspaceConfigStore } from './config/WorkspaceConfigStore.js';
 import { WorkspaceService } from './models/WorkspaceService.js';
 import { handleFeedbackReportsRoute, disposeFeedbackReportModels } from './routes/feedback-reports.js';
+import { handleFailedTasksRoute, disposeFailedTasksModels } from './routes/failed-tasks.js';
 import { handleApprovalsRoute, disposeApprovalsModels } from './routes/approvals.js';
 import { handleHealthRoute, disposeHealthModels } from './routes/health.js';
 import { handlePrinciplesRoute, disposePrinciplesModels } from './routes/principles.js';
@@ -175,6 +176,8 @@ function serveFile(res, filePath) {
 // ── Async handler wrapper ──────────────────────────────────────────────────────────────
 const REQUEST_TIMEOUT_MS = 10000;
 const UPDATE_APPLY_TIMEOUT_MS = 120000;
+// Full update downloads a tarball + copies files — allow 3 min for slow networks.
+const UPDATE_APPLY_FULL_TIMEOUT_MS = 180000;
 function asyncHandler(fn, timeoutMs = REQUEST_TIMEOUT_MS) {
     return (innerReq, innerRes) => {
         const timeoutId = setTimeout(() => {
@@ -204,22 +207,30 @@ async function initServices(workspaceDir, authConfig) {
     const configResult = loadPdConfig(workspaceDir);
     const pdFlags = computeFlagsFromLoadResult(configResult);
     const feedbackChannelEnabled = pdFlags.flags.feedback_channel?.enabled ?? false;
+    const failedTasksObservabilityEnabled = pdFlags.flags.failed_tasks_observability?.enabled ?? true;
     const feedbackFlags = {
         feedback_channel: { enabled: feedbackChannelEnabled },
+        failed_tasks_observability: { enabled: failedTasksObservabilityEnabled },
     };
     if (!configResult.ok) {
         console.warn('[pd-console] PD config loading failed (using defaults for feedback channel):', configResult.errors.map(e => e.reason).join('; '));
     }
+    // Read feedback.maintainer_email from .pd/config.yaml (defaults to
+    // csuzngjh@hotmail.com when absent). Used to build mailto: URLs in feedback
+    // reports so the owner can open a pre-filled email directly.
+    const maintainerEmail = getFeedbackMaintainerEmail(workspaceDir);
     return {
         workspaceDir,
         authConfig,
         configStore,
         workspaceService,
         feedbackFlags,
+        maintainerEmail,
     };
 }
 async function closeServices() {
     disposeFeedbackReportModels();
+    disposeFailedTasksModels();
     disposeApprovalsModels();
     disposeApprovalsGroupedModels();
     disposeHealthModels();
@@ -268,7 +279,13 @@ function handleRequest(services) {
             // GET/POST /api/feedback/reports, /api/feedback/reports/:id
             if (urlPath === '/api/feedback/reports' || urlPath.startsWith('/api/feedback/reports/')) {
                 const subPath = urlPath.slice('/api/feedback/reports'.length);
-                asyncHandler(() => handleFeedbackReportsRoute(req, res, { workspaceDir: services.workspaceDir, subPath, featureFlags: services.feedbackFlags }))(req, res);
+                asyncHandler(() => handleFeedbackReportsRoute(req, res, { workspaceDir: services.workspaceDir, subPath, featureFlags: services.feedbackFlags, maintainerEmail: services.maintainerEmail }))(req, res);
+                return;
+            }
+            // Task 9: GET /api/v1/failed-tasks, /api/v1/failed-tasks/:id
+            if (urlPath === '/api/v1/failed-tasks' || urlPath.startsWith('/api/v1/failed-tasks/')) {
+                const subPath = urlPath.slice('/api/v1/failed-tasks'.length);
+                asyncHandler(() => handleFailedTasksRoute(req, res, { workspaceDir: services.workspaceDir, subPath, featureFlags: services.feedbackFlags }))(req, res);
                 return;
             }
             // GET /api/v1/approvals/grouped (MUST be before approvals catch-all)
@@ -303,7 +320,11 @@ function handleRequest(services) {
             if (urlPath === '/api/update' || urlPath.startsWith('/api/update/')) {
                 const subPath = urlPath.slice('/api/update'.length);
                 const isApply = subPath === '/apply';
-                asyncHandler(() => handleUpdateRoute(req, res, services.workspaceDir, subPath), isApply ? UPDATE_APPLY_TIMEOUT_MS : undefined)(req, res);
+                const isApplyFull = subPath === '/apply-full';
+                const timeout = isApplyFull ? UPDATE_APPLY_FULL_TIMEOUT_MS
+                    : isApply ? UPDATE_APPLY_TIMEOUT_MS
+                        : undefined;
+                asyncHandler(() => handleUpdateRoute(req, res, services.workspaceDir, subPath), timeout)(req, res);
                 return;
             }
             // Config API routes: /api/v1/config/summary, /api/v1/config/catalog,

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

@@ -16,6 +16,18 @@ export interface SystemHealthStatus {
     checks: HealthCheckResult[];
     pipeline: PipelineTimestamps;
     generatedAt: string;
+    /** P0-2: PD/core/node versions for feedback report diagnostics. */
+    versions?: {
+        pd: string;
+        core: string;
+        node: string;
+    };
+    /** P0-2: OS/arch/nodeVersion for feedback report diagnostics. */
+    platform?: {
+        os: string;
+        arch: string;
+        nodeVersion: string;
+    };
 }
 export declare class HealthCheckModel {
     private readonly workspaceDir;
@@ -25,6 +37,21 @@ export declare class HealthCheckModel {
     private runtime;
     constructor(workspaceDir: string);
     checkSystemHealth(): Promise<SystemHealthStatus>;
+    /**
+     * P0-2: Read the PD (monorepo root) version from package.json.
+     * Returns 'unknown' on any resolution/parse failure (rc-9: no silent throw).
+     */
+    private static readPdVersion;
+    /**
+     * P0-2: Read the @principles/core version from its package.json.
+     * Returns 'unknown' on any resolution/parse failure (rc-9: log + fallback).
+     *
+     * The `./package.json` subpath is explicitly exported by @principles/core's
+     * package.json (see its `exports` field). Without that export entry, Node.js
+     * would throw ERR_PACKAGE_PATH_NOT_EXPORTED and this method would silently
+     * return 'unknown' for every feedback report — defeating the diagnostic.
+     */
+    private static readCoreVersion;
     private checkSqlite;
     private checkPainChainFlow;
     private checkTaskQueue;

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

@@ -1,4 +1,9 @@
+import { createRequire } from 'node:module';
 import { OperatorHealthReadModel, PainChainReadModel, PruningReadModel, RuntimeStateManager, } from '@principles/core/runtime-v2';
+// P0-2: createRequire lets us read package.json via Node's module resolution
+// in ESM context. Resolves relative to this module's URL in both tsx (dev)
+// and compiled JS (prod) since both mirror the same directory depth.
+const moduleRequire = createRequire(import.meta.url);
 const noop = () => { };
 export class HealthCheckModel {
     workspaceDir;
@@ -24,8 +29,59 @@ export class HealthCheckModel {
             checks,
             pipeline: await this.getPipelineTimestamps(),
             generatedAt: new Date().toISOString(),
+            // P0-2: collect version and platform info for feedback diagnostics.
+            // If a package.json read fails, the helper returns 'unknown' rather
+            // than throwing — the feedback report still gets a structured field.
+            versions: {
+                pd: HealthCheckModel.readPdVersion(),
+                core: HealthCheckModel.readCoreVersion(),
+                node: process.versions.node,
+            },
+            platform: {
+                os: process.platform,
+                arch: process.arch,
+                nodeVersion: process.versions.node,
+            },
         };
     }
+    /**
+     * P0-2: Read the PD (monorepo root) version from package.json.
+     * Returns 'unknown' on any resolution/parse failure (rc-9: no silent throw).
+     */
+    static readPdVersion() {
+        try {
+            // From src/server/models/ (or dist/server/models/), five levels up
+            // reaches the monorepo root package.json.
+            const pkg = moduleRequire('../../../../../package.json');
+            return typeof pkg.version === 'string' ? pkg.version : 'unknown';
+        }
+        catch {
+            return 'unknown';
+        }
+    }
+    /**
+     * P0-2: Read the @principles/core version from its package.json.
+     * Returns 'unknown' on any resolution/parse failure (rc-9: log + fallback).
+     *
+     * The `./package.json` subpath is explicitly exported by @principles/core's
+     * package.json (see its `exports` field). Without that export entry, Node.js
+     * would throw ERR_PACKAGE_PATH_NOT_EXPORTED and this method would silently
+     * return 'unknown' for every feedback report — defeating the diagnostic.
+     */
+    static readCoreVersion() {
+        try {
+            const pkg = moduleRequire('@principles/core/package.json');
+            return typeof pkg.version === 'string' ? pkg.version : 'unknown';
+        }
+        catch (err) {
+            // rc-9: surface the resolution failure so the operator can observe why
+            // the core version is missing from feedback reports instead of silently
+            // getting 'unknown' forever.
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[HealthCheckModel] readCoreVersion failed: ${msg}\n`);
+            return 'unknown';
+        }
+    }
     async checkSqlite() {
         try {
             const runtime = await this.getRuntime();

package/console/dist/server/routes/failed-tasks.d.ts

@@ -0,0 +1,24 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { SqliteTaskStore } from '@principles/core/runtime-v2';
+export declare function disposeFailedTasksModels(): void;
+export type FailedTasksContext = {
+    workspaceDir: string;
+    subPath: string;
+    featureFlags?: Record<string, {
+        enabled: boolean;
+    }>;
+    /** Optional injected store (used in tests). When absent, a per-workspace cached store is used. */
+    sqliteTaskStore?: SqliteTaskStore;
+};
+/**
+ * Handle requests to `/api/v1/failed-tasks*`.
+ *
+ * Routes:
+ *   GET /api/v1/failed-tasks         — list failed/needs_human_review tasks
+ *   GET /api/v1/failed-tasks/:id     — fetch single task detail (task + runs + lastError)
+ *   other methods                    — 405 Method Not Allowed
+ *
+ * Feature flag gate: when `ctx.featureFlags.failed_tasks_observability.enabled`
+ * is `false`, returns 403 `failed_tasks_observability_disabled`.
+ */
+export declare function handleFailedTasksRoute(req: IncomingMessage, res: ServerResponse, ctx: FailedTasksContext): Promise<void>;

package/console/dist/server/routes/failed-tasks.js

@@ -0,0 +1,207 @@
+// failed-tasks.ts
+// Server route for /api/v1/failed-tasks/*
+//
+// Lists tasks in 'failed' or 'needs_human_review' status and fetches single-task
+// detail (task record + run history + last error category). Gated by the
+// failed_tasks_observability feature flag.
+//
+// Trust boundary (rc-1, rc-2): all query string values are read via
+// URLSearchParams.get() and treated as `unknown` until validated with typeof /
+// Number.isFinite. Store return values are typed by the core contract and
+// further validated by SqliteTaskStore's row readers (rc-1 at the DB boundary).
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { SqliteConnection, SqliteTaskStore, } from '@principles/core/runtime-v2';
+import { sendSuccess, sendError, sendNotFound, sendMethodNotAllowed, sendBadRequest, } from '../utils/response.js';
+const entries = new Map();
+function stateDbExists(workspaceDir) {
+    return fs.existsSync(path.join(workspaceDir, '.pd', 'state.db'));
+}
+function getStore(workspaceDir) {
+    let entry = entries.get(workspaceDir);
+    if (!entry) {
+        const connection = new SqliteConnection({ workspaceDir, readonly: true });
+        const store = new SqliteTaskStore(connection);
+        entry = { store, connection };
+        entries.set(workspaceDir, entry);
+    }
+    return entry.store;
+}
+export function disposeFailedTasksModels() {
+    for (const entry of entries.values()) {
+        try {
+            entry.connection.close();
+        }
+        catch {
+            // best-effort close on shutdown
+        }
+    }
+    entries.clear();
+}
+// ── Helpers ────────────────────────────────────────────────────────────────
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Parse a non-negative integer query parameter.
+ *
+ * rc-1: the raw value from URLSearchParams is `string | null` (unknown shape
+ * from the wire). We validate with typeof + Number.isFinite before use.
+ *
+ * Returns the parsed integer, or `{ error }` if invalid. When `raw` is null,
+ * returns `defaultValue`.
+ */
+function parseNonNegInt(opts) {
+    const { raw, fieldName, max, defaultValue } = opts;
+    if (raw === null)
+        return defaultValue;
+    // rc-1: raw is string from URLSearchParams, but treat defensively
+    if (typeof raw !== 'string')
+        return { error: `${fieldName} must be a string` };
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed))
+        return { error: `${fieldName} must be a finite integer` };
+    if (parsed < 0)
+        return { error: `${fieldName} must be >= 0` };
+    if (parsed > max)
+        return { error: `${fieldName} must be <= ${max}` };
+    return parsed;
+}
+/**
+ * Extract query params from req.url.
+ *
+ * Returns `null` when the URL has no `?` component (no params).
+ */
+function extractQueryParams(req) {
+    const urlStr = req.url ?? '';
+    const qIdx = urlStr.indexOf('?');
+    if (qIdx < 0)
+        return null;
+    return new URLSearchParams(urlStr.slice(qIdx + 1));
+}
+/**
+ * Handle requests to `/api/v1/failed-tasks*`.
+ *
+ * Routes:
+ *   GET /api/v1/failed-tasks         — list failed/needs_human_review tasks
+ *   GET /api/v1/failed-tasks/:id     — fetch single task detail (task + runs + lastError)
+ *   other methods                    — 405 Method Not Allowed
+ *
+ * Feature flag gate: when `ctx.featureFlags.failed_tasks_observability.enabled`
+ * is `false`, returns 403 `failed_tasks_observability_disabled`.
+ */
+export async function handleFailedTasksRoute(req, res, ctx) {
+    const { workspaceDir, subPath } = ctx;
+    const method = req.method ?? 'GET';
+    // Feature flag gate — checked before any DB access so a disabled flag
+    // short-circuits cleanly (rc-9: error response includes reason + next action).
+    if (ctx.featureFlags && Object.hasOwn(ctx.featureFlags, 'failed_tasks_observability')) {
+        const flag = ctx.featureFlags.failed_tasks_observability;
+        if (flag && !flag.enabled) {
+            sendError(res, 403, 'failed_tasks_observability_disabled', 'failed_tasks_observability feature flag is disabled. Enable it in .pd/config.yaml (features.failed_tasks_observability.enabled: true) to list failed tasks.');
+            return;
+        }
+    }
+    // Collection: GET /api/v1/failed-tasks
+    if (subPath === '' || subPath === '/') {
+        if (method !== 'GET') {
+            sendMethodNotAllowed(res);
+            return;
+        }
+        try {
+            const params = extractQueryParams(req);
+            // kind: optional string filter (task_kind column)
+            const kindRaw = params?.get('kind') ?? null;
+            const kind = kindRaw !== null && kindRaw.length > 0 ? kindRaw : undefined;
+            // since: optional hours ago → Unix ms cutoff
+            let since;
+            const sinceRaw = params?.get('since') ?? null;
+            if (sinceRaw !== null) {
+                const sinceHours = Number.parseInt(sinceRaw, 10);
+                if (!Number.isFinite(sinceHours) || sinceHours < 0) {
+                    sendBadRequest(res, 'since must be a non-negative integer (hours ago)');
+                    return;
+                }
+                since = Date.now() - sinceHours * 3600 * 1000;
+            }
+            // limit: default 50, max 200
+            const limitResult = parseNonNegInt({ raw: params?.get('limit') ?? null, fieldName: 'limit', max: 200, defaultValue: 50 });
+            if (typeof limitResult !== 'number') {
+                sendBadRequest(res, limitResult.error);
+                return;
+            }
+            if (limitResult === 0) {
+                sendBadRequest(res, 'limit must be >= 1');
+                return;
+            }
+            // offset: default 0
+            const offsetResult = parseNonNegInt({ raw: params?.get('offset') ?? null, fieldName: 'offset', max: 1_000_000, defaultValue: 0 });
+            if (typeof offsetResult !== 'number') {
+                sendBadRequest(res, offsetResult.error);
+                return;
+            }
+            // If state.db does not exist yet (fresh workspace), return empty list
+            // with a reason rather than letting the store throw a schema error.
+            if (!stateDbExists(workspaceDir)) {
+                sendSuccess(res, {
+                    tasks: [],
+                    total: 0,
+                    nextAction: 'No failed tasks. PD pipeline is healthy. (state.db not yet initialized — no tasks have been created.)',
+                });
+                return;
+            }
+            const store = ctx.sqliteTaskStore ?? getStore(workspaceDir);
+            const tasks = await store.listFailedTasks({ kind, since, limit: limitResult, offset: offsetResult });
+            const total = await store.countFailedTasks({ kind, since });
+            // Only report "PD pipeline is healthy" when total === 0. When
+            // tasks.length === 0 but total > 0, the caller has paginated past the
+            // last page — returning "healthy" here would mask the failures that
+            // exist on earlier pages.
+            if (total === 0) {
+                sendSuccess(res, {
+                    tasks,
+                    total,
+                    nextAction: 'No failed tasks. PD pipeline is healthy.',
+                });
+            }
+            else {
+                sendSuccess(res, { tasks, total });
+            }
+        }
+        catch (err) {
+            sendError(res, 500, 'failed_tasks_list_error', errorMessage(err));
+        }
+        return;
+    }
+    // Detail: GET /api/v1/failed-tasks/:id
+    const id = subPath.replace(/^\//, '');
+    if (id.length === 0) {
+        sendNotFound(res, `Route /api/v1/failed-tasks${subPath} not found`);
+        return;
+    }
+    if (method !== 'GET') {
+        sendMethodNotAllowed(res);
+        return;
+    }
+    try {
+        if (!stateDbExists(workspaceDir)) {
+            sendNotFound(res, `Task ${id} not found`);
+            return;
+        }
+        const store = ctx.sqliteTaskStore ?? getStore(workspaceDir);
+        const detail = await store.getFailedTaskDetail(id);
+        if (!detail) {
+            sendNotFound(res, `Task ${id} not found (or it is not in 'failed' / 'needs_human_review' status)`);
+            return;
+        }
+        sendSuccess(res, {
+            task: detail.task,
+            runs: detail.runs,
+            lastError: detail.lastError,
+            pendingAgentDraft: detail.pendingAgentDraft,
+        });
+    }
+    catch (err) {
+        sendError(res, 500, 'failed_tasks_detail_error', errorMessage(err));
+    }
+}

package/console/dist/server/routes/feedback-reports.d.ts

@@ -13,6 +13,7 @@ export type FeedbackReportsContext = {
     featureFlags?: Record<string, {
         enabled: boolean;
     }>;
+    maintainerEmail?: string;
 };
 export declare function handleFeedbackReportsRoute(req: IncomingMessage, res: ServerResponse, ctx: FeedbackReportsContext): Promise<void>;
 export declare function disposeFeedbackReportModels(): void;

package/console/dist/server/routes/feedback-reports.js

@@ -5,7 +5,8 @@
 //
 // The route is a local-only CRUD over <workspaceDir>/.pd/feedback/drafts/.
 // It MUST NOT reach the network and MUST NOT auto-submit anything.
-import { createFeedbackReport, } from '@principles/core/runtime-v2/feedback';
+import { createFeedbackReport, PendingAgentDraftStore, } from '@principles/core/runtime-v2/feedback';
+import { SqliteConnection } from '@principles/core/runtime-v2';
 import { FeedbackReportConsoleModel, } from '../models/FeedbackReportConsoleModel.js';
 import { sendSuccess, sendError, sendNotFound, sendMethodNotAllowed, sendBadRequest, } from '../utils/response.js';
 const models = new Map();
@@ -17,6 +18,17 @@ function getModel(workspaceDir) {
     }
     return model;
 }
+const draftStores = new Map();
+function getDraftStore(workspaceDir) {
+    let entry = draftStores.get(workspaceDir);
+    if (!entry) {
+        const connection = new SqliteConnection({ workspaceDir, readonly: false });
+        const store = new PendingAgentDraftStore(connection);
+        entry = { store, connection };
+        draftStores.set(workspaceDir, entry);
+    }
+    return entry.store;
+}
 async function readJsonBody(req) {
     return new Promise((resolve) => {
         const chunks = [];
@@ -97,7 +109,8 @@ export async function handleFeedbackReportsRoute(req, res, ctx) {
             const obj = bodyResult.value;
             const { input } = obj;
             const diagnostics = obj.diagnostics ?? {};
-            const reportResult = createFeedbackReport(input, diagnostics);
+            const draftStore = getDraftStore(ctx.workspaceDir);
+            const reportResult = createFeedbackReport(input, diagnostics, ctx.maintainerEmail, draftStore);
             if (!reportResult.ok) {
                 sendBadRequest(res, reportResult.errors.map((e) => `${e.field}: ${e.reason}`).join('; '));
                 return;
@@ -136,6 +149,10 @@ export async function handleFeedbackReportsRoute(req, res, ctx) {
                 }
                 return;
             }
+            if (!result.report) {
+                sendError(res, 500, 'feedback_reports_get_empty', 'Report lookup succeeded but no report was returned');
+                return;
+            }
             sendSuccess(res, { report: result.report });
         }
         catch (err) {
@@ -164,4 +181,14 @@ export function disposeFeedbackReportModels() {
         model.dispose();
     }
     models.clear();
+    // Task 13: also close and clear the draft store cache
+    for (const entry of draftStores.values()) {
+        try {
+            entry.connection.close();
+        }
+        catch {
+            // best-effort close on shutdown
+        }
+    }
+    draftStores.clear();
 }

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

@@ -35,7 +35,25 @@ export async function handleLifecycleRoute(req, res, workspaceDir, subPath) {
         try {
             const result = model.getLifecycleMetrics(principleId);
             if (!result) {
-                sendNotFound(res, `Principle "${principleId}" not found in lifecycle read model`);
+                // DEFECT-006 (PRI-515): A null result means the principle is not in the
+                // lifecycle read model (recently created, no rules/implementations, or
+                // the ledger does not exist yet). The frontend calls this endpoint for
+                // every active principle on the activation page; returning 404 here
+                // causes the browser to log a network console error that frontend
+                // `try/catch` cannot suppress. Return 200 + insufficientData so the
+                // frontend can render the "no lifecycle data yet" state cleanly.
+                // EP-03 / ERR-002: graceful degradation carries a structured reason
+                // via the `note` field — same shape as the model-layer insufficientData
+                // branch, so the frontend needs only one rendering path.
+                sendSuccess(res, {
+                    principleId,
+                    adherence: {
+                        insufficientData: true,
+                        rate: null,
+                        note: '该原则尚无规则，无法计算依从率',
+                    },
+                    ruleMetrics: [],
+                });
                 return;
             }
             sendSuccess(res, result);

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

@@ -246,7 +246,7 @@ async function handleRunDemo(res, _workspaceDir) {
                 reason: `demo exited with code ${outcome.code}`,
                 nextAction: stderrText.trim()
                     ? `pd stderr: ${stderrText.trim()}`
-                    : 'Run `pd demo story-a --json` manually for diagnostics.',
+                    : 'Run `pd demo first-principle --json` manually for diagnostics.',
             });
             return;
         }
@@ -258,7 +258,7 @@ async function handleRunDemo(res, _workspaceDir) {
                 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.',
+                nextAction: 'Run `pd demo first-principle --json` manually and inspect the output.',
             });
             return;
         }