@mgiles/perk 3.1.0 → 3.3.0

package/extension/{doors → pi/v1}/lifecycleGates.ts

@@ -1,8 +1,10 @@
-// Session-lifecycle gates (the interior safety primitive). One reusable dirty-repo guard on
-// session_before_switch / session_before_fork that returns { cancel: true } when an *active perk
-// workflow* has uncommitted changes — so a stage transition never silently orphans work. Plus the
-// guard-only `/implement` command that *enforces* the implement stage's `warm: false` legality (the
-// plan→implement jump requires fresh context; that is the cold door `perk implement`).
+// Session-lifecycle gates (the interior safety primitive), the Pi registration half. One
+// reusable dirty-repo guard on session_before_switch / session_before_fork that returns
+// { cancel: true } when an *active perk workflow* has uncommitted changes — so a stage
+// transition never silently orphans work. Plus the guard-only `/implement` command that
+// *enforces* the implement stage's `warm: false` legality (the plan→implement jump requires
+// fresh context; that is the cold door `perk implement`). The Pi-free policy these hooks apply
+// (`implementHandoffPrompt`, `planningStageRefusal`) lives in `session/lifecycleGates.ts`.
 //
 // pi.on("session_before_fork"/"...switch") handlers are fired by extensionRunner.emit({type,...})
 // and their { cancel } result round-trips; the handler's
