@kal-elsam/kairo-runtime 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ Historical entries below may reference the legacy `@kal-elsam/harness` package n
 
 ## Unreleased
 
+## 0.16.0 — 2026-08-13 (Kairo Runtime)
+
+Minor release. Public `kairo control-plane` command and
+`kairo.control-plane/v1` Gentle companion report. Publish tag:
+`kairo-runtime-v0.16.0`. Extension VSIX stays out of this unit.
+
+### Added
+
+- `kairo control-plane [--json] [--client cursor]`: atomic panel report
+  (work + Gentle workflow + team + attention) as `kairo.control-plane/v1`.
+- Negotiate `gentle-ai.review-integration/v2` (protocol 2.0 and 2.1) before
+  any workflow fetch. Provider states: `connected`, `upgrade_required`,
+  `unavailable`, `incompatible`.
+- Official `review status` from Gentle's announced bootstrap argv; pass
+  `next_transition` through unaltered. Receipt/gate only when Gentle publishes
+  them.
+- `sdd-status --json` projection copies `changeName` / `nextRecommended` only.
+
+### Docs
+
+- Gentle companion boundary: Kairo observes `gentle-ai.review-integration/v2`
+  and projects official `next_transition` / `sdd-status --json`. Freeze
+  `kairo review`, Cockpit receipts, orchestrator, and intelligence routing so
+  they do not feed the panel Workflow. Propose upstream `gentle-ai observe --json`
+  in Kairo docs only (`docs/gentle-companion.md`).
+
 ## 0.15.0 — 2026-08-12 (Kairo Runtime)
 
 Minor release. Declared Fleet board + model configure, and the Cursor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Kairo Runtime — local agent operating system for Codex, Cursor, Claude, Pi, Engram, and Graphify.",
   "type": "module",
   "homepage": "https://github.com/Kal-elSam/harness#readme",

package/src/cli.js

@@ -178,6 +178,15 @@ export async function runCli(argv) {
       });
       return;
     }
