@mgiles/perk 1.0.1

package/extension/substrate/workflowState.ts

@@ -0,0 +1,233 @@
+// The `perk:workflow-state` session tier (contracts.md §8.3) — rebuild, claim, fork-derive,
+// and the strict-append seam (appendWorkflowState).
+//
+// Mostly pure, fs-light logic kept separate from the `pi`/`ctx` effects (in index.ts); the
+// strict-append seam touches effects only through structural slices (`EntrySink`, `BranchSource`,
+// `ReportTarget`), so the whole module stays unit-testable under `node --test` with fakes. The
+// reconstruction discipline (scan getBranch on session_start AND session_tree, per-field LWW)
+// and the verified-linkage claim live here.
+
+import { type ReportTarget, report } from "../surfaces/report.ts";
+import { listRunIds, type PlanRef, readHandoff } from "./cache.ts";
+
+export const WORKFLOW_STATE_TYPE = "perk:workflow-state";
+
+/**
+ * A session-artifact provenance pointer (contracts §8.3): the session tier's proof
+ * that a `scratch/runs/<run_id>/data/` file is current for THIS run. Reads validate the
+ * on-disk file against the rebuilt pointer (run_id match + digest match) and refuse otherwise.
+ */
+export interface SessionArtifactPointer {
+  run_id: string;
+  name: string;
+  /** Repo-relative, informational only — validation always re-derives via the seam. */
+  path: string;
+  /** `sha256:<hex>` of the file bytes as read back from disk. */
+  digest: string;
+  at: string; // ISO timestamp
+}
+
+export interface WorkflowState {
+  run_id?: string;
+  pi_session_id?: string;
+  mode?: string;
+  /** The registry stage id this run is acting on (recorded at cold claim from the handoff). */
+  stage?: 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.
+   */
+  last_pr_review?: unknown;
+  /** Session-artifact provenance pointers, keyed by artifact name (§8.3). */
+  session_artifacts?: Record<string, SessionArtifactPointer> | null;
+  /**
+   * The objective node this session has claimed `planning` (§8.3) — the warm
+   * node-link carrier an approval-triggered save recovers from. Written by the `objective_node`
+   * tool on a successful `planning` transition; cleared on a non-planning transition for the same
+   * node and after a successful node-linked plan save. Best-effort tier.
+   */
+  objective_node_claim?: { objective: string; node: string } | null;
+  /**
+   * The bounded conflict-resolution re-drive counter (§8.3). Incremented each time
+   * `/submit` drives the `perk.conflict-resolver` subagent on a definitively-unmergeable PR;
+   * reset to 0 on a clean submit. Best-effort tier (cheaply reconstructable). Per-field LWW in
+   * `rebuildWorkflowState` handles it with no rebuild change.
+   */
+  conflict_resolution_attempts?: number;
+}
+
+/** The structural slice of a session entry that the rebuild cares about. */
+export interface BranchEntry {
+  type: string;
+  customType?: string;
+  data?: Record<string, unknown>;
+}
+
+/** The minimal read-only session surface the branch accessor needs. */
+export interface BranchSource {
+  sessionManager: { getBranch(): unknown[] };
+}
+
+/**
+ * The one typed seam over `sessionManager.getBranch()`. Centralizes the single unavoidable
+ * assertion from the SDK's `SessionEntry[]` (surfaced here as `unknown[]`) to perk's structural
+ * `BranchEntry[]`. The SDK union (whose `CustomEntry.data` is `unknown`) is not assignable to the
+ * structural slice, so the assertion is irreducible — do not "fix" it into a type error.
+ * `ExtensionContext` and the test harness `session` both satisfy `BranchSource`.
+ */
+export function branchOf(source: BranchSource): BranchEntry[] {
+  return source.sessionManager.getBranch() as BranchEntry[];
+}
+
+/**
+ * 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).
+ */
+export function rebuildWorkflowState(entries: readonly BranchEntry[]): WorkflowState {
+  const state: Record<string, unknown> = {};
+  for (const entry of entries) {
+    if (entry.type !== "custom" || entry.customType !== WORKFLOW_STATE_TYPE) continue;
+    for (const [key, value] of Object.entries(entry.data ?? {})) {
+      if (value !== undefined) state[key] = value;
+    }
+  }
+  return state as WorkflowState;
+}
+
+/** The structural append surface the strict-append seam needs; ExtensionAPI satisfies it. */
+export interface EntrySink {
+  appendEntry(customType: string, data?: unknown): void;
+}
+
+/**
+ * The one strict-append seam over `perk:workflow-state` (contracts §8.3 verified-linkage tier):
+ * append → rebuild → compare → report. Loud-but-non-fatal and NEVER throws: a mismatch or a
+ * throwing append/rebuild is reported via the report() seam ({ alsoLog: true }) and returns
+ * false. Idempotence pre-checks ("append iff the rebuilt value differs") stay at call sites.
+ */
+export function appendWorkflowState<K extends keyof WorkflowState>(
+  sink: EntrySink,
+  source: BranchSource & ReportTarget,
+  opts: {
+    /** The entry payload — may carry extra fields beyond the verified one (the claim record). */
+    data: WorkflowState;
+    /** The field verified on read-back. */
+    field: K;
+    /** The value the rebuilt field must equal. */
+    expected: WorkflowState[K];
+    /** report() scope, e.g. "plan-save", "workflow-state linkage error". */
+    scope: string;
+    /** The mismatch message (byte-preserved per site). */
+    failure: string;
+    /** Comparator; default: (a, b) => Object.is(a ?? null, b ?? null). */
+    equals?: (rebuilt: WorkflowState[K] | undefined, expected: WorkflowState[K]) => boolean;
+  },
+): boolean {
+  const equals =
+    opts.equals ??
+    ((a: WorkflowState[K] | undefined, b: WorkflowState[K]) => Object.is(a ?? null, b ?? null));
+  try {
+    sink.appendEntry(WORKFLOW_STATE_TYPE, opts.data);
+    const rebuilt = rebuildWorkflowState(branchOf(source))[opts.field];
+    if (equals(rebuilt, opts.expected)) return true;
+    report(source, opts.scope, "error", opts.failure, { alsoLog: true });
+    return false;
+  } catch (error) {
+    report(source, opts.scope, "error", `${String(opts.field)} append threw — ${String(error)}`, {
+      alsoLog: true,
+    });
+    return false;
+  }
+}
+
+/**
+ * Equality by identity (provider + pr_id) — the plan-ref dedup key. Two refs to
+ * the same plan are equal even if other fields drift; absent compares equal only to absent.
+ */
+export function planRefsEqual(
+  a: PlanRef | null | undefined,
+  b: PlanRef | null | undefined,
+): boolean {
+  if (a === null || a === undefined || b === null || b === undefined) {
+    return (a === null || a === undefined) && (b === null || b === undefined);
+  }
+  return a.provider === b.provider && a.pr_id === b.pr_id;
+}
+
+/**
+ * Derive a fork-child run_id: `<parent>.<n>` where `n` is the max existing sibling + 1
+ * (scanning `scratch/runs/`), else 1.
+ */
+export function deriveForkRunId(parentRunId: string, cwd: string): string {
+  const prefix = `${parentRunId}.`;
+  let max = 0;
+  for (const id of listRunIds(cwd)) {
+    if (!id.startsWith(prefix)) continue;
+    const segment = id.slice(prefix.length).split(".")[0] ?? "";
+    const n = Number.parseInt(segment, 10);
+    if (Number.isInteger(n) && n > max) max = n;
+  }
+  return `${parentRunId}.${max + 1}`;
+}
+
+export type ClaimDecision =
+  | { action: "keep"; source: "session"; state: WorkflowState }
+  | {
+      action: "fork";
+      source: "fork";
+      childRunId: string;
+      parentRunId: string;
+      state: WorkflowState;
+    }
+  | { action: "claim"; source: "env"; runId: string }
+  | { action: "none"; source: "none"; state: WorkflowState };
+
+/**
+ * Decide what `session_start` should do, from the rebuilt state + the current session handle
+ * + the launch env. Reload vs fork is distinguished by the `run_id ↔ pi_session_id` mapping
+ * (NOT `event.reason`, which is "startup" for a headless `pi --fork`): if the branch already
+ * carries a `run_id` whose recorded `pi_session_id` differs from the current session, the id
+ * was inherited across a fork → derive a child; if it matches (or is absent), it's a reload.
+ */
+/**
+ * The registry stage id the launched run is acting on, read from its handoff blob, or null.
+ * Only `claim` (cold) and `keep` (reload) sessions have a settled run whose handoff records a
+ * `stage`; `fork` and `none` carry no launched stage (LWW restores their state instead). The
+ * stage gates whether `session_start` reconciles `cache.plan-ref` into `active_plan_ref`.
+ */
+export function resolveRunStage(decision: ClaimDecision, cwd: string): string | null {
+  const runId =
+    decision.action === "claim"
+      ? decision.runId
+      : decision.action === "keep"
+        ? decision.state.run_id
+        : null;
+  if (runId === undefined || runId === null) return null;
+  const stage = readHandoff(cwd, runId)?.stage;
+  return typeof stage === "string" && stage !== "" ? stage : null;
+}
+
+export function decideClaim(args: {
+  state: WorkflowState;
+  currentSessionId: string | null;
+  envRunId: string | null;
+  cwd: string;
+}): ClaimDecision {
+  const { state, currentSessionId, envRunId, cwd } = args;
+  if (state.run_id !== undefined) {
+    if (state.pi_session_id === undefined || state.pi_session_id === currentSessionId) {
+      return { action: "keep", source: "session", state };
+    }
+    const childRunId = deriveForkRunId(state.run_id, cwd);
+    return { action: "fork", source: "fork", childRunId, parentRunId: state.run_id, state };
+  }
+  if (envRunId !== null && envRunId !== "") {
+    return { action: "claim", source: "env", runId: envRunId };
+  }
+  return { action: "none", source: "none", state };
+}