@@ -13,25 +15,17 @@ import type {
   ExtensionCommandContext,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
-import type { PlanRef } from "../substrate/cache.ts";
-import { registerPerkCommand } from "../substrate/command.ts";
-import { render } from "../substrate/prompts.ts";
-import { branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
-import { report } from "../surfaces/report.ts";
+import { implementHandoffPrompt } from "../../session/lifecycleGates.ts";
+import type { PlanRef } from "../../substrate/cache.ts";
+import { registerPerkCommand } from "../../substrate/command.ts";
+import { branchOf, rebuildWorkflowState } from "../../substrate/workflowState.ts";
+import { report } from "../../surfaces/report.ts";
 
 const DIRTY_MESSAGE = "uncommitted changes — commit or stash before switching/forking this stage.";
 const HANDOFF_DIRTY_MESSAGE =
   "uncommitted changes — commit before a fresh-context /implement handoff (the plan is the " +
   "only artifact that crosses the boundary).";
 
-/**
- * Pure gate policy: cancel a transition only inside an active perk workflow whose tree is
- * dirty. Kept separate from the `pi.exec` effect so the matrix is unit-testable offline.
- */
-export function gateDecision(inputs: { active: boolean; dirty: boolean }): { cancel: boolean } {
-  return { cancel: inputs.active && inputs.dirty };
-}
-
 /** True when this session is linked to a plan (a perk workflow is in progress). */
 function workflowActive(ctx: ExtensionContext): boolean {
   return rebuildWorkflowState(branchOf(ctx)).active_plan_ref != null;
@@ -46,53 +40,14 @@ async function guardTransition(
   pi: ExtensionAPI,
   ctx: ExtensionContext,
 ): Promise<{ cancel: true } | undefined> {
-  const active = workflowActive(ctx);
-  if (!active) return undefined; // perk does not interfere with non-perk transitions
+  if (!workflowActive(ctx)) return undefined; // perk does not interfere with non-perk transitions
   const res = await pi.exec("git", ["status", "--porcelain"], { cwd: ctx.cwd });
   const dirty = res.code === 0 && res.stdout.trim().length > 0;
-  if (!gateDecision({ active, dirty }).cancel) return undefined;
+  if (!dirty) return undefined;
   report(ctx, "lifecycle", "warning", DIRTY_MESSAGE); // fail-safe-headless: loud, still cancels
   return { cancel: true };
 }
 
-/**
- * The per-backend plan-read instruction — the prompt SSOT for "how do I read the saved
- * plan". Byte-identical to `perk/run/launch.py::_plan_read_instruction` (the Python twin); drift in
- * either plane fails the paired parity suites. `github` reads via `gh`; `linear` points at the
- * pi-mono-linear tools with an `open <url>` fallback; any other provider falls back to opening
- * the url.
- *
- * The wording now lives in the canonical templates `prompts/common/plan-read/*.md`, rendered
- * identically by both planes via the shared render seam (contracts.md §8.31); branching stays in
- * code — only the arm chosen and the vars passed differ. Golden-fixture parity (the three
- * `plan-read-*` cases) plus a thin per-arm selection test replace the dedicated substring parity.
- */
-export function planReadInstruction(provider: string, prId: string, url: string): string {
-  if (provider === "github") return render("common/plan-read/github.md", { pr_id: prId, url });
-  if (provider === "linear") return render("common/plan-read/linear.md", { pr_id: prId, url });
-  return render("common/plan-read/other.md", { pr_id: prId, url });
-}
-
-/**
- * The plan-read priming seed for a fresh implement session. The in-session twin of
- * `perk/run/launch.py`'s `_implement_prompt`: carry the plan FORWARD (read it from its canonical
- * source), never summarize it — the plan is the only artifact that crosses the boundary.
- *
- * The wording lives in the canonical template `prompts/stages/implement.md`, rendered by the shared
- * seam (contracts.md §8.31); branching stays in code — only the `read_cmd` var differs. This warm
- * handoff is now byte-identical to the cold/worker primer, so it carries the same "Progress
- * tracking:" tail (the prior shorter near-copy omission is removed).
- */
-export function implementHandoffPrompt(ref: PlanRef): string {
-  const readCmd = planReadInstruction(ref.provider, String(ref.pr_id), ref.url);
-  return render("stages/implement.md", {
-    provider: ref.provider,
-    pr_id: String(ref.pr_id),
-    url: ref.url,
-    read_cmd: readCmd,
-  });
-}
-
 /**
  * The warm `/implement`. It still NEVER performs the cross-worktree plan→implement
  * transition (that is structurally the Python cold door's job — no extension session API can change

package/extension/{factories → pi/v1}/objective.ts

@@ -22,9 +22,11 @@
 // best-effort and never throw (logged-not-thrown).
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { registerPerkCommand } from "../substrate/command.ts";
-import { loadPerkConfig } from "../substrate/config.ts";
-import { branchOf, rebuildWorkflowState, WORKFLOW_STATE_TYPE } from "../substrate/workflowState.ts";
+import { openBranchWorkflowSession } from "../../session/branchWorkflowSession.ts";
+import { type ColdJson, objectField, runColdDoor, stringField } from "../../substrate/coldDoor.ts";
+import { registerPerkCommand } from "../../substrate/command.ts";
+import { loadPerkConfig } from "../../substrate/config.ts";
+import { type BranchEntry, branchOf, WORKFLOW_STATE_TYPE } from "../../substrate/workflowState.ts";
 import {
   formatBudgetLine,
   MARK_OBJECTIVE,
@@ -32,7 +34,7 @@ import {
   type PerkStatusHandle,
   registerTranscriptRenderer,
   report,
-} from "../surfaces/surfaces.ts";
+} from "../../surfaces/surfaces.ts";
 
 /** The dedicated budget/activation session entry type (kept off `perk:workflow-state`). */
 export const OBJECTIVE_BUDGET_TYPE = "perk:objective-budget";
@@ -41,10 +43,7 @@ export const OBJECTIVE_BUDGET_TYPE = "perk:objective-budget";
 export const DEFAULT_COMPACT_THRESHOLD = 0.8;
 
 /** A branch entry as seen by the budget scan: a custom marker OR an assistant message. */
-interface ScanEntry {
-  type: string;
-  customType?: string;
-  data?: { objective_id?: string; activated_at?: string };
+interface ScanEntry extends BranchEntry {
   message?: { role?: string; usage?: { input?: number; output?: number } };
 }
 
@@ -108,7 +107,7 @@ export function rebuildBudget(branch: readonly ScanEntry[], now: number): Budget
 
 /** True when context usage has crossed the compaction threshold (pure; tolerant of unknowns). */
 export function shouldCompact(
-  usage: { percent: number | null; tokens: number | null } | undefined,
+  usage: { percent: number | null } | undefined,
   threshold: number,
 ): boolean {
   if (!usage || usage.percent === null) return false;
@@ -118,16 +117,14 @@ export function shouldCompact(
 // --- the controller -----------------------------------------------------------------------------
 
 function scanBranchOf(ctx: ExtensionContext): ScanEntry[] {
-  return ctx.sessionManager.getBranch() as unknown as ScanEntry[];
+  // `branchOf` owns the typed accessor; the scan only ADDS the optional assistant-message
+  // shape, so no round-trip through `unknown` is needed (field presence is checked locally).
+  return branchOf(ctx) as ScanEntry[];
 }
 
-function activeObjective(ctx: ExtensionContext): string | null {
-  try {
-    const state = rebuildWorkflowState(branchOf(ctx));
-    return state.active_objective ?? null;
-  } catch {
-    return null;
-  }
+/** The rebuilt `active_objective`, read through the session seam (fail-open null). */
+function activeObjective(pi: ExtensionAPI, ctx: ExtensionContext): string | null {
+  return openBranchWorkflowSession(pi, ctx).activeObjective();
 }
 
 /**
@@ -135,10 +132,10 @@ function activeObjective(ctx: ExtensionContext): string | null {
  * widget is retired; the value carries id + tokens + elapsed). Headless-safe:
  * the handle no-ops without UI.
  */
-function renderStatus(ctx: ExtensionContext, status: PerkStatusHandle): void {
+function renderStatus(pi: ExtensionAPI, ctx: ExtensionContext, status: PerkStatusHandle): void {
   if (!ctx.hasUI) return;
   try {
-    const active = activeObjective(ctx);
+    const active = activeObjective(pi, ctx);
     if (active === null) {
       status.set(ctx, undefined);
       return;
@@ -164,7 +161,7 @@ function objectiveCommand(
   const arg = args.trim();
   try {
     if (arg === "") {
-      const active = activeObjective(ctx);
+      const active = activeObjective(pi, ctx);
       const budget = rebuildBudget(scanBranchOf(ctx), Date.now());
       const message =
         active === null
@@ -176,18 +173,20 @@ function objectiveCommand(
 
     if (arg === "clear") {
       pi.appendEntry(WORKFLOW_STATE_TYPE, { active_objective: null });
-      renderStatus(ctx, status);
+      renderStatus(pi, ctx, status);
       report(ctx, "objective", "info", "cleared the active objective.");
       return;
     }
 
-    // Activate: set the LWW field + seed a fresh budget activation marker.
+    // Activate: set the LWW field + seed a fresh budget activation marker. This command path's
+    // `active_objective` write is a raw LWW append WITHOUT the session seam's strict read-back
+    // (the seam path in `saveObjective` verifies; this one stays best-effort — stated honestly).
     pi.appendEntry(WORKFLOW_STATE_TYPE, { active_objective: arg });
     pi.appendEntry(OBJECTIVE_BUDGET_TYPE, {
       objective_id: arg,
       activated_at: new Date().toISOString(),
     });
-    renderStatus(ctx, status);
+    renderStatus(pi, ctx, status);
     report(ctx, "objective", "info", `activated objective ${arg} (budget tracking started).`);
   } catch (error) {
     reportError(ctx, `command failed: ${error}`);
@@ -195,37 +194,58 @@ function objectiveCommand(
 }
 
 /**
- * Register the objective substrate: `/objective` command, budget accounting (session_start /
- * session_tree / agent_settled), and threshold compaction (turn_end). All inert when no objective
- * is active; never throws.
+ * Fetch the objective's URL via `perk objective show <id> --json` (reading `objective.url`).
+ * Lenient: returns "" on any failure / missing url — `runColdDoor` is a soft-result seam and
+ * never throws (the seed prompt's step-1 `perk objective show <id>` step surfaces the URL
+ * anyway). Only called for the linear backend (github needs no clause → no fetch). Exported for
+ * the warm drives that compose the same backend-aware read clause (the ready-time reconcile
+ * drive in `pi/v1/delivery/ready.ts`).
+ */
+export async function fetchObjectiveUrl(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  objectiveId: string,
+): Promise<string> {
+  const r = await runColdDoor<string>(pi, ctx, ["objective", "show", objectiveId, "--json"], {
+    label: "perk objective show",
+    decode: (payload: ColdJson) =>
+      stringField(objectField(payload, "objective") ?? {}, "url") ?? "",
+  });
+  return r.ok ? r.data : "";
+}
+
+/**
+ * Install the objective substrate bindings: `/objective` command, budget accounting
+ * (session_start / session_tree / agent_settled), and threshold compaction (turn_end). All
+ * inert when no objective is active; never throws.
  */
-export function registerObjective(pi: ExtensionAPI, status: PerkStatusHandle): void {
+export function installObjectiveBindings(pi: ExtensionAPI, status: PerkStatusHandle): void {
   // Transcript marker for `perk:objective-budget` activations (audit §2.3): renderer body in
   // surfaces.ts, registration = wiring, feature-detect inside the seam (pre-0.80.4 hosts stay
   // inert). Also covers objectiveSave.ts's appends — registration is per entry TYPE.
   registerTranscriptRenderer(pi, OBJECTIVE_BUDGET_TYPE, objectiveBudgetEntryRenderer);
 
   pi.on("session_start", async (_event, ctx) => {
-    renderStatus(ctx, status);
+    renderStatus(pi, ctx, status);
   });
 
   pi.on("session_tree", async (_event, ctx) => {
-    renderStatus(ctx, status);
+    renderStatus(pi, ctx, status);
   });
 
   pi.on("agent_settled", async (_event, ctx) => {
     // Recompute the budget after each settled run (stateless rebuild from the branch).
-    renderStatus(ctx, status);
+    renderStatus(pi, ctx, status);
   });
 
   pi.on("turn_end", async (_event, ctx) => {
     try {
-      if (activeObjective(ctx) === null) return; // inert unless an objective is active
+      if (activeObjective(pi, ctx) === null) return; // inert unless an objective is active
       const threshold =
         loadPerkConfig(ctx.cwd).objectiveCompactThreshold ?? DEFAULT_COMPACT_THRESHOLD;
       const usage = ctx.getContextUsage();
       if (!shouldCompact(usage, threshold)) return;
-      const active = activeObjective(ctx);
+      const active = activeObjective(pi, ctx);
       ctx.compact({
         customInstructions:
           `Preserve the active perk objective (${active}) and its budget context. ` +
@@ -234,7 +254,7 @@ export function registerObjective(pi: ExtensionAPI, status: PerkStatusHandle): v
           console.error(`perk: objective compaction failed — ${error}`);
         },
         onComplete: () => {
-          renderStatus(ctx, status);
+          renderStatus(pi, ctx, status);
         },
       });
     } catch (error) {