@mgiles/perk 2.3.0 → 3.1.0

package/extension/substrate/workflowState.ts

@@ -33,14 +33,22 @@ export interface WorkflowState {
   mode?: string;
   /** The registry stage id this run is acting on (recorded at cold claim from the handoff). */
   stage?: string;
+  /**
+   * The running @mgiles/perk version stamped when run identity is established (§8.3) —
+   * claim/fork/adopt/mint in session_start. The session-audit vintage layer's exact basis;
+   * omitted when only the perkVersion() failure sentinel is available. Best-effort tier.
+   */
+  perk_version?: string;
   predecessor?: string;
   active_plan_ref?: PlanRef | null;
   active_objective?: string | null;
   last_review_batch?: unknown;
   /**
    * The last `/pr-review` outcome posted via the `post_pr_review` warm tool (§8.3):
-   * `{pr, verdict, angles, comment_count, mode, at}`. Best-effort tier (per-field LWW in
-   * `rebuildWorkflowState`, no rebuild change). The PR comment stays canonical.
+   * `{pr, verdict, angles, covered_angles, comment_count, mode, at}`. After a recorded wave,
+   * `angles` is the authoritative attempted manifest and `covered_angles` is its schema-valid
+   * subset; standalone posts use the caller's `angles` for both. Best-effort tier (per-field LWW
+   * in `rebuildWorkflowState`, no rebuild change). The PR comment stays canonical.
    */
   last_pr_review?: unknown;
   /**
@@ -58,6 +66,15 @@ export interface WorkflowState {
    * node and after a successful node-linked plan save. Best-effort tier.
    */
   objective_node_claim?: { objective: string; node: string } | null;
+  /**
+   * The dream-wave finalized-bundle digest marker (§8.61) — the freshness/integrity authority
+   * the dream-report recovery (§8.63) trusts over the bare run-scratch bundle file. `""` =
+   * invalidated (cleared unconditionally at wave entry BEFORE the stale-bundle removal attempt,
+   * so a failed cleanup leaves prior files behind but recovery refuses them); `sha256:<hex>` =
+   * the digest of the current finalized bundle bytes, set only after a successful finalize
+   * write. Per-field LWW; no rebuild change.
+   */
+  dream_bundle_digest?: string;
   /**
    * The bounded conflict-resolution re-drive counter (§8.3). Incremented each time
    * `/submit` drives the `perk.conflict-resolver` subagent on a definitively-unmergeable PR;
@@ -72,6 +89,8 @@ export interface BranchEntry {
   type: string;
   customType?: string;
   data?: Record<string, unknown>;
+  /** Present on Pi custom_message entries (hidden model-context messages). */
+  content?: unknown;
 }
 
 /** The minimal read-only session surface the branch accessor needs. */
@@ -101,6 +120,35 @@ export function branchCarries(branch: readonly BranchEntry[], needle: string): b
   return branch.some((entry) => JSON.stringify(entry).includes(needle));
 }
 
+/**
+ * The branch entries still represented directly in model context. Before compaction that is the
+ * full branch. After compaction, Pi keeps entries from `firstKeptEntryId` onward plus anything
+ * appended later; historical entries before that cutoff survive only through the summary.
+ * Compaction entries are excluded because text quoted by a summary is not a live custom block.
+ */
+export function activeContextWindow(branch: readonly BranchEntry[]): BranchEntry[] {
+  let latestCompaction = -1;
+  for (let i = branch.length - 1; i >= 0; i--) {
+    if (branch[i]?.type === "compaction") {
+      latestCompaction = i;
+      break;
+    }
+  }
+  if (latestCompaction === -1) return [...branch];
+
+  const firstKeptEntryId = (branch[latestCompaction] as { firstKeptEntryId?: unknown })
+    .firstKeptEntryId;
+  const firstKept =
+    typeof firstKeptEntryId === "string"
+      ? branch.findIndex(
+          (entry, index) =>
+            index < latestCompaction && (entry as { id?: unknown }).id === firstKeptEntryId,
+        )
+      : -1;
+  const start = firstKept === -1 ? latestCompaction + 1 : firstKept;
+  return branch.slice(start).filter((entry) => entry.type !== "compaction");
+}
+
 /**
  * Per-field last-write-wins over the `perk:workflow-state` custom entries on a branch.
  * Non-perk entries are ignored; `undefined` fields never clobber (but explicit `null` does).

package/extension/surfaces/footerProvider.ts

@@ -1,16 +1,16 @@
-// The footer provider seam (INSTALL-SITE / runtime vacating). The footer is the SECOND interface
-// seam (no durable artifact to bridge), mirroring askuser but with a different vacating mechanism:
+// The footer provider seam (INSTALL-SITE / runtime vacating). The footer is an interface
+// seam (no durable artifact to bridge) with a runtime vacating mechanism:
 // perk installs its own footer (`installPerkFooter`) inside `index.ts`'s `session_start` event
 // handler, so under a foreign `[providers] footer` selection perk simply does NOT call
 // `installPerkFooter` — a runtime guard at that single install site, keyed off `ctx.cwd`. That
 // leaves the foreign footer (`pi-powerline-footer` or `pi-bar`) as the sole footer surface;
-// perk's objective/checkpoints progress still reaches it automatically via the already-publishing
-// composed `perk` `setStatus` slot (both foreign footers render extension statuses), so the
+// perk's objective progress still reaches it automatically via the already-publishing
+// single-value `perk` `setStatus` slot (both foreign footers render extension statuses), so the
 // adapter is vacate-only (`adapter: null`, no shim, no injected context).
 //
 // This module reads config (via `resolveProviders`/`loadPerkConfig`) so it does NOT belong in the
 // dependency-free `surfaces.ts`; it contains no rich-UI calls, so `surfacesGuard.test.ts` passes
-// it cleanly. Mirror of `askUser.ts`'s `resolvedAskUserProviderId` / `isPerkAskUserReferenceSelected`.
+// it cleanly. Mirror of `planMode.ts`'s `resolvedPlanProviderId` / `isPerkPlanReferenceSelected`.
 
 import { loadPerkConfig } from "../substrate/config.ts";
 import {
@@ -22,7 +22,7 @@ import {
 /**
  * The resolved `[providers] footer` selection id for `cwd`. Fail-safe to the perk-footer
  * reference: any load/resolution failure returns the reference id so perk keeps installing its
- * own footer — the default path is the hard guarantee. Mirror of `resolvedAskUserProviderId`: the
+ * own footer — the default path is the hard guarantee. Mirror of `resolvedPlanProviderId`: the
  * catch narrows to genuine file-read/parse failures (the resolver is per-seam fail-open) and is
  * logged, never silent.
  */

