ultimate-pi 0.6.1 → 0.8.0

package/.pi/extensions/ultimate-pi-vcc.ts

@@ -9,7 +9,7 @@
  * - `HARNESS_VCC_DEBUG` — set `true` to write `/tmp/pi-vcc-debug.json` on compaction
  */
 
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import registerVcc from "../../vendor/pi-vcc/index.js";
 
 export default function ultimatePiVcc(pi: ExtensionAPI): void {

package/.pi/harness/README.md

@@ -29,6 +29,8 @@ Governance/runtime enforcement for this harness is implemented as Pi extensions
 under `.pi/extensions/` and auto-loaded through the package `pi.extensions`
 manifest (`package.json`).
 
+- `harness-run-context.ts` - active run + plan injection; short commands without run/plan args
+- `harness-live-widget.ts` - footer status (phase, plan ready, next command; no run id in UI)
 - `policy-gate.ts` - phase state machine + plan-before-mutate enforcement
 - `budget-guard.ts` - hard-stop token budget checks + budget exhausted artifacts
 - `trace-recorder.ts` - append-only run traces + HarnessRunRecord + compact index

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

@@ -1,12 +1,12 @@
 {
 	"schema_version": "1.0.0",
 	"package": "ultimate-pi",
-	"package_version": "0.3.1",
-	"generated_at": "2026-05-16T08:44:48.417Z",
+	"package_version": "0.7.0",
+	"generated_at": "2026-05-17T08:24:57.263Z",
 	"agents": {
 		"pi-pi/agent-expert": {
 			"path": ".pi/agents/pi-pi/agent-expert.md",
-			"sha256": "f52f7310adc28c3e51fc21f7e82eb3c0ec8abf33a1936518355c673b21b9a706"
+			"sha256": "86561eb092b92fa43f221bfc6305de8d5afe10d43c5f577b9bf15a71bda051c6"
 		},
 		"pi-pi/cli-expert": {
 			"path": ".pi/agents/pi-pi/cli-expert.md",
@@ -18,11 +18,11 @@
 		},
 		"pi-pi/ext-expert": {
 			"path": ".pi/agents/pi-pi/ext-expert.md",
-			"sha256": "ae71ccf598217c830ac99e3150365a075bde931778d8bc6305d0270ac959a8a9"
+			"sha256": "47c64a9e2cffe00a50cac5541b0edc89fe8bcbd66ec3bb302eecc10d405a977f"
 		},
 		"pi-pi/keybinding-expert": {
 			"path": ".pi/agents/pi-pi/keybinding-expert.md",
-			"sha256": "d8c3d645a507b453d9b338f7a5435232a23e4a00cb7981e3b81a4ce2a0df6bba"
+			"sha256": "bb83f5fd2178075c8374ef28c360339f7de9faeedf811670b43a536c5f65c58e"
 		},
 		"pi-pi/pi-orchestrator": {
 			"path": ".pi/agents/pi-pi/pi-orchestrator.md",
@@ -42,27 +42,31 @@
 		},
 		"pi-pi/tui-expert": {
 			"path": ".pi/agents/pi-pi/tui-expert.md",
-			"sha256": "cd6aaf6ca28e6e65a72ef1dc3c96e3315669ec0f859c148f0f15d0ee74a263d7"
+			"sha256": "a619b2ee3d3d94fe599abb61db0904f90d30335ec426851c3f1efdf2e5ce5390"
 		},
 		"harness/adversary": {
 			"path": ".pi/agents/harness/adversary.md",
-			"sha256": "17c29621d99dd46cf6ea6566845b502c5e825338b61f073a28cb53f297b2f208"
+			"sha256": "b965f90610ca942d08b656f1aee839266d08a92beb174b8761dd5e840694a899"
 		},
 		"harness/evaluator": {
 			"path": ".pi/agents/harness/evaluator.md",
-			"sha256": "71cfb070ec3bbec9d764052ba03fee8692f2db385ad19f15c2f3a157422c1c2b"
+			"sha256": "6c0de777a10de26dba4a6feb5641495fa5c2d31072a8b0e597a5ecc9921f129f"
 		},
 		"harness/executor": {
 			"path": ".pi/agents/harness/executor.md",
-			"sha256": "02cd2f438d97abb9f35ca6cdab51b3733fc6a9076427cf9c2c93fd4593052539"
+			"sha256": "5af3ec2be4d64a738834e36d480a36c2bee4359e8cd5a2e1aac49be4cff79589"
+		},
+		"harness/incident-recorder": {
+			"path": ".pi/agents/harness/incident-recorder.md",
+			"sha256": "2de405f77b62dde38f331665bff220a3ef131c3c1cd42eebee364000fc83352b"
 		},
 		"harness/meta-optimizer": {
 			"path": ".pi/agents/harness/meta-optimizer.md",
-			"sha256": "faf81af85d273796f059395287058d2f16fe70903c70b8c6ac9b3c5f12fca69c"
+			"sha256": "ef2fb950e18e3a6439e91a68f764fc7ec922cd2d6b35de8f656f376854974d04"
 		},
 		"harness/planner": {
 			"path": ".pi/agents/harness/planner.md",
-			"sha256": "58d9c983bddddd37070f33742409f16474bf7c54bdccb8808fca4926f4adfdad"
+			"sha256": "3052e0b4ca504c7aa025b1926228e34adfe7f1c42d66a24db43fc6a1abb9968d"
 		},
 		"harness/sentrux-bootstrap": {
 			"path": ".pi/agents/harness/sentrux-bootstrap.md",
@@ -70,11 +74,11 @@
 		},
 		"harness/tie-breaker": {
 			"path": ".pi/agents/harness/tie-breaker.md",
-			"sha256": "c8fd02b3423760d9503e20ea27d3a90aa11326fc38c98f1e7253e67676b15e42"
+			"sha256": "651f50b9e2c7903c542700e94908b1fcd026ebed12aa1f1d6ec481df3567e34f"
 		},
 		"harness/trace-librarian": {
 			"path": ".pi/agents/harness/trace-librarian.md",
-			"sha256": "f44439758317b5fbae66b760bb6a1b6df19787d344bf7038712368e8fe0594ee"
+			"sha256": "d63fe08a2ea0466c0fd89fff4da03ac1d9d3580c306381cee251c89d4e8fdb97"
 		}
 	}
 }

package/.pi/harness/docs/adrs/0009-sentrux-rules-lifecycle.md

@@ -15,7 +15,7 @@ Sentrux enforces architecture via [`.sentrux/rules.toml`](https://sentrux.dev/do
 4. **Re-sync command:** `node "$UP_PKG/.pi/scripts/sentrux-rules-sync.mjs" --force` or `harness-sentrux-bootstrap.mjs --force` (resolve `$UP_PKG` via [.pi/scripts/README.md](../../../scripts/README.md)).
 5. **Pi command:** `/harness-sentrux-sync` via `sentrux-rules-sync.ts` extension.
 6. **When to sync:**
-   - `/harness-setup` Step 4.3 (after sentrux CLI install in Step 2.8)
+   - `/harness-setup` Step 4.2 (after sentrux CLI install in Step 2.8)
    - After editing `architecture.manifest.json`
    - On `agent_end` when harness phase is `plan` or `merge`
    - `node "$UP_PKG/.pi/scripts/harness-verify.mjs"` fails if manifest hash ≠ last sync (`--check`)

package/.pi/harness/docs/adrs/0031-harness-run-context.md

@@ -0,0 +1,41 @@
+# ADR 0031: Harness active run context
+
+- **Status:** Accepted
+- **Date:** 2026-05-17
+
+## Context
+
+Manual harness steps required copying `run_id` and `plan-packet.json` paths between commands. `trace-recorder` minted a new `run_id` on every `agent_start`, splitting artifacts across phases. The live widget exposed raw trace ids.
+
+## Decision
+
+1. Add `.pi/lib/harness-run-context.ts` and `harness-run-context.ts` extension as the single source of truth for active runs.
+2. Persist mirrors:
+   - `.pi/harness/runs/<run_id>/run-context.json`
+   - `.pi/harness/active-run.json` (cross-session pointer for forked eval)
+3. Canonical plan path: `.pi/harness/runs/<run_id>/plan-packet.json` — injected via `[HarnessActivePlan]`; no `--plan` on the happy path.
+4. **Hook order:** `harness-run-context` `before_agent_start` allocates/reuses `run_id` before `trace-recorder` `agent_start`. Trace writes phase files `trace-<phase>.json` plus rollup `trace.json`.
+5. PostHog `harness_run_started` at most once per logical `run_id`.
+6. Short commands: `/harness-run`, `/harness-eval`, etc. without args; recovery via `/harness-run-status`, `/harness-use-run`.
+7. After execute, handoff recommends **`/harness-eval`** in the same session; review commands spawn isolated subagents (see ADR 0032). `active-run.json` still supports cross-session recovery when Pi was closed mid-run.
+8. `hasApprovedPlanSignal` uses user-visible prompt only; execute requires `plan_ready` from disk validation **and** recorded `ask_user` approval (or `harness-plan-approval` entry).
+9. **Plan-phase writes:** policy-gate allows `write`/`edit` only on canonical `.pi/harness/runs/<run_id>/plan-packet.json` after approval; all other paths stay blocked until execute phase.
+10. **Approval-before-persist:** agents present the full plan, call `ask_user` (Approve / Request changes / Cancel), then write the packet. `--quick` narrows planning only — it does not skip approval.
+11. **`/harness-auto`:** after an approved plan-packet write, policy phase promotes to `execute` in the same agent turn so implementation can proceed without a separate `/harness-run` message.
+
+## Consequences
+
+### Positive
+
+- One logical run per manual/auto pipeline; forensics and telemetry align.
+- Users never copy run ids or plan paths in normal workflows.
+
+### Negative
+
+- Extension ordering and disk reconciliation must stay correct when adding new harness commands.
+
+## References
+
+- `.pi/lib/harness-run-context.ts`
+- `.pi/extensions/harness-run-context.ts`
+- `.pi/harness/specs/harness-run-context.schema.json`

package/.pi/harness/docs/adrs/0032-harness-command-orchestration.md

@@ -0,0 +1,37 @@
+# ADR 0032: Harness slash commands as agent orchestrators
+
+- **Status:** Accepted
+- **Date:** 2026-05-17
+
+## Context
+
+Harness slash prompts duplicated logic already defined in `harness/*` agents. Commands did not invoke the `Agent` tool. Review docs told users to fork a new Pi session even though subagents already provide isolated context.
+
+## Decision
+
+1. **Slash commands** parse args, spawn the matching `harness/*` agent, run all `ask_user` gates, perform policy-gated writes, and emit handoff blocks.
+2. **Agents** perform multi-turn reads and emit structured JSON drafts; they do not approve plans or write canonical run artifacts (except executor mutations in scope).
+3. **HarnessSpawnContext** JSON (`.pi/harness/specs/harness-spawn-context.schema.json`) is required in every spawn prompt because subagents do not receive `[HarnessActivePlan]` injection.
+4. **Review isolation** uses `Agent` spawn with `inherit_context: false`, not session fork. `review-integrity` allows `Agent` / `get_subagent_result` for `harness/evaluator`, `harness/adversary`, and `harness/tie-breaker`.
+5. **Subagent policy** (`harness-subagent-policy.ts`) blocks mutating tools for planner/evaluator/adversary and related read-only agents; executor keeps write tools and `extensions: true`.
+6. **Planner** has `disallowed_tools: ask_user`; clarification options return in JSON for the parent orchestrator.
+
+## Consequences
+
+### Positive
+
+- Single source of truth for phase logic in agent files; prompts stay thin.
+- L4 review isolation without manual session management.
+
+### Negative
+
+- Orchestrator must parse subagent JSON reliably and pass complete spawn context.
+- Scope enforcement remains prompt-driven for executor until optional path allowlist.
+
+## References
+
+- `.pi/prompts/harness-*.md`
+- `.pi/agents/harness/*.md`
+- `.pi/extensions/lib/harness-subagents/harness-subagent-policy.ts`
+- `.pi/extensions/review-integrity.ts`
+- `.pi/lib/harness-agent-output.ts`

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

@@ -16,6 +16,8 @@ Team-shared ADRs for the ultimate-pi harness live under `.pi/harness/docs/adrs/`
 | [0008](0008-harness-posthog-telemetry.md) | Harness PostHog telemetry | Accepted |
 | [0009](0009-sentrux-rules-lifecycle.md) | Sentrux rules.toml lifecycle | Accepted |
 | [0030](0030-inhouse-vcc-compaction.md) | In-house VCC compaction (vendored pi-vcc) | Accepted |
+| [0031](0031-harness-run-context.md) | Harness active run context | Accepted |
+| [0032](0032-harness-command-orchestration.md) | Harness commands as agent orchestrators | Accepted |
 
 ## Template
 

package/.pi/harness/evals/smoke/run-context.fixture.json

@@ -0,0 +1,17 @@
+{
+	"schema_version": "1.0.0",
+	"run_id": "smoke-session-1",
+	"pi_session_id": "smoke-session",
+	"project_root": "/tmp/ultimate-pi-smoke",
+	"phase": "plan",
+	"plan_id": null,
+	"plan_packet_path": "/tmp/ultimate-pi-smoke/.pi/harness/runs/smoke-session-1/plan-packet.json",
+	"plan_ready": false,
+	"task_summary": "smoke task",
+	"status": "active",
+	"last_completed_step": null,
+	"last_outcome": null,
+	"next_recommended_command": "/harness-plan \"smoke task\"",
+	"owner_pi_session_id": "smoke-session",
+	"updated_at": "2026-05-17T00:00:00.000Z"
+}

package/.pi/harness/specs/harness-run-context.schema.json

@@ -0,0 +1,80 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/harness-run-context.schema.json",
+	"title": "HarnessRunContext",
+	"description": "Session- and disk-backed active harness run pointer.",
+	"type": "object",
+	"additionalProperties": false,
+	"required": [
+		"schema_version",
+		"run_id",
+		"pi_session_id",
+		"project_root",
+		"phase",
+		"plan_ready",
+		"status",
+		"owner_pi_session_id",
+		"updated_at"
+	],
+	"properties": {
+		"schema_version": {
+			"type": "string",
+			"const": "1.0.0"
+		},
+		"run_id": {
+			"type": "string",
+			"minLength": 1
+		},
+		"pi_session_id": {
+			"type": "string",
+			"minLength": 1
+		},
+		"project_root": {
+			"type": "string",
+			"minLength": 1
+		},
+		"phase": {
+			"type": "string",
+			"enum": ["plan", "execute", "evaluate", "adversary", "merge"]
+		},
+		"plan_id": {
+			"type": ["string", "null"]
+		},
+		"plan_packet_path": {
+			"type": ["string", "null"]
+		},
+		"plan_ready": {
+			"type": "boolean"
+		},
+		"task_summary": {
+			"type": ["string", "null"]
+		},
+		"status": {
+			"type": "string",
+			"enum": ["active", "aborted", "completed"]
+		},
+		"last_completed_step": {
+			"type": ["string", "null"]
+		},
+		"last_outcome": {
+			"type": ["string", "null"]
+		},
+		"next_recommended_command": {
+			"type": ["string", "null"]
+		},
+		"owner_pi_session_id": {
+			"type": "string",
+			"minLength": 1
+		},
+		"updated_at": {
+			"type": "string",
+			"format": "date-time"
+		},
+		"harness_run_started_emitted": {
+			"type": "boolean"
+		},
+		"turn_override_run_id": {
+			"type": ["string", "null"]
+		}
+	}
+}

package/.pi/harness/specs/harness-spawn-context.schema.json

@@ -0,0 +1,65 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/harness-spawn-context.schema.json",
+	"title": "HarnessSpawnContext",
+	"description": "Structured context passed from harness slash-command orchestrators to harness/* subagents.",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["schema_version", "agent", "mode"],
+	"properties": {
+		"schema_version": {
+			"type": "string",
+			"const": "1.0.0"
+		},
+		"agent": {
+			"type": "string",
+			"minLength": 1,
+			"description": "Target subagent id, e.g. harness/planner"
+		},
+		"mode": {
+			"type": "string",
+			"enum": [
+				"create",
+				"revise",
+				"execute",
+				"benchmark",
+				"verdict",
+				"adversary",
+				"trace",
+				"incident",
+				"tune"
+			]
+		},
+		"run_id": {
+			"type": "string"
+		},
+		"plan_packet_path": {
+			"type": "string"
+		},
+		"run_dir": {
+			"type": "string"
+		},
+		"task_summary": {
+			"type": "string"
+		},
+		"risk_level": {
+			"type": "string",
+			"enum": ["low", "med", "high"]
+		},
+		"quick": {
+			"type": "boolean"
+		},
+		"acceptance_checks": {
+			"type": "array",
+			"items": { "type": "string" }
+		},
+		"artifact_paths": {
+			"type": "object",
+			"additionalProperties": { "type": "string" }
+		},
+		"handoff_summary": {
+			"type": "string",
+			"description": "Prior phase bullet summary for chained spawns (harness-auto)"
+		}
+	}
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Parse structured JSON blocks from harness subagent assistant output.
+ */
+
+const JSON_FENCE_RE = /```(?:json)?\s*([\s\S]*?)```/i;
+
+export function extractJsonBlock(text: string): string | null {
+	const trimmed = text.trim();
+	if (trimmed.startsWith("{")) {
+		return trimmed;
+	}
+	const match = JSON_FENCE_RE.exec(text);
+	if (match?.[1]) {
+		return match[1].trim();
+	}
+	const lastBrace = trimmed.lastIndexOf("{");
+	const lastClose = trimmed.lastIndexOf("}");
+	if (lastBrace >= 0 && lastClose > lastBrace) {
+		return trimmed.slice(lastBrace, lastClose + 1);
+	}
+	return null;
+}
+
+export function parseHarnessAgentJson<T extends Record<string, unknown>>(
+	text: string,
+): { ok: true; value: T } | { ok: false; error: string } {
+	const block = extractJsonBlock(text);
+	if (!block) {
+		return { ok: false, error: "no JSON block found in subagent output" };
+	}
+	try {
+		const value = JSON.parse(block) as T;
+		if (!value || typeof value !== "object") {
+			return { ok: false, error: "parsed value is not an object" };
+		}
+		return { ok: true, value };
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		return { ok: false, error: message };
+	}
+}