@guanlin4924/devflow-pi 0.1.94 → 0.1.96

package/src/doctor.ts

@@ -1,10 +1,22 @@
-import { access, lstat, readFile } from "node:fs/promises";
+import { access, lstat, readFile, readdir } from "node:fs/promises";
+import { createHash } from "node:crypto";
 import path from "node:path";
 
 import { DEVFLOW_PLUGIN_NAMES, OMP_RUNTIME_VERSION, PRODUCT_VERSION } from "./constants.ts";
 import { devflowAgentDir, devflowHome, ompSdkManifestPath, pluginRoots, projectSessionDir } from "./paths.ts";
 import type { ProjectContext } from "./project-context.ts";
 
+const RUNTIME_FILES = ["runner.spec.mjs", "playwright.config.mjs", "reporter.mjs", "devflow-test-dsl-v1.schema.json"] as const;
+const SHA256 = /^[0-9a-f]{64}$/;
+const PROFILE_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const PROFILE_FIELDS = new Set(["profile", "base_url", "api_base_url", "navigation_origins", "api_origins", "subresources", "secret_env", "trace", "screenshots"]);
+const RESERVED_ENV = new Set([
+  "DEVFLOW_DSL_FILE", "DEVFLOW_DSL_SHA256", "DEVFLOW_TC_ID", "DEVFLOW_TC_SHA256", "DEVFLOW_EXECUTION_ID",
+  "DEVFLOW_EXECUTION_NONCE", "DEVFLOW_RESULT_FILE", "DEVFLOW_ARTIFACT_DIR", "DEVFLOW_ENVIRONMENT_FILE",
+  "PATH", "HOME", "TMPDIR", "LANG", "PLAYWRIGHT_BROWSERS_PATH", "SHELL", "USER", "PWD",
+]);
+const RESERVED_ENV_PREFIXES = ["NODE_", "LD_", "DYLD_", "PLAYWRIGHT_", "PYTHON", "BUN_", "NPM_", "DEVFLOW_HOME", "DEVFLOW_KIT", "DEVFLOW_SOFT"];
+
 export interface DoctorCheck {
   id: string;
   ok: boolean;
@@ -30,11 +42,200 @@ function bunVersionOk(version: string): boolean {
   return major > 1 || (major === 1 && (minor > 3 || (minor === 3 && patch >= 14)));
 }
 
-export async function runHostDoctor(project: ProjectContext): Promise<HostDoctorReport> {
+function majorVersion(version: string): number {
+  return Number((version.match(/v?(\d+)/) || [])[1] || 0);
+}
+
+export interface ProbeResult {
+  ok: boolean;
+  timedOut: boolean;
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+  /** Human-readable reason when ok is false. */
+  error?: string;
+}
+
+export interface ProbeOptions {
+  timeoutMs: number;
+  cwd?: string;
+}
+
+/** Runs one external command; must never throw and must always settle. */
+export type ProbeRunner = (argv: string[], options: ProbeOptions) => Promise<ProbeResult>;
+
+export interface DoctorOptions {
+  probe?: ProbeRunner;
+  /** Hard limits. A probe that exceeds them is reported as a failed check, never a pass. */
+  timeouts?: { browserLaunchMs?: number; versionMs?: number };
+}
+
+const DEFAULT_BROWSER_LAUNCH_TIMEOUT_MS = 20_000;
+const DEFAULT_VERSION_TIMEOUT_MS = 10_000;
+const PIPE_DRAIN_MS = 500;
+
+function settleWithin<T>(promise: Promise<T>, ms: number, fallback: T): Promise<T> {
+  return new Promise(resolve => {
+    const timer = setTimeout(() => resolve(fallback), ms);
+    promise.then(value => { clearTimeout(timer); resolve(value); }, () => { clearTimeout(timer); resolve(fallback); });
+  });
+}
+
+/** Async spawn with a hard timeout: the child is SIGKILLed on expiry and the result is marked failed. */
+export const spawnProbe: ProbeRunner = async (argv, options) => {
+  let child: ReturnType<typeof Bun.spawn>;
+  try {
+    child = Bun.spawn(argv, { stdout: "pipe", stderr: "pipe", stdin: "ignore", cwd: options.cwd });
+  } catch (error) {
+    return { ok: false, timedOut: false, exitCode: null, stdout: "", stderr: "", error: error instanceof Error ? error.message : String(error) };
+  }
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    try { child.kill("SIGKILL"); } catch { /* already gone */ }
+  }, options.timeoutMs);
+  const stdoutText = new Response(child.stdout as ReadableStream).text();
+  const stderrText = new Response(child.stderr as ReadableStream).text();
+  try {
+    const exitCode = await child.exited;
+    // A grandchild may keep the pipes open after the kill; never wait on them indefinitely.
+    const [stdout, stderr] = await Promise.all([
+      settleWithin(stdoutText, timedOut ? PIPE_DRAIN_MS : 5_000, ""),
+      settleWithin(stderrText, timedOut ? PIPE_DRAIN_MS : 5_000, ""),
+    ]);
+    if (timedOut) {
+      return { ok: false, timedOut: true, exitCode: null, stdout: stdout.trim(), stderr: stderr.trim(), error: `timed out after ${options.timeoutMs} ms and was killed` };
+    }
+    return { ok: exitCode === 0, timedOut: false, exitCode, stdout: stdout.trim(), stderr: stderr.trim(), error: exitCode === 0 ? undefined : `exit code ${exitCode}` };
+  } catch (error) {
+    return { ok: false, timedOut, exitCode: null, stdout: "", stderr: "", error: error instanceof Error ? error.message : String(error) };
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+/** Wraps a probe so that even a misbehaving runner cannot block the caller past its deadline. */
+async function guardedProbe(probe: ProbeRunner, argv: string[], options: ProbeOptions): Promise<ProbeResult> {
+  const deadline = options.timeoutMs + Math.min(2_000, Math.max(50, options.timeoutMs));
+  const fallback: ProbeResult = { ok: false, timedOut: true, exitCode: null, stdout: "", stderr: "", error: `timed out after ${options.timeoutMs} ms` };
+  try {
+    const result = await settleWithin(probe(argv, options), deadline, fallback);
+    // A timed-out probe can never count as a pass, whatever the runner claims.
+    return result.timedOut ? { ...result, ok: false } : result;
+  } catch (error) {
+    return { ...fallback, timedOut: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function probeFailure(result: ProbeResult): string {
+  const detail = (result.stderr || result.stdout).split("\n")[0]?.trim();
+  return [result.error, detail].filter(Boolean).join(": ") || "probe failed";
+}
+
+export async function verifyTestRuntime(runtimeRoot: string): Promise<{ ok: boolean; message: string; playwrightVersion?: string }> {
+  const manifestPath = path.join(runtimeRoot, "runtime-manifest.json");
+  try {
+    const manifest = JSON.parse(await readFile(manifestPath, "utf8")) as Record<string, unknown>;
+    const files = manifest.files && typeof manifest.files === "object" ? manifest.files as Record<string, unknown> : {};
+    const errors: string[] = [];
+    if (manifest.schema_version !== 1) errors.push("schema_version must be 1");
+    if (typeof manifest.runtime_version !== "string" || !manifest.runtime_version) errors.push("runtime_version is missing");
+    if (typeof manifest.playwright_version !== "string" || !/^\d+\.\d+\.\d+$/.test(manifest.playwright_version)) errors.push("playwright_version is invalid");
+    for (const name of RUNTIME_FILES) {
+      const expected = files[name];
+      const target = path.join(runtimeRoot, name);
+      const stat = await lstat(target).catch(() => null);
+      if (typeof expected !== "string" || !SHA256.test(expected)) errors.push(`manifest does not pin ${name}`);
+      else if (!stat?.isFile() || stat.isSymbolicLink()) errors.push(`runtime file is missing or unsafe: ${name}`);
+      else if (createHash("sha256").update(await readFile(target)).digest("hex") !== expected) errors.push(`runtime file hash mismatch: ${name}`);
+    }
+    if (!errors.length) {
+      const reporter = await readFile(path.join(runtimeRoot, "reporter.mjs"), "utf8");
+      const embedded = /RUNTIME_VERSION\s*=\s*["']([^"']+)["']/.exec(reporter)?.[1];
+      if (embedded !== manifest.runtime_version) errors.push(`runtime_version ${String(manifest.runtime_version)} does not match reporter ${String(embedded)}`);
+    }
+    return { ok: !errors.length, message: errors.length ? errors.join("; ") : manifestPath, playwrightVersion: typeof manifest.playwright_version === "string" ? manifest.playwright_version : undefined };
+  } catch (error) {
+    return { ok: false, message: `invalid manifest: ${error instanceof Error ? error.message : String(error)}` };
+  }
+}
+
+export function playwrightVersionMatches(installed: string, manifest: string | undefined): boolean {
+  return /^\d+\.\d+\.\d+$/.test(installed) && installed === manifest;
+}
+
+function exactOrigin(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  try {
+    const url = new URL(value);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) return null;
+    return `${url.protocol}//${url.host}` === value ? value : null;
+  } catch { return null; }
+}
+
+export async function validateEnvironmentProfile(file: string): Promise<string[]> {
+  try {
+    const stat = await lstat(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) return ["profile must be a regular non-symlink file"];
+    const profile = JSON.parse(await readFile(file, "utf8")) as Record<string, unknown>;
+    const name = path.basename(file, ".json");
+    const errors: string[] = [];
+    if (!profile || typeof profile !== "object" || Array.isArray(profile)) return ["profile root must be an object"];
+    if (!PROFILE_NAME.test(name)) errors.push(`invalid environment profile name: ${name}`);
+    for (const key of Object.keys(profile)) if (!PROFILE_FIELDS.has(key)) errors.push(`profile field is not allowed: ${key}`);
+    if (profile.profile !== name) errors.push("profile field must equal file name");
+    for (const key of ["navigation_origins", "api_origins"] as const) {
+      const values = key === "api_origins" && !(key in profile) ? [] : profile[key];
+      if (!Array.isArray(values) || (key === "navigation_origins" && !values.length)) errors.push(`${key} must be ${key === "navigation_origins" ? "a non-empty " : "an "}array`);
+      else {
+        if (values.some(value => !exactOrigin(value))) errors.push(`${key} contains an invalid origin`);
+        if (new Set(values).size !== values.length) errors.push(`${key} contains duplicate origins`);
+      }
+    }
+    const navigation = Array.isArray(profile.navigation_origins) ? profile.navigation_origins : [];
+    const api = Array.isArray(profile.api_origins) ? profile.api_origins : [];
+    for (const [key, allowed] of [["base_url", navigation], ["api_base_url", api]] as const) {
+      if (key === "api_base_url" && !(key in profile)) continue;
+      if (typeof profile[key] !== "string") errors.push(`${key} must be an absolute http(s) URL`);
+      else {
+        try { if (!allowed.includes(new URL(profile[key]).origin)) errors.push(`${key} origin is not declared`); }
+        catch { errors.push(`${key} must be an absolute http(s) URL`); }
+      }
+    }
+    const subresources = profile.subresources ?? { policy: "same-site-plus-declared", allowed_origins: [] };
+    if (!subresources || typeof subresources !== "object" || Array.isArray(subresources)) errors.push("subresources must be an object");
+    else {
+      const value = subresources as Record<string, unknown>;
+      if (Object.keys(value).some(key => !["policy", "allowed_origins"].includes(key))) errors.push("subresources contains an unsupported field");
+      if (!["same-site-plus-declared", "declared-only"].includes(String(value.policy))) errors.push("subresources.policy is invalid");
+      const allowed = value.allowed_origins;
+      if (!Array.isArray(allowed) || allowed.some(origin => !exactOrigin(origin))) errors.push("subresources.allowed_origins contains an invalid origin");
+    }
+    const secrets = profile.secret_env ?? {};
+    if (!secrets || typeof secrets !== "object" || Array.isArray(secrets)) errors.push("secret_env must be an object");
+    else for (const [key, value] of Object.entries(secrets)) {
+      if (!/^[A-Za-z_][A-Za-z0-9_]{0,63}$/.test(key)) errors.push(`secret_env key is invalid: ${key}`);
+      if (typeof value !== "string" || !/^[A-Z_][A-Z0-9_]{0,127}$/.test(value)) errors.push(`secret_env.${key} must name an upper-case environment variable`);
+      else if (RESERVED_ENV.has(value) || RESERVED_ENV_PREFIXES.some(prefix => value.startsWith(prefix))) errors.push(`secret_env.${key} uses a reserved environment variable`);
+    }
+    for (const key of ["trace", "screenshots"] as const) if (key in profile && !["on_failure", "off"].includes(String(profile[key]))) errors.push(`${key} is invalid`);
+    return errors;
+  } catch (error) {
+    return [`invalid profile: ${error instanceof Error ? error.message : String(error)}`];
+  }
+}
+
+export async function runHostDoctor(project: ProjectContext, options: DoctorOptions = {}): Promise<HostDoctorReport> {
   const checks: DoctorCheck[] = [];
   const add = (id: string, ok: boolean, message: string) => checks.push({ id, ok, message });
+  const probe = options.probe ?? spawnProbe;
+  const versionMs = options.timeouts?.versionMs ?? DEFAULT_VERSION_TIMEOUT_MS;
+  const browserMs = options.timeouts?.browserLaunchMs ?? DEFAULT_BROWSER_LAUNCH_TIMEOUT_MS;
   add("branch-runtime", true, `devflow-pi ${PRODUCT_VERSION}; OMP SDK ${OMP_RUNTIME_VERSION}`);
   add("bun", bunVersionOk(Bun.version), bunVersionOk(Bun.version) ? Bun.version : `${Bun.version}; requires >=1.3.14`);
+  const node = await guardedProbe(probe, ["node", "--version"], { timeoutMs: versionMs });
+  const nodeOk = node.ok && majorVersion(node.stdout) >= 20;
+  add("node", nodeOk, node.ok ? `${node.stdout}; requires >=20` : `missing or unusable: ${probeFailure(node)}`);
   add("project-root", path.isAbsolute(project.root), project.root);
   add("project-id", Boolean(project.manifest.projectId), project.manifest.projectId);
   const planningStat = await lstat(project.planningRoot).catch(() => null);
@@ -45,6 +246,62 @@ export async function runHostDoctor(project: ProjectContext): Promise<HostDoctor
     const root = roots[index];
     add(`plugin:${plugin}`, await exists(path.join(root, "skills")), root);
   }
+  const qualityRoot = roots[DEVFLOW_PLUGIN_NAMES.indexOf("devflow-quality")];
+  // Never fall back to a relative path: verifyTestRuntime("") would read ./runtime-manifest.json from the cwd.
+  const runtimeRoot = qualityRoot ? path.join(qualityRoot, "runtime", "playwright") : null;
+  const runtime = runtimeRoot
+    ? await verifyTestRuntime(runtimeRoot)
+    : { ok: false, message: "devflow-quality plugin root is unknown", playwrightVersion: undefined };
+  add("test-runtime-manifest", runtime.ok, runtime.message);
+  let installedPlaywright: ProbeResult | null = null;
+  if (runtime.ok && runtimeRoot) {
+    installedPlaywright = await guardedProbe(
+      probe,
+      ["node", "-e", "process.stdout.write(require(require.resolve('@playwright/test/package.json',{paths:[process.argv[1]]})).version)", runtimeRoot],
+      { timeoutMs: versionMs },
+    );
+  }
+  const versionOk = Boolean(installedPlaywright?.ok && playwrightVersionMatches(installedPlaywright.stdout, runtime.playwrightVersion));
+  add("test-runtime-playwright-version", versionOk,
+    !installedPlaywright ? "skipped: Runtime manifest is invalid"
+      : !installedPlaywright.ok ? `Playwright version probe failed: ${probeFailure(installedPlaywright)}`
+        : `${installedPlaywright.stdout}; manifest ${runtime.playwrightVersion}${versionOk ? "" : " (mismatch)"}`);
+  let chromiumOk = false;
+  let chromiumMessage = "not checked: Node >=20 and a valid Runtime manifest are required";
+  if (nodeOk && runtime.ok && runtimeRoot) {
+    const launch = await guardedProbe(
+      probe,
+      ["node", "-e", `const {chromium}=require(require.resolve('@playwright/test',{paths:[process.argv[1]]}));chromium.launch({timeout:${Math.max(1000, browserMs - 2000)}}).then(b=>b.close()).then(()=>process.exit(0),e=>{console.error(e.message);process.exit(1)})`, runtimeRoot],
+      { timeoutMs: browserMs },
+    );
+    chromiumOk = launch.ok && !launch.timedOut;
+    chromiumMessage = chromiumOk ? "launchable"
+      : launch.timedOut ? `Chromium launch timed out after ${browserMs} ms and was killed; the browser is not launchable`
+        : `Chromium is not launchable: ${probeFailure(launch)}`;
+  }
+  add("test-runtime-chromium", chromiumOk, chromiumMessage);
+  const environmentRoot = path.join(project.planningRoot, "test-environments");
+  const environmentStat = await lstat(environmentRoot).catch(() => null);
+  let profiles: string[] = [];
+  if (environmentStat?.isDirectory() && !environmentStat.isSymbolicLink()) {
+    profiles = (await readdir(environmentRoot)).filter(name => name.endsWith(".json") && !name.endsWith(".example.json"));
+  }
+  const profileErrors: string[] = [];
+  for (const profile of profiles) for (const error of await validateEnvironmentProfile(path.join(environmentRoot, profile))) profileErrors.push(`${profile}: ${error}`);
+  add("test-environments", profiles.length > 0 && !profileErrors.length,
+    !profiles.length ? `${environmentRoot}: configure a profile from local.example.json` : profileErrors.length ? profileErrors.join("; ") : `${environmentRoot}: ${profiles.join(", ")}`);
+  const runsRoot = path.join(project.root, ".devflow", "runs");
+  const runsStat = await lstat(runsRoot).catch(() => null);
+  if (!runsStat?.isDirectory() || runsStat.isSymbolicLink()) {
+    add("test-runs-root", false, `${runsRoot}: missing, not a directory, or a symlink`);
+  } else {
+    // Run directories hold traces, screenshots and result files and must never enter source control.
+    const ignored = await guardedProbe(probe, ["git", "-C", project.root, "check-ignore", "-q", "--no-index", ".devflow/runs/doctor-probe/x"], { timeoutMs: versionMs });
+    if (ignored.ok) add("test-runs-root", true, `${runsRoot} (git-ignored)`);
+    else if (ignored.exitCode === 1) add("test-runs-root", false, `${runsRoot} is not git-ignored; add .devflow/runs/ to .gitignore (run artifacts may contain secrets)`);
+    else if (ignored.exitCode === 128 && /not a git repository/i.test(ignored.stderr)) add("test-runs-root", true, `${runsRoot} (project is not a git repository; ignore rule not applicable)`);
+    else add("test-runs-root", false, `cannot verify that ${runsRoot} is git-ignored: ${probeFailure(ignored)}`);
+  }
   const sdkManifest = ompSdkManifestPath();
   let installedVersion = "missing";
   if (await exists(sdkManifest)) {
@@ -59,6 +316,15 @@ export async function runHostDoctor(project: ProjectContext): Promise<HostDoctor
   add("agent-dir", true, devflowAgentDir());
   add("session-isolation", true, projectSessionDir(project.manifest.projectId));
   add("devflow-home", true, devflowHome());
+  const mcpConfig = path.join(devflowHome(), "mcp.json");
+  if (!(await exists(mcpConfig))) add("mcp", true, "MCP 未配置");
+  else {
+    try {
+      const config = JSON.parse(await readFile(mcpConfig, "utf8")) as Record<string, unknown>;
+      const valid = config.schema_version === 1 && config.clients !== null && typeof config.clients === "object" && !Array.isArray(config.clients);
+      add("mcp", valid, valid ? `${mcpConfig} (schema_version 1)` : `${mcpConfig}: schema_version must be 1 and clients must be an object`);
+    } catch (error) { add("mcp", false, `${mcpConfig}: invalid JSON: ${error instanceof Error ? error.message : String(error)}`); }
+  }
   return { ok: checks.every(check => check.ok), checks };
 }
 

package/src/initialization-store.ts

@@ -7,7 +7,7 @@ import { Database } from "bun:sqlite";
 import { projectControlDatabasePath, projectDataDir } from "./paths.ts";
 import { DEVFLOW_SCAN_EXCLUDES, PLANNING_DIRECTORY } from "./project-layout.ts";
 
-export const INITIALIZATION_SCHEMA_VERSION = 2;
+export const INITIALIZATION_SCHEMA_VERSION = 3;
 export const FACT_KINDS = [
   "asset", "technology", "api", "page", "data_model", "integration",
   "rule", "toolchain", "evidence", "capability",
@@ -199,6 +199,48 @@ WHEN EXISTS(SELECT 1 FROM initialization_runs r WHERE r.id=OLD.run_id AND r.stat
 BEGIN SELECT RAISE(ABORT, 'published facts are immutable'); END;
 `;
 
+// Human approval records (schema v3). The column contract is shared with the
+// Python reader side; the triggers below make the records append-only except
+// for the Core-owned proposal lifecycle and approval supersession.
+export const APPROVAL_SCHEMA = `
+CREATE TABLE IF NOT EXISTS approval_proposals(
+  id TEXT PRIMARY KEY, project_id TEXT NOT NULL, feature TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK(kind IN ('execution_plan','environment_profile','mode_override','human_result')),
+  subject_key TEXT NOT NULL, payload_json TEXT NOT NULL, pins_json TEXT NOT NULL,
+  state_revision INTEGER NOT NULL, status TEXT NOT NULL CHECK(status IN ('proposed','consumed','rejected','expired')),
+  created_at TEXT NOT NULL, resolved_at TEXT);
+CREATE TABLE IF NOT EXISTS approvals(
+  id TEXT PRIMARY KEY, proposal_id TEXT NOT NULL UNIQUE REFERENCES approval_proposals(id),
+  project_id TEXT NOT NULL, feature TEXT NOT NULL, kind TEXT NOT NULL, subject_key TEXT NOT NULL,
+  pins_json TEXT NOT NULL, decision_json TEXT NOT NULL, approved_via TEXT NOT NULL CHECK(approved_via='runtime_ui_confirm'),
+  approved_at TEXT NOT NULL, superseded_at TEXT);
+CREATE INDEX IF NOT EXISTS idx_approval_proposals_subject ON approval_proposals(project_id, feature, kind, subject_key, status);
+CREATE INDEX IF NOT EXISTS idx_approvals_subject ON approvals(project_id, feature, kind, subject_key, superseded_at);
+CREATE TRIGGER IF NOT EXISTS approval_proposal_lifecycle BEFORE UPDATE ON approval_proposals
+WHEN OLD.status!='proposed' OR NEW.status='proposed' OR NEW.resolved_at IS NULL
+ OR NEW.id!=OLD.id OR NEW.project_id!=OLD.project_id OR NEW.feature!=OLD.feature OR NEW.kind!=OLD.kind
+ OR NEW.subject_key!=OLD.subject_key OR NEW.payload_json!=OLD.payload_json OR NEW.pins_json!=OLD.pins_json
+ OR NEW.state_revision!=OLD.state_revision OR NEW.created_at!=OLD.created_at
+BEGIN SELECT RAISE(ABORT, 'approval proposals only transition once from proposed'); END;
+CREATE TRIGGER IF NOT EXISTS approval_proposal_delete BEFORE DELETE ON approval_proposals
+BEGIN SELECT RAISE(ABORT, 'approval proposals are append-only'); END;
+CREATE TRIGGER IF NOT EXISTS approval_requires_open_proposal BEFORE INSERT ON approvals
+WHEN NOT EXISTS(
+  SELECT 1 FROM approval_proposals p
+  WHERE p.id=NEW.proposal_id AND p.status='proposed' AND p.project_id=NEW.project_id AND p.feature=NEW.feature
+    AND p.kind=NEW.kind AND p.subject_key=NEW.subject_key AND p.pins_json=NEW.pins_json
+)
+BEGIN SELECT RAISE(ABORT, 'approval does not match an open proposal'); END;
+CREATE TRIGGER IF NOT EXISTS approval_supersede_only BEFORE UPDATE ON approvals
+WHEN OLD.superseded_at IS NOT NULL OR NEW.superseded_at IS NULL
+ OR NEW.id!=OLD.id OR NEW.proposal_id!=OLD.proposal_id OR NEW.project_id!=OLD.project_id OR NEW.feature!=OLD.feature
+ OR NEW.kind!=OLD.kind OR NEW.subject_key!=OLD.subject_key OR NEW.pins_json!=OLD.pins_json
+ OR NEW.decision_json!=OLD.decision_json OR NEW.approved_via!=OLD.approved_via OR NEW.approved_at!=OLD.approved_at
+BEGIN SELECT RAISE(ABORT, 'approvals are immutable except supersession'); END;
+CREATE TRIGGER IF NOT EXISTS approval_delete BEFORE DELETE ON approvals
+BEGIN SELECT RAISE(ABORT, 'approvals are append-only'); END;
+`;
+
 function now(): string { return new Date().toISOString(); }
 function canonicalJson(value: unknown): string {
   if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
@@ -268,6 +310,7 @@ export class InitializationStore {
     }
     const migrate = db.transaction(() => {
       db.exec(SCHEMA);
+      db.exec(APPROVAL_SCHEMA);
       const ensureColumn = (table: string, column: string, definition: string) => {
         const columns = db.query(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>;
         if (!columns.some(item => item.name === column)) db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`);
@@ -287,6 +330,10 @@ export class InitializationStore {
           db.exec("CREATE INDEX IF NOT EXISTS idx_document_jobs_status ON document_jobs(status, updated_at)");
           version = 2;
         }
+        if (version < 3) {
+          // v3 only adds the approval tables created above; existing rows are untouched.
+          version = 3;
+        }
         db.query("UPDATE schema_meta SET version=?").run(version);
       }
       const verified = db.query("SELECT version FROM schema_meta LIMIT 1").get() as { version: number };

package/src/mcp/auth.ts

@@ -0,0 +1,103 @@
+import { createHash } from "node:crypto";
+import { readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+
+import { normalizeDevflowHome } from "../paths.ts";
+import type { McpToolName } from "./types.ts";
+
+export const FEATURE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+export const TOOLS = ["validate_feature", "run_feature", "get_feature_report", "dsl_draft_validate"] as const;
+export const MAX_DSL_BYTES = 2 * 1024 * 1024;
+const PERMISSIONS = new Set(["validate", "report", "run", "dsl_draft"]);
+
+export type ProjectGrant = { features: string[] | "*"; permissions: string[]; environment_profiles: string[] };
+export type McpConfig = { schema_version: 1; clients: Record<string, { projects: Record<string, ProjectGrant> }> };
+
+export class McpError extends Error {
+  constructor(public readonly code: string, message: string) { super(message); }
+}
+
+function invalidConfig(message: string): never {
+  throw new McpError("mcp_permission_denied", `invalid mcp.json: ${message}`);
+}
+
+function stringArray(value: unknown, label: string): string[] {
+  if (!Array.isArray(value) || value.some(item => typeof item !== "string")) invalidConfig(`${label} must be an array of strings`);
+  return value as string[];
+}
+
+function validateGrant(value: unknown, label: string): ProjectGrant {
+  if (!value || typeof value !== "object" || Array.isArray(value)) invalidConfig(`${label} must be an object`);
+  const grant = value as Record<string, unknown>;
+  const features = grant.features === "*" ? "*" : stringArray(grant.features, `${label}.features`);
+  const permissions = stringArray(grant.permissions, `${label}.permissions`);
+  if (permissions.some(permission => !PERMISSIONS.has(permission))) invalidConfig(`${label}.permissions contains an unsupported permission`);
+  const environmentProfiles = grant.environment_profiles === undefined ? [] : stringArray(grant.environment_profiles, `${label}.environment_profiles`);
+  return { features, permissions, environment_profiles: environmentProfiles };
+}
+
+function validateConfig(value: unknown): McpConfig {
+  if (!value || typeof value !== "object" || Array.isArray(value)) invalidConfig("root must be an object");
+  const root = value as Record<string, unknown>;
+  if (root.schema_version !== 1) invalidConfig("schema_version must be 1");
+  if (!root.clients || typeof root.clients !== "object" || Array.isArray(root.clients)) invalidConfig("clients must be an object");
+  const clients: McpConfig["clients"] = {};
+  for (const [clientName, clientValue] of Object.entries(root.clients as Record<string, unknown>)) {
+    if (!clientValue || typeof clientValue !== "object" || Array.isArray(clientValue)) invalidConfig(`clients.${clientName} must be an object`);
+    const projectsValue = (clientValue as Record<string, unknown>).projects;
+    if (!projectsValue || typeof projectsValue !== "object" || Array.isArray(projectsValue)) invalidConfig(`clients.${clientName}.projects must be an object`);
+    const projects: Record<string, ProjectGrant> = {};
+    for (const [project, grant] of Object.entries(projectsValue as Record<string, unknown>)) {
+      if (!path.isAbsolute(project)) invalidConfig(`project key must be absolute: ${project}`);
+      projects[project] = validateGrant(grant, `clients.${clientName}.projects.${project}`);
+    }
+    clients[clientName] = { projects };
+  }
+  return { schema_version: 1, clients };
+}
+
+export async function loadAuthorization(client: string, home = normalizeDevflowHome(process.env.DEVFLOW_HOME)): Promise<McpConfig> {
+  const file = path.join(home, "mcp.json");
+  let value: unknown;
+  try {
+    value = JSON.parse(await readFile(file, "utf8"));
+  } catch (error) {
+    throw new McpError("mcp_permission_denied", `MCP authorization is unavailable: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const config = validateConfig(value);
+  if (!Object.prototype.hasOwnProperty.call(config.clients, client)) throw new McpError("mcp_permission_denied", `unknown MCP client: ${client}`);
+  return config;
+}
+
+function permissionFor(tool: McpToolName): string {
+  if (tool === "dsl_draft_validate") return "dsl_draft";
+  if (tool === "get_feature_report") return "report";
+  if (tool === "validate_feature") return "validate";
+  return "run";
+}
+
+export async function authorize(config: McpConfig, client: string, tool: McpToolName, project: unknown, feature?: unknown): Promise<{ project: string; grant: ProjectGrant }> {
+  if (typeof project !== "string" || !path.isAbsolute(project)) throw new McpError("mcp_input_invalid", "project must be an absolute path");
+  let resolved: string;
+  try { resolved = await realpath(project); } catch { throw new McpError("mcp_project_not_allowed", "project does not exist"); }
+  const grants = config.clients[client]?.projects ?? {};
+  let grant: ProjectGrant | undefined;
+  for (const [key, candidate] of Object.entries(grants)) {
+    try {
+      if (await realpath(key) === resolved) { grant = candidate; break; }
+    } catch {
+      // A missing configured project cannot authorize a request.
+    }
+  }
+  if (!grant) throw new McpError("mcp_project_not_allowed", "project is not authorized");
+  if (tool !== "dsl_draft_validate") {
+    if (typeof feature !== "string" || !FEATURE_RE.test(feature)) throw new McpError("mcp_input_invalid", "feature is invalid");
+    if (grant.features !== "*" && !grant.features.includes(feature)) throw new McpError("mcp_feature_not_allowed", "feature is not authorized");
+  }
+  if (!grant.permissions.includes(permissionFor(tool))) throw new McpError("mcp_permission_denied", "permission is not authorized");
+  return { project: resolved, grant };
+}
+
+export function requestHash(value: unknown): string {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}

package/src/mcp/core.ts

@@ -0,0 +1,102 @@
+import path from "node:path";
+
+import { packageRoot } from "../paths.ts";
+import type { CoreRunner, CoreResult } from "./types.ts";
+
+export const runnerScript = path.join(packageRoot(), "plugins/devflow-core/skills/workflow-orchestrator/scripts/acceptance_test_runner.py");
+export const dslScript = path.join(packageRoot(), "plugins/devflow-core/skills/workflow-orchestrator/scripts/dsl_draft.py");
+
+const DEFAULT_TIMEOUT_MS = 7_200_000;
+const TERMINATION_GRACE_MS = 5_000;
+const PROGRESS_INTERVAL_MS = 10_000;
+
+function terminateProcessGroup(pid: number | undefined, signal: "SIGTERM" | "SIGKILL"): void {
+  if (pid === undefined) return;
+  try { process.kill(-pid, signal); } catch { /* process group may already be gone */ }
+}
+
+async function settleText(value: Promise<string>, timeoutMs: number): Promise<string> {
+  return Promise.race([
+    value,
+    new Promise<string>(resolve => setTimeout(() => resolve(""), timeoutMs)),
+  ]);
+}
+
+export const runPython: CoreRunner = async (script, args, cwd, stdin, timeoutMs = DEFAULT_TIMEOUT_MS, onProgress) => {
+  // -E/-s ignore PYTHON* variables and user site-packages.  Not -I: isolated mode also drops the
+  // script directory from sys.path, and the Core scripts import their sibling modules.
+  const child = Bun.spawn(["python3", "-E", "-s", script, ...args], {
+    cwd,
+    detached: true,
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const stdoutPromise = new Response(child.stdout).text();
+  const stderrPromise = new Response(child.stderr).text();
+  if (stdin !== undefined) child.stdin.write(stdin);
+  child.stdin.end();
+  const progressTimer = onProgress === undefined ? undefined : setInterval(() => {
+    void Promise.resolve(onProgress()).catch(() => undefined);
+  }, PROGRESS_INTERVAL_MS);
+
+  let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+  let timedOut = false;
+  const timeoutPromise = new Promise<"timeout">(resolve => {
+    timeoutHandle = setTimeout(() => resolve("timeout"), timeoutMs);
+  });
+  const exitPromise = child.exited.then(exitCode => ({ exitCode }));
+  const winner = await Promise.race([exitPromise, timeoutPromise]);
+  if (winner === "timeout") {
+    timedOut = true;
+    terminateProcessGroup(child.pid, "SIGTERM");
+    try { child.kill("SIGTERM"); } catch { /* already exited */ }
+    await new Promise(resolve => setTimeout(resolve, TERMINATION_GRACE_MS));
+    terminateProcessGroup(child.pid, "SIGKILL");
+    try { child.kill("SIGKILL"); } catch { /* already exited */ }
+    if (progressTimer !== undefined) clearInterval(progressTimer);
+    clearTimeout(timeoutHandle);
+    return {
+      exitCode: null,
+      stdout: await settleText(stdoutPromise, 100),
+      stderr: await settleText(stderrPromise, 100),
+      timedOut,
+    };
+  }
+
+  if (progressTimer !== undefined) clearInterval(progressTimer);
+  clearTimeout(timeoutHandle);
+  return {
+    exitCode: winner.exitCode,
+    stdout: await stdoutPromise,
+    stderr: await stderrPromise,
+    timedOut,
+  };
+};
+
+export async function invokeCore(
+  runner: CoreRunner,
+  action: string,
+  project: string,
+  feature: string,
+  timeoutMs?: number,
+  onProgress?: () => void | Promise<void>,
+): Promise<CoreResult> {
+  const result = await runner(
+    runnerScript,
+    [action, "--feature", feature, "--json", ...(action === "run" ? ["--write"] : [])],
+    project,
+    undefined,
+    timeoutMs,
+    onProgress,
+  );
+  if (result.timedOut) return { ok: false, reason: "mcp_run_timeout", error_code: "mcp_run_timeout" };
+  try {
+    return JSON.parse(result.stdout) as CoreResult;
+  } catch {
+    // Keep the tail of the diagnostic (where Python tracebacks end), without project paths.
+    const detail = (result.stderr || result.stdout || `Core exited ${result.exitCode}`).slice(-1000)
+      .replace(/(?:[A-Za-z]:)?[^\s,;()"']+[\/][^\s,;()"']+/g, "<path>");
+    return { ok: false, reason: "core_failed", error_code: "core_failed", errors: [detail] };
+  }
+}