+    case "control-plane": {
+      const { runControlPlaneCli } = await import("./global/control-plane/cli.js");
+      await runControlPlaneCli({
+        cwd: optionsWithPolicy.cwd,
+        json: optionsWithPolicy.json === true,
+        mcpClient: optionsWithPolicy.mcpClient ?? "cursor"
+      });
+      return;
+    }
     case "fleet": {
       const fleetAction = optionsWithPolicy.fleetAction ?? "show";
       if (fleetAction === "set") {
@@ -1052,6 +1061,7 @@ function normalizeCommand(command) {
   if (command === "mcp") return "mcp";
   if (command === "connections") return "connections";
   if (command === "next") return "next";
+  if (command === "control-plane") return "control-plane";
   if (command === "fleet") return "fleet";
   if (command === "intelligence" || command === "intel") return "intelligence";
   if (command === "setup") return "setup";

package/src/global/cli-help.js

@@ -116,6 +116,7 @@ Bootstrap: see README.md and docs/install.md (curl install.sh or npx ${PACKAGE_N
   ${cli} components rollback engram-memory|sdd-core --receipt <id> [--dry-run|--yes] [--json]
   ${cli} connections [--json] [--client cursor]
   ${cli} next [--json] [--client cursor]
+  ${cli} control-plane [--json] [--client cursor]
   ${cli} fleet [--json] [--verbose] [--include-variants]
   ${cli} fleet models [--profile] [--json]
   ${cli} fleet configure [--platforms claude,opencode,cursor|codex] [--from profile|gentle] [--codex-model <id>] [--assignments a=b,...] [--yes] [--json]
@@ -168,6 +169,7 @@ Commands:
   components List, validate, scaffold, pack, import, or configure integrations (Engram, SDD).
   connections Companion chips + MCP registration (IDE panel).
   next        Selected work snapshot + integration state (panel contract).
+  control-plane Atomic panel report (work + Gentle workflow + team + attention).
   fleet      Declared fleet floor + working activity; configure/set models across CLIs.
              fleet models [--profile]   available vs enabled per tool
              fleet configure            one plan for Claude+OpenCode+Cursor (profile)

package/src/global/control-plane/attention.js

@@ -0,0 +1,141 @@
+/**
+ * Attention items and ≤2 primary actions. Gentle commands stay verbatim.
+ */
+import {
+  GENTLE_DOCTOR_COMMAND,
+  GENTLE_INSTALL_HINT,
+  GENTLE_UPGRADE_LABEL,
+  NO_ACTIVE_WORKFLOW,
+  PROVIDER,
+  WORKFLOW_KIND
+} from "./constants.js";
+
+function gentlePrimary(workflow) {
+  const provider = workflow?.provider;
+  if (provider === PROVIDER.UPGRADE_REQUIRED) {
+    return {
+      item: {
+        id: "upgrade-gentle",
+        severity: "warning",
+        message: "Gentle contract is outdated. Upgrade Gentle — do not approximate workflow."
+      },
+      action: {
+        id: "upgrade-gentle",
+        label: GENTLE_UPGRADE_LABEL,
+        command: GENTLE_DOCTOR_COMMAND
+      }
+    };
+  }
+  if (provider === PROVIDER.UNAVAILABLE) {
+    return {
+      item: {
+        id: "install-gentle",
+        severity: "warning",
+        message: GENTLE_INSTALL_HINT
+      },
+      action: {
+        id: "install-gentle",
+        label: "Install Gentle",
+        command: null
+      }
+    };
+  }
+  if (provider === PROVIDER.INCOMPATIBLE) {
+    return {
+      item: {
+        id: "gentle-incompatible",
+        severity: "error",
+        message: "Gentle response is incompatible. Fail closed."
+      },
+      action: null
+    };
+  }
+  const command = workflow?.nextTransition?.execute?.command;
+  if (provider === PROVIDER.CONNECTED && typeof command === "string" && command) {
+    const operation = workflow.nextTransition.execute.operation;
+    return {
+      item: null,
+      action: {
+        id: "gentle-next",
+        label: typeof operation === "string" && operation ? operation : "Continue Gentle",
+        command
+      }
+    };
+  }
+  return { item: null, action: null };
+}
+
+export function buildAttention({ work, workflow, team, connections }) {
+  const items = [];
+  const primaryActions = [];
+  const secondaryActions = [
+    { id: "setup", label: "Setup", command: "kairo setup --dry-run" },
+    { id: "models", label: "Models", command: "kairo fleet models" },
+    { id: "catalog", label: "Catalog", command: "kairo fleet" },
+    { id: "doctor", label: "Doctor", command: "kairo doctor" }
+  ];
+
+  const gentle = gentlePrimary(workflow);
+  if (gentle.item) items.push(gentle.item);
+  if (gentle.action) primaryActions.push(gentle.action);
+
+  if (work?.integration?.showRepair === true) {
+    items.push({
+      id: "repair-integration",
+      severity: "error",
+      message: work.integration.detail ?? "MCP integration needs repair."
+    });
+    if (primaryActions.length < 2) {
+      primaryActions.push({
+        id: "repair",
+        label: "Repair",
+        command: "kairo mcp install --yes"
+      });
+    }
+  }
+
+  if (work?.integration?.state === "missing" && primaryActions.length < 2) {
+    items.push({
+      id: "connect-mcp",
+      severity: "warning",
+      message: "Kairo MCP is not registered."
+    });
+    primaryActions.push({
+      id: "connect",
+      label: "Connect Agent",
+      command: "kairo mcp install --yes"
+    });
+  }
+
+  for (const chip of connections ?? []) {
+    if (chip?.state === "error" || chip?.state === "conflict") {
+      items.push({
+        id: `conn-${chip.id}`,
+        severity: "warning",
+        message: `${chip.label ?? chip.id}: ${chip.detail ?? chip.state}`
+      });
+    }
+  }
+
+  if (!team?.platforms?.length) {
+    items.push({
+      id: "no-platforms",
+      severity: "info",
+      message: "No platforms detected in declared fleet topology."
+    });
+  }
+
+  if (workflow?.kind === WORKFLOW_KIND.NONE && !workflow?.active) {
+    items.push({
+      id: "no-workflow",
+      severity: "info",
+      message: NO_ACTIVE_WORKFLOW
+    });
+  }
+
+  return {
+    items,
+    primaryActions: primaryActions.slice(0, 2),
+    secondaryActions
+  };
+}

package/src/global/control-plane/build-report.js

@@ -0,0 +1,146 @@
+/**
+ * Build kairo.control-plane/v1 from next + connections/fleet + Gentle adapters.
+ */
+import { buildNextReport } from "../next/next-report.js";
+import { buildConnectionsReport } from "../connections.js";
+import { resolveHomeDir } from "../paths.js";
+import {
+  CONTROL_PLANE_SCHEMA,
+  NO_ACTIVE_WORKFLOW,
+  WORKFLOW_KIND
+} from "./constants.js";
+import { buildAttention } from "./attention.js";
+import { loadGentleWorkflow } from "./gentle-adapters.js";
+import { normalizeTeam } from "./team.js";
+
+function sectionOk() {
+  return { ok: true, error: null };
+}
+
+function sectionErr(error) {
+  return { ok: false, error: String(error ?? "section_failed") };
+}
+
+export async function buildControlPlaneReport({
+  homeDir = resolveHomeDir(),
+  cwd = process.cwd(),
+  client = "cursor",
+  provider = "cursor",
+  packageRoot = null,
+  packageName = null,
+  cliVersion = null,
+  buildNext = buildNextReport,
+  buildConnections = buildConnectionsReport,
+  loadWorkflow = loadGentleWorkflow
+} = {}) {
+  const diagnostics = [];
+  const sections = {
+    work: sectionOk(),
+    workflow: sectionOk(),
+    team: sectionOk(),
+    attention: sectionOk()
+  };
+
+  let work;
+  try {
+    work = await buildNext({ homeDir, cwd, provider, client });
+  } catch (error) {
+    work = {
+      schema: "kairo.next/v1",
+      ok: false,
+      goal: null,
+      progress: [],
+      now: null,
+      blockers: [],
+      next: null,
+      conversationId: null,
+      updatedAt: null,
+      integration: {
+        state: "broken",
+        provider,
+        client,
+        mcpConnected: false,
+        enrolled: false,
+        showRepair: true,
+        detail: error instanceof Error ? error.message : String(error)
+      },
+      diagnostics: ["work_build_failed"]
+    };
+    sections.work = sectionErr("work_build_failed");
+    diagnostics.push("work_build_failed");
+  }
+
+  let connectionsReport;
+  try {
+    connectionsReport = await buildConnections({
+      homeDir,
+      workspaceRoot: cwd,
+      client,
+      packageRoot,
+      packageName,
+      cliVersion
+    });
+  } catch (error) {
+    connectionsReport = {
+      ok: false,
+      connections: [],
+      fleets: [],
+      activity: null,
+      fleetNote: null,
+      orchestratorAuthority: null
+    };
+    sections.team = sectionErr("team_build_failed");
+    diagnostics.push("team_build_failed");
+  }
+
+  const team = normalizeTeam(connectionsReport);
+  if (sections.team.ok && team.platforms.length === 0 && connectionsReport?.ok === false) {
+    sections.team = sectionErr(connectionsReport.error ?? "team_empty");
+  }
+
+  const gentle = await loadWorkflow({ cwd });
+  let workflow = gentle.workflow;
+  if (workflow && gentle.provider && workflow.provider == null) {
+    workflow = { ...workflow, provider: gentle.provider };
+  }
+  if (!gentle.ok) {
+    sections.workflow = sectionErr(gentle.error ?? "gentle_unavailable");
+    diagnostics.push(gentle.error ?? "gentle_unavailable");
+    if (!workflow?.active && !workflow?.review) {
+      workflow = {
+        kind: WORKFLOW_KIND.NONE,
+        active: false,
+        label: NO_ACTIVE_WORKFLOW,
+        phase: null,
+        nextTransition: null,
+        changeName: null,
+        review: null,
+        provider: gentle.provider ?? workflow?.provider ?? null
+      };
+    }
+  }
+
+  const attention = buildAttention({
+    work,
+    workflow,
+    team,
+    connections: team.connections
+  });
+
+  const ok = sections.work.ok || sections.team.ok;
+
+  return {
+    schema: CONTROL_PLANE_SCHEMA,
+    ok,
+    generatedAt: new Date().toISOString(),
+    client,
+    work,
+    workflow,
+    team,
+    attention,
+    sections,
+    diagnostics
+  };
+}
+
+export { normalizeTeam };

package/src/global/control-plane/cli.js

@@ -0,0 +1,36 @@
+import { resolveHomeDir } from "../paths.js";
+import { printJson } from "../json-output.js";
+import { commandHeader } from "../brand/index.js";
+import { buildControlPlaneReport } from "./build-report.js";
+
+export async function runControlPlaneCli(options = {}) {
+  const report = await buildControlPlaneReport({
+    homeDir: options.homeDir ?? resolveHomeDir(),
+    cwd: options.cwd ?? process.cwd(),
+    client: options.mcpClient ?? options.client ?? "cursor",
+    provider: options.provider ?? "cursor",
+    packageRoot: options.packageRoot ?? null,
+    packageName: options.packageName ?? null,
+    cliVersion: options.cliVersion ?? null
+  });
+
+  if (options.json) {
+    printJson(report);
+    return report;
+  }
+
+  console.log(commandHeader("Control plane"));
+  console.log(`Work · ${report.work?.integration?.state ?? "—"}`);
+  console.log(`Workflow · ${report.workflow?.label ?? "—"}`);
+  const platforms = report.team?.platforms ?? [];
+  console.log(`Team · ${platforms.length} platform(s)`);
+  for (const p of platforms) {
+    console.log(`  ${p.platform} · ${p.honesty} · agents=${p.agents?.length ?? 0}`);
+  }
+  const primary = report.attention?.primaryActions ?? [];
+  if (primary.length) {
+    console.log("Primary");
+    for (const action of primary) console.log(`- ${action.label}`);
+  }
+  return report;
+}

package/src/global/control-plane/constants.js

@@ -0,0 +1,38 @@
+/**
+ * kairo.control-plane/v1 — atomic panel report (work + workflow + team + attention).
+ */
+export const CONTROL_PLANE_SCHEMA = "kairo.control-plane/v1";
+
+export const WORKFLOW_KIND = Object.freeze({
+  SDD: "sdd",
+  REVIEW: "review",
+  DIRECT: "direct",
+  DELEGATED: "delegated",
+  NONE: "none"
+});
+
+export const HONESTY = Object.freeze({
+  LIVE: "live",
+  DECLARED: "declared",
+  OPAQUE: "opaque"
+});
+
+export const NO_ACTIVE_WORKFLOW = "No active workflow";
+
+/** Control-plane Gentle provider — distinct from observability probe states. */
+export const PROVIDER = Object.freeze({
+  CONNECTED: "connected",
+  UPGRADE_REQUIRED: "upgrade_required",
+  UNAVAILABLE: "unavailable",
+  INCOMPATIBLE: "incompatible"
+});
+
+export const PROVIDER_ERROR = Object.freeze({
+  [PROVIDER.UPGRADE_REQUIRED]: "gentle_upgrade_required",
+  [PROVIDER.UNAVAILABLE]: "gentle_unavailable",
+  [PROVIDER.INCOMPATIBLE]: "gentle_incompatible"
+});
+
+export const GENTLE_INSTALL_HINT = "Install gentle-ai separately, then Refresh.";
+export const GENTLE_UPGRADE_LABEL = "Upgrade Gentle";
+export const GENTLE_DOCTOR_COMMAND = "gentle-ai doctor";

package/src/global/control-plane/gentle-adapters.js

@@ -0,0 +1,183 @@
+/**
+ * Read-only Gentle adapters for control-plane workflow/review.
+ * Negotiate capabilities before any workflow fetch. Never invent authority.
+ */
+import { spawnSync } from "node:child_process";
+import { isAbsolute } from "node:path";
+import { probeGentle, resolveGentleBinaryPath } from "../observability/gentle-probe.js";
+import { WORKFLOW_KIND, PROVIDER } from "./constants.js";
+import {
+  emptyGentleWorkflow,
+  mapGentleProviderState,
+  providerError
+} from "./provider.js";
+import {
+  argvFromBootstrap,
+  bootstrapCommandFromProbe,
+  mapOfficialReviewStatus
+} from "./review-status.js";
+import {
+  SDD_STATUS_ARGS,
+  applySddProjection,
+  mapOfficialSddStatus
+} from "./sdd-status.js";
+
+const DEFAULT_TIMEOUT_MS = 8_000;
+
+export function parseStrictJson(text) {
+  if (typeof text !== "string" || !text.trim()) return null;
+  try {
+    const parsed = JSON.parse(text.trim());
+    return parsed != null && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function extractJsonPayload(text) {
+  if (typeof text !== "string" || !text.trim()) return null;
+  const strict = parseStrictJson(text);
+  if (strict) return strict;
+  const trimmed = text.trim();
+  const fenced = trimmed.match(/```json\s*([\s\S]*?)```/i);
+  if (fenced?.[1]) {
+    try {
+      return JSON.parse(fenced[1].trim());
+    } catch {
+      return null;
+    }
+  }
+  const start = trimmed.indexOf("{");
+  const end = trimmed.lastIndexOf("}");
+  if (start >= 0 && end > start) {
+    try {
+      return JSON.parse(trimmed.slice(start, end + 1));
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+function resolvedGentleBinary(probed, command) {
+  if (typeof command === "string" && isAbsolute(command)) return command;
+  const path = probed?.evidence?.find((row) => row?.kind === "binary")?.path;
+  return typeof path === "string" && isAbsolute(path) ? path : resolveGentleBinaryPath();
+}
+
+export function runGentleCommand(args, {
+  cwd = process.cwd(),
+  env = process.env,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  spawn = spawnSync,
+  command,
+  strict = false
+} = {}) {
+  try {
+    if (typeof command !== "string" || !isAbsolute(command)) {
+      return { ok: false, error: "gentle_incompatible", payload: null };
+    }
+    const result = spawn(command, args, {
+      cwd,
+      env,
+      encoding: "utf8",
+      timeout: timeoutMs,
+      maxBuffer: 2 * 1024 * 1024,
+      shell: false
+    });
+    if (result.error) {
+      return { ok: false, error: result.error.message || "gentle_spawn_failed", payload: null };
+    }
+    const payload = strict
+      ? parseStrictJson(result.stdout ?? "")
+      : (extractJsonPayload(result.stdout ?? "") ?? extractJsonPayload(result.stderr ?? ""));
+    if (!payload) {
+      return { ok: false, error: "gentle_parse_failed", payload: null, status: result.status };
+    }
+    if (result.status !== 0 && result.status != null) {
+      return { ok: false, error: "gentle_nonzero_status", payload, status: result.status };
+    }
+    return { ok: true, payload, status: result.status, error: null };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+      payload: null
+    };
+  }
+}
+
+function applyOfficialReview(workflow, mapped) {
+  workflow.review = mapped.review;
+  workflow.nextTransition = mapped.nextTransition;
+  if (workflow.kind === WORKFLOW_KIND.NONE && mapped.nextTransition != null) {
+    workflow.kind = WORKFLOW_KIND.REVIEW;
+    workflow.active = mapped.nextTransition?.kind === "execute" || mapped.review != null;
+    workflow.label = "Review";
+  }
+}
+
+export async function loadGentleWorkflow({
+  cwd,
+  env,
+  timeoutMs,
+  spawn,
+  command,
+  probe = probeGentle,
+  runCommand = runGentleCommand
+} = {}) {
+  const probed = await probe({ cwd, env });
+  const provider = mapGentleProviderState(probed);
+  if (provider !== PROVIDER.CONNECTED) {
+    return {
+      ok: false,
+      error: providerError(provider, probed),
+      provider,
+      workflow: emptyGentleWorkflow({ provider })
+    };
+  }
+
+  const parsed = argvFromBootstrap(bootstrapCommandFromProbe(probed), {
+    repo: cwd ?? process.cwd(),
+    binaryPath: resolvedGentleBinary(probed, command)
+  });
+  if (!parsed.ok) {
+    const incompatible = PROVIDER.INCOMPATIBLE;
+    return {
+      ok: false, error: "gentle_incompatible", provider: incompatible,
+      workflow: emptyGentleWorkflow({ provider: incompatible })
+    };
+  }
+
+  const workflow = emptyGentleWorkflow({ provider });
+  const sdd = runCommand([...SDD_STATUS_ARGS], {
+    cwd, env, timeoutMs, spawn, command: parsed.binary, strict: true
+  });
+  if (sdd.ok) {
+    const mappedSdd = mapOfficialSddStatus(sdd.payload);
+    if (mappedSdd.ok) applySddProjection(workflow, mappedSdd.projection);
+  }
+
+  const reviewRun = runCommand(parsed.argv, {
+    cwd, env, timeoutMs, spawn, command: parsed.binary, strict: true
+  });
+  if (reviewRun.ok) {
+    const mapped = mapOfficialReviewStatus(reviewRun.payload);
+    if (mapped.ok) applyOfficialReview(workflow, mapped);
+  }
+
+  if (!sdd.ok && workflow.kind === WORKFLOW_KIND.NONE && workflow.review == null) {
+    return {
+      ok: false,
+      error: sdd.error ?? "gentle_sdd_unavailable",
+      provider,
+      workflow
+    };
+  }
+  return {
+    ok: true,
+    error: sdd.ok ? null : (sdd.error ?? "gentle_sdd_unavailable"),
+    provider,
+    workflow
+  };
+}

package/src/global/control-plane/provider.js

@@ -0,0 +1,69 @@
+/**
+ * Map Gentle observability probe → control-plane provider.
+ * Version is evidence only; v1 contract is upgrade, unknown schema fails closed.
+ */
+import {
+  NO_ACTIVE_WORKFLOW,
+  PROVIDER,
+  PROVIDER_ERROR,
+  WORKFLOW_KIND
+} from "./constants.js";
+
+const LEGACY_SCHEMA = "gentle-ai.review-integration.capabilities/v1";
+const LEGACY_CONTRACT = "gentle-ai.review-integration/v1";
+
+export function emptyGentleWorkflow({ provider = null } = {}) {
+  return {
+    kind: WORKFLOW_KIND.NONE,
+    active: false,
+    label: NO_ACTIVE_WORKFLOW,
+    phase: null,
+    nextTransition: null,
+    changeName: null,
+    review: null,
+    sdd: null,
+    provider
+  };
+}
+
+export function isRecognizedLegacyContract(probe) {
+  const evidenceSchemas = (probe?.evidence ?? [])
+    .map((row) => row?.schema)
+    .filter(Boolean)
+    .join(" ");
+  const blob = `${(probe?.diagnostics ?? []).join(" ")} ${evidenceSchemas}`;
+  return blob.includes(LEGACY_SCHEMA)
+    || blob.includes(LEGACY_CONTRACT)
+    || /protocol\.major mismatch: got 1\b/.test(blob);
+}
+
+export function mapGentleProviderState(probe) {
+  if (probe == null || typeof probe !== "object" || Array.isArray(probe)) {
+    return PROVIDER.INCOMPATIBLE;
+  }
+  if (probe.state === "missing") return PROVIDER.UNAVAILABLE;
+  if (probe.state === "available" && probe.contractCompatible === true) {
+    return PROVIDER.CONNECTED;
+  }
+  if (probe.state === "error") {
+    const blob = `${probe.error ?? ""} ${(probe.diagnostics ?? []).join(" ")}`;
+    if (/parse|not an object|invalid capabilities/i.test(blob)) {
+      return PROVIDER.INCOMPATIBLE;
+    }
+    return PROVIDER.UNAVAILABLE;
+  }
+  if (probe.state === "incompatible") {
+    return isRecognizedLegacyContract(probe)
+      ? PROVIDER.UPGRADE_REQUIRED
+      : PROVIDER.INCOMPATIBLE;
+  }
+  return PROVIDER.INCOMPATIBLE;
+}
+
+export function providerError(provider, probe = null) {
+  if (provider === PROVIDER.CONNECTED) return null;
+  if (provider === PROVIDER.UNAVAILABLE && probe?.state === "error") {
+    return "gentle_capabilities_failed";
+  }
+  return PROVIDER_ERROR[provider] ?? "gentle_incompatible";
+}

package/src/global/control-plane/review-status.js

@@ -0,0 +1,115 @@
+/**
+ * Official Gentle review status v2/v3 only. Never read authority inventory.
+ */
+import { isAbsolute } from "node:path";
+import { SUPPORTED_CONTRACT } from "../observability/gentle-probe.js";
+
+export const REVIEW_STATUS_SCHEMAS = Object.freeze([
+  "gentle-ai.review-integration.status/v2",
+  "gentle-ai.review-integration.status/v3"
+]);
+
+const INVENTORY_SCHEMA = "gentle-ai.review-authority-status/v1";
+const UNSAFE_TOKEN = /[|;&$`\n\r]/;
+const PLACEHOLDER = /^<[^>]+>$/;
+
+export const GENTLE_224_BOOTSTRAP =
+  "gentle-ai review status --cwd <repo> --contract gentle-ai.review-integration/v2 --next-transition";
+export const GENTLE_230_BOOTSTRAP =
+  "gentle-ai review status --cwd <repo> --contract gentle-ai.review-integration/v2 --agent claude-code --next-transition";
+
+const failArgv = () => ({ ok: false, error: "gentle_incompatible", binary: null, argv: null });
+
+export function bootstrapCommandFromProbe(probe) {
+  return probe?.evidence?.find((row) => row?.kind === "bootstrap" && row.command)?.command ?? null;
+}
+
+export function argvFromBootstrap(command, { repo, binaryPath }) {
+  if (typeof command !== "string" || !command.trim() || UNSAFE_TOKEN.test(command)) return failArgv();
+  if (typeof binaryPath !== "string" || !isAbsolute(binaryPath)) return failArgv();
+  if (typeof repo !== "string" || !repo) return failArgv();
+  const tokens = command.trim().split(/\s+/);
+  if (tokens[0] !== "gentle-ai") return failArgv();
+  const args = [];
+  const rest = tokens.slice(1);
+  for (let i = 0; i < rest.length; i += 1) {
+    const tok = rest[i];
+    if (UNSAFE_TOKEN.test(tok)) return failArgv();
+    if (tok === "--cwd") {
+      const next = rest[i + 1];
+      const needsRepo = next === "<repo>" || next == null || next.startsWith("-");
+      args.push("--cwd", needsRepo ? repo : next);
+      if (!needsRepo || next === "<repo>") i += 1;
+      continue;
+    }
+    if (PLACEHOLDER.test(tok)) return failArgv();
+    args.push(tok);
+  }
+  if (args[0] !== "review" || args[1] !== "status") return failArgv();
+  return { ok: true, error: null, binary: binaryPath, argv: args };
+}
+
+function isObject(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+function publishedReceipt(receiptField) {
+  if (typeof receiptField === "string" && receiptField) return receiptField;
+  if (!isObject(receiptField)) return null;
+  if (typeof receiptField.id === "string" && receiptField.id) return receiptField.id;
+  if (typeof receiptField.digest === "string" && receiptField.digest) return receiptField.digest;
+  return null;
+}
+
+function publishedGate(payload) {
+  if (typeof payload.gate === "string" && payload.gate) return payload.gate;
+  if (isObject(payload.receipt) && typeof payload.receipt.gate === "string" && payload.receipt.gate) {
+    return payload.receipt.gate;
+  }
+  return null;
+}
+
+/**
+ * Fail closed unless schema/contract are official. Pass next_transition through unaltered.
+ */
+export function mapOfficialReviewStatus(payload) {
+  if (!isObject(payload)) {
+    return { ok: false, error: "gentle_incompatible", review: null, nextTransition: null };
+  }
+  if (
+    payload.schema === INVENTORY_SCHEMA
+    || payload.authoritative === true
+    || Array.isArray(payload.entries)
+  ) {
+    return { ok: false, error: "gentle_incompatible", review: null, nextTransition: null };
+  }
+  if (!REVIEW_STATUS_SCHEMAS.includes(payload.schema)) {
+    return { ok: false, error: "gentle_incompatible", review: null, nextTransition: null };
+  }
+  if (payload.contract != null && payload.contract !== SUPPORTED_CONTRACT) {
+    return { ok: false, error: "gentle_incompatible", review: null, nextTransition: null };
+  }
+
+  const nextTransition = Object.prototype.hasOwnProperty.call(payload, "next_transition")
+    ? payload.next_transition
+    : null;
+  const receipt = publishedReceipt(payload.receipt);
+  const gate = publishedGate(payload);
+  const applicability = typeof payload.applicability === "string" ? payload.applicability : null;
+  const action = typeof payload.action === "string" ? payload.action : null;
+  const receiptStatus = isObject(payload.receipt) && typeof payload.receipt.status === "string"
+    ? payload.receipt.status
+    : null;
+
+  const review = (receipt || gate || applicability || action)
+    ? {
+        lineageId: null,
+        state: applicability ?? action,
+        status: receiptStatus,
+        receipt,
+        gate
+      }
+    : null;
+
+  return { ok: true, error: null, review, nextTransition };
+}

package/src/global/control-plane/sdd-status.js

@@ -0,0 +1,49 @@
+/**
+ * Official `sdd-status --json` projection. No inferred phase/route/next.
+ */
+import { NO_ACTIVE_WORKFLOW, WORKFLOW_KIND } from "./constants.js";
+
+export const SDD_STATUS_SCHEMA_PREFIX = "gentle-ai.sdd-status";
+export const SDD_STATUS_ARGS = Object.freeze(["sdd-status", "--json"]);
+
+function isObject(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+export function mapOfficialSddStatus(payload) {
+  if (!isObject(payload)) {
+    return { ok: false, error: "gentle_incompatible", projection: null };
+  }
+  const schemaName = typeof payload.schemaName === "string"
+    ? payload.schemaName
+    : (typeof payload.schema === "string" ? payload.schema : null);
+  if (!schemaName || !schemaName.startsWith(SDD_STATUS_SCHEMA_PREFIX)) {
+    return { ok: false, error: "gentle_incompatible", projection: null };
+  }
+  const changeName = typeof payload.changeName === "string" && payload.changeName
+    ? payload.changeName
+    : null;
+  const nextRecommended = typeof payload.nextRecommended === "string" && payload.nextRecommended
+    ? payload.nextRecommended
+    : null;
+  return {
+    ok: true,
+    error: null,
+    projection: { schemaName, changeName, nextRecommended }
+  };
+}
+
+export function applySddProjection(workflow, projection) {
+  workflow.sdd = projection;
+  workflow.changeName = projection.changeName;
+  workflow.phase = null;
+  if (projection.changeName) {
+    workflow.kind = WORKFLOW_KIND.SDD;
+    workflow.active = true;
+    workflow.label = "SDD";
+  } else if (workflow.kind !== WORKFLOW_KIND.REVIEW) {
+    workflow.kind = WORKFLOW_KIND.NONE;
+    workflow.active = false;
+    workflow.label = NO_ACTIVE_WORKFLOW;
+  }
+}

package/src/global/control-plane/team.js

@@ -0,0 +1,63 @@
+/**
+ * Normalize declared fleets into honest control-plane team nodes.
+ * Live requires OpenCode active-agent evidence — never idle sessions.
+ */
+import { HONESTY } from "./constants.js";
+
+function honestyForNode(node, { platform, hasLiveActivity }) {
+  if (node?.opaque === true) return HONESTY.OPAQUE;
+  if (platform === "opencode" && hasLiveActivity) return HONESTY.LIVE;
+  return HONESTY.DECLARED;
+}
+
+export function normalizeTeam(connectionsReport = {}) {
+  const fleets = Array.isArray(connectionsReport.fleets) ? connectionsReport.fleets : [];
+  const activity = connectionsReport.activity ?? null;
+  const hasLiveActivity = Boolean(
+    activity
+    && (
+      (Array.isArray(activity.agents) && activity.agents.some((a) => a?.state === "active"))
+      || (typeof activity.activeCount === "number" && activity.activeCount > 0)
+      || activity.active === true
+    )
+  );
+
+  // Cursor configured agents are declared topology (not live); only opaque nodes stay opaque.
+  const platforms = fleets.map((fleet) => {
+    const platform = fleet?.platform ?? "unknown";
+    const orch = fleet?.orchestrator ?? null;
+    return {
+      platform,
+      honesty: honestyForNode(fleet, { platform, hasLiveActivity }),
+      source: fleet?.source ?? null,
+      orchestrator: orch
+        ? {
+            id: orch.id ?? null,
+            model: orch.modelShort ?? orch.model ?? null,
+            honesty: honestyForNode(orch, { platform, hasLiveActivity }),
+            role: orch.mode ?? "orchestrator"
+          }
+        : null,
+      agents: (Array.isArray(fleet?.minions) ? fleet.minions : []).map((m) => ({
+        id: m.id,
+        model: m.modelShort ?? m.model ?? null,
+        role: m.role ?? null,
+        honesty: m?.opaque === true && platform === "cursor"
+          ? HONESTY.DECLARED
+          : honestyForNode(m, { platform, hasLiveActivity: false })
+      }))
+    };
+  });
+
+  return {
+    platforms,
+    // Only surface activity when there is live evidence (active workers).
+    activity: hasLiveActivity ? activity : null,
+    fleetNote: connectionsReport.fleetNote
+      ?? "Declared config topology — not live token usage.",
+    orchestratorAuthority: connectionsReport.orchestratorAuthority ?? null,
+    connections: Array.isArray(connectionsReport.connections)
+      ? connectionsReport.connections
+      : []
+  };
+}

package/src/global/observability/gentle-probe.js

@@ -7,8 +7,15 @@ import {
 import { normalizeProbeResult } from "./probe-contract.js";
 
 export const SUPPORTED_PROTOCOL = Object.freeze({ major: 2, minor: 0 });
+export const SUPPORTED_PROTOCOL_MINORS = Object.freeze([0, 1]);
 export const SUPPORTED_SCHEMA = "gentle-ai.review-integration.capabilities/v2";
+export const SUPPORTED_SCHEMA_V21 = "gentle-ai.review-integration.capabilities/v2.1";
+export const SUPPORTED_CAPABILITY_SCHEMAS = Object.freeze([
+  SUPPORTED_SCHEMA,
+  SUPPORTED_SCHEMA_V21
+]);
 export const SUPPORTED_CONTRACT = "gentle-ai.review-integration/v2";
+export const ADDITIVE_MINOR_POLICY = "optional-fields-only";
 export const SUPPORTED_MANDATORY_FEATURES = Object.freeze([
   "compact_v2_authority", "exact_receipt_replay", "five_delivery_gates",
   "immutable_snapshot", "legacy_v1_target_scoped_read_only",
@@ -51,7 +58,7 @@ export function evaluateGentleCapabilities(payload) {
       diagnostics: ["Capabilities payload is not an object."]
     });
   }
-  if (payload.schema !== SUPPORTED_SCHEMA) {
+  if (!SUPPORTED_CAPABILITY_SCHEMAS.includes(payload.schema)) {
     diagnostics.push(`schema mismatch: got ${String(payload.schema)}`);
   }
   if (payload.contract !== SUPPORTED_CONTRACT) {
@@ -60,9 +67,30 @@ export function evaluateGentleCapabilities(payload) {
   if (payload.protocol?.major !== SUPPORTED_PROTOCOL.major) {
     diagnostics.push(`protocol.major mismatch: got ${String(payload.protocol?.major)}`);
   }
-  if (payload.protocol?.minor !== SUPPORTED_PROTOCOL.minor) {
+  if (!SUPPORTED_PROTOCOL_MINORS.includes(payload.protocol?.minor)) {
     diagnostics.push(`protocol.minor mismatch: got ${String(payload.protocol?.minor)}`);
   }
+  const additivePolicy = payload.compatibility?.additive_minor_policy;
+  if (additivePolicy != null && additivePolicy !== ADDITIVE_MINOR_POLICY) {
+    diagnostics.push(`additive_minor_policy mismatch: got ${String(additivePolicy)}`);
+  }
+  if (typeof payload.bootstrap?.command === "string" && payload.bootstrap.command) {
+    evidence.push({
+      kind: "bootstrap",
+      command: payload.bootstrap.command,
+      required_feature: payload.bootstrap.required_feature ?? null
+    });
+  }
+  const requiredFeature = payload.bootstrap?.required_feature;
+  if (typeof requiredFeature === "string" && requiredFeature) {
+    const named = [
+      ...(Array.isArray(payload.features?.mandatory) ? payload.features.mandatory : []),
+      ...(Array.isArray(payload.features?.optional) ? payload.features.optional : [])
+    ];
+    if (!named.some((feature) => feature?.name === requiredFeature && feature.supported === true)) {
+      diagnostics.push(`bootstrap required_feature not supported: ${requiredFeature}`);
+    }
+  }
   const mandatory = payload.features?.mandatory;
   if (!Array.isArray(mandatory)) {
     diagnostics.push("features.mandatory must be an array.");

package/src/global/observability/index.js

@@ -24,7 +24,8 @@ export {
   runPassiveObservabilitySnapshot
 } from "./passive-snapshot-flight.js";
 export {
-  SUPPORTED_PROTOCOL, SUPPORTED_SCHEMA, SUPPORTED_CONTRACT,
+  SUPPORTED_PROTOCOL, SUPPORTED_PROTOCOL_MINORS, SUPPORTED_SCHEMA, SUPPORTED_SCHEMA_V21,
+  SUPPORTED_CAPABILITY_SCHEMAS, SUPPORTED_CONTRACT, ADDITIVE_MINOR_POLICY,
   SUPPORTED_MANDATORY_FEATURES, evaluateGentleCapabilities, probeGentle, createGentleProbe,
   resolveGentleBinaryPath
 } from "./gentle-probe.js";