@kontourai/flow-agents 1.4.0 → 2.0.1

package/src/cli/init.ts

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
 import * as os from "node:os";
 import * as path from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -16,13 +17,13 @@ type TelemetrySink = "local-files" | "local-kontour-console" | "kontour-hosted-c
 type InitOptions = {
   runtime: Runtime;
   dest: string;
+  global?: boolean;
   consoleUrl?: string;
   consoleEndpoint?: string;
   consoleTokenFile?: string;
   consoleTokenValue?: string;
   consoleTenant?: string;
   telemetrySinks: TelemetrySink[];
-  packs?: string;
   activateKits: boolean;
 };
 
@@ -95,12 +96,19 @@ function usage(): void {
 Options:
   --runtime base|codex|claude-code|kiro|opencode|pi
   --dest PATH
+  --global              Target the runtime's global/user-level config path.
+                        claude-code: merges FA hooks into ~/.claude/settings.json.
+                          Honors FLOW_AGENTS_USER_CLAUDE_SETTINGS for test isolation.
+                        opencode: merges opencode.json into ~/.config/opencode/opencode.json
+                          (honors XDG_CONFIG_HOME; test isolation via FLOW_AGENTS_USER_OPENCODE_CONFIG).
+                        codex: runs install-codex-home.sh into ~/.flow-agents/codex
+                          (the isolated Codex HOME; hooks merged, not overwritten).
+                        pi: NOT_VERIFIED (no documented global dir); warns and falls back to workspace default.
   --telemetry-sink local-files|local-kontour-console|kontour-hosted-console|user-hosted-console
   --console-url URL
   --console-endpoint URL
   --console-token-file PATH
   --console-tenant ID
-  --packs LIST
   --activate-kits
   --yes, --headless
 `);
@@ -169,6 +177,34 @@ function defaultDest(runtime: Runtime): string {
   return process.cwd();
 }
 
+function globalDest(runtime: Runtime): string {
+  if (runtime === "claude-code") {
+    // Honor FLOW_AGENTS_USER_CLAUDE_SETTINGS for test isolation (same as checkScopeCollision).
+    const override = process.env["FLOW_AGENTS_USER_CLAUDE_SETTINGS"];
+    if (override) return path.dirname(override);
+    return path.join(os.homedir(), ".claude");
+  }
+  if (runtime === "opencode") {
+    // Honor FLOW_AGENTS_USER_OPENCODE_CONFIG (points to the opencode.json FILE) for test isolation,
+    // mirroring FLOW_AGENTS_USER_CLAUDE_SETTINGS for claude-code.
+    const override = process.env["FLOW_AGENTS_USER_OPENCODE_CONFIG"];
+    if (override) return path.dirname(override);
+    // Global opencode config: ~/.config/opencode/ (honor XDG_CONFIG_HOME when set, else ~/.config).
+    return path.join(process.env["XDG_CONFIG_HOME"] ?? path.join(os.homedir(), ".config"), "opencode");
+  }
+  if (runtime === "codex") {
+    // codex --global routes to the isolated Codex HOME at ~/.flow-agents/codex.
+    // This is the same path used by install-codex-home.sh; --dest overrides it for sandbox testing.
+    return path.join(os.homedir(), ".flow-agents", "codex");
+  }
+  if (runtime === "pi") {
+    // pi has no documented global config dir.
+    // NOT_VERIFIED: fall back to workspace default and warn caller.
+    return defaultDest(runtime);
+  }
+  return defaultDest(runtime);
+}
+
 function parseYesNo(value: string, fallback: boolean): boolean {
   const normalized = value.trim().toLowerCase();
   if (!normalized) return fallback;
@@ -184,7 +220,9 @@ async function interactiveOptions(argv: string[]): Promise<InitOptions> {
     const runtimeDefault = normalizeRuntime(flagString(args.flags, "runtime")) ?? "base";
     const runtimeAnswer = flagString(args.flags, "runtime") ?? await rl.question(`Runtime [${runtimeDefault}]: `);
     const runtime = normalizeRuntime(runtimeAnswer.trim() || runtimeDefault) ?? runtimeDefault;
-    const destDefault = flagString(args.flags, "dest", defaultDest(runtime)) ?? defaultDest(runtime);
+    const isGlobal = flagBool(args.flags, "global");
+    const destBase = isGlobal ? globalDest(runtime) : defaultDest(runtime);
+    const destDefault = flagString(args.flags, "dest", destBase) ?? destBase;
     const destAnswer = flagString(args.flags, "dest") ?? await rl.question(`Install destination [${destDefault}]: `);
     const sinkDefault = telemetrySinksFromFlags(args.flags);
     const sinkAnswer = flagList(args.flags, "telemetry-sink").length || flagList(args.flags, "telemetry-sinks").length
@@ -205,6 +243,7 @@ async function interactiveOptions(argv: string[]): Promise<InitOptions> {
         : "no";
     return {
       runtime,
+      global: isGlobal,
       dest: path.resolve(destAnswer.trim() || destDefault),
       consoleUrl: consoleUrl?.trim() || undefined,
       consoleEndpoint: consoleEndpoint?.trim() || undefined,
@@ -212,7 +251,6 @@ async function interactiveOptions(argv: string[]): Promise<InitOptions> {
       consoleTokenValue: consoleTokenValue?.trim() || undefined,
       consoleTenant: consoleTenant?.trim() || undefined,
       telemetrySinks,
-      packs: flagString(args.flags, "packs"),
       activateKits: runtime === "codex" && parseYesNo(activateAnswer, activateDefault),
     };
   } finally {
@@ -223,15 +261,17 @@ async function interactiveOptions(argv: string[]): Promise<InitOptions> {
 function headlessOptions(argv: string[]): InitOptions {
   const args = parseArgs(argv);
   const runtime = normalizeRuntime(flagString(args.flags, "runtime")) ?? "base";
+  const isGlobal = flagBool(args.flags, "global");
+  const destBase = isGlobal ? globalDest(runtime) : defaultDest(runtime);
   return {
     runtime,
-    dest: path.resolve(flagString(args.flags, "dest", defaultDest(runtime)) ?? defaultDest(runtime)),
+    global: isGlobal,
+    dest: path.resolve(flagString(args.flags, "dest", destBase) ?? destBase),
     consoleUrl: flagString(args.flags, "console-url"),
     consoleEndpoint: flagString(args.flags, "console-endpoint") ?? flagString(args.flags, "console-endpoint-url"),
     consoleTokenFile: flagString(args.flags, "console-token-file"),
     consoleTenant: flagString(args.flags, "console-tenant") ?? flagString(args.flags, "console-tenant-id"),
     telemetrySinks: telemetrySinksFromFlags(args.flags),
-    packs: flagString(args.flags, "packs"),
     activateKits: runtime === "codex" && flagBool(args.flags, "activate-kits"),
   };
 }
@@ -262,7 +302,6 @@ function installBundle(bundle: string, options: InitOptions): number {
   if (consoleTokenFile) args.push("--console-token-file", consoleTokenFile);
   if (options.consoleTenant) args.push("--console-tenant", options.consoleTenant);
   const env = { ...process.env };
-  if (options.packs) env.FLOW_AGENTS_PACKS = options.packs;
   const result = spawnSync("bash", args, { cwd: bundle, env, encoding: "utf8", stdio: "inherit" });
   if (tempTokenFile) fs.rmSync(path.dirname(tempTokenFile), { recursive: true, force: true });
   if (result.error) {
@@ -302,7 +341,122 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
     // There is no well-known user-level codex hooks file in our install paths,
     // so no collision check is needed for codex.
     if (options.runtime === "claude-code") {
-      checkScopeCollision();
+      // Skip collision check when --global is set: the user is intentionally
+      // targeting the global settings, so the collision they'd create is expected.
+      if (!options.global) checkScopeCollision();
+    }
+    // --global for claude-code: merge only into the global/user-level settings dir.
+    // This writes only the hook-wiring config (merge into ~/.claude/settings.json),
+    // not the full workspace bundle. The global settings dir is the claude config root,
+    // so the settings.json lives directly in dest (not dest/.claude/).
+    if (options.global && options.runtime === "claude-code") {
+      const bundle = ensureBundle(options.runtime);
+      // For --global, dest is ~/.claude/ (the global settings dir).
+      // dogfoodClaudeCode writes to dest/.claude/settings.json — but for global,
+      // the settings.json lives at dest/settings.json (dest IS ~/.claude/).
+      // We use a special global-merge path: merge directly into dest/settings.json.
+      const sourcePath = path.join(bundle, ".claude", "settings.json");
+      if (!fs.existsSync(sourcePath)) {
+        console.error(`flow-agents init: bundle settings missing: ${sourcePath}`);
+        return 1;
+      }
+      const managed = JSON.parse(fs.readFileSync(sourcePath, "utf8")) as Record<string, unknown>;
+      // Remove permissive defaults (not appropriate for global user settings).
+      delete managed["permissions"];
+      delete managed["skipDangerousModePermissionPrompt"];
+      fs.mkdirSync(options.dest, { recursive: true });
+      const destSettingsPath = path.join(options.dest, "settings.json");
+      const installMergePath = path.join(root, "scripts", "install-merge.js");
+      const _require = createRequire(import.meta.url);
+      const { mergeSettings } = _require(installMergePath) as { mergeSettings: (a: Record<string, unknown>, b: Record<string, unknown>) => Record<string, unknown> };
+      let existing: Record<string, unknown> = {};
+      if (fs.existsSync(destSettingsPath)) {
+        try { existing = JSON.parse(fs.readFileSync(destSettingsPath, "utf8")) as Record<string, unknown>; } catch { existing = {}; }
+      }
+      const merged = mergeSettings(existing, managed);
+      const tmp = `${destSettingsPath}.tmp.${process.pid}`;
+      fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+      fs.renameSync(tmp, destSettingsPath);
+      // Write version stamp.
+      const installRecordDir = path.join(options.dest, ".flow-agents");
+      fs.mkdirSync(installRecordDir, { recursive: true });
+      const pkgJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")) as Record<string, string>;
+      const record = { version: pkgJson["version"] ?? "0.0.0", installedAt: new Date().toISOString(), runtime: "claude-code", global: true };
+      const recordPath = path.join(installRecordDir, "install.json");
+      const recordTmp = `${recordPath}.tmp.${process.pid}`;
+      fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+      fs.renameSync(recordTmp, recordPath);
+      console.log(`Flow Agents global hooks merged for claude-code in ${options.dest}`);
+      return 0;
+    }
+    // --global for opencode: merge FA opencode.json into the global opencode config dir.
+    // Global path: ~/.config/opencode/opencode.json (honor XDG_CONFIG_HOME).
+    // Test isolation: FLOW_AGENTS_USER_OPENCODE_CONFIG points to the opencode.json FILE.
+    if (options.global && options.runtime === "opencode") {
+      const bundle = ensureBundle(options.runtime);
+      const sourcePath = path.join(bundle, "opencode.json");
+      if (!fs.existsSync(sourcePath)) {
+        console.error(`flow-agents init: bundle opencode.json missing: ${sourcePath}`);
+        return 1;
+      }
+      const managed = JSON.parse(fs.readFileSync(sourcePath, "utf8")) as Record<string, unknown>;
+      fs.mkdirSync(options.dest, { recursive: true });
+      // The global opencode.json lives directly at dest/opencode.json.
+      const destConfigPath = path.join(options.dest, "opencode.json");
+      const installMergePath = path.join(root, "scripts", "install-merge.js");
+      const _require = createRequire(import.meta.url);
+      const { mergeSettings } = _require(installMergePath) as { mergeSettings: (a: Record<string, unknown>, b: Record<string, unknown>) => Record<string, unknown> };
+      let existing: Record<string, unknown> = {};
+      if (fs.existsSync(destConfigPath)) {
+        try { existing = JSON.parse(fs.readFileSync(destConfigPath, "utf8")) as Record<string, unknown>; } catch { existing = {}; }
+      }
+      const merged = mergeSettings(existing, managed);
+      const tmp = `${destConfigPath}.tmp.${process.pid}`;
+      fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}
+`, "utf8");
+      fs.renameSync(tmp, destConfigPath);
+      // Write version stamp.
+      const installRecordDir = path.join(options.dest, ".flow-agents");
+      fs.mkdirSync(installRecordDir, { recursive: true });
+      const pkgJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")) as Record<string, string>;
+      const record = { version: pkgJson["version"] ?? "0.0.0", installedAt: new Date().toISOString(), runtime: "opencode", global: true };
+      const recordPath = path.join(installRecordDir, "install.json");
+      const recordTmp = `${recordPath}.tmp.${process.pid}`;
+      fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}
+`, "utf8");
+      fs.renameSync(recordTmp, recordPath);
+      console.log(`Flow Agents global config merged for opencode in ${options.dest}`);
+      return 0;
+    }
+    // --global for codex: run install-codex-home.sh to install into the isolated Codex HOME.
+    // The codex --global path is ~/.flow-agents/codex (the isolated home IS codex's global).
+    // Pass through telemetry/console args and honor --dest override for sandbox testing.
+    if (options.global && options.runtime === "codex") {
+      const codexHomeScript = path.join(root, "scripts", "install-codex-home.sh");
+      if (!fs.existsSync(codexHomeScript)) {
+        console.error(`flow-agents init: install-codex-home.sh missing: ${codexHomeScript}`);
+        return 1;
+      }
+      const scriptArgs: string[] = [options.dest];
+      for (const sink of options.telemetrySinks) scriptArgs.push("--telemetry-sink", sink);
+      if (options.consoleUrl) scriptArgs.push("--console-url", options.consoleUrl);
+      if (options.consoleEndpoint) scriptArgs.push("--console-endpoint", options.consoleEndpoint);
+      if (options.consoleTokenFile) scriptArgs.push("--console-token-file", options.consoleTokenFile);
+      if (options.consoleTenant) scriptArgs.push("--console-tenant", options.consoleTenant);
+      const result = spawnSync("bash", [codexHomeScript, ...scriptArgs], { env: { ...process.env }, encoding: "utf8", stdio: "inherit" });
+      if (result.error) {
+        console.error(`flow-agents init: unable to run install-codex-home.sh: ${result.error.message}`);
+        return 1;
+      }
+      return result.status ?? 1;
+    }
+    // --global for pi: NOT_VERIFIED (no documented global dir). Warn and fall through to workspace install.
+    if (options.global && options.runtime === "pi") {
+      console.warn(
+        `flow-agents init: NOT_VERIFIED: pi has no documented global config directory. ` +
+        `The --global flag for pi is not verified against pi documentation. ` +
+        `Falling back to workspace default destination: ${options.dest}`
+      );
     }
     const bundle = ensureBundle(options.runtime);
     const installed = installBundle(bundle, options);
@@ -350,38 +504,82 @@ function normalizeDogfoodRuntime(value: string | undefined): DogfoodRuntime | un
 }
 
 /**
- * Write the claude-code hook-wiring artifacts into dest.
+ * Write the claude-code hook-wiring artifacts into dest using merge semantics.
  * Reads dist/claude-code/.claude/settings.json (generated by build-bundles),
- * strips the permissive-mode permission keys (defaultMode, skipDangerousModePermissionPrompt),
- * and writes .claude/settings.json to dest.
+ * strips the permissive-mode permission keys (defaultMode, skipDangerousModePermissionPrompt)
+ * from the managed bundle settings, then MERGES into any existing dest settings.json —
+ * preserving user keys, auth, and non-flow-agents hooks. Writes version stamp.
  */
 function dogfoodClaudeCode(bundleRoot: string, dest: string): void {
   const sourcePath = path.join(bundleRoot, ".claude", "settings.json");
   if (!fs.existsSync(sourcePath)) throw new Error(`dogfood: bundle settings missing: ${sourcePath}`);
-  const settings = JSON.parse(fs.readFileSync(sourcePath, "utf8")) as Record<string, unknown>;
+  const managed = JSON.parse(fs.readFileSync(sourcePath, "utf8")) as Record<string, unknown>;
   // Remove permissive defaults that are only appropriate for installed workspaces.
   // These keys must not be present in the source repo's .claude/settings.json.
-  delete settings["permissions"];
-  delete settings["skipDangerousModePermissionPrompt"];
+  delete managed["permissions"];
+  delete managed["skipDangerousModePermissionPrompt"];
   const outDir = path.join(dest, ".claude");
   fs.mkdirSync(outDir, { recursive: true });
-  fs.writeFileSync(path.join(outDir, "settings.json"), `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+  const destSettingsPath = path.join(outDir, "settings.json");
+  // Merge: read existing, strip FA hooks, append new FA hooks, preserve all other keys.
+  const installMergePath = path.join(root, "scripts", "install-merge.js");
+  const _require = createRequire(import.meta.url);
+  const { mergeSettings } = _require(installMergePath) as { mergeSettings: (a: Record<string, unknown>, b: Record<string, unknown>) => Record<string, unknown> };
+  let existing: Record<string, unknown> = {};
+  if (fs.existsSync(destSettingsPath)) {
+    try { existing = JSON.parse(fs.readFileSync(destSettingsPath, "utf8")) as Record<string, unknown>; } catch { existing = {}; }
+  }
+  const merged = mergeSettings(existing, managed);
+  const tmp = `${destSettingsPath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+  fs.renameSync(tmp, destSettingsPath);
+  // Write version stamp.
+  const installRecordDir = path.join(dest, ".flow-agents");
+  fs.mkdirSync(installRecordDir, { recursive: true });
+  const pkgJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")) as Record<string, string>;
+  const record = { version: pkgJson["version"] ?? "0.0.0", installedAt: new Date().toISOString(), runtime: "claude-code" };
+  const recordPath = path.join(installRecordDir, "install.json");
+  const recordTmp = `${recordPath}.tmp.${process.pid}`;
+  fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+  fs.renameSync(recordTmp, recordPath);
 }
 
 /**
- * Write the codex hook-wiring artifacts into dest.
- * Reads dist/codex/.codex/hooks.json and writes .codex/hooks.json to dest.
+ * Write the codex hook-wiring artifacts into dest using merge semantics.
+ * Reads dist/codex/.codex/hooks.json and MERGES into any existing dest hooks.json —
+ * preserving user non-FA hook groups. Writes version stamp.
  * The monolithic .codex/config.toml is not written here because it contains
  * workspace settings (approvals_reviewer, features) that would override the
- * developer's existing codex configuration. Only the hooks file is written.
+ * developer's existing codex configuration. Only the hooks file is merged.
  */
 function dogfoodCodex(bundleRoot: string, dest: string): void {
   const sourcePath = path.join(bundleRoot, ".codex", "hooks.json");
   if (!fs.existsSync(sourcePath)) throw new Error(`dogfood: bundle hooks.json missing: ${sourcePath}`);
-  const hooks = fs.readFileSync(sourcePath, "utf8");
+  const managed = JSON.parse(fs.readFileSync(sourcePath, "utf8")) as Record<string, unknown>;
   const outDir = path.join(dest, ".codex");
   fs.mkdirSync(outDir, { recursive: true });
-  fs.writeFileSync(path.join(outDir, "hooks.json"), hooks, "utf8");
+  const destHooksPath = path.join(outDir, "hooks.json");
+  // Merge: read existing, strip FA hook-groups, append new FA hook-groups, preserve user groups.
+  const installMergePath = path.join(root, "scripts", "install-merge.js");
+  const _require = createRequire(import.meta.url);
+  const { mergeSettings } = _require(installMergePath) as { mergeSettings: (a: Record<string, unknown>, b: Record<string, unknown>) => Record<string, unknown> };
+  let existing: Record<string, unknown> = {};
+  if (fs.existsSync(destHooksPath)) {
+    try { existing = JSON.parse(fs.readFileSync(destHooksPath, "utf8")) as Record<string, unknown>; } catch { existing = {}; }
+  }
+  const merged = mergeSettings(existing, managed);
+  const tmp = `${destHooksPath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+  fs.renameSync(tmp, destHooksPath);
+  // Write version stamp.
+  const installRecordDir = path.join(dest, ".flow-agents");
+  fs.mkdirSync(installRecordDir, { recursive: true });
+  const pkgJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")) as Record<string, string>;
+  const record = { version: pkgJson["version"] ?? "0.0.0", installedAt: new Date().toISOString(), runtime: "codex" };
+  const recordPath = path.join(installRecordDir, "install.json");
+  const recordTmp = `${recordPath}.tmp.${process.pid}`;
+  fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+  fs.renameSync(recordTmp, recordPath);
 }
 
 /**

package/src/cli/validate-workflow-artifacts.ts

@@ -368,10 +368,26 @@ function validateSidecarGroup(inputs: string[], markdown: string[], requireSidec
     for (const dir of dirs) {
       const deliver = markdown.find((p) => path.dirname(p) === dir && p.includes("deliver") && !p.includes("plan") && !p.includes("review"));
       const delivered = deliver ? /status:\s*(delivered|accepted|archived)/i.test(readText(deliver)) : true;
-      for (const name of ["state.json", "acceptance.json", ...(delivered ? ["evidence.json"] : []), "handoff.json"]) {
+      // ADR 0010 Phase 4b: trust.bundle is the primary artifact at the delivered phase.
+      // evidence.json is OPTIONAL when trust.bundle is present (still schema-validated when present).
+      // Hard-fail on evidence.json absence only when no trust.bundle exists for a delivered session.
+      const hasTrustBundle = fs.existsSync(path.join(dir, "trust.bundle"));
+      const evidenceRequired = delivered && !hasTrustBundle;
+      for (const name of ["state.json", "acceptance.json", ...(evidenceRequired ? ["evidence.json"] : []), "handoff.json"]) {
         if (!fs.existsSync(path.join(dir, name))) issues.push({ path: path.join(dir, name), message: "required sidecar is missing" });
       }
-      if (requireCritique && !fs.existsSync(path.join(dir, "critique.json"))) issues.push({ path: path.join(dir, "critique.json"), message: "required sidecar is missing" });
+      // ADR 0010 Phase 4c: critique.json no longer written; trust.bundle carries critique claims. Accept either.
+      if (requireCritique && !fs.existsSync(path.join(dir, "critique.json")) && !fs.existsSync(path.join(dir, "trust.bundle"))) issues.push({ path: path.join(dir, "critique.json"), message: "required sidecar is missing" });
+      // ADR 0010 Phase 4c: validate critique claims in trust.bundle (sole verification artifact).
+      const trustBundlePath = path.join(dir, "trust.bundle");
+      if (requireCritique && fs.existsSync(trustBundlePath)) {
+        const { value: bundleValue } = readJson(trustBundlePath);
+        if (bundleValue) {
+          const claims = Array.isArray(bundleValue.claims) ? bundleValue.claims : [];
+          const critiqueClaims = claims.filter((c: any) => c && c.claimType === "workflow.critique.review");
+          if (critiqueClaims.some((c: any) => c.value === "fail" || c.status === "disputed")) issues.push({ path: trustBundlePath, message: "required critique must pass" });
+        }
+      }
       const acceptance = path.join(dir, "acceptance.json");
       if (deliver && fs.existsSync(acceptance)) {
         const expected = definitionAcceptanceCriteria(readText(deliver)).length;

package/src/cli/verify.ts

@@ -0,0 +1,100 @@
+import { createRequire } from "node:module";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs, flagString, flagList } from "../lib/args.js";
+import { root } from "../tools/common.js";
+
+/**
+ * flow-agents verify — CI trust anchor for downstream repos.
+ *
+ * Re-runs canonical verification FRESH in the current environment, then reconciles
+ * a delivered trust.bundle's claimed passes against those fresh results. Exits 1
+ * on divergence, fresh-verify failure, laundered commands, or no verify configured.
+ * Exits 0 on clean pass.
+ *
+ * This is a thin wrapper around scripts/ci/trust-reconcile.js: it resolves the
+ * script from the installed package root (via createRequire) and calls the exported
+ * runTrustReconcile() function directly so all output goes to the same process
+ * stdout/stderr without an extra subprocess layer.
+ *
+ * The script ships in the npm package `files` list, so downstream repos always have
+ * access to it at the same relative path from the package root.
+ */
+
+const _require = createRequire(import.meta.url);
+
+type RunTrustReconcileFn = (opts: {
+  bundle?: string | null;
+  commands?: string[];
+  repoRoot?: string | null;
+}) => number;
+
+function usage(): void {
+  process.stderr.write(
+    "usage: flow-agents verify [--commands <cmd[,cmd...]>] [--bundle <path>] [--repo-root <path>]\n" +
+    "\n" +
+    "Re-runs canonical verification fresh and reconciles a delivered trust.bundle's\n" +
+    "claimed passes against CI results. Exits 1 on divergence, fresh-verify failure,\n" +
+    "compile-only/no-verify, or laundered commands. Exits 0 on clean pass.\n" +
+    "\n" +
+    "Options:\n" +
+    "  --commands <cmd,...>  Canonical verify command(s). Comma-separated or repeated.\n" +
+    "                        Falls back to TRUST_RECONCILE_COMMANDS env or\n" +
+    "                        package.json scripts['trust-reconcile-verify'].\n" +
+    "                        No-commands → fail-closed (compile-only refused).\n" +
+    "  --bundle <path>       Delivered trust.bundle or trust.checkpoint.json path.\n" +
+    "                        Falls back to TRUST_RECONCILE_BUNDLE env, then auto-\n" +
+    "                        discovers delivery/trust.bundle or delivery/trust.checkpoint.json.\n" +
+    "                        Absent bundle: only fresh verify is enforced (fail-open).\n" +
+    "  --repo-root <path>    Repository root. Default: TRUST_RECONCILE_REPO_ROOT env or cwd.\n" +
+    "\n" +
+    "Examples:\n" +
+    "  # Re-run build+test fresh; reconcile against a delivered bundle:\n" +
+    "  flow-agents verify --commands 'npm run build,npm test' --bundle delivery/trust.bundle\n" +
+    "\n" +
+    "  # Fresh-verify only (no bundle), using package.json trust-reconcile-verify script:\n" +
+    "  flow-agents verify\n"
+  );
+}
+
+export async function main(argv = process.argv.slice(2)): Promise<number> {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    usage();
+    return 0;
+  }
+
+  const { flags } = parseArgs(argv);
+
+  // --commands may be specified multiple times or comma-separated within a single value.
+  const commandsRaw = flagList(flags, "commands");
+  const commands = commandsRaw.flatMap((c) => c.split(",").map((s) => s.trim()).filter(Boolean));
+
+  const bundle = flagString(flags, "bundle") ?? null;
+  const repoRoot = flagString(flags, "repo-root") ?? null;
+
+  // Resolve the trust-reconcile.js script from the installed package root.
+  // `root` (from tools/common.ts) walks up from this compiled file's directory until
+  // it finds a directory with both package.json and packaging/ — the package root.
+  // In a downstream installed package: node_modules/@kontourai/flow-agents/
+  // In the dev repo: the repo root itself.
+  // scripts/ci/trust-reconcile.js ships in the npm package `files` list.
+  const reconcilePath = path.join(root, "scripts", "ci", "trust-reconcile.js");
+
+  if (!fs.existsSync(reconcilePath)) {
+    process.stderr.write(
+      `[flow-agents verify] error: trust-reconcile.js not found at ${reconcilePath}\n` +
+      "[flow-agents verify] Is the package correctly installed? Expected scripts/ci/trust-reconcile.js.\n"
+    );
+    return 1;
+  }
+
+  const { runTrustReconcile } = _require(reconcilePath) as { runTrustReconcile: RunTrustReconcileFn };
+
+  return runTrustReconcile({ bundle, commands, repoRoot });
+}
+
+// Direct-script guard (mirrors pattern from other CLI subcommands).
+const _selfReal = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1Real = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfReal === _argv1Real) { process.exitCode = await main(); }