@mgiles/perk 1.0.1

package/extension/doors/selfcheck.ts

@@ -0,0 +1,155 @@
+// `/perk-selfcheck` — the session-wiring verifier.
+//
+// perk converges two pieces of session context onto disk and trusts Pi to splice them into the
+// model's system prompt:
+//
+//   1. `.pi/APPEND_SYSTEM.md` — the COMPRESSED ambient routing index (maintained by `/learn-docs`,
+//      NOT `perk init`). Pi loads it verbatim and joins it into `appendSystemPrompt`.
+//   2. the `<!-- BEGIN perk managed -->` block in `AGENTS.md` — written by `perk init` (the Python
+//      plane). Pi loads `AGENTS.md` into `contextFiles` as `{ path, content }`.
+//
+// `perk doctor` checks the DISK side (the files converged). This selfcheck checks the PROMPT side:
+// it reads the live `getSystemPromptOptions()` (only available on a command context) and confirms
+// the converged content actually *reached* the prompt. That closes perk's two-plane blind spot —
+// doctor checks disk, selfcheck checks the prompt.
+//
+// Sensitivity: `getSystemPromptOptions()` exposes the full system-prompt construction inputs. This
+// module logs ONLY derived booleans/counts (never the raw prompt text). See docs/learned/pi/.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { report as reportTo } from "../surfaces/report.ts";
+
+/** Project-scoped ambient routing index, relative to the repo root. */
+export const AMBIENT_INDEX_REL_PATH = join(".pi", "APPEND_SYSTEM.md");
+
+/** The managed `AGENTS.md` block marker (cross-plane: written by `perk init`, read here). */
+export const MANAGED_AGENTS_MARKER = "<!-- BEGIN perk managed -->";
+
+/** The narrow slice of `BuildSystemPromptOptions` the verifier probes. */
+export interface SystemPromptProbeInput {
+  appendSystemPrompt?: string;
+  contextFiles?: { path: string; content: string }[];
+}
+
+/** Read the on-disk ambient routing index (`.pi/APPEND_SYSTEM.md`), or `null` if absent. */
+export function readAmbientIndex(cwd: string): string | null {
+  const path = join(cwd, AMBIENT_INDEX_REL_PATH);
+  if (!existsSync(path)) return null;
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/** Derived booleans/counts for the ambient routing index — never the raw text. */
+export interface AmbientIndexProbe {
+  /** The `.pi/APPEND_SYSTEM.md` file exists on disk. */
+  onDisk: boolean;
+  /** Its verbatim content is present in `appendSystemPrompt`. */
+  reachedPrompt: boolean;
+  /** Either nothing to wire (no on-disk index) or it reached the prompt. */
+  wired: boolean;
+  /** Length of `appendSystemPrompt` (count only — never the content). */
+  promptChars: number;
+}
+
+/**
+ * Probe whether the on-disk ambient index reached `appendSystemPrompt`. Pi loads the file verbatim
+ * and joins it with `\n\n`, so a trimmed substring match is the faithful "reached the prompt" test.
+ * An absent on-disk index is `wired` (a fresh consumer repo has none until `/learn-docs` lands one).
+ */
+export function ambientIndexProbe(
+  onDiskIndex: string | null,
+  appendSystemPrompt: string | undefined,
+): AmbientIndexProbe {
+  const append = appendSystemPrompt ?? "";
+  const onDisk = onDiskIndex !== null;
+  const trimmed = (onDiskIndex ?? "").trim();
+  const reachedPrompt = onDisk && trimmed.length > 0 && append.includes(trimmed);
+  return {
+    onDisk,
+    reachedPrompt,
+    wired: !onDisk || reachedPrompt,
+    promptChars: append.length,
+  };
+}
+
+/** Derived booleans/counts for the managed `AGENTS.md` block — never the raw text. */
+export interface ManagedAgentsProbe {
+  /** Number of context files spliced into the prompt. */
+  contextFileCount: number;
+  /** Some context file carries the `<!-- BEGIN perk managed -->` marker. */
+  reachedPrompt: boolean;
+}
+
+/** Probe whether the managed `AGENTS.md` block reached `contextFiles`. */
+export function managedAgentsProbe(
+  contextFiles: { path: string; content: string }[] | undefined,
+): ManagedAgentsProbe {
+  const files = contextFiles ?? [];
+  return {
+    contextFileCount: files.length,
+    reachedPrompt: files.some((f) => f.content.includes(MANAGED_AGENTS_MARKER)),
+  };
+}
+
+/** The full derived selfcheck report (booleans/counts + a one-line summary, no raw content). */
+export interface SelfcheckReport {
+  version: string;
+  sharedOk: boolean;
+  ambient: AmbientIndexProbe;
+  agents: ManagedAgentsProbe;
+  /** Everything the session needs is wired through to the prompt. */
+  ok: boolean;
+  /** One-line, content-free summary (safe to surface in UI/logs). */
+  summary: string;
+  level: "info" | "warning";
+}
+
+/** Build the derived selfcheck report from the version, shared-dir state, and the live prompt. */
+export function buildSelfcheckReport(input: {
+  version: string;
+  sharedOk: boolean;
+  onDiskIndex: string | null;
+  options: SystemPromptProbeInput | undefined;
+}): SelfcheckReport {
+  const { version, sharedOk, onDiskIndex, options } = input;
+  const ambient = ambientIndexProbe(onDiskIndex, options?.appendSystemPrompt);
+  const agents = managedAgentsProbe(options?.contextFiles);
+  const ok = sharedOk && ambient.wired && agents.reachedPrompt;
+  const summary =
+    `${version}: ${ok ? "ok" : "WIRING GAP"}; ` +
+    `shared=${sharedOk ? "ok" : "miss"}; ` +
+    `ambient=${ambient.onDisk ? (ambient.reachedPrompt ? "reached" : "MISSING") : "none"} ` +
+    `(append=${ambient.promptChars}c); ` +
+    `agents=${agents.reachedPrompt ? "reached" : "MISSING"} (files=${agents.contextFileCount})`;
+  return { version, sharedOk, ambient, agents, ok, summary, level: ok ? "info" : "warning" };
+}
+
+/**
+ * Register `/perk-selfcheck`: the session-wiring verifier. Runs on a command context (the only
+ * context exposing `getSystemPromptOptions()`), so it sees the live splice — not just disk.
+ */
+export function registerSelfcheck(
+  pi: ExtensionAPI,
+  opts: { version: string; sharedOk: boolean },
+): void {
+  pi.registerCommand("perk-selfcheck", {
+    description:
+      "Verify perk's session wiring: the ambient index + managed AGENTS block reached the prompt.",
+    handler: async (_args, ctx) => {
+      const options = ctx.getSystemPromptOptions() as SystemPromptProbeInput;
+      const report = buildSelfcheckReport({
+        version: opts.version,
+        sharedOk: opts.sharedOk,
+        onDiskIndex: readAmbientIndex(ctx.cwd),
+        options,
+      });
+      // Headless-safe: report() surfaces the derived booleans/counts (never raw prompt content).
+      reportTo(ctx, "selfcheck", report.level, report.summary);
+    },
+  });
+}

package/extension/doors/submit.ts

@@ -0,0 +1,253 @@
+// The warm `/submit` door. The in-session twin of the Python cold door
+// (`perk pr submit`): a deterministic, terminating tool + command that DELEGATE the GitHub write —
+// they do NOT reimplement it (GitHub mutations are canonical in the Python gateway). Mirrors
+// `planSave.ts`: write nothing, delegate to `perk pr submit --json` via `pi.exec`, surface the
+// structured result, never throw (failures are loud-but-non-fatal via `details.ok = false`).
+//
+// Mergeability gate: `perk pr submit` probes the PR's mergeability against the base branch
+// (a deterministic local `git merge-tree` probe). When it reports a definitively-unmergeable PR
+// (`mergeable === false` + conflicts), the warm door drives a fresh-context, write-capable
+// `perk.conflict-resolver` subagent (mirroring `/pr-review`'s dispatch and `/land`'s reconcile
+// drive) to rebase + resolve + push, then asks the model to re-`/submit` to confirm. Bounded by
+// `CONFLICT_RESOLUTION_ATTEMPT_CAP` via the `conflict_resolution_attempts` workflow-state field.
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { bindingSuffix } from "../substrate/bindingDelivery.ts";
+import {
+  booleanField,
+  type ColdJson,
+  numberField,
+  objectField,
+  runColdDoor,
+  stringField,
+} from "../substrate/coldDoor.ts";
+import { loadPerkConfig } from "../substrate/config.ts";
+import { failFor, type OkDetails, ok, type Result } from "../substrate/result.ts";
+import { appendWorkflowState, branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
+import { report } from "../surfaces/report.ts";
+
+/** The bounded conflict-resolution re-drive cap: drive the resolver at most this many times. */
+export const CONFLICT_RESOLUTION_ATTEMPT_CAP = 2;
+
+/** The ok-arm fields — the structured `details` surface doubles as branch-safe persisted state. */
+export interface SubmitOk {
+  pr: { number: number; url: string; is_draft: boolean; existed: boolean };
+  branch?: string;
+  issue?: number;
+  plan_embedded?: boolean;
+  /** The target branch the PR merges into (the conflict-resolver rebases onto it). */
+  base?: string;
+  /** Tri-state mergeability from the Python `git merge-tree` probe: true/false/null/absent. */
+  mergeable?: boolean | null;
+  /** The conflicted paths when `mergeable === false`; `[]` otherwise (advisory). */
+  conflicts?: string[];
+}
+
+export type SubmitResult = Result<SubmitOk>;
+export type SubmitDetails = SubmitResult["details"];
+
+/**
+ * A tri-state read of the advisory `mergeable` field: `true`/`false`/`null` pass through;
+ * anything else (absent, mistyped) → `undefined`. Kept lenient so a malformed value never sinks
+ * an otherwise-successful submit decode.
+ */
+function mergeableField(payload: ColdJson): boolean | null | undefined {
+  const value = payload.mergeable;
+  if (value === true || value === false || value === null) return value;
+  return undefined;
+}
+
+/** A lenient string-array read for the advisory `conflicts` field; malformed → `[]`. */
+function conflictsField(payload: ColdJson): string[] {
+  const value = payload.conflicts;
+  if (Array.isArray(value) && value.every((p) => typeof p === "string")) return value as string[];
+  return [];
+}
+
+/**
+ * Narrow the `perk pr submit --json` success payload; strict on `pr`, lenient on the rest. The
+ * `base`/`mergeable`/`conflicts` mergeability fields are advisory (mirror land.ts's lenient
+ * sub-fields): a malformed value must NOT make a successful submit decode to `null`.
+ */
+function decodeSubmit(payload: ColdJson): SubmitOk | null {
+  const pr = objectField(payload, "pr");
+  if (pr === undefined) return null;
+  const number = numberField(pr, "number");
+  const url = stringField(pr, "url");
+  const isDraft = booleanField(pr, "is_draft");
+  const existed = booleanField(pr, "existed");
+  if (number === undefined || url === undefined || isDraft === undefined || existed === undefined) {
+    return null;
+  }
+  return {
+    pr: { number, url, is_draft: isDraft, existed },
+    branch: stringField(payload, "branch"),
+    issue: numberField(payload, "issue"),
+    plan_embedded: booleanField(payload, "plan_embedded"),
+    base: stringField(payload, "base"),
+    mergeable: mergeableField(payload),
+    conflicts: conflictsField(payload),
+  };
+}
+
+/** A definitively-unmergeable submit: the gate fires only on a *definitive* `false` + conflicts. */
+function isUnmergeable(details: SubmitDetails): details is OkDetails<SubmitOk> {
+  return details.ok && details.mergeable === false && (details.conflicts?.length ?? 0) > 0;
+}
+
+/**
+ * The single submit implementation both surfaces call. Delegates to the Python cold door; returns a
+ * soft result (never throws) — failures set `details.ok = false`. On a clean submit
+ * (`mergeable !== false`) it resets the bounded conflict-resolution counter so a later independent
+ * conflict starts fresh; on conflicts the success message reflects the in-flight resolution.
+ */
+export async function submitPr(pi: ExtensionAPI, ctx: ExtensionContext): Promise<SubmitResult> {
+  const fail = failFor(ctx, "submit");
+
+  const r = await runColdDoor<SubmitOk>(pi, ctx, ["pr", "submit", "--json"], {
+    label: "perk pr submit",
+    decode: decodeSubmit,
+  });
+  if (!r.ok) return fail(r.message, r.errorType);
+
+  const verb = r.data.pr.existed ? "Found existing" : "Opened draft";
+  const conflicted = r.data.mergeable === false && (r.data.conflicts?.length ?? 0) > 0;
+  // Reset the counter on every clean (or undetermined) submit — idempotent; keeps a later
+  // independent conflict bounded fresh.
+  if (r.data.mergeable !== false) resetConflictAttempts(pi, ctx);
+  const message = conflicted
+    ? `${verb} PR #${r.data.pr.number} → ${r.data.pr.url} — merge conflicts detected; resolving`
+    : `${verb} PR #${r.data.pr.number} → ${r.data.pr.url} (${
+        r.data.plan_embedded ? "plan embedded" : "no plan embed"
+      })`;
+  return ok(message, r.data, { terminate: true });
+}
+
+/** Reset `conflict_resolution_attempts` to 0 (idempotent: a no-op when already 0/absent). */
+function resetConflictAttempts(pi: ExtensionAPI, ctx: ExtensionContext): void {
+  const attempts = rebuildWorkflowState(branchOf(ctx)).conflict_resolution_attempts ?? 0;
+  if (attempts === 0) return;
+  appendWorkflowState(pi, ctx, {
+    data: { conflict_resolution_attempts: 0 },
+    field: "conflict_resolution_attempts",
+    expected: 0,
+    scope: "submit",
+    failure: "conflict_resolution_attempts reset read-back failed (expected 0)",
+  });
+}
+
+/**
+ * The follow-up guidance the warm `/submit` injects to spawn the conflict-resolver (modeled on
+ * `prReviewGuidance`). Pure + exported for offline tests. When `model` is set, the spawn carries an
+ * inline `model` override; otherwise the agent's default model is used.
+ */
+export function conflictResolutionGuidance(
+  base: string,
+  attempt: number,
+  cap: number,
+  model?: string,
+): string {
+  const modelClause = model
+    ? `, and pass \`model: "${model}"\` on that call (the configured [subagents] conflict-resolver model)`
+    : " (no model override — the agent's default model is used)";
+  return [
+    `perk /submit — your PR has merge conflicts against \`${base}\`; resolve them before the work ` +
+      "is submitted for review. This is attempt " +
+      `${attempt} of ${cap}.`,
+    `1. Spawn the \`perk.conflict-resolver\` agent via the \`subagent\` tool with \`context: "fresh"\`${modelClause}. ` +
+      "A fresh context keeps this implementation session's history from biasing the resolution.",
+    `2. Tell it: rebase the PR branch onto \`${base}\` and **carefully** resolve all merge ` +
+      "conflicts so the resulting diff is **clean** (no stray markers, no unrelated churn) and " +
+      "**correct** (preserve the change's intent on both sides). The child reads its own plan + PR " +
+      "diff context first (it runs `perk pr review-context`) so it resolves with the change's " +
+      "intent in hand, verifies, and force-pushes — the raw diff never enters this session.",
+    "3. After the child reports success, call `/submit` again to re-verify mergeability. Do NOT " +
+      "edit or resolve conflicts yourself here — the child owns the rebase/resolve/push.",
+  ].join("\n");
+}
+
+/**
+ * After a submit that opened a PR with detected merge conflicts, drive the session into the
+ * conflict-resolution pass by injecting `conflictResolutionGuidance` (warm-door driving pattern,
+ * modeled on `driveReconcileAfterLand`). The terminating `submit` tool stays terminating — a
+ * `followUp` user message is a separate deliberate new turn. Short-circuits (sends nothing) unless
+ * the submit succeeded with a definitively-unmergeable PR. Bounded by
+ * `CONFLICT_RESOLUTION_ATTEMPT_CAP` via the `conflict_resolution_attempts` field: past the cap it
+ * surfaces the unresolved conflict loudly instead of looping.
+ */
+export function driveConflictResolution(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  details: SubmitDetails,
+): void {
+  if (!isUnmergeable(details)) return;
+  const base = details.base ?? "";
+  const attempts = rebuildWorkflowState(branchOf(ctx)).conflict_resolution_attempts ?? 0;
+  if (attempts >= CONFLICT_RESOLUTION_ATTEMPT_CAP) {
+    report(
+      ctx,
+      "submit",
+      "error",
+      `merge conflicts persist after ${attempts} resolution attempt(s) — resolve manually ` +
+        `(rebase onto \`${base}\` and push), then re-run /submit.`,
+      { alsoLog: true },
+    );
+    return;
+  }
+  const next = attempts + 1;
+  appendWorkflowState(pi, ctx, {
+    data: { conflict_resolution_attempts: next },
+    field: "conflict_resolution_attempts",
+    expected: next,
+    scope: "submit",
+    failure: `conflict_resolution_attempts read-back failed (expected ${next})`,
+  });
+  const model = loadPerkConfig(ctx.cwd).subagents["conflict-resolver"];
+  const message =
+    conflictResolutionGuidance(base, next, CONFLICT_RESOLUTION_ATTEMPT_CAP, model) +
+    bindingSuffix(ctx.cwd, "command:submit");
+  if (ctx.isIdle()) {
+    // The `/submit` command path (idle): inject an immediate turn.
+    pi.sendUserMessage(message);
+  } else {
+    // The `submit` tool path (streaming): deliver after the terminating submit batch.
+    pi.sendUserMessage(message, { deliverAs: "followUp" });
+  }
+}
+
+const TOOL_GUIDELINES = [
+  "Call submit only after the implementation is committed in this worktree; it pushes the branch and opens the draft PR, then ends the turn.",
+  "submit operates on the active plan's worktree — it takes no arguments; the branch and plan come from the local plan-ref.",
+];
+
+/** Register the warm door: the `submit` terminating tool (canonical) + the `/submit` command twin. */
+export function registerSubmit(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "submit",
+    label: "Submit PR",
+    description:
+      "Push the current plan's branch and open a draft pull request linking the plan. " +
+      "Terminating: ends the turn on submit. Call only after the implementation is committed.",
+    promptSnippet: "Open the draft PR for the committed implementation (terminates the turn)",
+    promptGuidelines: TOOL_GUIDELINES,
+    executionMode: "sequential",
+    parameters: { type: "object", additionalProperties: false, properties: {} },
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      const result = await submitPr(pi, ctx);
+      driveConflictResolution(pi, ctx, result.details);
+      return result;
+    },
+  });
+
+  pi.registerCommand("submit", {
+    description: "Push the branch and open a draft PR for the active plan (implement → submit).",
+    handler: async (_args, ctx) => {
+      const result = await submitPr(pi, ctx);
+      // Failure already reported loudly via failFor (the single error surface) — success only.
+      if (result.details.ok) {
+        report(ctx, "submit", "info", result.content[0]?.text ?? "submit done");
+      }
+      driveConflictResolution(pi, ctx, result.details);
+    },
+  });
+}

