feat(harness): launch read-only builder planning sessions

.changeset/real-builder-planning-sessions.md

@@ -0,0 +1,9 @@
+---
+"@sapiom/harness": minor
+---
+
+Let the trusted Agent Map planner prepare the exact top-level session list when a build plan becomes planning-eligible, summarize that list in the planning conversation, and ask for explicit consent. There is no separate Studio button. Before a pending consent can open sessions, Studio separately proves that a non-empty user submission entered the trusted planner-input boundary after preparation; this mechanical check does not interpret the reply's meaning, which remains a planner attestation. Queued messages retain their original acceptance time so pre-preparation backlog cannot qualify, and raw terminal lines are recorded before a follow-up tool call can run. Studio also revalidates the current source, plan, assignment set, focused brief versions, consent scope, and eligibility before any process side effect.
+
+Planning builders run under adapter-enforced read-only policies, receive exact trusted bootstrap context, submit immutable structured results, and appear with lifecycle state in the existing project-wide session tabs. Stable bindings and spawn claims keep retries from creating duplicate processes or tabs. Only top-level planned agents receive sessions; ordinary user-started agents never receive the fan-out tool or planning-only policy. Planning sessions cannot authorize implementation or deployment, which remain behind a separate execution gate.
+
+Claude Code must be version 2.1.248 or newer so planning sessions can use its enforceable restricted mode. Version 2.1.248 was published on 2026-08-27 according to the package's npm registry metadata.

packages/harness/src/cli/doctor.test.ts

@@ -53,12 +53,12 @@ import { MIN_CLAUDE_CODE_VERSION } from "../core/adapters/claude-code.js";
 describe("runDoctor", () => {
   it("passes when node, claude, and git are present and codex is absent", async () => {
     presentBinaries = new Set(["claude", "git"]);
-    claudeVersion = "2.1.220 (Claude Code)";
+    claudeVersion = `${MIN_CLAUDE_CODE_VERSION} (Claude Code)`;
     const report = await runDoctor();
     const byName = Object.fromEntries(report.checks.map((c) => [c.name, c]));
 
     expect(byName.node.ok).toBe(true);
-    expect(byName.claude).toEqual({ name: "claude", ok: true, detail: "2.1.220 (Claude Code)" });
+    expect(byName.claude).toEqual({ name: "claude", ok: true, detail: `${MIN_CLAUDE_CODE_VERSION} (Claude Code)` });
     expect(byName.git).toEqual({ name: "git", ok: true, detail: "git version 2.43.0" });
     expect(byName.codex.ok).toBe(false);
 
@@ -121,7 +121,7 @@ describe("runDoctor", () => {
 
   it("prefers claude-code when both agents are present", async () => {
     presentBinaries = new Set(["claude", "codex", "git"]);
-    claudeVersion = "2.1.220 (Claude Code)";
+    claudeVersion = `${MIN_CLAUDE_CODE_VERSION} (Claude Code)`;
     const report = await runDoctor();
 
     expect(report.ok).toBe(true);