@mgiles/perk 3.2.0 → 3.3.0

package/extension/pi/v1/lifecycleGates.ts

@@ -0,0 +1,127 @@
+// 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
+// pi.exec("git",["status","--porcelain"],{cwd}) resolves the session cwd.
+
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+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).";
+
+/** 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;
+}
+
+/**
+ * The shared dirty-repo guard for switch/fork. Allows (returns undefined) outside a workflow or on
+ * a clean tree; cancels with a loud, fail-safe-headless message on a dirty tree in a workflow. If
+ * `git status` itself fails (e.g. not a repo) we allow — this is a hygiene guard, not a validator.
+ */
+async function guardTransition(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+): Promise<{ cancel: true } | undefined> {
+  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 (!dirty) return undefined;
+  report(ctx, "lifecycle", "warning", DIRTY_MESSAGE); // fail-safe-headless: loud, still cancels
+  return { cancel: true };
+}
+
+/**
+ * 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
+ * cwd). Outside an impl context it refuses and points at `perk implement`. INSIDE an active
+ * impl worktree (read-write + a linked plan-ref) it offers the in-process twin of the cold door: a
+ * lossless `ctx.newSession` fresh-context handoff seeded with the plan-read priming (the plan, and
+ * the worktree's materialized plan-ref, are the durable state — model-visible output stays capped).
+ * Dirty-tree hygiene is gated manually here (belt-and-suspenders: `newSession` is a session-replace,
+ * not a fork/switch, so it may bypass the `session_before_*` gate — we refuse on a dirty tree
+ * either way), fail-safe-headless.
+ */
+function registerImplementGuard(pi: ExtensionAPI): void {
+  registerPerkCommand(pi, "implement", {
+    description:
+      "Refresh implement context (in-worktree handoff); cross-worktree is `perk implement`.",
+    handler: async (_args, ctx) => {
+      const state = rebuildWorkflowState(branchOf(ctx));
+      const ref = state.active_plan_ref;
+      const inImpl = state.mode === "read-write" && ref != null;
+      if (!inImpl) {
+        report(
+          ctx,
+          "implement",
+          "warning",
+          "/implement is cold-only here — run `perk implement` from a shell for fresh context.",
+        );
+        return;
+      }
+
+      // Dirty-tree gate (manual; see the doc comment). Refuse the handoff with uncommitted work.
+      const status = await pi.exec("git", ["status", "--porcelain"], { cwd: ctx.cwd });
+      if (status.code === 0 && status.stdout.trim().length > 0) {
+        report(ctx, "implement", "warning", HANDOFF_DIRTY_MESSAGE);
+        return;
+      }
+
+      const commandCtx = ctx as ExtensionCommandContext;
+      if (typeof commandCtx.newSession !== "function") {
+        report(
+          ctx,
+          "implement",
+          "warning",
+          "a fresh-context /implement handoff needs an interactive session.",
+        );
+        return;
+      }
+
+      const prompt = implementHandoffPrompt(ref as PlanRef);
+      const parentSession = ctx.sessionManager.getSessionFile() ?? undefined;
+      const result = await commandCtx.newSession({
+        parentSession,
+        withSession: async (fresh) => {
+          await fresh.sendUserMessage(prompt);
+        },
+      });
+
+      // Verify + cap model-visible output (the full state lives in the worktree + the plan issue).
+      if (result.cancelled) {
+        report(ctx, "implement", "info", "/implement handoff cancelled — staying in this session.");
+        return;
+      }
+      report(
+        ctx,
+        "implement",
+        "info",
+        `fresh implement session started for plan #${(ref as PlanRef).pr_id} — the plan is carried forward, not summarized.`,
+      );
+    },
+  });
+}
+
+/** Register the dirty-repo lifecycle gate (switch + fork) and the guard-only `/implement`. */
+export function registerLifecycleGates(pi: ExtensionAPI): void {
+  pi.on("session_before_fork", async (_event, ctx) => guardTransition(pi, ctx));
+  pi.on("session_before_switch", async (_event, ctx) => guardTransition(pi, ctx));
+  registerImplementGuard(pi);
+}

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) {