ultimate-pi 0.19.1 → 0.20.0

package/.pi/agents/harness/running/executor.md

@@ -1,6 +1,5 @@
 ---
 description: Harness executor that implements only within approved PlanPacket scope.
-extensions: true
 thinking: medium
 max_turns: 20
 ---
@@ -41,3 +40,45 @@ Call **`submit_executor_handoff`** with a document matching `harness-executor-ha
 - `files_changed`, `validation_summary`, `rollback_refs`, `handoff_ready`
 
 Do not write `artifacts/executor-rollback.json` — rollback is emitted as YAML by the submit pipeline.
+
+## Hash-anchored read/edit (default)
+
+`read` returns each line as `AnchorWord§line text`. `edit` uses anchors from the latest read — not raw `oldText`/`newText`.
+
+- For **single-line replace**, set `anchor` and omit `end_anchor` (defaults to the same line) or set `end_anchor` to the same anchored line.
+- For **multi-line replace**, set `anchor` and `end_anchor` to the first and last lines of the range (with matching line text after `§`).
+- **Batch** all edits for one file in one `edit` call. Edit independent files in the same turn when lakes allow.
+- Do not re-read a file unless anchors failed or the file changed outside your session.
+
+harness-lens may fix indentation on anchored `edit.text` before apply.
+
+## Context discipline (read order)
+
+1. Lake `context_bundle_path` and plan scope.
+2. `sg -p '…'` via bash for structural search (never `grep`/`find` for code).
+3. `ccc search` when you need semantic matches.
+4. Targeted **read** only for lines you will edit — no full-file reads for discovery.
+
+## Batching discipline
+
+- One read pass per file before editing it.
+- Group work by lake; batch all edits per file in one `edit` call.
+- Independent files may be edited in the same turn when safe.
+
+## Structural refactor (no AST tools)
+
+1. **Locate** with `sg -p 'pattern'` (bash).
+2. **Read** anchored regions you will change.
+3. **Edit** minimally with batched anchored `edit`.
+
+Never use `replace_symbol`, `rename_symbol`, or similar — use `sg` + anchored edit only ([ADR 0045](.pi/harness/docs/adrs/0045-harness-lens-minimal-contract.md)).
+
+## Post-edit verification (before handoff)
+
+Do **not** call `submit_executor_handoff` until:
+
+1. Plan **`acceptance_checks`** for touched scope have been run (record commands and outcomes in `validation_summary`).
+2. **Lens/LSP blockers** on changed files are resolved when extensions are enabled (fix errors, do not ignore).
+3. **`files_changed`** stays within approved `PlanPacket` scope.
+
+You still do not self-certify final quality — `/harness-review` owns adversary and Sentrux gate.

package/.pi/extensions/harness-anchored-edit.ts

@@ -0,0 +1,141 @@
+/**
+ * Hash-anchored read/edit — first-class harness read and edit tools (always on).
+ * @see .pi/harness/docs/adrs/0051-hash-anchored-executor-edits.md
+ */
+import { resolve } from "node:path";
+import type { TextContent } from "@earendil-works/pi-ai";
+import {
+	createReadTool,
+	type ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+	anchoredEditTaskId,
+	applyAnchoredEditsToFile,
+	hashLinesStateful,
+} from "../lib/harness-anchored-edit/index.js";
+import type { AnchoredEdit } from "../lib/harness-anchored-edit/types.js";
+
+const anchoredEditEntrySchema = Type.Object({
+	anchor: Type.String({
+		description:
+			"Start anchor from read output, format Word§exact line text (e.g. Apple§const x = 1).",
+	}),
+	end_anchor: Type.Optional(
+		Type.String({
+			description: "End anchor for replace ranges (same format as anchor).",
+		}),
+	),
+	edit_type: Type.Optional(
+		Type.Union([
+			Type.Literal("replace"),
+			Type.Literal("insert_after"),
+			Type.Literal("insert_before"),
+		]),
+	),
+	text: Type.String({ description: "New text for insert/replace." }),
+});
+
+const anchoredEditSchema = Type.Object({
+	path: Type.String({ description: "Path to the file to edit." }),
+	edits: Type.Array(anchoredEditEntrySchema, {
+		description:
+			"Batch all edits for this file in one call. Use anchors from the latest read.",
+	}),
+});
+
+const readSchema = Type.Object({
+	path: Type.String({ description: "Path to the file to read." }),
+	offset: Type.Optional(Type.Number({ description: "1-based start line." })),
+	limit: Type.Optional(Type.Number({ description: "Max lines to read." })),
+});
+
+function stripAnchoredFromReadOutput(text: string): string {
+	return text
+		.split("\n")
+		.map((line) => {
+			const idx = line.indexOf("§");
+			if (idx === -1) return line;
+			const prefix = line.slice(0, idx);
+			if (/^[A-Z][a-zA-Z]*$/.test(prefix)) {
+				return line.slice(idx + 1);
+			}
+			return line;
+		})
+		.join("\n");
+}
+
+export default function harnessAnchoredEdit(pi: ExtensionAPI): void {
+	const readToolByCwd = new Map<string, ReturnType<typeof createReadTool>>();
+
+	function getReadTool(cwd: string) {
+		let tool = readToolByCwd.get(cwd);
+		if (!tool) {
+			tool = createReadTool(cwd);
+			readToolByCwd.set(cwd, tool);
+		}
+		return tool;
+	}
+
+	pi.registerTool({
+		name: "read",
+		label: "read",
+		description:
+			"Read a file; each line is prefixed with a stable anchor (Word§line). Use those anchors in edit.",
+		parameters: readSchema,
+		async execute(toolCallId, params, signal, onUpdate, ctx) {
+			const base = getReadTool(ctx.cwd);
+			const result = await base.execute(
+				toolCallId,
+				params,
+				signal,
+				onUpdate,
+				ctx,
+			);
+			const taskId = anchoredEditTaskId(ctx);
+			const absolutePath = resolve(ctx.cwd, params.path);
+			for (const block of result.content) {
+				if (block.type !== "text") continue;
+				const plain = stripAnchoredFromReadOutput(block.text);
+				block.text = hashLinesStateful(absolutePath, plain, taskId);
+			}
+			return result;
+		},
+	});
+
+	pi.registerTool({
+		name: "edit",
+		label: "edit",
+		description:
+			"Edit using line anchors from read. Batch multiple edits per file. For replace, set end_anchor (defaults to anchor for single-line replace).",
+		parameters: anchoredEditSchema,
+		promptGuidelines: [
+			"Use anchors from the latest read output (Word§line).",
+			"Batch all edits for one file in a single edit call.",
+			"For renames across files: sg -p to locate, then minimal anchored edits — do not use replace_symbol tools.",
+		],
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const absolutePath = resolve(ctx.cwd, params.path);
+			const taskId = anchoredEditTaskId(ctx);
+			const edits = params.edits as AnchoredEdit[];
+
+			const result = await applyAnchoredEditsToFile(
+				absolutePath,
+				edits,
+				taskId,
+			);
+
+			if (!result.ok) {
+				return {
+					content: [{ type: "text", text: result.error }] as TextContent[],
+					details: { error: true },
+				};
+			}
+
+			return {
+				content: [{ type: "text", text: result.message }] as TextContent[],
+				details: result.details,
+			};
+		},
+	});
+}

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

@@ -1,9 +1,9 @@
 {
 	"schema_version": "1.0.0",
 	"package": "ultimate-pi",
-	"package_version": "0.19.0",
-	"generated_at": "2026-05-26T06:39:19.250Z",
-	"policy_sha256": "f0eb41bc6a877a237087e87762ce11908e93755a42d58f19d6573665b198665f",
+	"package_version": "0.19.1",
+	"generated_at": "2026-05-26T07:37:49.163Z",
+	"policy_sha256": "5a1e71f380df7dde8f6d1f33b366da8bba191689476a6440b3bcdbd776dc617a",
 	"agents": {
 		"pi-pi/agent-expert": {
 			"path": ".pi/agents/pi-pi/agent-expert.md",
@@ -87,7 +87,7 @@
 		},
 		"harness/running/executor": {
 			"path": ".pi/agents/harness/running/executor.md",
-			"sha256": "219c9307567acc95a9c1b1340f899fac860406fb2c2e84f51b4a8c3ba3a0e2ec"
+			"sha256": "1b8aa6e05ffacc8550569465d47cc8525902b53431e36b1c0f973ca633eab450"
 		},
 		"harness/reviewing/adversary": {
 			"path": ".pi/agents/harness/reviewing/adversary.md",

package/.pi/harness/agents.policy.yaml

@@ -22,10 +22,10 @@ kinds:
       - write
       - edit
       - bash
-      - grep
-      - find
       - ls
-    extensions: true
+    # Subprocess bundle (governance + anchored read/edit + lens) — not full .pi/extensions (parent phase hooks).
+    extension_bundle: executor
+    extensions: false
     read_only: false
   evaluator:
     tools:
@@ -141,7 +141,6 @@ agents:
     kind: executor
     tools_add:
       - submit_executor_handoff
-    extensions: true
     max_turns: 20
     thinking: medium
     submit_tool: submit_executor_handoff

package/.pi/harness/docs/adrs/0051-hash-anchored-executor-edits.md

@@ -0,0 +1,41 @@
+# ADR 0051: Hash-anchored read/edit (Dirac-inspired)
+
+- **Status:** Accepted
+- **Date:** 2026-05-26
+
+## Context
+
+Harness executor sessions used Pi’s `oldText`/`newText` `edit` tool. Line-number and fuzzy-match edits fail when files drift between read and edit, causing retries and token waste. [Dirac](https://github.com/dirac-run/dirac) demonstrates stable **hash-anchored** line targeting with Myers-diff anchor reconciliation; user evaluation chose adoption for the harness.
+
+We already own adjacent concerns: **harness-lens** (LSP, indentation autopatch, format), **shell `sg`** (structural search per ADR 0045), **Sentrux** (architecture gate). We must not duplicate those layers.
+
+## Decision
+
+1. **First-class tools** — [`.pi/extensions/harness-anchored-edit.ts`](../../../extensions/harness-anchored-edit.ts) registers harness `read` and `edit`. No env toggle.
+2. **Vendored core** in [`.pi/lib/harness-anchored-edit/`](../../../lib/harness-anchored-edit/) (Apache-2.0 subset from Dirac: anchor state, line protocol, resolve/apply).
+3. **`read`** output: `AnchorWord§line` per line; anchor state scoped per session/task id.
+4. **`edit`** input: `anchor`, optional `end_anchor` (defaults to `anchor` for single-line replace), `edit_type`, `text`; batch `edits[]` per file.
+5. **Native apply** — `applyAnchoredEditsToFile` writes disk directly (Pi `edit-diff` for unified diff in tool result). No `resolve-to-pi-edit` / no delegation to `createEditTool`.
+6. **Lens** — `tool_call` autopatch corrects indentation on anchored `edits[].text` only ([`anchored-edit-autopatch.ts`](../../../lib/harness-lens/clients/anchored-edit-autopatch.ts)). Legacy `oldText` autopatch remains for non-harness agents that still use Pi edit.
+7. **Executor subprocess bundle** — `kinds.executor.extension_bundle: executor` loads `--no-extensions` plus curated `-e` modules only: `subagent-governance.ts`, `harness-anchored-edit.ts`, `harness-lens.ts` ([`resolveExtensionBundlePaths`](../../../lib/agents-policy.mjs)). Avoids loading the full `.pi/extensions` tree (parent orchestration, run-context phase hooks) while still providing hash-anchored read/edit and lens format-on-result.
+8. **Builtin suppression** — Executor subprocesses use `--no-builtin-tools` + tool allowlist ([`agents.policy.yaml`](../agents.policy.yaml) via `noBuiltinTools` when `extension_bundle` or full extensions apply).
+9. **Executor policy** (prompt + practice-map): batching discipline, post-edit verification before `submit_executor_handoff`, structural refactor via `sg -p` → anchored edit — **no** `replace_symbol` Pi tools.
+10. **Remove** `grep`/`find` from executor tool policy; use `bash` + `sg` for code search.
+
+## Consequences
+
+### Positive
+
+- More stable edits across multi-step executor and steer repair loops.
+- Single anchored edit surface; no Pi text-match shim on the hot path.
+
+### Negative
+
+- Models must learn anchor `§` protocol.
+- Vendored Dirac code must be kept in sync for security fixes (small surface).
+
+## References
+
+- [practice-map.md](../practice-map.md) — Executor edit discipline
+- [ADR 0045](0045-harness-lens-minimal-contract.md) — lens vs sg vs Sentrux
+- [ADR 0044](0044-harness-steer-loop.md) — repair mode uses same edit rules

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

@@ -36,6 +36,8 @@ Team-shared ADRs for the ultimate-pi harness live under `.pi/harness/docs/adrs/`
 | [0047](0047-agt-layered-security.md) | AGT layered security (rings, prompt defense, CI) | Accepted |
 | [0048](0048-tool-call-hook-order.md) | tool_call hook interaction matrix | Accepted |
 | [0049](0049-agents-policy-manifest.md) | agents.policy.yaml SSOT + native discovery | Accepted |
+| [0050](0050-agentic-web-retrieval-stack.md) | Agentic Web Retrieval Stack (WRS) | Accepted |
+| [0051](0051-hash-anchored-executor-edits.md) | Hash-anchored read/edit (Dirac-inspired) | Accepted |
 
 ## Practice map
 

package/.pi/harness/docs/practice-map.md

@@ -75,6 +75,17 @@ See also: [ADRs](adrs/README.md), [ADR 0040](adrs/0040-practice-grounded-orchest
 | Handoff | Generator–evaluator | `submit_executor_handoff` | Executor |
 | Next | Always verify | **`/harness-review`** (not replan on blocked) | Parent routing |
 
+
+### Executor edit discipline (ADR 0051)
+
+| Practice | Agent rule |
+|----------|------------|
+| Hash-anchored targeting | `read` → `Anchor§line`; `edit` uses anchors (default harness tools) |
+| Batching | All edits per file in one `edit`; independent files same turn when safe |
+| Pre-handoff verify | Run `acceptance_checks`; clear lens blockers; then `submit_executor_handoff` |
+| Structural refactor | `sg -p` locate → read slice → anchored edit — no `replace_symbol` tools |
+| Code search | `sg` / `ccc` only — not `grep`/`find` on executor |
+
 ## `/harness-review` — Monitoring and Controlling
 
 | Phase | Practice | Agent translation | Actor |

package/.pi/lib/agents-policy.d.mts

@@ -6,6 +6,10 @@ export interface AgentPolicySpec {
 	kind: string;
 	effectiveTools: string[];
 	extensionsOff: boolean;
+	/** Subprocess-only: load curated -e extensions instead of full .pi/extensions. */
+	extensionBundle?: string;
+	extensionsFull: boolean;
+	noBuiltinTools: boolean;
 	readOnly: boolean;
 	maxTurns?: number;
 	thinking?: string;

package/.pi/lib/agents-policy.mjs

@@ -31,10 +31,26 @@ const MUTATING_TOOLS = new Set(["write", "edit"]);
 
 const cache = new Map();
 
+const EXTENSION_BUNDLE_MODULES = {
+	executor: [
+		"subagent-governance.ts",
+		"harness-anchored-edit.ts",
+		"harness-lens.ts",
+	],
+};
+
 export function packageAgentsPolicyPath(packageRoot) {
 	return join(packageRoot, ".pi", "harness", "agents.policy.yaml");
 }
 
+/** Absolute paths for subprocess `-e` loads (curated; avoids parent-only extensions). */
+export function resolveExtensionBundlePaths(packageRoot, bundleName) {
+	const modules = EXTENSION_BUNDLE_MODULES[bundleName];
+	if (!modules) return [];
+	const extDir = join(packageRoot, ".pi", "extensions");
+	return modules.map((name) => join(extDir, name));
+}
+
 export function projectAgentsPolicyPath(projectRoot) {
 	return join(projectRoot, ".pi", "agents.policy.yaml");
 }
@@ -52,12 +68,19 @@ function readYamlFile(path) {
 	}
 }
 
+function normalizeExtensionBundle(raw) {
+	if (typeof raw.extension_bundle !== "string") return undefined;
+	const bundle = raw.extension_bundle.trim();
+	return bundle.length > 0 ? bundle : undefined;
+}
+
 function normalizeKindEntry(raw) {
 	if (!raw || typeof raw !== "object") return null;
 	const tools = Array.isArray(raw.tools) ? raw.tools.map(String) : [];
 	return {
 		tools,
 		extensions: raw.extensions === false ? false : Boolean(raw.extensions),
+		extensionBundle: normalizeExtensionBundle(raw),
 		readOnly: raw.read_only === true,
 		maxTurns:
 			typeof raw.max_turns === "number" && raw.max_turns > 0
@@ -93,6 +116,7 @@ function normalizeAgentEntry(raw) {
 				: raw.extensions === true
 					? true
 					: undefined,
+		extensionBundle: normalizeExtensionBundle(raw),
 		maxTurns:
 			typeof raw.max_turns === "number" && raw.max_turns > 0
 				? raw.max_turns
@@ -162,10 +186,25 @@ export function resolveEffectiveTools(agentId, merged) {
 	for (const t of entry.toolsDeny ?? []) base.delete(t);
 	for (const t of BUILTIN_DENY_TOOLS) base.delete(t);
 
+	const extensionBundle =
+		entry.extensionBundle ?? kind.extensionBundle ?? undefined;
+	const extensionsFull =
+		!extensionBundle &&
+		(entry.extensions === true
+			? true
+			: entry.extensions === false
+				? false
+				: Boolean(kind.extensions));
+	const extensionsOff = !extensionsFull;
+
 	return {
 		kind: kindName,
 		effectiveTools: [...base],
-		extensionsOff: entry.extensions === true ? false : entry.extensions === false ? true : !kind.extensions,
+		extensionsOff,
+		extensionBundle,
+		extensionsFull,
+		/** Suppress Pi builtins when harness read/edit register (full extensions or subprocess bundle). */
+		noBuiltinTools: extensionsFull || Boolean(extensionBundle),
 		readOnly: kind.readOnly,
 		maxTurns: entry.maxTurns ?? kind.maxTurns,
 		thinking: entry.thinking ?? kind.thinking,
@@ -304,6 +343,9 @@ export function applyAgentPolicyToConfig(agent, packageRoot, projectRoot) {
 		...agent,
 		tools: spec.effectiveTools.length > 0 ? spec.effectiveTools : undefined,
 		extensionsOff: spec.extensionsOff,
+		extensionBundle: spec.extensionBundle,
+		extensionsFull: spec.extensionsFull,
+		noBuiltinTools: spec.noBuiltinTools,
 		maxTurns: spec.maxTurns ?? agent.maxTurns,
 		thinking: spec.thinking ?? agent.thinking,
 		model: spec.model ?? agent.model,

package/.pi/lib/agents-policy.ts

@@ -16,4 +16,5 @@ export {
 	projectAgentsPolicyPath,
 	projectPoliciesDir,
 	resolveEffectiveTools,
+	resolveExtensionBundlePaths,
 } from "./agents-policy.mjs";