ultimate-pi 0.15.0 → 0.16.0

package/.pi/extensions/lib/harness-subagent-submit-registry.ts

@@ -0,0 +1,172 @@
+/**
+ * Registry: submit tool name → agent allowlist, schema, artifact path.
+ */
+
+import type { DebateLaneKind } from "./plan-debate-lane.js";
+
+export interface SubmitToolSpec {
+	toolName: string;
+	agents: readonly string[];
+	schemaFile: string;
+	artifactPath: string | ((doc: Record<string, unknown>) => string);
+	debateLane?: DebateLaneKind;
+	humanRequired?: boolean;
+}
+
+function roundPath(prefix: string, doc: Record<string, unknown>): string {
+	const r =
+		typeof doc.round_index === "number"
+			? doc.round_index
+			: Number(doc.round_index ?? 1);
+	return `artifacts/${prefix}-r${r}.yaml`;
+}
+
+export const SUBMIT_TOOL_SPECS: readonly SubmitToolSpec[] = [
+	{
+		toolName: "submit_scout_findings",
+		agents: [
+			"harness/planning/scout-graphify",
+			"harness/planning/scout-structure",
+			"harness/planning/scout-semantic",
+		],
+		schemaFile: "plan-scout-findings.schema.json",
+		artifactPath: (doc) => {
+			const lane =
+				typeof doc.lane === "string"
+					? doc.lane
+					: typeof doc.scout_lane === "string"
+						? doc.scout_lane
+						: "graphify";
+			return `artifacts/scout-${lane}.yaml`;
+		},
+	},
+	{
+		toolName: "submit_decomposition_brief",
+		agents: ["harness/planning/decompose"],
+		schemaFile: "plan-decomposition-brief.schema.json",
+		artifactPath: "artifacts/decomposition.yaml",
+	},
+	{
+		toolName: "submit_hypothesis_brief",
+		agents: ["harness/planning/hypothesis"],
+		schemaFile: "plan-hypothesis-brief.schema.json",
+		artifactPath: "artifacts/hypothesis.yaml",
+	},
+	{
+		toolName: "submit_implementation_research",
+		agents: ["harness/planning/implementation-researcher"],
+		schemaFile: "plan-implementation-research-brief.schema.json",
+		artifactPath: "artifacts/implementation-research.yaml",
+	},
+	{
+		toolName: "submit_stack_brief",
+		agents: ["harness/planning/stack-researcher"],
+		schemaFile: "plan-stack-brief.schema.json",
+		artifactPath: "artifacts/stack.yaml",
+	},
+	{
+		toolName: "submit_execution_plan_brief",
+		agents: ["harness/planning/execution-plan-author"],
+		schemaFile: "plan-execution-plan-brief.schema.json",
+		artifactPath: "artifacts/execution-plan-draft.yaml",
+	},
+	{
+		toolName: "submit_hypothesis_validation",
+		agents: ["harness/planning/hypothesis-validator"],
+		schemaFile: "plan-hypothesis-eval.schema.json",
+		artifactPath: (doc) => roundPath("hypothesis-validation", doc),
+		debateLane: "hypothesis-validation",
+	},
+	{
+		toolName: "submit_validation_turn",
+		agents: ["harness/planning/plan-evaluator"],
+		schemaFile: "plan-validation-turn.schema.json",
+		artifactPath: (doc) => roundPath("validation-turn", doc),
+		debateLane: "validation-turn",
+	},
+	{
+		toolName: "submit_adversary_brief",
+		agents: ["harness/planning/plan-adversary"],
+		schemaFile: "plan-adversary-brief.schema.json",
+		artifactPath: (doc) => roundPath("adversary-brief", doc),
+		debateLane: "adversary-brief",
+	},
+	{
+		toolName: "submit_sprint_audit",
+		agents: ["harness/planning/sprint-contract-auditor"],
+		schemaFile: "plan-sprint-audit-turn.schema.json",
+		artifactPath: (doc) => roundPath("sprint-audit", doc),
+		debateLane: "sprint-audit",
+	},
+	{
+		toolName: "submit_review_round_draft",
+		agents: ["harness/planning/review-integrator"],
+		schemaFile: "plan-review-round-draft.schema.json",
+		artifactPath: (doc) => roundPath("review-round-draft", doc),
+	},
+	{
+		toolName: "submit_executor_handoff",
+		agents: ["harness/executor"],
+		schemaFile: "harness-executor-handoff.schema.json",
+		artifactPath: "handoff/executor-summary.yaml",
+	},
+	{
+		toolName: "submit_eval_verdict",
+		agents: ["harness/evaluator"],
+		schemaFile: "eval-verdict.schema.json",
+		artifactPath: "artifacts/eval-verdict.yaml",
+	},
+	{
+		toolName: "submit_adversary_report",
+		agents: ["harness/adversary"],
+		schemaFile: "adversary-report.schema.json",
+		artifactPath: "artifacts/adversary-report.yaml",
+	},
+	{
+		toolName: "submit_human_required",
+		agents: ["harness/planning/decompose", "harness/planning/hypothesis"],
+		schemaFile: "harness-human-required.schema.json",
+		artifactPath: "artifacts/human-required.yaml",
+		humanRequired: true,
+	},
+] as const;
+
+export const SUBMIT_TOOLS_BY_AGENT: Readonly<
+	Record<string, ReadonlySet<string>>
+> = (() => {
+	const map = new Map<string, Set<string>>();
+	for (const spec of SUBMIT_TOOL_SPECS) {
+		for (const agent of spec.agents) {
+			if (!map.has(agent)) map.set(agent, new Set());
+			map.get(agent)?.add(spec.toolName);
+		}
+	}
+	return Object.fromEntries(map.entries());
+})();
+
+export function specForSubmitTool(
+	toolName: string,
+): SubmitToolSpec | undefined {
+	return SUBMIT_TOOL_SPECS.find((s) => s.toolName === toolName);
+}
+
+export function resolveArtifactRelPath(
+	spec: SubmitToolSpec,
+	doc: Record<string, unknown>,
+): string {
+	if (typeof spec.artifactPath === "function") {
+		return spec.artifactPath(doc);
+	}
+	return spec.artifactPath;
+}
+
+export function isSubmitToolName(toolName: string): boolean {
+	return toolName.startsWith("submit_");
+}
+
+export const DEBATE_AGENT_SUBMIT_TOOL: Readonly<Record<string, string>> = {
+	"harness/planning/hypothesis-validator": "submit_hypothesis_validation",
+	"harness/planning/plan-evaluator": "submit_validation_turn",
+	"harness/planning/plan-adversary": "submit_adversary_brief",
+	"harness/planning/sprint-contract-auditor": "submit_sprint_audit",
+};