package/extension/surfaces/report.ts

@@ -1,20 +1,39 @@
-// The one headless-safe report seam — owns the `perk: <scope> — <message>` prefix, the severity,
-// and the `hasUI ? notify : console.error` routing so callers inherit the headless-fail-safe
-// invariant for free (cf. the `branchOf`/`BranchSource` seam in workflowState.ts).
+// The one terminal-safe report seam — owns the `perk: <scope> — <message>` prefix, the severity,
+// and the projection of complete diagnostics into a managed headline plus an optional durable detail
+// sink (cf. the `branchOf`/`BranchSource` seam in workflowState.ts).
 
 export type Severity = "info" | "warning" | "error";
+export type ReportDetailSink = (text: string, severity: Severity) => void;
 
 /** The minimal headless-aware surface report() needs. `ExtensionContext` satisfies it; tests fake it. */
 export interface ReportTarget {
   hasUI: boolean;
+  mode?: "tui" | "rpc" | "json" | "print";
   ui: { notify(message: string, type?: Severity): void };
 }
 
+const detailSinks = new WeakMap<ReportTarget, ReportDetailSink>();
+const LOGICAL_LINE = /\r\n|\n|\r/;
+const HORIZONTAL_WHITESPACE = /[^\S\r\n]+/g;
+
+/** Attach display-only multiline report detail to this exact context object. */
+export function attachReportDetailSink(target: ReportTarget, sink: ReportDetailSink): void {
+  detailSinks.set(target, sink);
+}
+
+function headlineFor(prefix: string, message: string): string {
+  for (const line of message.split(LOGICAL_LINE)) {
+    const trimmed = line.trim();
+    if (trimmed.length > 0) return `${prefix}${trimmed.replace(HORIZONTAL_WHITESPACE, " ")}`;
+  }
+  return prefix;
+}
+
 /**
- * The single headless-safe report seam. Builds `perk: <scope> — <message>`, notifies the UI when
- * present and otherwise writes to stderr (the headless-fail-safe invariant — callers inherit it for
- * free). Pass { alsoLog: true } to ALSO write to stderr when headful (cold-door failures land in run
- * logs even in a TUI). Returns the prefixed string for reuse (tool-result text, etc.).
+ * Build and return the complete `perk: <scope> — <message>` value. Headless targets receive that
+ * value on stderr. Headful targets receive a managed one-line headline; multiline detail goes to an
+ * attached display-only sink in every non-RPC mode. `{ alsoLog: true }` is narrowly an RPC/headless
+ * diagnostic mirror and never permits raw terminal output in a headful non-RPC context.
  */
 export function report(
   target: ReportTarget,
@@ -23,12 +42,19 @@ export function report(
   message: string,
   opts?: { alsoLog?: boolean },
 ): string {
-  const full = `perk: ${scope} — ${message}`;
-  if (target.hasUI) {
-    target.ui.notify(full, severity);
-    if (opts?.alsoLog) console.error(full);
-  } else {
+  const prefix = `perk: ${scope} — `;
+  const full = `${prefix}${message}`;
+  if (!target.hasUI) {
     console.error(full);
+    return full;
   }
+
+  target.ui.notify(headlineFor(prefix, message), severity);
+  if (target.mode === "rpc") {
+    if (opts?.alsoLog) console.error(full);
+    return full;
+  }
+
+  if (message.split(LOGICAL_LINE).length > 1) detailSinks.get(target)?.(full, severity);
   return full;
 }