package/extension/surfaces/footerProvider.ts

@@ -0,0 +1,43 @@
+// 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:
+// 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
+// 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`.
+
+import { loadPerkConfig } from "../substrate/config.ts";
+import {
+  loadProviders,
+  PERK_FOOTER_PROVIDER_ID,
+  resolveProviders,
+} from "../substrate/providers.ts";
+
+/**
+ * The resolved `[providers] footer` selection id for `cwd`. Fail-safe to the perk-footer
+ * reference: any load/resolution failure (corrupt bundled set, etc.) returns the reference id so
+ * perk keeps installing its own footer — the default path is the hard guarantee. Mirror of
+ * `resolvedAskUserProviderId`.
+ */
+export function resolvedFooterProviderId(cwd: string): string {
+  try {
+    return resolveProviders(loadPerkConfig(cwd).providers, loadProviders()).footer.id;
+  } catch {
+    return PERK_FOOTER_PROVIDER_ID;
+  }
+}
+
+/**
+ * Whether perk's own footer reference is the selected footer provider for `cwd`. When a foreign
+ * footer provider is selected via `[providers] footer`, perk vacates `installPerkFooter` so the
+ * foreign footer is the sole footer surface.
+ */
+export function isPerkFooterReferenceSelected(cwd: string): boolean {
+  return resolvedFooterProviderId(cwd) === PERK_FOOTER_PROVIDER_ID;
+}

package/extension/surfaces/report.ts

@@ -0,0 +1,34 @@
+// 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).
+
+export type Severity = "info" | "warning" | "error";
+
+/** The minimal headless-aware surface report() needs. `ExtensionContext` satisfies it; tests fake it. */
+export interface ReportTarget {
+  hasUI: boolean;
+  ui: { notify(message: string, type?: Severity): void };
+}
+
+/**
+ * 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.).
+ */
+export function report(
+  target: ReportTarget,
+  scope: string,
+  severity: Severity,
+  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 {
+    console.error(full);
+  }
+  return full;
+}