package/.pi/extensions/lib/harness-subagents-bridge.ts

@@ -2,6 +2,7 @@
  * ultimate-pi harness wrapper around vendored pi-subagents.
  */
 
+import { join } from "node:path";
 import type {
 	ExtensionAPI,
 	ExtensionContext,
@@ -12,6 +13,8 @@ import {
 	type HarnessSubagentsOptions,
 	type SpawnAuthForward,
 } from "../../../vendor/pi-subagents/src/subagents.js";
+import { parseSpawnContextFromTask } from "../../lib/harness-spawn-parse.js";
+import { harnessSubagentSubmitExtensionPath } from "../harness-subagent-submit.js";
 import { refreshHarnessCocoindexIndex } from "./harness-cocoindex-refresh.js";
 import { captureHarnessEvent } from "./harness-posthog.js";
 import {
@@ -58,8 +61,47 @@ async function resolveHarnessSpawnAuth(
 export function createHarnessSubagentsExtension(
 	packageRoot: string,
 ): (pi: ExtensionAPI) => void {
+	const submitExtPath = harnessSubagentSubmitExtensionPath(packageRoot);
 	const options: HarnessSubagentsOptions = {
 		packageRoot,
+		harnessSubprocessExtensionPath: submitExtPath,
+		resolveSubprocessEnv: (task, agent) => {
+			if (!agent.name.startsWith("harness/")) return undefined;
+			const ctx = parseSpawnContextFromTask(task);
+			// #region agent log
+			fetch(
+				"http://127.0.0.1:7928/ingest/a5d40896-34cb-4f12-97db-df7ada0b22f0",
+				{
+					method: "POST",
+					headers: {
+						"Content-Type": "application/json",
+						"X-Debug-Session-Id": "2ca12b",
+					},
+					body: JSON.stringify({
+						sessionId: "2ca12b",
+						hypothesisId: "H1",
+						location: "harness-subagents-bridge.ts:resolveSubprocessEnv",
+						message: "parsed spawn context for subprocess env",
+						data: {
+							agent: agent.name,
+							hasCtx: Boolean(ctx?.run_id),
+							run_id: ctx?.run_id ?? null,
+							run_dir: ctx?.run_dir ?? null,
+							taskPrefix: task.slice(0, 160),
+						},
+						timestamp: Date.now(),
+					}),
+				},
+			).catch(() => {});
+			// #endregion
+			if (!ctx?.run_id) return undefined;
+			return {
+				HARNESS_RUN_ID: ctx.run_id,
+				HARNESS_RUN_DIR:
+					ctx.run_dir ??
+					join(packageRoot, ".pi", "harness", "runs", ctx.run_id),
+			};
+		},
 		defaultAgentScope: "both",
 		defaultConfirmProjectAgents: false,
 		truncateDetails: true,

package/.pi/extensions/lib/plan-debate-gate.ts

@@ -5,6 +5,7 @@
 import { constants } from "node:fs";
 import { access, readFile } from "node:fs/promises";
 import { join } from "node:path";
+import { isHarnessBudgetEnforceOn } from "../../lib/harness-budget-enforce.js";
 import { capsForDebate } from "./debate-bus-core.js";
 import {
 	getPlanFocusCoverage,
@@ -117,10 +118,20 @@ export async function validatePlanDebateGate(
 		}
 	}
 
-	if (coverage.last_round_index > caps.max_rounds) {
+	if (
+		isHarnessBudgetEnforceOn() &&
+		coverage.last_round_index > caps.max_rounds
+	) {
 		errors.push(
 			`round_count ${coverage.last_round_index} exceeds max_rounds ${caps.max_rounds}`,
 		);
+	} else if (
+		!isHarnessBudgetEnforceOn() &&
+		coverage.last_round_index > caps.max_rounds
+	) {
+		warnings.push(
+			`round_count ${coverage.last_round_index} exceeds advisory max_rounds ${caps.max_rounds} (budget enforce off)`,
+		);
 	}
 
 	if (!messenger) {

package/.pi/extensions/lib/plan-debate-lane.ts

@@ -45,6 +45,21 @@ export function laneArtifactPath(
 	}
 }
 
+/** Apply messenger side effects when artifact YAML was already written via submit tool. */
+export async function applyDebateLaneFromDoc(opts: {
+	runDir: string;
+	lane: DebateLaneKind;
+	doc: Record<string, unknown>;
+	roundIndex?: number;
+}): Promise<ApplyDebateLaneResult> {
+	return applyDebateLane({
+		runDir: opts.runDir,
+		lane: opts.lane,
+		content: JSON.stringify(opts.doc),
+		roundIndex: opts.roundIndex,
+	});
+}
+
 export function extractClaimIds(doc: Record<string, unknown>): string[] {
 	const explicit = doc.messenger_claim_ids;
 	if (Array.isArray(explicit)) {

package/.pi/harness/agents.manifest.json

@@ -1,8 +1,8 @@
 {
 	"schema_version": "1.0.0",
 	"package": "ultimate-pi",
-	"package_version": "0.14.0",
-	"generated_at": "2026-05-19T10:53:28.359Z",
+	"package_version": "0.15.0",
+	"generated_at": "2026-05-19T12:56:13.369Z",
 	"agents": {
 		"pi-pi/agent-expert": {
 			"path": ".pi/agents/pi-pi/agent-expert.md",
@@ -46,23 +46,23 @@
 		},
 		"harness/adversary": {
 			"path": ".pi/agents/harness/adversary.md",
-			"sha256": "dd2ef87139cb175d795f4d7bde78dca1a181d2e42c3c3bd0d48832cf5069aa29"
+			"sha256": "560c7571ab91478bde1271e9ae6c3a112c3e1d28e1a261c5450fd1d00f9f89af"
 		},
 		"harness/evaluator": {
 			"path": ".pi/agents/harness/evaluator.md",
-			"sha256": "2b8039fd79f9177fdafd5319a53a96812719d4f1f68e2de70632030142649cfe"
+			"sha256": "a4667d3efb305ba2fe79118e3d7d2b0de5e0369637af040d1238161d75cd28ac"
 		},
 		"harness/executor": {
 			"path": ".pi/agents/harness/executor.md",
-			"sha256": "b549e9fc802ba23857a1bc6b2ff36f3c169e708fe5ec13857b3bcfe841384f1f"
+			"sha256": "6baffcc3d89954494ce3ae439175686a39928b6a543a0a451da27475094b1712"
 		},
 		"harness/incident-recorder": {
 			"path": ".pi/agents/harness/incident-recorder.md",
-			"sha256": "d7577c911a9e6c9607eb64f76337aab85c4eb9a92e7cd917eb8d989ef3cd1de5"
+			"sha256": "d42fa45de1a2fe3842d075c6f319315266588942e314f1b650caabac39bdc29a"
 		},
 		"harness/meta-optimizer": {
 			"path": ".pi/agents/harness/meta-optimizer.md",
-			"sha256": "a4eed88084c7cfb5ace3edc72b72d7ead4134b3eae0d444b391decfe2640a632"
+			"sha256": "cbaab35367126796b7136389a02ab41b4fd1fe7098cf83be562d7b7493ccc297"
 		},
 		"harness/sentrux-bootstrap": {
 			"path": ".pi/agents/harness/sentrux-bootstrap.md",
@@ -70,63 +70,63 @@
 		},
 		"harness/tie-breaker": {
 			"path": ".pi/agents/harness/tie-breaker.md",
-			"sha256": "68f02b86e95927f06d7f963e1f61f193159bbef1ba4558d90c84d5457d62b3f7"
+			"sha256": "1c54c1c3274291dea1ea8826563a7ad4fe1d9c4302984e907bfcd22cfc4f5eba"
 		},
 		"harness/trace-librarian": {
 			"path": ".pi/agents/harness/trace-librarian.md",
-			"sha256": "03b499a948b8467f1cfe2b4e63190feb7b8b9d96461055638e774253b9b6b2d4"
+			"sha256": "336b3f3f6141cef8750ab18d29bbe454caf26973830a86afe099d9e4ad8b0abe"
 		},
 		"harness/planning/decompose": {
 			"path": ".pi/agents/harness/planning/decompose.md",
-			"sha256": "5c3b983772d013741d50f39945bc77f178aa338aecab56b93c09216d72192c69"
+			"sha256": "0919dafa1d1cd008d513c28524c1e7218867586a138982dccf01db5270c42c73"
 		},
 		"harness/planning/execution-plan-author": {
 			"path": ".pi/agents/harness/planning/execution-plan-author.md",
-			"sha256": "16f8800c50bcaf1b82ed9138889c8a0e538ee6a139aeae129ccd20cec2ec25f7"
+			"sha256": "55ece0f1ee14abd17fe7b3e478b548240f637eacbfc2a34758e98d3878dc82fd"
 		},
 		"harness/planning/hypothesis-validator": {
 			"path": ".pi/agents/harness/planning/hypothesis-validator.md",
-			"sha256": "9e68ec5d6aef96a3666c30227c3cbddf1aaed1182fdc94dbbd21ad3d48315ff2"
+			"sha256": "36f0baa7796229f21bd02faf5e70402c7bf054289eab557a25bfbe3cb7781de7"
 		},
 		"harness/planning/hypothesis": {
 			"path": ".pi/agents/harness/planning/hypothesis.md",
-			"sha256": "b20c527d15c2243cd5d3a8f16cea6d44bdfd16e01915d42f3b830bf9938e5f8b"
+			"sha256": "e83d5c4faaee8d32af4a5f22c9917b70a173f3e22d7c0f182b361706f2309171"
 		},
 		"harness/planning/implementation-researcher": {
 			"path": ".pi/agents/harness/planning/implementation-researcher.md",
-			"sha256": "dbd1c4fc74d538b110d406febfd4603eebea77d82e8b367df4596ac7ff6e54cc"
+			"sha256": "653f320b5d51bb331774246687f24a75347b406bba4e6dfd2968d6e5d4cc8bb3"
 		},
 		"harness/planning/plan-adversary": {
 			"path": ".pi/agents/harness/planning/plan-adversary.md",
-			"sha256": "7c14eaab65f356003ee2ff380f5d4e620170b5126daa67c3d226b12342f47bd2"
+			"sha256": "3241d7ec939dc29e0af64690b99e9f74b209f40b0daa4a2a1f9ff86f99f94a8d"
 		},
 		"harness/planning/plan-evaluator": {
 			"path": ".pi/agents/harness/planning/plan-evaluator.md",
-			"sha256": "846575abe9df3e7e5be812c0c474989c1a9de8074a7884d77b9d3dd423643480"
+			"sha256": "71660ab58bfcfdfae56c873140d4ea5946ae30cd5719c96afeabfd02b1d1f81d"
 		},
 		"harness/planning/review-integrator": {
 			"path": ".pi/agents/harness/planning/review-integrator.md",
-			"sha256": "bed43f3f049c279ac50a24bcffac1bbe46a8605d89c9cc6d0c3c6a87d488b1b8"
+			"sha256": "cf3f0dbe81274ec9ef0ff2e0c170e8dc929b20be65492d0ee9a80d985acf6d71"
 		},
 		"harness/planning/scout-graphify": {
 			"path": ".pi/agents/harness/planning/scout-graphify.md",
-			"sha256": "7f385d5bda2fe04b9da52cb4cb9247324efd345579b483d3ad55a6abefad50d5"
+			"sha256": "6e2bda8ad38311810c9916d9dab311873bc776e4b8832bb0e574136e45e1255e"
 		},
 		"harness/planning/scout-semantic": {
 			"path": ".pi/agents/harness/planning/scout-semantic.md",
-			"sha256": "36bd424ebd422bda82bd447b22f591f99f32ec897ea43f385586119da5c26caa"
+			"sha256": "416e518d8204a55b26dc53da1f750865c6f09ee2c7f343b41e7c08da3230c089"
 		},
 		"harness/planning/scout-structure": {
 			"path": ".pi/agents/harness/planning/scout-structure.md",
-			"sha256": "e67b7cd75519e5ae36e1bb5f49ca158888c28d365465863aee50a9b2e8e5b7d7"
+			"sha256": "76c42a15cc74cf1de2cf861cb0146c865c205f69cce7b9605d41893b19600029"
 		},
 		"harness/planning/sprint-contract-auditor": {
 			"path": ".pi/agents/harness/planning/sprint-contract-auditor.md",
-			"sha256": "d915274dc9b5addae5499bc2390b348eddeb8f133b526a816e23d0d19a2618bf"
+			"sha256": "12cb5e6b53dcc19ace62e8e4c152d96440717df53a182e76216dd2327410df4d"
 		},
 		"harness/planning/stack-researcher": {
 			"path": ".pi/agents/harness/planning/stack-researcher.md",
-			"sha256": "fa228920abe2b66d4d8921c4a5d85593e3019a24bbe9ae512ed9149f235e3536"
+			"sha256": "ce546ef3aca19da7f334f07cef8f510b79068bffeb7f276c428f3e6236bbe96b"
 		}
 	}
 }

package/.pi/harness/docs/adrs/0037-subagent-submit-tools.md

@@ -0,0 +1,31 @@
+# ADR 0037: Subagent submit tools (replace JSON prose contracts)
+
+**Status:** Accepted  
+**Date:** 2026-05-19
+
+## Context
+
+Harness plan/execute agents used fenced JSON in `finalOutput`, requiring the parent orchestrator to parse prose and call `write_harness_yaml`. This was fragile (truncated parallel summaries, invalid JSON, double-hop writes).
+
+Planning agents set `extensions: false` and subprocess spawn used `--no-extensions`, so harness tools were unavailable in children.
+
+## Decision
+
+1. **Option A — subprocess-only extension bundle:** vendored spawn passes `--no-extensions -e .pi/extensions/harness-subagent-submit.ts` for `harness/*` agents with `extensions: false`.
+2. **Scoped `submit_*` tools** per agent, validated against `.pi/harness/specs/*.schema.json` (Ajv) and written deterministically under `HARNESS_RUN_DIR`.
+3. **Parent gates** via `harness_artifact_ready` (file existence) instead of parsing subprocess JSON.
+4. **Debate lanes:** `tool_result` hook prefers last `submit_*` in `details.results[].messages`; skips `finalOutput` auto-apply when submit present (`HARNESS_SUBMIT_TOOLS` default on).
+5. **Parent** blocks all `submit_*`; keeps `write_harness_yaml` for merges and debate round submission only.
+
+## Consequences
+
+- Agent frontmatter lists one terminal `submit_*` tool per role.
+- `HarnessSpawnContext` must include `run_id` / `run_dir`; bridge sets `HARNESS_RUN_ID`, `HARNESS_RUN_DIR`, `HARNESS_AGENT_ID` on spawn.
+- `parseHarnessAgentJson` retained for migration/tests; hot path is tool args.
+- See ADR 0038 for budget telemetry-only default.
+
+## References
+
+- `.pi/extensions/harness-subagent-submit.ts`
+- `.pi/extensions/lib/harness-subagent-submit-registry.ts`
+- `.pi/harness/specs/plan-scout-findings.schema.json`

package/.pi/harness/docs/adrs/0038-budget-telemetry-only.md

@@ -0,0 +1,23 @@
+# ADR 0038: Budget enforcement telemetry-only (default)
+
+**Status:** Accepted  
+**Date:** 2026-05-19
+
+## Context
+
+Token and debate caps emitted `harness-budget-exhausted`, which set `budgetExhausted` in the live widget and blocked flows even when `HARNESS_BUDGET_HARD_STOP` was false. `max_rounds` and messenger exchange limits in `validatePlanDebateGate` also hard-failed approval.
+
+## Decision
+
+- **`HARNESS_BUDGET_ENFORCE` default `off`:** phase/debate caps log `harness-budget-soft-limit` and `harness-budget-telemetry` only; `harness-budget-exhausted` is emitted only when enforce is on **and** hard-stop flags are set.
+- **UI:** `budgetExhausted` / blocked substate only when blocking exhaustion events qualify.
+- **Debate:** `capsForDebate` uses sentinel caps when enforce is off; `max_rounds` gate errors become warnings.
+- **CLI:** `--budget` on harness prompts is reserved/no-op until a real budget story ships.
+
+Re-enable: `HARNESS_BUDGET_ENFORCE=1` plus `HARNESS_BUDGET_HARD_STOP` / `HARNESS_DEBATE_HARD_STOP` as needed.
+
+## Consequences
+
+- Long debates and large plans are not blocked by soft token telemetry.
+- Quality gates (`min_focus_rounds`, required focuses, `review_gate_ready`) remain enforced.
+- PostHog should prefer `harness_budget_telemetry` over exhausted for dashboards until enforce returns.

package/.pi/harness/docs/adrs/README.md

@@ -22,6 +22,8 @@ Team-shared ADRs for the ultimate-pi harness live under `.pi/harness/docs/adrs/`
 | [0034](0034-darwin-plan-research-pipeline.md) | Darwin plan research pipeline | Accepted |
 | [0035](0035-plan-phase-review-gate.md) | Plan-phase Review Gate | Accepted |
 | [0036](0036-implementation-research-and-selective-debate.md) | Implementation research and selective debate | Accepted |
+| [0037](0037-subagent-submit-tools.md) | Subagent submit tools (subprocess extension) | Accepted |
+| [0038](0038-budget-telemetry-only.md) | Budget caps telemetry-only by default | Accepted |
 
 ## Template
 

package/.pi/harness/specs/harness-executor-handoff.schema.json

@@ -0,0 +1,19 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/harness-executor-handoff.schema.json",
+	"title": "HarnessExecutorHandoff",
+	"type": "object",
+	"additionalProperties": true,
+	"required": ["schema_version", "execution_status"],
+	"properties": {
+		"schema_version": { "type": "string", "const": "1.0.0" },
+		"execution_status": {
+			"type": "string",
+			"enum": ["completed", "blocked", "scope_drift"]
+		},
+		"files_changed": { "type": "array" },
+		"validation_summary": { "type": "string" },
+		"rollback_refs": { "type": "object" },
+		"handoff_ready": { "type": "object" }
+	}
+}

package/.pi/harness/specs/harness-human-required.schema.json

@@ -0,0 +1,16 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/harness-human-required.schema.json",
+	"title": "HarnessHumanRequired",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["schema_version", "reason"],
+	"properties": {
+		"schema_version": { "type": "string", "const": "1.0.0" },
+		"reason": { "type": "string", "minLength": 1 },
+		"questions": {
+			"type": "array",
+			"items": { "type": "string" }
+		}
+	}
+}

package/.pi/harness/specs/plan-scout-findings.schema.json

@@ -0,0 +1,19 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/plan-scout-findings.schema.json",
+	"title": "PlanScoutFindings",
+	"type": "object",
+	"additionalProperties": true,
+	"required": ["schema_version", "lane", "summary"],
+	"properties": {
+		"schema_version": { "type": "string", "const": "1.0.0" },
+		"lane": {
+			"type": "string",
+			"enum": ["graphify", "structure", "semantic"]
+		},
+		"scout_lane": { "type": "string" },
+		"summary": { "type": "string", "minLength": 1 },
+		"key_paths": { "type": "array", "items": { "type": "string" } },
+		"findings": { "type": "array" }
+	}
+}

package/.pi/lib/harness-agent-output.ts

@@ -21,6 +21,51 @@ export function extractJsonBlock(text: string): string | null {
 	return null;
 }
 
+export interface ToolCallPartLike {
+	type?: string;
+	name?: string;
+	arguments?: Record<string, unknown>;
+}
+
+export interface MessageLike {
+	role?: string;
+	content?: ToolCallPartLike[] | unknown;
+}
+
+/** Last matching submit_* tool call in subprocess messages (chain-safe). */
+export function extractLastSubmitCall(
+	messages: MessageLike[],
+	toolNames: string | string[],
+): { toolName: string; document: Record<string, unknown> } | null {
+	const allowed = new Set(
+		(Array.isArray(toolNames) ? toolNames : [toolNames]).map((n) => n.trim()),
+	);
+	let last: { toolName: string; document: Record<string, unknown> } | null =
+		null;
+	for (const msg of messages) {
+		if (msg.role !== "assistant" || !Array.isArray(msg.content)) continue;
+		for (const part of msg.content) {
+			if (part.type !== "toolCall" || !part.name) continue;
+			if (!allowed.has(part.name)) continue;
+			const doc = part.arguments?.document;
+			if (doc && typeof doc === "object" && !Array.isArray(doc)) {
+				last = {
+					toolName: part.name,
+					document: doc as Record<string, unknown>,
+				};
+			}
+		}
+	}
+	return last;
+}
+
+export function extractLastSubmitCallForAgent(
+	messages: MessageLike[],
+	agentToolNames: readonly string[],
+): { toolName: string; document: Record<string, unknown> } | null {
+	return extractLastSubmitCall(messages, [...agentToolNames]);
+}
+
 export function parseHarnessAgentJson<T extends Record<string, unknown>>(
 	text: string,
 ): { ok: true; value: T } | { ok: false; error: string } {

package/.pi/lib/harness-budget-enforce.ts

@@ -0,0 +1,18 @@
+/**
+ * Central switch for harness token/debate budget enforcement.
+ * Default: telemetry-only (HARNESS_BUDGET_ENFORCE off).
+ */
+
+export function isHarnessBudgetEnforceOn(): boolean {
+	const raw = (process.env.HARNESS_BUDGET_ENFORCE ?? "off").toLowerCase();
+	return raw === "1" || raw === "true" || raw === "on";
+}
+
+/** When false, soft-limit and debate telemetry must not block UI or gates. */
+export function shouldEmitBlockingBudgetExhausted(): boolean {
+	if (!isHarnessBudgetEnforceOn()) return false;
+	return (
+		process.env.HARNESS_BUDGET_HARD_STOP === "true" ||
+		process.env.HARNESS_DEBATE_HARD_STOP === "true"
+	);
+}