package/extension/factories/objective.ts

@@ -0,0 +1,240 @@
+// The objective TS substrate: `active_objective` live use + budget accounting + threshold
+// compaction. The deterministic mechanics (storage, roadmap, next-node) live in the Python plane
+// (`perk objective …`); this is the in-session interior keyed off the now-live `active_objective`
+// workflow-state field.
+//
+// NO model-facing bounded transition tools here — the `objective-plan` stage, the plan factory, and
+// the "fire only when…" tools live elsewhere. This module ships three pieces, all inert when no
+// objective is active:
+//   1. `/objective [<id>|clear]` — set/clear `active_objective` (LWW field) + seed a dedicated
+//      `perk:objective-budget` activation marker (high-churn budget data kept OFF the shared record,
+//      mirroring checkpoints' dedicated entry).
+//   2. Budget accounting — stateless rebuild (the goal.ts pattern): sum assistant-message tokens
+//      AFTER the latest activation marker; surface via ctx.ui guarded by ctx.hasUI; rebuilt on
+//      session_start AND session_tree AND agent_end (survives reload/branch/compaction for free).
+//   3. Threshold-triggered compaction (the trigger-compact.ts pattern): on turn_end, only when an
+//      objective is active, compact when context usage crosses a configurable threshold.
+//
+// Headless-fail-safe: every UI call is ctx.hasUI-guarded; budget accounting + compaction are
+// best-effort and never throw (logged-not-thrown, like checkpoints).
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadPerkConfig } from "../substrate/config.ts";
+import { branchOf, rebuildWorkflowState, WORKFLOW_STATE_TYPE } from "../substrate/workflowState.ts";
+import {
+  formatBudgetLine,
+  MARK_OBJECTIVE,
+  type PerkStatusHandle,
+  report,
+} from "../surfaces/surfaces.ts";
+
+/** The dedicated budget/activation session entry type (kept off `perk:workflow-state`). */
+export const OBJECTIVE_BUDGET_TYPE = "perk:objective-budget";
+
+/** The default context-usage fraction that triggers threshold compaction (overridable via config). */
+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 };
+  message?: { role?: string; usage?: { input?: number; output?: number } };
+}
+
+export interface BudgetMarker {
+  index: number;
+  objectiveId: string;
+  activatedAt: string;
+}
+
+export interface BudgetState {
+  objectiveId: string | null;
+  tokens: number;
+  elapsedMs: number;
+}
+
+// --- pure helpers (offline-testable) ------------------------------------------------------------
+
+/** The latest `perk:objective-budget` activation marker on the branch, or null. */
+export function findBudgetMarker(branch: readonly ScanEntry[]): BudgetMarker | null {
+  for (let i = branch.length - 1; i >= 0; i--) {
+    const e = branch[i];
+    if (e?.type === "custom" && e.customType === OBJECTIVE_BUDGET_TYPE) {
+      const objectiveId = e.data?.objective_id;
+      const activatedAt = e.data?.activated_at;
+      if (typeof objectiveId === "string" && typeof activatedAt === "string") {
+        return { index: i, objectiveId, activatedAt };
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Sum assistant-message tokens (`max(0,input) + max(0,output)`) over branch entries AFTER
+ * `afterIdx`. Non-assistant / marker entries are ignored; negatives are clamped to 0.
+ */
+export function sumAssistantTokens(branch: readonly ScanEntry[], afterIdx: number): number {
+  let total = 0;
+  for (let i = afterIdx + 1; i < branch.length; i++) {
+    const e = branch[i];
+    if (e?.type !== "message" || e.message?.role !== "assistant") continue;
+    const usage = e.message.usage;
+    if (!usage) continue;
+    total += Math.max(0, usage.input ?? 0) + Math.max(0, usage.output ?? 0);
+  }
+  return total;
+}
+
+/** Rebuild the budget state from a branch (stateless; survives reload/branch/compaction). */
+export function rebuildBudget(branch: readonly ScanEntry[], now: number): BudgetState {
+  const marker = findBudgetMarker(branch);
+  if (marker === null) return { objectiveId: null, tokens: 0, elapsedMs: 0 };
+  const activatedMs = Date.parse(marker.activatedAt);
+  const elapsedMs = Number.isFinite(activatedMs) ? Math.max(0, now - activatedMs) : 0;
+  return {
+    objectiveId: marker.objectiveId,
+    tokens: sumAssistantTokens(branch, marker.index),
+    elapsedMs,
+  };
+}
+
+/** True when context usage has crossed the compaction threshold (pure; tolerant of unknowns). */
+export function shouldCompact(
+  usage: { percent: number | null; tokens: number | null } | undefined,
+  threshold: number,
+): boolean {
+  if (!usage || usage.percent === null) return false;
+  return usage.percent / 100 >= threshold;
+}
+
+// --- the controller -----------------------------------------------------------------------------
+
+function scanBranchOf(ctx: ExtensionContext): ScanEntry[] {
+  return ctx.sessionManager.getBranch() as unknown as ScanEntry[];
+}
+
+function activeObjective(ctx: ExtensionContext): string | null {
+  try {
+    const state = rebuildWorkflowState(branchOf(ctx));
+    return state.active_objective ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Surface the budget as the objective segment of the composed `perk` status (the `perk-objective`
+ * widget is retired; the segment carries id + tokens + elapsed). Headless-safe:
+ * the handle no-ops without UI.
+ */
+function renderStatus(ctx: ExtensionContext, status: PerkStatusHandle): void {
+  if (!ctx.hasUI) return;
+  try {
+    const active = activeObjective(ctx);
+    if (active === null) {
+      status.set(ctx, "objective", undefined);
+      return;
+    }
+    const budget = rebuildBudget(scanBranchOf(ctx), Date.now());
+    status.set(ctx, "objective", `${MARK_OBJECTIVE} ${active} · ${formatBudgetLine(budget)}`);
+  } catch (error) {
+    console.error(`perk: objective status render failed — ${error}`);
+  }
+}
+
+function reportError(ctx: ExtensionContext, message: string): void {
+  report(ctx, "objective", "error", message);
+}
+
+/** The `/objective [<id>|clear]` handler (set/clear active_objective + seed/clear the marker). */
+function objectiveCommand(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  args: string,
+  status: PerkStatusHandle,
+): void {
+  const arg = args.trim();
+  try {
+    if (arg === "") {
+      const active = activeObjective(ctx);
+      const budget = rebuildBudget(scanBranchOf(ctx), Date.now());
+      const message =
+        active === null
+          ? "no active objective. Use `/objective <id>` to activate one."
+          : `active objective ${active} · ${formatBudgetLine(budget)}`;
+      report(ctx, "objective", "info", message);
+      return;
+    }
+
+    if (arg === "clear") {
+      pi.appendEntry(WORKFLOW_STATE_TYPE, { active_objective: null });
+      renderStatus(ctx, status);
+      report(ctx, "objective", "info", "cleared the active objective.");
+      return;
+    }
+
+    // Activate: set the LWW field + seed a fresh budget activation marker.
+    pi.appendEntry(WORKFLOW_STATE_TYPE, { active_objective: arg });
+    pi.appendEntry(OBJECTIVE_BUDGET_TYPE, {
+      objective_id: arg,
+      activated_at: new Date().toISOString(),
+    });
+    renderStatus(ctx, status);
+    report(ctx, "objective", "info", `activated objective ${arg} (budget tracking started).`);
+  } catch (error) {
+    reportError(ctx, `command failed: ${error}`);
+  }
+}
+
+/**
+ * Register the objective substrate: `/objective` command, budget accounting (session_start /
+ * session_tree / agent_end), and threshold compaction (turn_end). All inert when no objective is
+ * active; never throws.
+ */
+export function registerObjective(pi: ExtensionAPI, status: PerkStatusHandle): void {
+  pi.on("session_start", async (_event, ctx) => {
+    renderStatus(ctx, status);
+  });
+
+  pi.on("session_tree", async (_event, ctx) => {
+    renderStatus(ctx, status);
+  });
+
+  pi.on("agent_end", async (_event, ctx) => {
+    // Recompute the budget after each agent loop (stateless rebuild from the branch).
+    renderStatus(ctx, status);
+  });
+
+  pi.on("turn_end", async (_event, ctx) => {
+    try {
+      if (activeObjective(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);
+      ctx.compact({
+        customInstructions:
+          `Preserve the active perk objective (${active}) and its budget context. ` +
+          "Keep the roadmap progress and the current node's intent in the summary.",
+        onError: (error) => {
+          console.error(`perk: objective compaction failed — ${error}`);
+        },
+        onComplete: () => {
+          renderStatus(ctx, status);
+        },
+      });
+    } catch (error) {
+      console.error(`perk: objective compaction trigger failed on turn_end — ${error}`);
+    }
+  });
+
+  pi.registerCommand("objective", {
+    description: "Show, set (`<id>`), or clear (`clear`) the active perk objective + budget.",
+    handler: async (args, ctx) => {
+      objectiveCommand(pi, ctx, args, status);
+    },
+  });
+}