ultimate-pi 0.20.0 → 0.22.0

package/.pi/scripts/ls-lint-rules-sync.mjs

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+/**
+ * Sync .ls-lint.yml from .pi/harness/ls-lint/naming.manifest.json.
+ * Preserves user content outside the harness managed block.
+ *
+ * Usage: node .pi/scripts/ls-lint-rules-sync.mjs [--check] [--force] [PROJECT_ROOT]
+ */
+
+import { readFile, writeFile, mkdir, access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
+import { spawn, execSync } from "node:child_process";
+
+const UP_PKG = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+/** Target project root (consumer repo). Default: process.cwd(). */
+const PROJECT_ROOT =
+	process.argv.find((a, i) => i >= 2 && !a.startsWith("-")) || process.cwd();
+const MANIFEST = join(
+	PROJECT_ROOT,
+	".pi",
+	"harness",
+	"ls-lint",
+	"naming.manifest.json",
+);
+const MANIFEST_TEMPLATE = join(
+	UP_PKG,
+	".pi",
+	"harness",
+	"ls-lint",
+	"naming.manifest.json",
+);
+const RULES_PATH = join(PROJECT_ROOT, ".ls-lint.yml");
+const META_PATH = join(PROJECT_ROOT, ".ls-lint", ".harness-naming-meta.json");
+
+const MANAGED_START = "# --- harness:managed:start ---";
+const MANAGED_END = "# --- harness:managed:end ---";
+
+function fail(msg) {
+	console.error(`ls-lint-rules-sync: ${msg}`);
+	process.exit(1);
+}
+
+function hashContent(text) {
+	return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+
+function yamlScalar(value) {
+	const s = String(value);
+	if (/^[a-zA-Z0-9_.|]+$/.test(s) && !s.includes("regex:")) {
+		return s;
+	}
+	return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function renderRulesBlock(rules, indent) {
+	const lines = [];
+	const pad = " ".repeat(indent);
+	for (const [key, value] of Object.entries(rules)) {
+		lines.push(`${pad}${key}: ${yamlScalar(value)}`);
+	}
+	return lines.join("\n");
+}
+
+function renderManagedBlock(manifest) {
+	const lines = [];
+	lines.push(MANAGED_START);
+	lines.push(
+		"# Generated from .pi/harness/ls-lint/naming.manifest.json",
+	);
+	lines.push(`# Project: ${manifest.project ?? "unknown"}`);
+	lines.push(`# Schema: ${manifest.schema_version}`);
+	lines.push("");
+	lines.push("ls:");
+
+	const globalRules = manifest.global_rules ?? {};
+	for (const [key, value] of Object.entries(globalRules)) {
+		lines.push(`  ${key}: ${yamlScalar(value)}`);
+	}
+
+	for (const scoped of manifest.scoped_rules ?? []) {
+		const pathKey = scoped.path;
+		const pathYaml = /^[a-zA-Z_][\w/-]*$/.test(pathKey)
+			? pathKey
+			: yamlScalar(pathKey);
+		lines.push(`  ${pathYaml}:`);
+		lines.push(renderRulesBlock(scoped.rules ?? {}, 4));
+	}
+
+	lines.push("");
+	lines.push("ignore:");
+	for (const item of manifest.ignores ?? []) {
+		lines.push(`  - ${yamlScalar(item)}`);
+	}
+
+	lines.push(MANAGED_END);
+	return lines.join("\n");
+}
+
+function mergeRules(existing, managedBlock) {
+	const header = `# ls-lint — ${new Date().toISOString().slice(0, 10)}
+# Docs: https://ls-lint.org/
+# Sync: node $UP_PKG/.pi/scripts/ls-lint-rules-sync.mjs --force (see .pi/scripts/README.md for UP_PKG) or /harness-ls-lint-sync in pi
+#
+# Custom rules: add YAML below the managed block; they are preserved on sync.
+
+`;
+
+	if (!existing || !existing.includes(MANAGED_START)) {
+		return `${header}${managedBlock}\n`;
+	}
+
+	const start = existing.indexOf(MANAGED_START);
+	const end = existing.indexOf(MANAGED_END);
+	if (start === -1 || end === -1 || end < start) {
+		return `${header}${managedBlock}\n`;
+	}
+
+	const before = existing.slice(0, start);
+	const after = existing.slice(end + MANAGED_END.length);
+	return `${before}${managedBlock}${after}`.replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+}
+
+async function fileExists(path) {
+	try {
+		await access(path, constants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function countViolations(output) {
+	const matches = output.match(/\d+\s+violations?/i);
+	if (matches) {
+		const n = Number.parseInt(matches[0], 10);
+		if (!Number.isNaN(n)) return n;
+	}
+	if (/no\s+violations/i.test(output) || /0\s+violations/i.test(output)) {
+		return 0;
+	}
+	const lineMatches = output.match(/✖|✗|error|violation/gi);
+	return lineMatches ? lineMatches.length : 0;
+}
+
+function lintPathEnv() {
+	const extra = [
+		process.env.PATH,
+		`${process.env.HOME || ""}/.local/bin`,
+	].filter(Boolean);
+	try {
+		const npmBin = execSync("npm prefix -g", { encoding: "utf-8" }).trim();
+		extra.push(`${npmBin}/bin`);
+	} catch {
+		/* ignore */
+	}
+	return { ...process.env, PATH: extra.join(":") };
+}
+
+async function runLsLint() {
+	return new Promise((resolve) => {
+		const child = spawn("ls-lint", [], {
+			cwd: PROJECT_ROOT,
+			stdio: ["ignore", "pipe", "pipe"],
+			env: lintPathEnv(),
+		});
+		let out = "";
+		child.stdout?.on("data", (d) => {
+			out += d.toString();
+		});
+		child.stderr?.on("data", (d) => {
+			out += d.toString();
+		});
+		child.on("close", (code) => {
+			resolve({ code: code ?? 1, out: out.trim() });
+		});
+		child.on("error", () => resolve({ code: 127, out: "ls-lint not installed" }));
+	});
+}
+
+async function main() {
+	const checkOnly = process.argv.includes("--check");
+	const force = process.argv.includes("--force");
+	const strict = process.argv.includes("--strict");
+
+	if (!(await fileExists(MANIFEST))) {
+		if (await fileExists(MANIFEST_TEMPLATE)) {
+			await mkdir(dirname(MANIFEST), { recursive: true });
+			await writeFile(
+				MANIFEST,
+				await readFile(MANIFEST_TEMPLATE, "utf-8"),
+				"utf-8",
+			);
+			console.log(
+				`ls-lint-rules-sync: seeded manifest from package -> ${MANIFEST}`,
+			);
+		} else {
+			fail(`missing manifest ${MANIFEST} (and no template in package)`);
+		}
+	}
+
+	const manifestRaw = await readFile(MANIFEST, "utf-8");
+	const manifest = JSON.parse(manifestRaw);
+	const manifestHash = hashContent(manifestRaw);
+	const managedBlock = renderManagedBlock(manifest);
+
+	let existing = "";
+	if (await fileExists(RULES_PATH)) {
+		existing = await readFile(RULES_PATH, "utf-8");
+	}
+
+	let meta = { manifest_hash: null, synced_at: null };
+	if (await fileExists(META_PATH)) {
+		try {
+			meta = JSON.parse(await readFile(META_PATH, "utf-8"));
+		} catch {
+			/* ignore */
+		}
+	}
+
+	const unchanged =
+		meta.manifest_hash === manifestHash &&
+		(await fileExists(RULES_PATH)) &&
+		existing.includes(MANAGED_START);
+
+	if (unchanged && !force) {
+		console.log("ls-lint-rules-sync: .ls-lint.yml already up to date");
+		if (checkOnly) process.exit(0);
+	} else if (checkOnly) {
+		fail(
+			'.ls-lint.yml out of date — run node "$UP_PKG/.pi/scripts/ls-lint-rules-sync.mjs" --force (see .pi/scripts/README.md for UP_PKG)',
+		);
+	} else {
+		await mkdir(join(PROJECT_ROOT, ".ls-lint"), { recursive: true });
+		const next = mergeRules(existing, managedBlock);
+		await writeFile(RULES_PATH, next, "utf-8");
+		meta = {
+			manifest_hash: manifestHash,
+			synced_at: new Date().toISOString(),
+			manifest_path: ".pi/harness/ls-lint/naming.manifest.json",
+		};
+		await writeFile(META_PATH, `${JSON.stringify(meta, null, 2)}\n`, "utf-8");
+		console.log(`ls-lint-rules-sync: wrote ${RULES_PATH}`);
+	}
+
+	const { code, out } = await runLsLint();
+	if (code === 127) {
+		console.log(
+			"ls-lint-rules-sync: ls-lint CLI not found — install via harness-setup §2.9",
+		);
+		process.exit(0);
+	}
+	if (code !== 0) {
+		console.warn(out || "ls-lint: violations (update manifest or fix paths)");
+		if (strict || checkOnly) process.exit(code);
+		process.exit(0);
+	}
+	console.log(out || "ls-lint: pass");
+}
+
+main().catch((err) => {
+	console.error(err);
+	process.exit(1);
+});

package/.pi/scripts/run-tests.mjs

@@ -10,6 +10,7 @@ const NODE_ONLY_TESTS = [
 	'harness-subagents-loader.test.mjs',
 	'harness-subagent-precheck.test.mjs',
 	'sentrux-rules-sync.test.mjs',
+	'ls-lint-rules-sync.test.mjs',
 	'harness-budget-guard.test.mjs',
 ];
 

package/.pi/settings.example.json

@@ -3,5 +3,6 @@
 		"enabled": true,
 		"maxRetries": 3
 	},
+	"autocompleteMaxVisible": 12,
 	"packages": ["npm:ultimate-pi", "npm:@posthog/pi", "npm:context-mode"]
 }

package/.sentrux/rules.toml

@@ -12,7 +12,7 @@
 [constraints]
 max_cycles = 0
 max_coupling = "B"
-max_cc = 35
+max_cc = 25
 no_god_files = true
 
 [[layers]]

package/AGENTS.md

@@ -37,6 +37,7 @@ Created: 2026-05-14
 - `graphify update .` after significant code changes
 - ast-grep (`sg`) is the default code search tool — use `sg -p 'pattern'` for structural search, never grep for code
 - Non-API web: invoke **`web-retrieval`** skill (WRS tiers; default `tier=deep` with `web-query-expander` → `anglesFile`). CLI: `python3 "$UP_PKG/.pi/scripts/harness-web.py"`
+- Git commits: invoke **`harness-git-commit`** skill — `node "$UP_PKG/.pi/scripts/harness-git-commit.mjs"` (config: `.pi/auto-commit.json`)
 
 ## graphify
 

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project are documented in this file.
 
+## [v0.22.0] — 2026-05-27
+
+### ✨ Features
+
+- OSS Sentrux structured repair without Pro or MCP
+
+### 📖 Documentation
+
+- split repo docs by audience
+
+### 🔧 Chores
+
+- apply pending harness and ask-user updates
+- remove obsolete PostHog plan latency dashboard doc
+
 ## [Unreleased]
 
 ### ✨ Features
@@ -9,6 +24,16 @@ All notable changes to this project are documented in this file.
 - **Harness lens:** Integrate selected pi-lens capabilities through a harness-owned extension, store lens state under `.pi/harness/.lens`, and route lens findings through harness PostHog telemetry instead of standalone lens health/telemetry surfaces.
 - **Graphify KB updater:** Productize conservative daily discovery/promotion with explicit repo/release taxonomy, allowlist source-class gates, operator review queue reporting, scheduler smoke validation, and safe Graphify refresh controls.
 
+## [v0.21.0] — 2026-05-26
+
+### ✨ Features
+
+- **Harness:** Add ls-lint filename fitness (manifest, sync, steward agent, harness-verify) and plan-phase task clarification gate before execution.
+
+### 🔧 Chores
+
+- Add `agents-policy.d.mts` and hash-anchored edit typecheck fixes so `npm run check:ts` passes on main.
+
 ## [v0.20.0] — 2026-05-26
 
 ### ✨ Features

package/README.md

@@ -4,6 +4,11 @@
 
 `ultimate-pi` adds a governed coding workflow to Pi: bootstrap the repo, plan with evidence, execute only against an approved PlanPacket, then run an independent review gate before merge.
 
+## Documentation Paths
+
+Use [`DOCS_BY_AUDIENCE.md`](./DOCS_BY_AUDIENCE.md) as the routing source of truth.
+This README stays focused on the package itself, not on repeating the full doc map.
+
 ## Quick start
 
 **Requirements:** Node 18+, npm 9+, git, and Pi.
@@ -64,9 +69,9 @@ If `/harness-review` returns `implementation_gap`, run:
 
 | Command | Purpose |
 |---|---|
-| `/harness-setup [--skip-graphify] [--skip-tools] [--non-interactive] [--force]` | Idempotent project bootstrap: Graphify, harness-web/Scrapling, CLI tools, settings, contracts, Sentrux, harness lens, and verification. |
+| `/harness-setup [--skip-graphify] [--skip-tools] [--non-interactive] [--force]` | Idempotent project bootstrap: Graphify, harness-web/Scrapling, CLI tools, settings, contracts, Sentrux, ls-lint naming, harness lens, and verification. |
 | `/harness-auto "<task>" [--quick] [--risk low\|med\|high]` | Strict full pipeline: plan, execute, review, steer when appropriate. |
-| `/harness-plan "<task>" [--risk low\|med\|high] [--quick]` | PM-grade planning: reconnaissance, decomposition, hypothesis, external research, ExecutionPlan, DAG validation, Review Gate debate, `approve_plan`, `create_plan`. |
+| `/harness-plan "<task>" [--risk low\|med\|high] [--quick]` | PM-grade planning: clarifies the task with you first, then reconnaissance, decomposition, hypothesis, external research, ExecutionPlan, DAG validation, Review Gate debate, `approve_plan`, `create_plan`. |
 | `/harness-run` | Executes the approved active PlanPacket by spawning `harness/running/executor`; no inline implementation. |
 | `/harness-review [--run <id>] [--quick] [--readonly] [--trace <ref>]` | Post-run verification gate: deterministic checks, benchmark evaluator, policy verdict, adversary, optional tie-breaker. |
 | `/harness-steer [--attempt N]` | Post-review repair pass for `implementation_gap`; executor reads `repair-brief.yaml`, then you re-run `/harness-review`. |
@@ -74,6 +79,8 @@ If `/harness-review` returns `implementation_gap`, run:
 | `/harness-trace [--run <id>] [--phase plan\|execute\|evaluate\|adversary\|merge]` | Summarizes run traces and artifact handoffs for replay/forensics. |
 | `/harness-incident --trigger <reason> [--run <id>] [--severity low\|med\|high\|critical]` | Records incident, rollback, and override trail for harness failures. |
 | `/harness-sentrux-steward [--run <id>]` | Ad-hoc architectural intent review for Sentrux manifest/rule alignment. |
+| `/harness-ls-lint-sync` | Regenerate `.ls-lint.yml` from `.pi/harness/ls-lint/naming.manifest.json`. |
+| `/harness-ls-lint-steward [--run <id>]` | Ad-hoc naming-intent review for ls-lint manifest/rule alignment. |
 | `/graphify [directory]` | Bootstraps or updates the Graphify knowledge graph. |
 | `/wiki-autoresearch [topic]` | Runs autonomous web research and builds a Graphify-backed research wiki. |
 | `/wiki-save` | Saves the current conversation or insight as a structured wiki note. |
@@ -84,7 +91,7 @@ If `/harness-review` returns `implementation_gap`, run:
 - **Planning** uses agents under `.pi/agents/harness/planning/` plus parent-led Graphify → `sg` → `ccc` reconnaissance. Legacy tool-tied `planning/scout-*` agents have been removed; planning context is captured in `artifacts/planning-context.yaml`.
 - **Running** uses `.pi/agents/harness/running/executor.md` via agent id `harness/running/executor`.
 - **Reviewing** uses `.pi/agents/harness/reviewing/` via `harness/reviewing/evaluator`, `harness/reviewing/adversary`, and `harness/reviewing/tie-breaker`.
-- **Support agents** such as `harness/incident-recorder`, `harness/sentrux-steward`, and `harness/trace-librarian` remain under `.pi/agents/harness/`.
+- **Support agents** such as `harness/incident-recorder`, `harness/sentrux-steward`, `harness/ls-lint-steward`, and `harness/trace-librarian` remain under `.pi/agents/harness/`.
 
 Subagents run isolated from the parent session. They persist canonical YAML through `submit_*` tools; the parent gates with `harness_artifact_ready` and writes only orchestrator-owned merge artifacts.
 
@@ -95,7 +102,7 @@ Subagents run isolated from the parent session. They persist canonical YAML thro
 | `.pi/harness/active-run.json` | Active run pointer for happy-path commands. |
 | `.pi/harness/runs/<run_id>/plan-packet.yaml` | Approved execution baseline. |
 | `.pi/harness/runs/<run_id>/research-brief.yaml` | Planning evidence and research merge. |
-| `.pi/harness/runs/<run_id>/artifacts/` | Planning context, decomposition, research, benchmark, verdict, adversary, repair, and Sentrux artifacts. |
+| `.pi/harness/runs/<run_id>/artifacts/` | Planning context, decomposition, research, benchmark, verdict, adversary, repair, Sentrux, and ls-lint signal artifacts. |
 | `.pi/harness/runs/<run_id>/handoff/executor-summary.yaml` | Executor handoff written by `submit_executor_handoff`. |
 | `.pi/harness/incidents/` | Incident records and rollback/override trail. |
 | `.pi/harness/docs/adrs/` | Harness architectural decisions. |
@@ -109,6 +116,7 @@ Subagents run isolated from the parent session. They persist canonical YAML thro
 - **No inline review:** `/harness-review` delegates verdicts to isolated reviewing agents.
 - **No auto-merge:** final merge remains a human/operator decision.
 - **Sentrux is the architecture signal:** structural baselines and gates inform review; executor does not optimize metrics as a goal.
+- **ls-lint is the naming signal:** manifest-driven `.ls-lint.yml` enforces filesystem conventions; steward evolves rules via chair-approved proposals (ADR 0052).
 - **pi-lens is edit-time diagnostics:** LSP/lint/format/ast feedback complements Sentrux and does not replace architecture gating.
 
 ## Troubleshooting
@@ -122,6 +130,7 @@ Subagents run isolated from the parent session. They persist canonical YAML thro
 | Review says `implementation_gap` | Run `/harness-steer`, then `/harness-review`. |
 | Review says `plan_gap` | Revise with `/harness-plan "<updated task>"`. |
 | Sentrux missing | Install/configure Sentrux or keep it skipped; harness verification still reports the status. |
+| ls-lint failures | Run `node .pi/scripts/harness-ls-lint-cli.mjs`, fix paths or propose manifest changes via `/harness-ls-lint-steward`. |
 
 Optional integrations can be configured by copying `.env.example` to `.env`; `/harness-setup` appends missing keys without overwriting existing values.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ultimate-pi",
-	"version": "0.20.0",
+	"version": "0.22.0",
 	"description": "Ultimate AI coding harness for pi.dev — extensible skills, Obsidian wiki knowledge layer, compressed context, deterministic output",
 	"keywords": [
 		"pi-package",
@@ -37,6 +37,7 @@
 	"files": [
 		".agents",
 		".sentrux",
+		".pi/harness/ls-lint",
 		".pi/extensions",
 		".pi/prompts",
 		"!.pi/prompts/release.md",
@@ -91,6 +92,9 @@
 		"test:vcc": "npx -y tsx --test vendor/pi-vcc/tests/*.test.ts",
 		"harness:sentrux-bootstrap": "node .pi/scripts/harness-sentrux-bootstrap.mjs",
 		"harness:sentrux-sync": "node .pi/scripts/sentrux-rules-sync.mjs --force",
+		"harness:ls-lint-bootstrap": "node .pi/scripts/harness-ls-lint-bootstrap.mjs",
+		"harness:ls-lint-sync": "node .pi/scripts/ls-lint-rules-sync.mjs --force",
+		"harness:git-commit": "node .pi/scripts/harness-git-commit.mjs",
 		"test:integration": "npx -y tsx --test test/cursor-sdk-provider.integration.test.ts"
 	},
 	"devDependencies": {

package/vendor/pi-vcc/src/hooks/before-compact.ts

@@ -137,6 +137,87 @@ const REASON_MESSAGES: Record<OwnCutCancelReason, string> = {
   too_few_live_messages: "pi-vcc: Too few messages to compact",
 };
 
+
+function collectLiveRolesForDiagnostics(
+  branchEntries: any[],
+  lastCompIdx: number,
+  lastKeptId: string | undefined,
+): string[] {
+  const hasPriorCompaction = lastCompIdx >= 0;
+  const hasValidKeptId = !!lastKeptId && branchEntries.some((e: any) => e.id === lastKeptId);
+  const diagOrphan = hasPriorCompaction && !hasValidKeptId;
+  const liveRoles: string[] = [];
+  if (diagOrphan) {
+    for (let i = lastCompIdx + 1; i < branchEntries.length; i++) {
+      const e = branchEntries[i];
+      if (e.type === "compaction") continue;
+      if (e.type === "message" && e.message) liveRoles.push(e.message.role);
+    }
+    return liveRoles;
+  }
+  let foundKept = !lastKeptId;
+  for (const e of branchEntries) {
+    if (!foundKept && e.id === lastKeptId) foundKept = true;
+    if (!foundKept || e.type === "compaction") continue;
+    if (e.type === "message" && e.message) liveRoles.push(e.message.role);
+  }
+  return liveRoles;
+}
+
+function handleOwnCutCancellation(args: {
+  ownCut: Extract<OwnCutResult, { ok: false }>;
+  isPiVcc: boolean;
+  settings: PiVccSettings;
+  branchEntries: any[];
+  ctx: any;
+}): { cancel: true } {
+  const { ownCut, isPiVcc, settings, branchEntries, ctx } = args;
+  const lastComp = [...branchEntries].reverse().find((e: any) => e.type === "compaction");
+  const lastCompIdx = lastComp ? branchEntries.indexOf(lastComp) : -1;
+  const lastKeptId: string | undefined = lastComp?.firstKeptEntryId;
+  const liveRoles = collectLiveRolesForDiagnostics(branchEntries, lastCompIdx, lastKeptId);
+  const userIndices = liveRoles.reduce<number[]>((acc, r, i) => (r === "user" ? (acc.push(i), acc) : acc), []);
+
+  dbg(settings, {
+    cancelled: true,
+    reason: ownCut.reason,
+    isPiVcc,
+    counts: {
+      total: branchEntries.length,
+      messages: branchEntries.filter((e: any) => e.type === "message").length,
+      compactions: branchEntries.filter((e: any) => e.type === "compaction").length,
+      entriesAfterLastCompaction: lastCompIdx >= 0 ? branchEntries.length - lastCompIdx - 1 : null,
+    },
+    liveMessages: {
+      count: liveRoles.length,
+      userCount: userIndices.length,
+      firstUserIdx: userIndices[0] ?? null,
+      lastUserIdx: userIndices[userIndices.length - 1] ?? null,
+      roleSequence: liveRoles.length <= 30
+        ? liveRoles
+        : [...liveRoles.slice(0, 10), "...", ...liveRoles.slice(-10)],
+    },
+    lastCompaction: lastComp
+      ? {
+          hasFirstKeptEntryId: !!lastComp.firstKeptEntryId,
+          foundInBranch: lastComp.firstKeptEntryId
+            ? branchEntries.some((e: any) => e.id === lastComp.firstKeptEntryId)
+            : null,
+        }
+      : null,
+    tail: branchEntries.slice(-5).map((e: any) => ({
+      type: e.type,
+      role: e.type === "message" ? e.message?.role : undefined,
+      hasContent: e.type === "message" ? e.message?.content != null : undefined,
+    })),
+  });
+
+  try {
+    ctx?.ui?.notify?.(REASON_MESSAGES[ownCut.reason], "warning");
+  } catch {}
+  return { cancel: true };
+}
+
 export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
   pi.on("session_before_compact", (event, ctx) => {
     const { preparation, branchEntries, customInstructions } = event;
@@ -149,68 +230,13 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
 
     const ownCut = buildOwnCut(branchEntries as any[]);
     if (!ownCut.ok) {
-      const lastComp = [...branchEntries].reverse().find((e: any) => e.type === "compaction");
-      const lastCompIdx = lastComp ? (branchEntries as any[]).indexOf(lastComp) : -1;
-
-      // Recompute liveMessages view (same logic as buildOwnCut) for diagnostic
-      const lastKeptId: string | undefined = lastComp?.firstKeptEntryId;
-      const hasPriorCompaction = lastCompIdx >= 0;
-      const hasValidKeptId = !!lastKeptId && (branchEntries as any[]).some((e: any) => e.id === lastKeptId);
-      const diagOrphan = hasPriorCompaction && !hasValidKeptId;
-      const liveRoles: string[] = [];
-      if (diagOrphan) {
-        for (let i = lastCompIdx + 1; i < branchEntries.length; i++) {
-          const e = (branchEntries as any[])[i];
-          if (e.type === "compaction") continue;
-          if (e.type === "message" && e.message) liveRoles.push(e.message.role);
-        }
-      } else {
-        let foundKept = !lastKeptId;
-        for (const e of branchEntries as any[]) {
-          if (!foundKept && e.id === lastKeptId) foundKept = true;
-          if (!foundKept) continue;
-          if (e.type === "compaction") continue;
-          if (e.type === "message" && e.message) liveRoles.push(e.message.role);
-        }
-      }
-      const userIndices = liveRoles.reduce<number[]>((acc, r, i) => (r === "user" ? (acc.push(i), acc) : acc), []);
-
-      dbg(settings, {
-        cancelled: true,
-        reason: ownCut.reason,
+      return handleOwnCutCancellation({
+        ownCut,
         isPiVcc,
-        counts: {
-          total: branchEntries.length,
-          messages: (branchEntries as any[]).filter((e: any) => e.type === "message").length,
-          compactions: (branchEntries as any[]).filter((e: any) => e.type === "compaction").length,
-          entriesAfterLastCompaction: lastCompIdx >= 0 ? branchEntries.length - lastCompIdx - 1 : null,
-        },
-        liveMessages: {
-          count: liveRoles.length,
-          userCount: userIndices.length,
-          firstUserIdx: userIndices[0] ?? null,
-          lastUserIdx: userIndices[userIndices.length - 1] ?? null,
-          roleSequence: liveRoles.length <= 30
-            ? liveRoles
-            : [...liveRoles.slice(0, 10), "...", ...liveRoles.slice(-10)],
-        },
-        lastCompaction: lastComp ? {
-          hasFirstKeptEntryId: !!lastComp.firstKeptEntryId,
-          foundInBranch: lastComp.firstKeptEntryId
-            ? (branchEntries as any[]).some((e: any) => e.id === lastComp.firstKeptEntryId)
-            : null,
-        } : null,
-        tail: (branchEntries as any[]).slice(-5).map((e: any) => ({
-          type: e.type,
-          role: e.type === "message" ? e.message?.role : undefined,
-          hasContent: e.type === "message" ? e.message?.content != null : undefined,
-        })),
+        settings,
+        branchEntries: branchEntries as any[],
+        ctx,
       });
-
-      try {
-        ctx?.ui?.notify?.(REASON_MESSAGES[ownCut.reason], "warning");
-      } catch {}
-      return { cancel: true };
     }
 
     const agentMessages = ownCut.messages;