@promptctl/cc-candybar 1.4.0 → 1.6.0

package/src/daemon/render-payload.ts

@@ -25,7 +25,10 @@ import type { GitInfo, GitInfoOptions } from "../segments/git.js";
 import { ABSENT, failed, type Outcome } from "../utils/outcome.js";
 import { cacheExpiresAt } from "../segments/cache.js";
 import type { DaemonLogger } from "./log.js";
-import type { SessionUsageStore } from "./cache/session-usage-store.js";
+import type {
+  SessionUsageStore,
+  SpeedObservation,
+} from "./cache/session-usage-store.js";
 import type { ContextProvider } from "../segments/context.js";
 import type { MetricsProvider } from "../segments/metrics.js";
 import type { TmuxService } from "../segments/tmux.js";
@@ -65,6 +68,7 @@ export interface RenderPayload extends ClaudeHookData {
   readonly session?: SessionPayload;
   readonly today?: TodayPayload;
   readonly burn?: BurnPayload;
+  readonly speed?: SpeedPayload;
   readonly block?: BlockPayload;
   readonly weekly?: WeeklyPayload;
   readonly cache?: CachePayload;
@@ -94,6 +98,16 @@ export interface GitPayload {
   readonly status?: string;
   readonly operation?: string;
   readonly timeSinceCommit?: number;
+  // Forge PR/MR. [LAW:no-silent-failure] Unlike every other git field (where
+  // `failed` collapses to a missing key), the PR's failure is surfaced as
+  // `prError` so the segment can render a VISIBLY DISTINCT marker — a forge
+  // outage must not look like "no PR". The three render-distinguishable states:
+  // open PR (prNumber/prState/prUrl present), lookup failed (prError present),
+  // no PR (all absent → segment when-gated off).
+  readonly prNumber?: number;
+  readonly prState?: string;
+  readonly prUrl?: string;
+  readonly prError?: string;
 }
 
 export interface SessionPayload {
@@ -115,6 +129,19 @@ export interface BurnPayload {
   readonly costPerHour?: number;
 }
 
+// [LAW:one-type-per-behavior] Token throughput for the active turn — tokens per
+// second on each of three lanes (prompt-side input, generated output, their
+// total). Each lane is INDEPENDENTLY optional: during streaming `output` moves
+// while `input` (fixed at turn start) is idle, so an absent `input` rate beside a
+// live `output` rate is the honest shape, not a zero. Absence (no baseline yet,
+// idle between turns, or a too-stale prior sample) travels as a missing field to
+// the -1 default, which the `formatSpeed` helper reads as "—". [LAW:no-silent-failure]
+export interface SpeedPayload {
+  readonly input?: number;
+  readonly output?: number;
+  readonly total?: number;
+}
+
 export interface BlockPayload {
   readonly nativeUtilization: number;
   readonly resetsAt: number;
@@ -200,6 +227,15 @@ const MIN_PROJECTABLE_ELAPSED_MS = 5 * 60 * 1000;
 // $/hr is dominated by a single turn rather than a sustained burn.
 const MIN_BURN_SECONDS = 60;
 
+// tok/s is a delta between two successive render observations. The wall-time
+// between them must clear a tiny floor (the clock has to have advanced — below
+// it the rate is divide-by-near-zero noise) and stay under a ceiling: a gap
+// wider than this means the prior sample predates an idle stretch, so the rate
+// would be diluted by dead time. Both bounds → no reading (re-baseline silently
+// on the next render) rather than a misleading number. [LAW:no-silent-failure]
+const MIN_SPEED_SAMPLE_MS = 50;
+const MAX_SPEED_SAMPLE_MS = 10 * 1000;
+
 /**
  * Linearly extrapolate a rate-limit window's utilization to its 100% cap.
  * The window started `windowMs` before `resetsAtSec`; elapsed time and the
@@ -236,6 +272,64 @@ export function projectCostPerHour(
   return (cost * 3600) / durationSeconds;
 }
 
+/**
+ * Instantaneous tokens-per-second between two successive render observations of
+ * one cumulative token count. Returns undefined when the sample window is too
+ * small or too large to be honest (see the floor/ceiling constants) or when the
+ * count did not advance (idle / between turns — a true 0 over a real window is
+ * reported as 0, but a flat count carries no throughput to report). A real
+ * positive rate is always >= 0, so callers use -1 as the absence default — 0
+ * tok/s never doubles as the "no reading" marker. [LAW:no-silent-failure]
+ */
+export function projectTokensPerSecond(
+  prevTokens: number,
+  prevMs: number,
+  curTokens: number,
+  nowMs: number,
+): number | undefined {
+  const deltaMs = nowMs - prevMs;
+  if (deltaMs < MIN_SPEED_SAMPLE_MS || deltaMs > MAX_SPEED_SAMPLE_MS)
+    return undefined;
+  const deltaTokens = curTokens - prevTokens;
+  if (deltaTokens <= 0) return undefined;
+  return (deltaTokens * 1000) / deltaMs;
+}
+
+// [LAW:effects-at-boundaries] Pure fold of one speed observation into the
+// payload's three rate lanes. No baseline (first render of a session) or every
+// lane un-projectable → undefined (the whole `speed` key is dropped); otherwise
+// each lane that projects contributes its rate, each that doesn't is a missing
+// field → the -1 default → "—".
+function projectSpeed(obs: SpeedObservation): SpeedPayload | undefined {
+  const { prev, cur } = obs;
+  if (prev === undefined) return undefined;
+  const input = projectTokensPerSecond(
+    prev.input,
+    prev.atMs,
+    cur.input,
+    cur.atMs,
+  );
+  const output = projectTokensPerSecond(
+    prev.output,
+    prev.atMs,
+    cur.output,
+    cur.atMs,
+  );
+  const total = projectTokensPerSecond(
+    prev.total,
+    prev.atMs,
+    cur.total,
+    cur.atMs,
+  );
+  if (input === undefined && output === undefined && total === undefined)
+    return undefined;
+  return {
+    ...(input !== undefined && { input }),
+    ...(output !== undefined && { output }),
+    ...(total !== undefined && { total }),
+  };
+}
+
 // ─── Builder ─────────────────────────────────────────────────────────────────
 
 // ─── Config-driven provider gating ───────────────────────────────────────────
@@ -388,6 +482,12 @@ function gitOptionsFromClosure(needed: ReadonlySet<string>): GitInfoOptions {
     ...(has("git.repoName") && { showRepoName: true }),
     ...(has("git.operation") && { showOperation: true }),
     ...(has("git.timeSinceCommit") && { showTimeSinceCommit: true }),
+    // Any PR field laid out turns on the (network) forge lookup. Keep these in
+    // lockstep with the projected `git.pr*` fields below.
+    ...((has("git.prNumber") ||
+      has("git.prState") ||
+      has("git.prUrl") ||
+      has("git.prError")) && { showPullRequest: true }),
   };
 }
 
@@ -428,6 +528,11 @@ export async function buildRenderPayload(
   const wants = (prefix: string): boolean =>
     anyPathStartsWith(neededInputPaths, prefix);
 
+  // [LAW:single-enforcer] One clock read feeds every projection this render —
+  // the ETA extrapolations below AND the tok/s sample window in the speed lane,
+  // so an ETA, a reset countdown, and a throughput figure all agree on "now".
+  const nowMs = (deps.clock ?? (() => new Date()))().getTime();
+
   // [LAW:dataflow-not-control-flow][LAW:one-type-per-behavior] Every provider
   // lane is ONE shape: "needed → call provider (whose contract is to never
   // reject — the catch makes the lane total against bugs, mapping a throw
@@ -443,40 +548,57 @@ export async function buildRenderPayload(
       ? run().catch((e: unknown) => failed(`${name}: ${String(e)}`))
       : Promise.resolve(ABSENT);
 
-  const [gitOutcome, usage, today, context, metrics, tmuxSession, cacheExpiry] =
-    await Promise.all([
-      lane("git", wants("git"), () =>
-        deps.gitProvider.getGitInfo(
-          cwd ?? hookData.workspace?.current_dir,
-          gitOptionsFromClosure(neededInputPaths),
-          hookData.workspace?.project_dir,
-        ),
-      ),
-      // [LAW:dataflow-not-control-flow] The burn segment reads `burn.costPerHour`,
-      // a derivative of session cost and metrics duration — so wanting `burn`
-      // pulls in exactly the two lanes it is folded from.
-      lane(
-        "session",
-        wants("session.cost") || wants("session.tokens") || wants("burn"),
-        () => deps.usageStore.getUsageInfo(hookData.session_id, hookData),
-      ),
-      lane("today", wants("today"), () =>
-        deps.usageStore.getTodayInfo(hookData),
+  const [
+    gitOutcome,
+    usage,
+    today,
+    context,
+    metrics,
+    tmuxSession,
+    cacheExpiry,
+    speed,
+  ] = await Promise.all([
+    lane("git", wants("git"), () =>
+      deps.gitProvider.getGitInfo(
+        cwd ?? hookData.workspace?.current_dir,
+        gitOptionsFromClosure(neededInputPaths),
+        hookData.workspace?.project_dir,
       ),
-      lane("context", wants("context"), () =>
-        deps.contextProvider.getContextInfo(hookData),
-      ),
-      lane("metrics", wants("metrics") || wants("burn"), () =>
-        deps.metricsProvider.getMetricsInfo(hookData.session_id, hookData),
-      ),
-      lane("tmux", wants("tmux"), () => deps.tmuxService.getSessionId()),
-      // Prompt-cache expiry: a bounded tail-read through the gated transcript-fs
-      // seam, so it runs alongside the other providers and stays in the shared
-      // in-flight budget rather than blocking the event loop on sync fs.
-      lane("cache", wants("cache"), () =>
-        cacheExpiresAt(hookData.transcript_path),
+    ),
+    // [LAW:dataflow-not-control-flow] The burn segment reads `burn.costPerHour`,
+    // a derivative of session cost and metrics duration — so wanting `burn`
+    // pulls in exactly the two lanes it is folded from.
+    lane(
+      "session",
+      wants("session.cost") || wants("session.tokens") || wants("burn"),
+      () => deps.usageStore.getUsageInfo(hookData.session_id, hookData),
+    ),
+    lane("today", wants("today"), () => deps.usageStore.getTodayInfo(hookData)),
+    lane("context", wants("context"), () =>
+      deps.contextProvider.getContextInfo(hookData),
+    ),
+    lane("metrics", wants("metrics") || wants("burn"), () =>
+      deps.metricsProvider.getMetricsInfo(hookData.session_id, hookData),
+    ),
+    lane("tmux", wants("tmux"), () => deps.tmuxService.getSessionId()),
+    // Prompt-cache expiry: a bounded tail-read through the gated transcript-fs
+    // seam, so it runs alongside the other providers and stays in the shared
+    // in-flight budget rather than blocking the event loop on sync fs.
+    lane("cache", wants("cache"), () =>
+      cacheExpiresAt(hookData.transcript_path),
+    ),
+    // [LAW:one-source-of-truth] tok/s folds from the SAME store the session
+    // lane reads — observeSpeed both reports the prior sample and records this
+    // render's, so it must run every render the speed segment is laid out (the
+    // first establishes the baseline that the second projects from).
+    lane("speed", wants("speed"), () =>
+      deps.usageStore.observeSpeed(
+        hookData.session_id,
+        hookData.transcript_path,
+        nowMs,
       ),
-    ]);
+    ),
+  ]);
   // [LAW:effects-at-boundaries] The projections are pure folds returning data
   // (payload fragment + failure descriptions); the log effect happens once,
   // here, at the edge. `take` is the total fold for the single-value lanes:
@@ -505,8 +627,6 @@ export async function buildRenderPayload(
   // the formatter func — a duplicate code path was retired.)
   const fiveHour = hookData.rate_limits?.five_hour;
   const sevenDay = hookData.rate_limits?.seven_day;
-  // [LAW:single-enforcer] One clock read feeds every projection this render.
-  const nowMs = (deps.clock ?? (() => new Date()))().getTime();
   const blockEta = fiveHour
     ? projectEtaMinutes(
         fiveHour.used_percentage,
@@ -532,6 +652,13 @@ export async function buildRenderPayload(
     wants("burn") && burnCost != null && burnDuration != null
       ? projectCostPerHour(burnCost, burnDuration)
       : undefined;
+  // [LAW:effects-at-boundaries] The store reported the prev+cur samples (an
+  // effect: it read state and advanced the baseline); the rate is a pure fold of
+  // that data here at the edge. Absent observation (lane skipped/failed) or no
+  // projectable lane → no `speed` key → every lane reads its -1 default.
+  const speedObs = take(speed);
+  const speedPayload =
+    speedObs !== undefined ? projectSpeed(speedObs) : undefined;
 
   // [LAW:one-source-of-truth] The theme variable surfaces the session's
   // resolved theme so the toolbar/tray DSL templates can encode it into
@@ -597,6 +724,7 @@ export async function buildRenderPayload(
     ...(sessionPayload !== undefined && { session: sessionPayload }),
     ...(todayPayload !== undefined && { today: todayPayload }),
     ...(costPerHour !== undefined && { burn: { costPerHour } }),
+    ...(speedPayload !== undefined && { speed: speedPayload }),
     ...(wants("block") &&
       fiveHour !== undefined && {
         block: {
@@ -697,6 +825,28 @@ function projectGitInfo(outcome: Outcome<GitInfo>): {
   const upstream = field("upstream", info.upstream);
   const repoName = field("repoName", info.repoName);
 
+  // [LAW:no-silent-failure] The PR deliberately breaks the `field` pattern: a
+  // `failed` lookup is NOT dropped to a missing key (which the template can't
+  // tell apart from "no PR"). It is BOTH logged AND surfaced as `prError` so
+  // the segment renders a distinct marker. `absent` is still a missing key (no
+  // PR / no forge → segment off). The reason is the gate value the template
+  // tests; the same reason is logged for the operator.
+  const pr = info.pullRequest;
+  const prFields: {
+    prNumber?: number;
+    prState?: string;
+    prUrl?: string;
+    prError?: string;
+  } = {};
+  if (pr?.kind === "ok") {
+    prFields.prNumber = pr.value.number;
+    prFields.prState = pr.value.state;
+    prFields.prUrl = pr.value.url;
+  } else if (pr?.kind === "failed") {
+    failures.push(`git.pr: ${pr.reason}`);
+    prFields.prError = pr.reason;
+  }
+
   return {
     git: {
       branch: info.branch,
@@ -717,6 +867,7 @@ function projectGitInfo(outcome: Outcome<GitInfo>): {
       ...(stash !== undefined && { stash }),
       ...(upstream !== undefined && { upstream }),
       ...(repoName !== undefined && { repoName }),
+      ...prFields,
     },
     failures,
   };

package/src/proc/launch.ts

@@ -31,6 +31,10 @@ import type { LaunchStatsHandle } from "./stats-handle";
 // pattern. [LAW:no-mode-explosion]: no per-site escape hatch.
 export const LAUNCH_CATEGORIES = [
   "git",
+  // Forge CLIs (gh / glab) for the PR/MR lookup. A network-bound spawn,
+  // separate from "git" so daemon-stats attributes it independently and a
+  // future rate limit can target it without throttling local git.
+  "forge",
   "user-shell",
   "tmux",
   "click.pbcopy",

package/src/segments/git.ts

@@ -16,6 +16,17 @@ export interface AheadBehind {
   behind: number;
 }
 
+// [LAW:types-are-the-program] The branch's open PR/MR as the forge reports it.
+// `number` and `url` are the click target; `state` is the forge's status string
+// (GitHub "OPEN", GitLab "opened") — carried so a consumer can color/label it,
+// though resolvePullRequest only ever returns a PR whose state is open (a
+// merged/closed PR for the branch is the domain's `absent`, not a value).
+export interface PullRequest {
+  number: number;
+  state: string;
+  url: string;
+}
+
 // [LAW:types-are-the-program] Every on-demand field is an Outcome, so "this
 // value is unknown because the fetch failed" is representable distinct from
 // a real 0/""/basename — the states the old catch-and-substitute blocks
@@ -37,6 +48,13 @@ export interface GitInfo {
   upstream?: Outcome<string>;
   repoName?: Outcome<string>;
   isWorktree?: boolean;
+  // [LAW:no-silent-failure] The forge lookup's three outcomes are all kept
+  // distinct here: `ok` is an open PR, `absent` is "this branch has none / no
+  // forge / no forge CLI", `failed` is "the forge was asked but couldn't
+  // answer" (auth, network, API error). The render boundary surfaces `failed`
+  // as a VISIBLE marker — collapsing it to `absent` would make a transient
+  // outage look like the PR vanished. Undefined = `showPullRequest` was off.
+  pullRequest?: Outcome<PullRequest>;
 }
 
 // [LAW:one-source-of-truth] The one shape of getGitInfo's `show*` toggles. Each
@@ -53,6 +71,11 @@ export interface GitInfoOptions {
   showStashCount?: boolean;
   showUpstream?: boolean;
   showRepoName?: boolean;
+  // Opts into the forge (gh/glab) PR/MR lookup — a network call, so it is the
+  // one option whose fetch the daemon caches on a longer, independent TTL than
+  // the rest of GitInfo (see src/daemon/cache/git.ts). Never resolved by the
+  // inner GitService's computeGitInfo; the cache layer owns the lookup+cache.
+  showPullRequest?: boolean;
 }
 
 // [LAW:dataflow-not-control-flow] One classifier for every git invocation.
@@ -89,6 +112,134 @@ function nonEmpty(o: Outcome<string>): Outcome<string> {
   return v ? ok(v) : ABSENT;
 }
 
+// [LAW:one-type-per-behavior] `gh` and `glab` are two instances of one act:
+// "ask a forge CLI for the branch's PR, fold the typed launch result into an
+// Outcome<PullRequest>." The accept/reject shape table is identical across
+// both — only the no-PR stderr signature and the JSON field names differ — so
+// the classification lives here once and each forge supplies its own
+// (noPrPattern, parse) as data.
+//
+// [LAW:no-silent-failure] The full shape table, enumerated so no input leaks:
+//   ok + parse ok (open PR)         → ok            (the value)
+//   ok + parse ok (not open)        → absent        (branch's PR is done)
+//   ok + parse fails                → failed        (forge answered garbage)
+//   non-zero + no-PR stderr         → absent        (genuine "none for branch")
+//   spawn-error ENOENT (no CLI)     → absent        (no forge integration)
+//   spawn-error other (EACCES, …)   → failed        (CLI present but unlaunchable)
+//   non-zero (auth/net/not-a-repo)  → failed        (forge couldn't answer)
+//   timeout / signal / rate-limited → failed        (forge couldn't answer)
+export type ForgeName = "github" | "gitlab";
+
+// [LAW:types-are-the-program] Extract the host from a git remote, handling the
+// two shapes git uses: scp-like `[user@]host:path` and URL `scheme://[user@]
+// host[:port]/path`. The URL form is checked first — its `host` in a scp regex
+// would mis-capture the scheme (`https` before `://`). Returns null for an
+// unrecognized shape (local path, unknown syntax).
+function remoteHost(remoteUrl: string): string | null {
+  const url = remoteUrl.trim();
+  const proto = url.match(/^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]+@)?([^/:]+)/i);
+  if (proto) return proto[1]!.toLowerCase();
+  const scp = url.match(/^(?:[^@/]+@)?([^/:]+):/);
+  if (scp) return scp[1]!.toLowerCase();
+  return null;
+}
+
+// [LAW:types-are-the-program] Branch on the HOST, not a substring of the whole
+// URL — a non-GitLab remote whose path merely contains "gitlab" (a repo named
+// `gitlab`) must not dispatch to glab. Self-hosted GitLab is detected by a
+// `gitlab.`-prefixed host label (gitlab.example.com); a GitLab on an arbitrary
+// hostname is undetectable here and falls through to null (absent), same as
+// GitHub Enterprise on a custom domain.
+export function detectForge(remoteUrl: string): ForgeName | null {
+  const host = remoteHost(remoteUrl);
+  if (!host) return null;
+  if (host === "github.com" || host.endsWith(".github.com")) return "github";
+  if (/(^|\.)gitlab\./.test(host)) return "gitlab";
+  return null;
+}
+
+export function classifyForgePr(
+  label: string,
+  result: LaunchResult,
+  noPrPattern: RegExp,
+  parse: (stdout: string) => Outcome<PullRequest>,
+): Outcome<PullRequest> {
+  if (result.ok) return parse(result.stdout);
+  // ENOENT (no forge CLI on PATH) is a static configuration absence, not a
+  // transient lookup failure — it never showed a PR, so showing nothing costs
+  // nothing. [LAW:no-silent-failure] Every OTHER spawn failure (EACCES,
+  // resource limits) means the CLI is present but could not launch — a real
+  // failure that must stay visible, so it falls through to the `failed` path.
+  if (result.reason === "spawn-error" && /ENOENT/i.test(result.error ?? ""))
+    return ABSENT;
+  if (result.reason === "non-zero" && noPrPattern.test(result.stderr))
+    return ABSENT;
+  const detail = [
+    result.reason,
+    result.exitCode != null ? `exit ${result.exitCode}` : null,
+    result.error ?? firstLine(result.stderr),
+  ]
+    .filter(Boolean)
+    .join(", ");
+  return failed(`${label}: ${detail}`);
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+// `gh pr view --json number,state,url` → one JSON object. Only an OPEN PR is a
+// value; a MERGED/CLOSED PR for the branch is the domain's `absent`.
+export function parseGithubPr(stdout: string): Outcome<PullRequest> {
+  let json: unknown;
+  try {
+    json = JSON.parse(stdout);
+  } catch (e) {
+    return failed(
+      `gh pr view: unparseable JSON (${e instanceof Error ? e.message : String(e)})`,
+    );
+  }
+  if (!isRecord(json)) return failed("gh pr view: JSON is not an object");
+  const { number, state, url } = json;
+  if (
+    typeof number !== "number" ||
+    typeof state !== "string" ||
+    typeof url !== "string"
+  ) {
+    return failed("gh pr view: missing number/state/url");
+  }
+  if (state.toUpperCase() !== "OPEN") return ABSENT;
+  return ok({ number, state, url });
+}
+
+// `glab mr view --output json` → one JSON object (iid / state / web_url). State
+// "opened" is the open MR; anything else is `absent`. NOTE: verified against
+// glab's documented JSON shape, not runtime-exercised here (glab not installed
+// on the dev machine) — the github path is the runtime-verified one.
+export function parseGitlabMr(stdout: string): Outcome<PullRequest> {
+  let json: unknown;
+  try {
+    json = JSON.parse(stdout);
+  } catch (e) {
+    return failed(
+      `glab mr view: unparseable JSON (${e instanceof Error ? e.message : String(e)})`,
+    );
+  }
+  if (!isRecord(json)) return failed("glab mr view: JSON is not an object");
+  const iid = json.iid;
+  const state = json.state;
+  const url = json.web_url;
+  if (
+    typeof iid !== "number" ||
+    typeof state !== "string" ||
+    typeof url !== "string"
+  ) {
+    return failed("glab mr view: missing iid/state/web_url");
+  }
+  if (state.toLowerCase() !== "opened") return ABSENT;
+  return ok({ number: iid, state, url });
+}
+
 export class GitService {
   private isGitRepo(workingDir: string): boolean {
     try {
@@ -407,6 +558,83 @@ export class GitService {
     return ok(match?.[1] || path.basename(workingDir));
   }
 
+  // [LAW:locality-or-seam] Public so the daemon's GitDataProvider can read the
+  // remote to fold into its PR cache key (the PR value depends on the remote;
+  // a re-pointed origin must be a new key). Raw origin URL (unparsed) — the
+  // forge detector reads the host from it. `config --get` exits 1 when unset →
+  // `absent` (no remote, hence no forge PR concept), distinct from a failure.
+  async getRemoteOriginUrl(workingDir: string): Promise<Outcome<string>> {
+    return nonEmpty(
+      classify(
+        "git config remote.origin.url",
+        await this.execGitAsync(["config", "--get", "remote.origin.url"], {
+          cwd: workingDir,
+          timeout: 2000,
+        }),
+        "absent",
+      ),
+    );
+  }
+
+  // [LAW:single-enforcer] One boundary for forge-CLI spawns. Mirrors
+  // execGitAsync but carries the "forge" launch category and a longer timeout
+  // (this is a network call, not a local git read). Returns the typed
+  // LaunchResult so classifyForgePr maps every termination cause to an Outcome.
+  private async execForgeAsync(
+    bin: string,
+    args: readonly string[],
+    options: { cwd: string; timeout: number },
+  ): Promise<LaunchResult> {
+    return launch({
+      bin,
+      args: [...args],
+      cwd: options.cwd,
+      env: { ...process.env },
+      timeoutMs: options.timeout,
+      category: "forge",
+    });
+  }
+
+  // [LAW:effects-at-boundaries] Resolve the branch's open PR/MR via the forge
+  // CLI. Pure dispatch over a remote the CALLER has already read: pick the
+  // forge by host, run its CLI, fold the launch result into an Outcome. The
+  // remote is a parameter (not read here) so the cache layer can fold it into
+  // its key in the same read — no caching here; the daemon's GitDataProvider
+  // owns the PR cache + TTL (a network resource wants a longer, independent
+  // lifecycle than local git state). `absent` when the host is no recognized
+  // forge; the CLI dispatch then classifies the rest.
+  async resolvePullRequest(
+    workingDir: string,
+    remoteUrl: string,
+  ): Promise<Outcome<PullRequest>> {
+    const forge = detectForge(remoteUrl);
+    if (forge === "github") {
+      return classifyForgePr(
+        "gh pr view",
+        await this.execForgeAsync(
+          "gh",
+          ["pr", "view", "--json", "number,state,url"],
+          { cwd: workingDir, timeout: 5000 },
+        ),
+        /no (open )?pull requests? found/i,
+        parseGithubPr,
+      );
+    }
+    if (forge === "gitlab") {
+      return classifyForgePr(
+        "glab mr view",
+        await this.execForgeAsync("glab", ["mr", "view", "--output", "json"], {
+          cwd: workingDir,
+          timeout: 5000,
+        }),
+        /no (open )?merge requests? (found|available)/i,
+        parseGitlabMr,
+      );
+    }
+    // Recognized neither host → no forge integration for this remote.
+    return ABSENT;
+  }
+
   private isWorktree(workingDir: string): boolean {
     try {
       const gitDir = path.join(workingDir, ".git");