@mgiles/perk 2.3.0 → 3.0.0

package/extension/doors/learn.ts

@@ -53,7 +53,7 @@ import {
   stringField,
 } from "../substrate/coldDoor.ts";
 import { registerPerkCommand } from "../substrate/command.ts";
-import { loadPerkConfig } from "../substrate/config.ts";
+import { subagentModel } from "../substrate/config.ts";
 import { render } from "../substrate/prompts.ts";
 import { failFor, ok, type Result } from "../substrate/result.ts";
 import { arrayParam, paramsOf, stringParam } from "../substrate/toolParams.ts";
@@ -65,7 +65,11 @@ import {
   type LearnAngleSelection,
   runLearnWave,
 } from "../waves/learnWave.ts";
-import type { WaveAdapter } from "../waves/reportWave.ts";
+import {
+  toAttemptReceipt,
+  type WaveAdapter,
+  type WaveAttemptReceipt,
+} from "../waves/reportWave.ts";
 import { createRpcWaveAdapter } from "../waves/rpcAdapter.ts";
 import { planReadInstruction } from "./lifecycleGates.ts";
 
@@ -301,9 +305,12 @@ export function learnOrchestrateGuidance(opts: {
 export interface LearnWaveOk {
   reports: { angle: string; report: unknown }[];
   skipped: { angle: string; reason: string; detail: string }[];
+  /** The single launch's output-free attempt receipt (observability only — details, not prose). */
+  attempts: WaveAttemptReceipt[];
 }
 
-export type LearnWaveResult = Result<LearnWaveOk>;
+/** The fail arm retains any receipt known before the failure (the `failFor` extras hook). */
+export type LearnWaveResult = Result<LearnWaveOk, { attempts: WaveAttemptReceipt[] }>;
 
 /**
  * The `run_learn_wave` execute core, extracted for testability with the adapter as the injected
@@ -326,7 +333,7 @@ export async function executeLearnWave(
     signal?: AbortSignal;
   },
 ): Promise<LearnWaveResult> {
-  const fail = failFor(target, "run_learn_wave");
+  const fail = failFor<{ attempts: WaveAttemptReceipt[] }>(target, "run_learn_wave");
   const manifestPath = join(opts.bundleDir, "manifest.json");
   const result = await runLearnWave(
     adapter,
@@ -338,12 +345,23 @@ export async function executeLearnWave(
     },
     opts.signal,
   );
+  // The learn flow has no retry — ONE attempt over the validated selection.
+  const attempts = [
+    toAttemptReceipt(
+      "learn",
+      1,
+      opts.selections.map((s) => s.angle),
+      result.receipt,
+    ),
+  ];
 
   if (!result.complete) {
     const waveFailure = result.failures.find((f) => f.key === null);
+    // The receipt known before the failure rides the fail details (never the prose).
     return fail(
       waveFailure?.detail ?? "the analyst wave failed without detail",
       waveFailure?.reason ?? "run-failed",
+      { attempts },
     );
   }
 
@@ -368,7 +386,7 @@ export async function executeLearnWave(
         .join("\n")}`,
     );
   }
-  return ok(parts.join("\n\n"), { reports, skipped });
+  return ok(parts.join("\n\n"), { reports, skipped, attempts });
 }
 
 const WAVE_TOOL_GUIDELINES = [
@@ -533,7 +551,7 @@ export function registerLearn(pi: ExtensionAPI): void {
       }
       // Model resolution lives here (not in the guidance): `[models.subagents] learn-analyst`
       // rides the wave as the workflow-level `model` default.
-      const model = loadPerkConfig(ctx.cwd).subagents["learn-analyst"];
+      const model = subagentModel(ctx.cwd, "learn-analyst");
       return executeLearnWave(createRpcWaveAdapter(pi.events), ctx, {
         bundleDir,
         selections,

package/extension/doors/learnFactory.ts

@@ -6,21 +6,27 @@
 // Each door DELEGATES the gather to the Python plane (`perk learn <kind> --gather --json` via the
 // shared cold-door client `runColdDoor` — gate-safe, not subject to the read-only bash allowlist),
 // decodes `{ inbox_path, learn_numbers }`, then injects the factory guidance via
-// `pi.sendUserMessage` so the model reads the inbox, authors the plan, and saves it. The save is
-// surface-dependent (the seed spells this out): where `plan_save` is active (a read-write session,
-// the warm doors' usual host) the model passes `consumed_learn` explicitly — load-bearing here,
-// because the warm gather is side-effect-free and writes NO handoff carrier; in a gated read-only
-// session `plan_save` is hidden (toolGating.ts), so the save lands review-first via `plan_review`
-// and the COLD doors' handoff carrier supplies `consumed_learn`. No model tool is registered here.
+// `pi.sendUserMessage` so the model reads the inbox, authors the plan, and saves it. The warm
+// gather is side-effect-free and writes NO handoff carrier, so `plan_save` passing
+// `consumed_learn` explicitly is the ONLY surface that can carry the consumed numbers here — the
+// interactive host guard (contracts.md §8.2) enforces it: an interactive session where the
+// `plan_save` tool is not currently active (`pi.getActiveTools()` — the authority, reflecting the
+// read-only gate, worktree stage scoping, AND foreign providers' `setActiveTools` restrictions
+// that write no perk workflow-state) is refused BEFORE the gather, pointing at the cold door
+// (`perk learn docs` / `perk learn code`), whose handoff carrier supplies `consumed_learn` on the
+// review-first save path. Workflow-state only flavors the refusal message, never decides it. No
+// model tool is registered here.
 //
 // Headless-safe: rich UI is guarded by `ctx.hasUI`; without a UI it logs to stderr and returns
-// (the gather still runs so the inbox is materialized, but no turn is driven).
+// (the gather still runs so the inbox is materialized, but no turn is driven — the save hazard
+// cannot occur, so the guard is interactive-only).
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { bindingSuffix } from "../substrate/bindingDelivery.ts";
 import { type ColdJson, runColdDoor, stringField } from "../substrate/coldDoor.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";
 
 /**
@@ -106,6 +112,26 @@ export function registerLearnFactoryDoor(pi: ExtensionAPI, kind: LearnFactoryDoo
   registerPerkCommand(pi, kind.name, {
     description: kind.description,
     handler: async (_args, ctx: ExtensionContext) => {
+      // The interactive host guard (see the header): refuse BEFORE the gather when `plan_save`
+      // is not currently active — `pi.getActiveTools()` is the authoritative predicate;
+      // workflow-state only flavors the message (it cannot see foreign restrictions).
+      if (ctx.hasUI && !pi.getActiveTools().includes("plan_save")) {
+        const state = rebuildWorkflowState(branchOf(ctx));
+        const why =
+          state.mode === "read-only"
+            ? "this session is read-only"
+            : state.stage !== undefined
+              ? `this session is scoped to the ${state.stage} stage`
+              : "a provider restriction hides it";
+        report(
+          ctx,
+          kind.name,
+          "error",
+          `the plan_save tool is not active here (${why}), so this session cannot save a plan ` +
+            `carrying consumed_learn — use the cold door instead: perk learn ${kind.subcommand}.`,
+        );
+        return;
+      }
       // Report-only door (no Result type): branch on `errorType` directly (the coldDoor header
       // convention). A clean empty inbox exits non-zero with error_type=no_learn_issues — the
       // client's envelope-aware arm surfaces it gently.

package/extension/doors/lifecycleGates.ts

@@ -81,7 +81,7 @@ export function planReadInstruction(provider: string, prId: string, url: string)
  * 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
- * markers:" tail (the prior shorter near-copy omission is removed).
+ * 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);