@mgiles/perk 1.0.1 → 1.1.0

package/extension/factories/planMode.ts

@@ -31,6 +31,7 @@
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Key } from "@earendil-works/pi-tui";
+import { registerPerkCommand } from "../substrate/command.ts";
 import { loadPerkConfig } from "../substrate/config.ts";
 import {
   loadProviders,
@@ -82,6 +83,9 @@ When the plan is decision-complete, request a human review:
 - If the review is APPROVED: the plan is auto-saved and the session leaves read-only. Relay the
   save outcome — do NOT re-dump the plan as a final message and do NOT tell the user to run
   /plan-save.
+- If the review returns IMPLEMENT HERE: the human chose to implement without saving an issue —
+  the session is read-write; implement the plan now in this checkout (edits only; leave git
+  gestures to the user).
 - If plan_review reports it was skipped or unavailable (headless, dismissed, no surface): present
   the complete plan as your final message; the human runs /plan-save (the manual failsafe).`;
 
@@ -150,7 +154,7 @@ export function registerPlanMode(pi: ExtensionAPI, gating: ToolGating): void {
     }
   }
 
-  pi.registerCommand("plan", {
+  registerPerkCommand(pi, "plan", {
     description: "Toggle perk plan mode (read-only exploration + plan authoring).",
     handler: async (_args, ctx) => toggle(ctx),
   });

package/extension/factories/planReview.ts

@@ -6,8 +6,10 @@
 // (`runFirstPartyReview`): display the draft in pi's built-in `ctx.ui.editor` dialog (scrollable,
 // Ctrl+G opens the user's external $EDITOR), write optional human edits back to the draft via
 // `writePlanDraft` BEFORE the verdict (reviewed bytes == artifact bytes == saved bytes — a failed
-// write-back ABORTS the review fail-open, nothing saved), then a 3-option approve/deny/skip
-// `ctx.ui.select` verdict, with deny feedback via a second editor dialog.
+// write-back ABORTS the review fail-open, nothing saved), then an approve/deny/skip
+// `ctx.ui.select` verdict — on the plan arm with a 4th "Implement here — no issue saved" option
+// (§8.23; suppressed in objective-node planning sessions) — with deny feedback via a second
+// editor dialog.
 //
 // REVIEW SEMANTICS (file-first, approval auto-saves): the review runs while the session is still
 // read-only (the tool is in READ_ONLY_TOOLS — review happens before the gate ever comes off).
@@ -51,8 +53,10 @@ import {
 import type { ToolGating } from "../substrate/toolGating.ts";
 import { paramsOf, stringParam } from "../substrate/toolParams.ts";
 import { branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
+import { implementHereExit, implementHereGuidance } from "./implementHere.ts";
 import { OBJECTIVE_AUTHOR_STAGE } from "./objectiveAuthor.ts";
 import { readObjectiveDraft, renderObjectiveDraft } from "./objectiveDraft.ts";
+import { readNodeClaim } from "./objectivePlan.ts";
 import { type ObjectiveApprovalSaveOutcome, objectiveApprovalSave } from "./objectiveSave.ts";
 import { writePlanDraft } from "./planDraft.ts";
 import { type ApprovalSaveOutcome, approvalSave, resolvePlanSource } from "./planSave.ts";
@@ -62,12 +66,15 @@ import { type ApprovalSaveOutcome, approvalSave, resolvePlanSource } from "./pla
 /**
  * The review outcome a backend produces, mapped into a tool result below (also `details.status`).
  * The `dismissed` arm is FIRST-PARTY ONLY (Esc anywhere = fail-open skip; the plannotator bridge
- * never produces it).
+ * never produces it). The `implement-here` arm is first-party PLAN-arm only (the human chose the
+ * no-save exit — contracts.md §8.23); the plannotator bridge never produces it (its browser
+ * envelope returns only approve/deny) and the objective arm never offers it.
  */
 export type ReviewOutcome =
   | { status: "unavailable"; warning: string }
   | { status: "aborted" }
   | { status: "dismissed" }
+  | { status: "implement-here"; reviewId: string }
   | { status: "completed"; approved: boolean; feedback?: string; reviewId: string };
 
 interface ToolResult {
@@ -121,6 +128,20 @@ export function reviewOutcomeResult(outcome: ReviewOutcome): ToolResult {
         ],
         details: { status: "skipped", reason: "dismissed" },
       };
+    case "implement-here":
+      // Defensively unreachable: the execute path routes implement-here to implementHereResult
+      // FIRST (mirror the approved-first routing). Map to a skip shape rather than throwing.
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              "implement-here verdict received outside the execute path — nothing saved; " +
+              "present the complete plan to the user.",
+          },
+        ],
+        details: { status: "skipped", reason: "implement-here" },
+      };
     case "completed": {
       const feedback = outcome.feedback ? `\n\nReviewer feedback:\n${outcome.feedback}` : "";
       const text =
@@ -206,6 +227,36 @@ export function approvedSaveResult(
   };
 }
 
+/**
+ * Map an IMPLEMENT-HERE review outcome + the `implementHereExit` outcome into the model-facing
+ * tool result (exported for the offline tests). NON-terminating on purpose — the model continues
+ * the turn and implements immediately. The text is the implement-here guidance; when the human
+ * edited the plan during review (`edited`), the final reviewed bytes are inlined so the model
+ * implements THOSE, not its stale in-context version (the draft write-back already happened
+ * pre-verdict). Nothing is saved: no issue, no plan-ref, the draft artifact intact (§8.23).
+ */
+export function implementHereResult(
+  outcome: Extract<ReviewOutcome, { status: "implement-here" }>,
+  exit: { gateExited: boolean },
+  opts: { cwd: string; plan: string; edited: boolean },
+): ToolResult {
+  return {
+    content: [
+      {
+        type: "text",
+        text: implementHereGuidance(opts.cwd, { editedPlan: opts.edited ? opts.plan : undefined }),
+      },
+    ],
+    details: {
+      status: "implement-here",
+      saved: false,
+      gateExited: exit.gateExited,
+      reviewId: outcome.reviewId,
+      ...(opts.edited ? { edited: true } : {}),
+    },
+  };
+}
+
 // ----------------------------------------------------------------- the first-party review core
 
 /** The minimal structural `ctx.ui` subset the first-party review needs (the askUser.ts recipe). */
@@ -222,6 +273,8 @@ export interface PlanReviewUI {
 const VERDICT_APPROVE = "Approve — auto-save to GitHub";
 const VERDICT_DENY = "Deny — send feedback for revision";
 const VERDICT_SKIP = "Skip — decide later (manual /plan-save)";
+/** The optional 4th verdict (plan arm only): the no-save implement-here exit (§8.23). */
+const VERDICT_IMPLEMENT_HERE = "Implement here — no issue saved";
 
 const REVIEW_EDITOR_TITLE =
   "Plan review — Enter: continue to verdict · Esc: skip · Ctrl+G: $EDITOR";
@@ -238,7 +291,10 @@ const DENY_FEEDBACK_TITLE = "Deny feedback (optional) — Enter to send";
  * AbortSignal — `signal?.aborted` is checked before each dialog (the aborted arm wins).
  *
  * Presentation options (defaults preserve the plan-path behavior byte-for-byte):
- * `editorTitle`/`verdicts` swap the displayed strings; `viewOnly: true` skips the write-back
+ * `editorTitle`/`verdicts` swap the displayed strings; `verdicts.implementHere`, when present,
+ * makes the verdict select 4 options — approve, implement-here, deny, skip (implement-here sits
+ * adjacent to approve: both are "accept the plan" outcomes) — and selecting it returns the
+ * `implement-here` outcome arm; `viewOnly: true` skips the write-back
  * branch entirely — the editor output is used only for Esc/dismissed detection, `plan` is
  * returned unchanged and `edited` stays false (deny+feedback is the change channel).
  */
@@ -249,7 +305,7 @@ export async function runFirstPartyReview(args: {
   writeDraft(plan: string): boolean;
   signal?: AbortSignal;
   editorTitle?: string;
-  verdicts?: { approve: string; deny: string; skip: string };
+  verdicts?: { approve: string; deny: string; skip: string; implementHere?: string };
   viewOnly?: boolean;
 }): Promise<{ outcome: ReviewOutcome; plan: string; edited: boolean }> {
   const { ui, writeDraft, signal } = args;
@@ -291,15 +347,18 @@ export async function runFirstPartyReview(args: {
   }
 
   if (signal?.aborted) return result({ status: "aborted" });
-  const verdict = await ui.select(
-    "Plan review verdict",
-    [verdicts.approve, verdicts.deny, verdicts.skip],
-    { signal },
-  );
+  const options =
+    verdicts.implementHere === undefined
+      ? [verdicts.approve, verdicts.deny, verdicts.skip]
+      : [verdicts.approve, verdicts.implementHere, verdicts.deny, verdicts.skip];
+  const verdict = await ui.select("Plan review verdict", options, { signal });
   if (signal?.aborted) return result({ status: "aborted" });
   if (verdict === verdicts.approve) {
     return result({ status: "completed", approved: true, reviewId: randomUUID() });
   }
+  if (verdicts.implementHere !== undefined && verdict === verdicts.implementHere) {
+    return result({ status: "implement-here", reviewId: randomUUID() });
+  }
   if (verdict === verdicts.deny) {
     const feedback = await ui.editor(DENY_FEEDBACK_TITLE, "");
     if (signal?.aborted) return result({ status: "aborted" });
@@ -366,6 +425,20 @@ export function objectiveReviewOutcomeResult(outcome: ReviewOutcome): ToolResult
         ],
         details: { status: "skipped", reason: "dismissed", subject: "objective" },
       };
+    case "implement-here":
+      // Defensively unreachable twice over: the objective arm never offers the verdict, and the
+      // execute path routes implement-here first. Map to a skip shape rather than throwing.
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              "implement-here verdict received on the objective path — nothing saved; present " +
+              "the complete objective + structured roadmap to the user.",
+          },
+        ],
+        details: { status: "skipped", reason: "implement-here", subject: "objective" },
+      };
     case "completed": {
       const feedback = outcome.feedback ? `\n\nReviewer feedback:\n${outcome.feedback}` : "";
       return {
@@ -577,17 +650,36 @@ export async function executePlanReview(
   if (isPlannotatorPlanSelected(ctx.cwd)) {
     outcome = await bridge.review(src.plan, sig);
   } else {
+    // The 4th verdict (implement-here, the no-save exit) is offered UNLESS this is an
+    // objective-node planning session — a node-linked plan must save (the node advance and
+    // backlink depend on it), so the claim suppresses it back to the 3-option select.
     const fp = await runFirstPartyReview({
       ui: ctx.ui,
       plan: src.plan,
       writeDraft: (text) => writePlanDraft(pi, ctx, text).details.ok,
       signal: sig,
+      verdicts:
+        readNodeClaim(ctx) === null
+          ? {
+              approve: VERDICT_APPROVE,
+              deny: VERDICT_DENY,
+              skip: VERDICT_SKIP,
+              implementHere: VERDICT_IMPLEMENT_HERE,
+            }
+          : undefined,
     });
     outcome = fp.outcome;
     reviewedPlan = fp.plan;
     edited = fp.edited;
   }
-  // 5. An APPROVED decision (either backend) wires into the approvalSave seam (auto-save → D1a
+  // 5. IMPLEMENT-HERE (first-party only) routes before the generic mapper (mirror the
+  //    approved-first split): gate exit WITHOUT save through the implementHereExit seam → a
+  //    NON-terminating result carrying the implement-now guidance.
+  if (outcome.status === "implement-here") {
+    const exit = implementHereExit(ctx, gating);
+    return implementHereResult(outcome, exit, { cwd: ctx.cwd, plan: reviewedPlan, edited });
+  }
+  // 6. An APPROVED decision (either backend) wires into the approvalSave seam (auto-save → D1a
   //    gate exit → terminating result); everything else maps via reviewOutcomeResult.
   if (outcome.status === "completed" && outcome.approved) {
     const save = await approvalSave(pi, ctx, gating, { reviewedPlan });

package/extension/factories/planSave.ts

@@ -34,8 +34,10 @@ import {
   runColdDoor,
   stringField,
 } from "../substrate/coldDoor.ts";
+import { registerPerkCommand } from "../substrate/command.ts";
 import { failFor, ok, type Result } from "../substrate/result.ts";
 import { readSessionArtifact, type SessionDataCtx } from "../substrate/sessionData.ts";
+import { captureSessionPointer } from "../substrate/sessionPointers.ts";
 import type { ToolGating } from "../substrate/toolGating.ts";
 import { idArrayParam, paramsOf, stringParam } from "../substrate/toolParams.ts";
 import {
@@ -312,6 +314,19 @@ export async function savePlan(
   });
   if (!r.ok) return fail(r.message, r.errorType);
 
+  // Capture the planning session pointer (contracts.md §8.35): this planning run self-keys by its
+  // own run_id into the shared main checkout, so a later/other session can resolve it cross-run.
+  // Best-effort + non-fatal (the carrier warns + returns false; a successful save must stand).
+  // Covers /plan-save, the plan_save tool, and approvalSave (all flow through savePlan).
+  captureSessionPointer({
+    cwd: ctx.cwd,
+    runId,
+    klass: "planning",
+    site: "main",
+    // Optional-chained: best-effort, and some side-session fakes have no getSessionFile.
+    sessionFile: ctx.sessionManager.getSessionFile?.(),
+  });
+
   // Link the live session (turn-3 D4): append iff the rebuilt ref differs, with a strict read-back.
   const ref = r.data.plan_ref;
   if (!planRefsEqual(rebuildWorkflowState(branch()).active_plan_ref ?? null, ref)) {
@@ -552,7 +567,7 @@ export function registerPlanSave(pi: ExtensionAPI, gating: ToolGating): void {
     },
   });
 
-  pi.registerCommand("plan-save", {
+  registerPerkCommand(pi, "plan-save", {
     description:
       "Save the latest proposed plan to GitHub — the manual failsafe for the approval→save flow " +
       "(the read-only → read-write boundary).",

package/extension/index.ts

@@ -16,12 +16,15 @@ import { registerAskUser } from "./doors/askUser.ts";
 import { registerCiExecutor } from "./doors/ciExecutor.ts";
 import { registerLand } from "./doors/land.ts";
 import { registerLearn } from "./doors/learn.ts";
+import { registerLearnCode } from "./doors/learnCode.ts";
 import { registerLearnDocs } from "./doors/learnDocs.ts";
 import { registerLifecycleGates } from "./doors/lifecycleGates.ts";
 import { registerPrReview } from "./doors/prReview.ts";
+import { registerPrReviewLocal } from "./doors/prReviewLocal.ts";
 import { registerReady } from "./doors/ready.ts";
 import { registerSelfcheck } from "./doors/selfcheck.ts";
 import { registerSubmit } from "./doors/submit.ts";
+import { registerImplementHere } from "./factories/implementHere.ts";
 import { registerObjective } from "./factories/objective.ts";
 import { registerObjectiveAuthor } from "./factories/objectiveAuthor.ts";
 import { registerObjectiveDraft } from "./factories/objectiveDraft.ts";
@@ -38,10 +41,12 @@ import {
   readHandoff,
   readPlanRef,
   setMarker,
+  workflowDir,
 } from "./substrate/cache.ts";
 import { loadRegistry, type Registry, stageConsumesPlanRef } from "./substrate/registry.ts";
 import { perkVersion, sharedDir } from "./substrate/resources.ts";
 import { mintRunId } from "./substrate/runId.ts";
+import { captureSessionPointer } from "./substrate/sessionPointers.ts";
 import { registerToolGating } from "./substrate/toolGating.ts";
 import {
   appendWorkflowState,
@@ -69,7 +74,7 @@ function writeT3Sentinel(
   runMode: string | null,
 ): void {
   try {
-    const dir = join(cwd, ".pi", "workflow");
+    const dir = workflowDir(cwd);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     writeFileSync(
       join(dir, ".perk-t3.json"),
@@ -290,6 +295,24 @@ export default function (pi: ExtensionAPI) {
       resolved = { ...resolved, active_plan_ref: linked };
     }
 
+    // Implementation session pointer (contracts.md §8.35): an implement session self-keys its own
+    // session file into the shared main checkout so a later/other session resolves it cross-run.
+    // The headless worker's inner session lands here too (.main); driveStage records the matching
+    // .worker. A forked implement session inherits the parent's launched stage + threads the
+    // inherited parent session id as fork provenance. Best-effort + non-fatal (carrier warns).
+    const implStage =
+      runStage ?? (decision.action === "fork" ? (decision.state.stage ?? null) : null);
+    if (resolved.run_id && implStage === "implement") {
+      captureSessionPointer({
+        cwd: ctx.cwd,
+        runId: resolved.run_id,
+        klass: "implementation",
+        site: "main",
+        sessionFile,
+        parentSessionId: decision.action === "fork" ? (decision.state.pi_session_id ?? null) : null,
+      });
+    }
+
     // Reapply the read-only allowlist from the resolved mode. Fail-closed: if the sync throws,
     // leave the gate as-is (a failed sync never opens it).
     try {
@@ -327,6 +350,7 @@ export default function (pi: ExtensionAPI) {
         identity: `perk v${version}`,
         status: perkStatus,
         getModelId: () => ctx.model?.id ?? null,
+        getThinkingLevel: () => (ctx.model ? pi.getThinkingLevel() : null),
         getContext: () => {
           const usage = ctx.getContextUsage();
           return usage ? { percent: usage.percent, contextWindow: usage.contextWindow } : null;
@@ -337,7 +361,7 @@ export default function (pi: ExtensionAPI) {
 
     if (process.env.PERK_SELFCHECK) {
       try {
-        const dir = join(ctx.cwd, ".pi", "workflow");
+        const dir = workflowDir(ctx.cwd);
         if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
         // The gate sentinel (unchanged — those gates parse this line).
         writeFileSync(
@@ -371,6 +395,11 @@ export default function (pi: ExtensionAPI) {
   // a successful command-path save exits read-only mode (the read-only → read-write boundary).
   registerPlanSave(pi, gating);
 
+  // The `/implement-here` command: the human-only no-save exit from plan mode (§8.23) —
+  // implement the reviewed draft in-session, no issue created. Composes the gate through the
+  // implementHereExit seam; no model tool is registered (machine-unreachable by construction).
+  registerImplementHere(pi, gating);
+
   // The `plan_draft` working-draft file tool. Registered in the factory so it
   // exists before the gate snapshots tools; its name is in READ_ONLY_TOOLS (the structural
   // session-data carve-out), so it survives plan mode.
@@ -406,6 +435,10 @@ export default function (pi: ExtensionAPI) {
   // POSTS its review to the PR (the deliberate departure from /address's read-only-child rule).
   registerPrReview(pi);
 
+  // The warm `/pr-review-local` command: open the plannotator browser code review on the active
+  // PR (URL filled in implicitly) by bridging to plannotator's published `code-review` event.
+  registerPrReviewLocal(pi);
+
   // The read-only CI executor: the `run_ci` tool + `/ci` command + `--allow-project-ci`
   // flag. Runs the project's `[ci]` named checks deterministically and reports (never fixes/loops).
   registerCiExecutor(pi);
@@ -447,9 +480,15 @@ export default function (pi: ExtensionAPI) {
   // factory guidance so the model authors a docs/learned consolidation plan (no model tool).
   registerLearnDocs(pi);
 
+  // The learn-code plan factory's warm surface: the `/learn-code` command gathers pre-stamped
+  // SHOULD_BE_CODE perk:learn issues into an inbox (via the `perk learn code --gather` cold door)
+  // and injects the factory guidance so the model authors a code-routing plan (no model tool).
+  registerLearnCode(pi);
+
   // Warm-door skill-binding delivery: Mechanism A's `before_agent_start` injection of
   // the launched stage's user-originated bindings (+ the stale-context strip). Mechanism B (the
-  // `command:<id>` suffix) is wired into the `/objective-reconcile` + `/learn-docs` guidance.
+  // `command:<id>` suffix) is wired into the `/objective-reconcile` + `/learn-docs` +
+  // `/learn-code` guidance.
   registerBindingDelivery(pi);
 
   // `/perk-selfcheck` — the session-wiring verifier (turned from a liveness ping into a real check

package/extension/substrate/bindings.ts

@@ -74,7 +74,7 @@ export function loadDefaultBindings(): SkillBinding[] {
 }
 
 /**
- * Parse `.pi/perk.toml` `[[bindings]]` rows (string tables) into `SkillBinding`s. Tolerant like
+ * Parse `.perk/config.toml` `[[bindings]]` rows (string tables) into `SkillBinding`s. Tolerant like
  * the YAML reader: absent/ill-typed fields become empty strings so the *resolver* reports them.
  */
 export function parseUserBindings(rows: Array<Record<string, string>>): SkillBinding[] {

package/extension/substrate/cache.ts

@@ -1,4 +1,4 @@
-// `.pi/workflow/` cache-tier I/O — the TS twin of perk/state/cache.py (contracts.md §8.1).
+// `.perk/workflow/` cache-tier I/O — the TS twin of perk/state/cache.py (contracts.md §8.1).
 //
 // Both planes read and write the SAME files; the cross-plane contract is the *files*, not a
 // shared module. State-tiering primitives only — no workflow semantics. Imports use no
@@ -18,7 +18,7 @@ export interface Handoff {
 }
 
 export function workflowDir(cwd: string): string {
-  return join(cwd, ".pi", "workflow");
+  return join(cwd, ".perk", "workflow");
 }
 
 // --- handoff -----------------------------------------------------------------------------

package/extension/substrate/command.ts

@@ -0,0 +1,25 @@
+// The single chokepoint that gives every perk command a uniform, immediate "running…"
+// acknowledgement at entry. pi does not echo the invoked command and handlers only report() at the
+// end, so without this a command's async work (cold-door subprocess calls, GitHub round-trips) is
+// dead air between Enter and completion. registerPerkCommand wraps the handler to emit one transient
+// entry toast through the headless-safe report() seam (no cleanup state, headless-fail-safe for
+// free) before awaiting the original handler. The toast fires synchronously before the first await,
+// so it lands before any cold-door work, sendUserMessage drive, or gate transition; the wrapper does
+// not try/catch, so errors propagate exactly as before.
+
+import type { ExtensionAPI, RegisteredCommand } from "@earendil-works/pi-coding-agent";
+import { report } from "../surfaces/report.ts";
+
+export function registerPerkCommand(
+  pi: ExtensionAPI,
+  name: string,
+  options: Omit<RegisteredCommand, "name" | "sourceInfo">,
+): void {
+  pi.registerCommand(name, {
+    ...options,
+    handler: async (args, ctx) => {
+      report(ctx, name, "info", "running…");
+      await options.handler(args, ctx);
+    },
+  });
+}

package/extension/substrate/config.ts

@@ -1,5 +1,5 @@
 // The minimal TS config port. Mirrors `perk/substrate/config.py`'s overlay: read
-// `.pi/perk.toml` (committed) overlaid by `.pi/perk.local.toml` (gitignored, local wins). The only
+// `.perk/config.toml` (committed) overlaid by `.perk/local.toml` (gitignored, local wins). The only
 // setting consumed today is an optional `[workflow]` plan-authoring addendum, appended into the
 // `perk:plan-context` injection (extension/factories/planMode.ts) when present.
 //
@@ -10,11 +10,8 @@
 // Dynamic `resources_discover` skill/prompt contribution is a flagged follow-up, not built here.
 
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
 import { parseUserBindings, type SkillBinding } from "./bindings.ts";
-
-const CONFIG_FILENAME = "perk.toml";
-const LOCAL_CONFIG_FILENAME = "perk.local.toml";
+import { configFile, localConfigFile } from "./paths.ts";
 
 /**
  * One configured CI check (a `[[ci]]` array-of-tables row). `name`/`command` are required
@@ -39,7 +36,8 @@ export interface PerkConfig {
   ci: CiCheck[];
   /**
    * The agent-keyed `[subagents]` table: a per-agent model override for each perk-owned
-   * project agent (`pr-reviewer`, `review-classifier`, `objective-explorer`). Each configured
+   * project agent (`pr-reviewer`, `review-classifier`, `objective-explorer`, `conflict-resolver`,
+   * `learn-analyst`). Each configured
    * value is injected as a per-call inline `model` override on that agent's `subagent` spawn; when
    * a key is absent the agent's frontmatter `model` (in `.pi/agents/<name>.md`) is the default.
    * (`subagents.agentOverrides` does NOT reach project agents — `pi-subagents`'
@@ -51,6 +49,7 @@ export interface PerkConfig {
     "review-classifier"?: string;
     "objective-explorer"?: string;
     "conflict-resolver"?: string;
+    "learn-analyst"?: string;
   };
   /**
    * Optional `[objective] compact_threshold` — the context-usage fraction (0,1] that triggers
@@ -210,12 +209,11 @@ function overlay(base: TomlSubset, over: TomlSubset): TomlSubset {
   return { tables, arrays };
 }
 
-/** Load `.pi/perk.toml` overlaid by `.pi/perk.local.toml` from `cwd` (mirror of perk/substrate/config.py). */
+/** Load `.perk/config.toml` overlaid by `.perk/local.toml` from `cwd` (mirror of perk/substrate/config.py). */
 export function loadPerkConfig(cwd: string): PerkConfig {
-  const piDir = join(cwd, ".pi");
   let merged: TomlSubset = emptySubset();
-  for (const name of [CONFIG_FILENAME, LOCAL_CONFIG_FILENAME]) {
-    merged = overlay(merged, readTomlFile(join(piDir, name)));
+  for (const file of [configFile(cwd), localConfigFile(cwd)]) {
+    merged = overlay(merged, readTomlFile(file));
   }
 
   const planAuthoring = merged.tables.workflow?.plan_authoring;
@@ -263,6 +261,7 @@ const SUBAGENT_KEYS = [
   "review-classifier",
   "objective-explorer",
   "conflict-resolver",
+  "learn-analyst",
 ] as const;
 
 /**
@@ -320,16 +319,16 @@ export const GITHUB_ISSUE_BACKEND_ID: IssueBackendId = "github";
 /**
  * The fail-safe TS mirror of the issue-backend selection.
  *
- * Reads ONLY committed `.pi/perk.toml` — deliberately not `loadPerkConfig`'s overlay, mirroring
+ * Reads ONLY committed `.perk/config.toml` — deliberately not `loadPerkConfig`'s overlay, mirroring
  * the Python committed-only read (the backend decides where canonical durable state is written;
- * a per-user `perk.local.toml` override would fragment the canonical store). Python
+ * a per-user `.perk/local.toml` override would fragment the canonical store). Python
  * (`perk/backends/issues.py::resolve_issue_backend_id`) is the AUTHORITATIVE validator and **raises** on
  * "linear"/unknown; this mirror is fail-safe (absence/unknown/any error → `"github"`) because
  * the TS plane only renders prompts — it never writes canonical issues.
  */
 export function resolveIssueBackendId(cwd: string): IssueBackendId {
   try {
-    const committed = readTomlFile(join(cwd, ".pi", CONFIG_FILENAME));
+    const committed = readTomlFile(configFile(cwd));
     const backend = committed.tables.issues?.backend;
     if (backend === "github" || backend === "linear") return backend;
     return GITHUB_ISSUE_BACKEND_ID;

package/extension/substrate/consoleCapture.ts

@@ -0,0 +1,90 @@
+// A small, pure swap of the global `console.error` so in-process chatter can be re-routed through a
+// TUI-safe sink while a background task runs. plannotator's browser code-review setup writes
+// progress straight to `process.stderr` via plain `console.error(...)` (fetching the PR, creating
+// the local checkout, …); those raw writes bypass pi's managed rendering and paint over the input
+// box. While the request is in flight we install a replacement that forwards each captured line to
+// an injected sink (perk routes it through `report()`), then restore the original.
+//
+// Restore is debounce-driven: setup emits a burst of lines then goes quiet once the browser is up,
+// so we restore after `quietMs` with no new line (self-adjusts to the variable several-second
+// setup, no fixed-duration guess). A `finally` backstop in the caller restores too; `restore()` is
+// idempotent and only reassigns `console.error` when our replacement is still installed, so an
+// accidental overlap with a newer patcher is safe rather than clobbering. The replacement is inert
+// once restored (a stale reference delegates to the original) and re-entrancy-safe (a console.error
+// from inside the sink delegates to the original instead of recursing).
+
+export type ConsoleErrorSink = (line: string) => void;
+
+export interface ConsoleErrorInterceptor {
+  restore(): void;
+}
+
+interface InterceptOptions {
+  quietMs: number;
+  /** Injectable purely so the unit test drives a deterministic fake clock. */
+  schedule?: (fn: () => void, ms: number) => unknown;
+  clearScheduled?: (handle: unknown) => void;
+}
+
+/**
+ * Swap `console.error` so captured lines reach `sink` (joined with a space for multi-arg calls,
+ * mirroring plannotator's occasional 2-arg `console.error`). Returns an interceptor whose
+ * `restore()` reinstates the original. The original is also restored automatically once no captured
+ * line has arrived for `quietMs`.
+ */
+export function interceptConsoleError(
+  sink: ConsoleErrorSink,
+  opts: InterceptOptions,
+): ConsoleErrorInterceptor {
+  const schedule = opts.schedule ?? ((fn, ms) => globalThis.setTimeout(fn, ms));
+  const clearScheduled =
+    opts.clearScheduled ??
+    ((handle) => globalThis.clearTimeout(handle as ReturnType<typeof setTimeout>));
+
+  const original = console.error;
+  let restored = false;
+  let active = false;
+  let handle: unknown;
+
+  const restore = (): void => {
+    if (handle !== undefined) {
+      clearScheduled(handle);
+      handle = undefined;
+    }
+    if (restored) return;
+    restored = true;
+    // Only reclaim the slot if it is still OUR replacement — never clobber a newer patcher.
+    if (console.error === replacement) console.error = original;
+  };
+
+  const resetQuietTimer = (): void => {
+    if (handle !== undefined) clearScheduled(handle);
+    handle = schedule(restore, opts.quietMs);
+    // Never keep the event loop alive on our account.
+    (handle as { unref?: () => void })?.unref?.();
+  };
+
+  const replacement = (...args: unknown[]): void => {
+    // Once restored, behave as the original — a stale reference still holding `replacement`
+    // (a module that cached console.error, or a wrapping patcher) never re-routes to the sink.
+    // And if the sink (or a downstream report()/ui.notify) ever writes to console.error while we
+    // are installed, delegate to the original instead of recursing into ourselves.
+    if (restored || active) {
+      original(...args);
+      return;
+    }
+    active = true;
+    try {
+      sink(args.map(String).join(" "));
+    } finally {
+      active = false;
+    }
+    resetQuietTimer();
+  };
+
+  console.error = replacement;
+  // Start the timer immediately so a zero-line case (no setup output) still restores after quietMs.
+  resetQuietTimer();
+
+  return { restore };
+}

package/extension/substrate/git.ts

@@ -0,0 +1,34 @@
+// A thin `git`-shelling seam for the extension interior — the TS twin of perk/substrate/git.py.
+//
+// Node builtins only (so it loads cleanly under `node --test`); shells `git` via `execFileSync`,
+// never with a shell. Fail-open by design: every failure degrades to the caller's `cwd` (or null
+// where stated) rather than throwing — the carriers that use this must never wedge a session.
+
+import { execFileSync } from "node:child_process";
+import { isAbsolute, resolve } from "node:path";
+
+/**
+ * The MAIN working tree's root, even when `cwd` is inside a linked worktree — the TS twin of
+ * `main_worktree_root`. Resolves `git rev-parse --git-common-dir` (the shared `.git` of the main
+ * checkout) and returns its parent (equal to the repo root in the main checkout). **Fail-open**:
+ * any failure (not a repo, git missing) returns `cwd`, so a session-pointer write always has a
+ * location — never throws. (Python returns `null` outside a repo; here the single caller wants
+ * `main_worktree_root(cwd) or cwd`, so we fold the fallback in.)
+ */
+export function mainCheckoutRoot(cwd: string): string {
+  let out: string;
+  try {
+    out = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return cwd;
+  }
+  if (out === "") return cwd;
+  // `--git-common-dir` may be relative (to `cwd`) or absolute; resolve then take the parent
+  // (the dir containing `.git` = the main checkout root).
+  const common = isAbsolute(out) ? out : resolve(cwd, out);
+  return resolve(common, "..");
+}