@mgiles/perk 1.1.0 → 2.0.0

package/extension/index.ts

@@ -16,14 +16,15 @@ import { registerAskUser } from "./doors/askUser.ts";
 import { registerCiExecutor } from "./doors/ciExecutor.ts";
 import { registerLand } from "./doors/land.ts";
 import { registerLearn } from "./doors/learn.ts";
-import { registerLearnCode } from "./doors/learnCode.ts";
-import { registerLearnDocs } from "./doors/learnDocs.ts";
+import { CODE_DOOR, DOCS_DOOR, registerLearnFactoryDoor } from "./doors/learnFactory.ts";
 import { registerLifecycleGates } from "./doors/lifecycleGates.ts";
 import { registerPrReview } from "./doors/prReview.ts";
-import { registerPrReviewLocal } from "./doors/prReviewLocal.ts";
+import { registerPrReviewBrowser } from "./doors/prReviewBrowser.ts";
+import { registerPrReviewTerminal } from "./doors/prReviewTerminal.ts";
 import { registerReady } from "./doors/ready.ts";
 import { registerSelfcheck } from "./doors/selfcheck.ts";
 import { registerSubmit } from "./doors/submit.ts";
+import { registerSubmitPrReview } from "./doors/submitPrReview.ts";
 import { registerImplementHere } from "./factories/implementHere.ts";
 import { registerObjective } from "./factories/objective.ts";
 import { registerObjectiveAuthor } from "./factories/objectiveAuthor.ts";
@@ -60,7 +61,13 @@ import {
 } from "./substrate/workflowState.ts";
 import { isPerkFooterReferenceSelected } from "./surfaces/footerProvider.ts";
 import { report } from "./surfaces/report.ts";
-import { createPerkStatus, installPerkFooter } from "./surfaces/surfaces.ts";
+import {
+  createPerkStatus,
+  installPerkFooter,
+  latestCacheHitRate,
+  registerTranscriptRenderer,
+  workflowStateEntryRenderer,
+} from "./surfaces/surfaces.ts";
 import { registerBtw } from "./vendor/btw/btw.ts";
 import { registerWhimsical } from "./vendor/whimsical/whimsical.ts";
 
@@ -173,6 +180,11 @@ export default function (pi: ExtensionAPI) {
   // session_start (reload) could leak the previous handle subscription.
   let footerInstalled = false;
 
+  // Transcript marker for `perk:workflow-state` deltas (audit §2.3): the renderer body lives in
+  // surfaces.ts, this registration is wiring, and the seam carries the typeof feature-detect
+  // (pre-0.80.4 hosts stay inert). One registration covers every workflow-state appender.
+  registerTranscriptRenderer(pi, WORKFLOW_STATE_TYPE, workflowStateEntryRenderer);
+
   pi.on("session_start", async (_event, ctx) => {
     const branchEntries = () => branchOf(ctx);
     const sessionFile = ctx.sessionManager.getSessionFile();
@@ -190,7 +202,9 @@ export default function (pi: ExtensionAPI) {
       cwd: ctx.cwd,
     });
 
-    let resolved: WorkflowState = decision.action === "claim" ? {} : decision.state;
+    // `claim`/`adopt` carry no prior branch state (adopt's is written by its arm below).
+    let resolved: WorkflowState =
+      decision.action === "claim" || decision.action === "adopt" ? {} : decision.state;
     let minted = false;
 
     if (decision.action === "claim") {
@@ -234,6 +248,22 @@ export default function (pi: ExtensionAPI) {
       };
       pi.appendEntry(WORKFLOW_STATE_TYPE, data);
       resolved = data;
+    } else if (decision.action === "adopt") {
+      // An env-inherited run id whose handoff was already consumed by a different session: a
+      // spawned child (contracts §8.2). Mirror the fork arm — derived child identity, isolated
+      // scratch, inherited mode (read-only gating survives) — minus everything that belongs to
+      // the launched session: never re-consume the handoff (its pi_session_id keeps the true
+      // claimer), no `stage` (no stage impersonation / stage-binding injection), and no
+      // implementation/main pointer capture (resolveRunStage stays null for adopt).
+      ensureRunScratch(ctx.cwd, decision.childRunId);
+      const data: WorkflowState = {
+        run_id: decision.childRunId,
+        pi_session_id: currentSessionId ?? undefined,
+        predecessor: decision.parentRunId,
+        mode: decision.mode,
+      };
+      pi.appendEntry(WORKFLOW_STATE_TYPE, data);
+      resolved = data;
     } else if (decision.action === "none") {
       // A warm session with no identity mints its own run_id so
       // per-run state (the session data dir) can key off it. No disk artifacts —
@@ -254,7 +284,28 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
-    // Plan-ref linkage (turn-2b §6, stage-gated): reconcile the cache.plan-ref file into
+    // Reapply the read-only allowlist + stage scoping from the resolved mode/stage — FIRST,
+    // before the plan-ref/stage reconciliation below. `resolved.mode` is final once the
+    // claim/fork/none arms settle (the later blocks only touch `active_plan_ref` / capture
+    // pointers), and ordering the sync ahead of them guarantees no cache read or reconciliation
+    // failure can leave the gate unsynced (defense in depth on top of the total cache readers).
+    // The scope stage is the workflow-state `stage` key (§8.40): claim → the handoff-recorded
+    // stage just appended; keep/none → the branch-LWW stage; fork INHERITS the parent's stage (a
+    // forked implement session is an implement session); adopt NEVER impersonates (subagent
+    // children stay unscoped — their fresh branch carries no stage, so session_tree agrees). A
+    // failed claim leaves `resolved` empty → no stage → unscoped (stage scoping is fail-open).
+    // Fail-closed on the gate: if the sync throws, leave it as-is (a failed sync never opens it).
+    const scopeStage =
+      decision.action === "adopt"
+        ? undefined
+        : (resolved.stage ?? (decision.action === "fork" ? decision.state.stage : undefined));
+    try {
+      gating.syncFromState(resolved.mode, scopeStage);
+    } catch (error) {
+      console.error(`perk: tool-gating sync failed on session_start — ${error}`);
+    }
+
+    // Plan-ref linkage (stage-gated): reconcile the cache.plan-ref file into
     // active_plan_ref — but ONLY when the launched stage *consumes* the ref (its registry
     // `requires`/`reads` list `cache.plan-ref`). That is the worktree binding stages
     // (implement/submit/address/land/learn); the root `worktree: none` stages
@@ -300,6 +351,9 @@ export default function (pi: ExtensionAPI) {
     // The headless worker's inner session lands here too (.main); driveStage records the matching
     // .worker. A forked implement session inherits the parent's launched stage + threads the
     // inherited parent session id as fork provenance. Best-effort + non-fatal (carrier warns).
+    // First-write-wins (`preserveForeign`): this is the corroborated shadowing defect site — the
+    // claimer's original capture stays authoritative, and any future shadow vector warns loudly
+    // instead of silently corrupting /learn evidence.
     const implStage =
       runStage ?? (decision.action === "fork" ? (decision.state.stage ?? null) : null);
     if (resolved.run_id && implStage === "implement") {
@@ -310,17 +364,10 @@ export default function (pi: ExtensionAPI) {
         site: "main",
         sessionFile,
         parentSessionId: decision.action === "fork" ? (decision.state.pi_session_id ?? null) : null,
+        preserveForeign: true,
       });
     }
 
-    // Reapply the read-only allowlist from the resolved mode. Fail-closed: if the sync throws,
-    // leave the gate as-is (a failed sync never opens it).
-    try {
-      gating.syncFromState(resolved.mode);
-    } catch (error) {
-      console.error(`perk: tool-gating sync failed on session_start — ${error}`);
-    }
-
     // Soft version-parity drift signal: pi can lazy-install / load a stale `npm:@mgiles/perk`, so the
     // extension actually running may differ from the `perk` CLI that launched it. The local launch
     // seam injects PERK_CLI_VERSION; compare it against this extension's own `perkVersion()`. Soft +
@@ -351,6 +398,7 @@ export default function (pi: ExtensionAPI) {
         status: perkStatus,
         getModelId: () => ctx.model?.id ?? null,
         getThinkingLevel: () => (ctx.model ? pi.getThinkingLevel() : null),
+        getCacheHitRate: () => latestCacheHitRate(ctx.sessionManager.getEntries()),
         getContext: () => {
           const usage = ctx.getContextUsage();
           return usage ? { percent: usage.percent, contextWindow: usage.contextWindow } : null;
@@ -380,9 +428,10 @@ export default function (pi: ExtensionAPI) {
   // Non-negotiable: rebuild on branch navigation too, or state goes stale after /tree (§8.3).
   pi.on("session_tree", async (_event, ctx) => {
     const state = rebuildWorkflowState(branchOf(ctx));
-    // Non-negotiable: re-sync the gate on tree navigation too (mode is per-field LWW). Fail-closed.
+    // Non-negotiable: re-sync the gate + stage scoping on tree navigation too (mode and stage are
+    // per-field LWW — the branch-rebuilt stage is the §8.40 key). Fail-closed on the gate.
     try {
-      gating.syncFromState(state.mode);
+      gating.syncFromState(state.mode, state.stage);
     } catch (error) {
       console.error(`perk: tool-gating sync failed on session_tree — ${error}`);
     }
@@ -391,7 +440,7 @@ export default function (pi: ExtensionAPI) {
     }
   });
 
-  // Warm door: the `plan_save` tool + `/plan-save` command (turn-3). Takes `gating` for D1a:
+  // Warm door: the `plan_save` tool + `/plan-save` command. Takes `gating`:
   // a successful command-path save exits read-only mode (the read-only → read-write boundary).
   registerPlanSave(pi, gating);
 
@@ -413,16 +462,16 @@ export default function (pi: ExtensionAPI) {
   // before the gate snapshots tools; its name is in READ_ONLY_TOOLS so it survives plan mode.
   registerAskUser(pi);
 
-  // Lifecycle gates: the dirty-repo switch/fork guard + the guard-only `/implement` (turn-4b).
+  // Lifecycle gates: the dirty-repo switch/fork guard + the guard-only `/implement`.
   registerLifecycleGates(pi);
 
-  // Warm door: the `submit` tool + `/submit` command (turn-5a).
+  // Warm door: the `submit` tool + `/submit` command.
   registerSubmit(pi);
 
   // The warm `ready` door: the deliberate draft→ready review gate (submit keeps draft).
   registerReady(pi);
 
-  // Warm doors: `land` (turn-5b) merges + sets pending-learn; `learn` clears it (TS-only).
+  // Warm doors: `land` merges + sets pending-learn; `learn` clears it (TS-only).
   registerLand(pi);
   registerLearn(pi);
 
@@ -435,9 +484,18 @@ export default function (pi: ExtensionAPI) {
   // POSTS its review to the PR (the deliberate departure from /address's read-only-child rule).
   registerPrReview(pi);
 
-  // The warm `/pr-review-local` command: open the plannotator browser code review on the active
-  // PR (URL filled in implicitly) by bridging to plannotator's published `code-review` event.
-  registerPrReviewLocal(pi);
+  // The warm `submit_pr_review` tool: the human-gated curated-posting surface both review
+  // doors ride (contracts §8.4) — neither door registers tools of its own.
+  registerSubmitPrReview(pi);
+
+  // The warm `/pr-review-terminal` door: the terminal review entry — hunk always, no provider
+  // dispatch (the command IS the selection); posting rides `submit_pr_review` above.
+  registerPrReviewTerminal(pi);
+
+  // The warm `/pr-review-browser` door: the browser review entry — plannotator always, opened
+  // in the background (pre-PR it absorbs the since-base local browser review); posting is the
+  // human's own platform-post from the UI, with `submit_pr_review` for request-changes only.
+  registerPrReviewBrowser(pi);
 
   // The read-only CI executor: the `run_ci` tool + `/ci` command + `--allow-project-ci`
   // flag. Runs the project's `[ci]` named checks deterministically and reports (never fixes/loops).
@@ -478,12 +536,12 @@ export default function (pi: ExtensionAPI) {
   // The learned-docs plan factory's warm surface: the `/learn-docs` command gathers open
   // perk:learn issues into an inbox (via the `perk learn docs --gather` cold door) and injects the
   // factory guidance so the model authors a docs/learned consolidation plan (no model tool).
-  registerLearnDocs(pi);
+  registerLearnFactoryDoor(pi, DOCS_DOOR);
 
   // The learn-code plan factory's warm surface: the `/learn-code` command gathers pre-stamped
   // SHOULD_BE_CODE perk:learn issues into an inbox (via the `perk learn code --gather` cold door)
   // and injects the factory guidance so the model authors a code-routing plan (no model tool).
-  registerLearnCode(pi);
+  registerLearnFactoryDoor(pi, CODE_DOOR);
 
   // Warm-door skill-binding delivery: Mechanism A's `before_agent_start` injection of
   // the launched stage's user-originated bindings (+ the stale-context strip). Mechanism B (the

package/extension/substrate/bindingDelivery.ts

@@ -14,8 +14,11 @@
 //
 // This is the SINGLE delivery path for perk's own nudges. Delivery NEVER double-delivers: the
 // cold↔warm dedup marker is `BINDING_HEADER` itself — the cold door's initial prompt and every warm
-// injection carry it, so Mechanism A injects ONLY when nothing on the branch already carries the
-// header (idempotent across turns/reloads; after compaction drops the original it re-delivers).
+// injection carry it, so Mechanism A injects ONLY when neither the branch NOR the submitting
+// turn's prompt already carries the header (idempotent across turns/reloads; after compaction
+// drops the original it re-delivers). The prompt scan is load-bearing on the launch turn: at
+// `before_agent_start` the just-submitted prompt is NOT yet on the branch, so the branch scan
+// alone would miss a cold seed's binding suffix and double-deliver.
 //
 // LBYL throughout: a missing/unreadable transclude target degrades to the nudge pointer with a
 // loud-but-non-fatal warning, never throws, never blocks a turn. Resolver shape `issues` are NOT
@@ -26,7 +29,12 @@ import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { loadDefaultBindings, resolveBindings, type SkillBinding } from "./bindings.ts";
 import { loadPerkConfig } from "./config.ts";
-import { type BranchEntry, branchOf, rebuildWorkflowState } from "./workflowState.ts";
+import {
+  type BranchEntry,
+  branchCarries,
+  branchOf,
+  rebuildWorkflowState,
+} from "./workflowState.ts";
 
 /**
  * The cross-plane dedup marker AND render header. MUST stay byte-identical to the Python cold
@@ -58,7 +66,10 @@ export function resolvedBindings(cwd: string): SkillBinding[] {
 
 /**
  * Render the resolved bindings matching `trigger` into a header-joined fragment (or `null` when
- * none match). `nudge` renders a `Follow the \`<skill>\` skill.` pointer; `transclude` inlines
+ * none match). `nudge` renders a `Follow the \`<skill>\` skill (read
+ * \`.agents/skills/<skill>/SKILL.md\`).` pointer — the read path is unconditional, so a skill
+ * hidden from the ambient prompt (`disable-model-invocation: true`) stays reachable; `transclude`
+ * inlines
  * `.agents/skills/<skill>/SKILL.md` (frontmatter stripped), degrading to the nudge pointer with a
  * loud-but-non-fatal warning when the file is absent/unreadable. Pure but for the LBYL file read.
  */
@@ -86,7 +97,10 @@ export function renderBindings(cwd: string, trigger: string): BindingRender {
           `under ${SKILLS_SUBDIR}/${binding.skill}/${SKILL_FILENAME} — the pointer may dangle.`,
       );
     }
-    parts.push(`Follow the \`${binding.skill}\` skill.`);
+    parts.push(
+      `Follow the \`${binding.skill}\` skill ` +
+        `(read \`${SKILLS_SUBDIR}/${binding.skill}/${SKILL_FILENAME}\`).`,
+    );
   }
   const text = parts.length > 0 ? [BINDING_HEADER, ...parts].join("\n\n") : null;
   return { text, warnings };
@@ -116,7 +130,11 @@ function readSkillBody(cwd: string, skill: string): string | null {
   const path = join(cwd, SKILLS_SUBDIR, skill, SKILL_FILENAME);
   if (!existsSync(path)) return null;
   try {
-    return stripFrontmatter(readFileSync(path, "utf8"));
+    // Normalize CRLF/CR before stripping (the miniJinja.ts pattern): Node's readFileSync keeps
+    // `\r\n` where Python's read_text() normalizes, so without this a CRLF checkout would defeat
+    // the `---\n` frontmatter check AND break the cross-plane byte parity pinned by
+    // tests/test_binding_render_parity.py.
+    return stripFrontmatter(readFileSync(path, "utf8").replace(/\r\n?/g, "\n"));
   } catch {
     return null;
   }
@@ -142,7 +160,7 @@ function stripFrontmatter(text: string): string {
  * header is a distinctive literal, so a substring hit means "already delivered on this branch".
  */
 function branchHasHeader(branch: readonly BranchEntry[]): boolean {
-  return branch.some((entry) => JSON.stringify(entry).includes(BINDING_HEADER));
+  return branchCarries(branch, BINDING_HEADER);
 }
 
 /** The launched stage's `stage:<id>` render, or `null` when there is no stage / nothing matches. */
@@ -160,13 +178,17 @@ function activeStageRender(cwd: string, branch: readonly BranchEntry[]): Binding
  */
 export function registerBindingDelivery(pi: ExtensionAPI): void {
   // Mechanism A — inject the launched stage's resolved bindings as a hidden context message,
-  // but ONLY when no entry on the branch already carries BINDING_HEADER (the cold door's initial
-  // prompt or a prior warm inject) — the cold↔warm idempotency guard.
-  pi.on("before_agent_start", async (_event, ctx) => {
+  // but ONLY when no entry on the branch AND not the submitting turn's prompt already carries
+  // BINDING_HEADER (the cold door's initial prompt or a prior warm inject) — the cold↔warm
+  // idempotency guard. The `event.prompt` scan covers the launch turn, where the just-submitted
+  // prompt is not yet on the branch; a worker prompt carries no header, so Mechanism A still
+  // fires there (contracts.md §8.38).
+  pi.on("before_agent_start", async (event, ctx) => {
     const branch = branchOf(ctx);
     const rendered = activeStageRender(ctx.cwd, branch);
     if (rendered === null || rendered.text === null) return;
     if (branchHasHeader(branch)) return;
+    if (event.prompt.includes(BINDING_HEADER)) return;
     for (const warning of rendered.warnings) console.error(`perk: ${warning}`);
     return {
       message: {

package/extension/substrate/bindings.ts

@@ -12,6 +12,8 @@
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+// Type-only import (config.ts value-imports this module; a value import here would cycle).
+import type { TomlScalar } from "./config.ts";
 import { parse } from "./miniYaml.ts";
 import { sharedDir } from "./resources.ts";
 
@@ -74,10 +76,10 @@ export function loadDefaultBindings(): SkillBinding[] {
 }
 
 /**
- * Parse `.perk/config.toml` `[[bindings]]` rows (string tables) into `SkillBinding`s. Tolerant like
+ * Parse `.perk/config.toml` `[[bindings]]` rows (scalar tables) into `SkillBinding`s. Tolerant like
  * the YAML reader: absent/ill-typed fields become empty strings so the *resolver* reports them.
  */
-export function parseUserBindings(rows: Array<Record<string, string>>): SkillBinding[] {
+export function parseUserBindings(rows: Array<Record<string, TomlScalar>>): SkillBinding[] {
   return rows.map((row) => {
     const trigger = typeof row.trigger === "string" ? row.trigger : "";
     const [kind, targetId] = splitTrigger(trigger);

package/extension/substrate/cache.ts

@@ -3,6 +3,13 @@
 // Both planes read and write the SAME files; the cross-plane contract is the *files*, not a
 // shared module. State-tiering primitives only — no workflow semantics. Imports use no
 // relative paths (only node builtins), so this module loads cleanly under `node --test`.
+//
+// Readers are TOTAL: a corrupt/unreadable file is reported loudly on stderr (`console.error` —
+// the report() seam is intentionally unavailable here, and stderr is headless-safe) and treated
+// as absent (`null`), so a bad cache blob can never crash a caller mid-`session_start` before
+// the read-only gate engages. The Python twins (src/perk/state/cache.py) deliberately keep
+// RAISING `CacheError` (exterior plane, launch-time fail-loud) — the cross-plane contract is
+// the *files*, not error semantics.
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
@@ -21,6 +28,25 @@ export function workflowDir(cwd: string): string {
   return join(cwd, ".perk", "workflow");
 }
 
+/**
+ * Read + parse a JSON cache blob, totally: a missing file is a silent `null` (absence is the
+ * normal state); an unreadable/corrupt/wrong-shape file is a LOUD `null` (one stderr line naming
+ * the file kind + path + error) — treated as absent by every caller.
+ */
+function readJsonOrNull<T>(path: string, what: string): T | null {
+  if (!existsSync(path)) return null;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error(`expected a JSON object, got ${JSON.stringify(parsed)}`);
+    }
+    return parsed as T;
+  } catch (error) {
+    console.error(`perk: unreadable ${what} at ${path} — treating as absent (${error})`);
+    return null;
+  }
+}
+
 // --- handoff -----------------------------------------------------------------------------
 
 export function handoffPath(cwd: string, runId: string): string {
@@ -28,9 +54,7 @@ export function handoffPath(cwd: string, runId: string): string {
 }
 
 export function readHandoff(cwd: string, runId: string): Handoff | null {
-  const path = handoffPath(cwd, runId);
-  if (!existsSync(path)) return null;
-  return JSON.parse(readFileSync(path, "utf8")) as Handoff;
+  return readJsonOrNull<Handoff>(handoffPath(cwd, runId), "handoff");
 }
 
 /** Mark a handoff consumed (idempotent); a no-op when absent. Keeps the file (audit + GC). */
@@ -113,9 +137,7 @@ export function planRefPath(cwd: string): string {
 }
 
 export function readPlanRef(cwd: string): PlanRef | null {
-  const path = planRefPath(cwd);
-  if (!existsSync(path)) return null;
-  return JSON.parse(readFileSync(path, "utf8")) as PlanRef;
+  return readJsonOrNull<PlanRef>(planRefPath(cwd), "plan-ref");
 }
 
 export function writePlanRef(cwd: string, ref: PlanRef): void {
@@ -137,7 +159,12 @@ export function planBodyPath(cwd: string): string {
 export function readPlanBody(cwd: string): string | null {
   const path = planBodyPath(cwd);
   if (!existsSync(path)) return null;
-  return readFileSync(path, "utf8");
+  try {
+    return readFileSync(path, "utf8");
+  } catch (error) {
+    console.error(`perk: unreadable plan body at ${path} — treating as absent (${error})`);
+    return null;
+  }
 }
 
 // --- markers (existence-only) ------------------------------------------------------------

package/extension/substrate/clipboard.ts

@@ -0,0 +1,81 @@
+// A fail-soft "copy this text to the OS clipboard" seam for the extension interior. Used by the
+// terminal review door's R7 hunk handoff so the human always has the launch command one paste
+// away — belt-and-braces beside the loud print and the terminal auto-launch.
+//
+// Two functions: a pure `resolveClipboardScript` (platform + env → a POSIX `sh` script, or `null`
+// for "don't copy") and a thin `copyToClipboard` runner that stages the text in a temp file and
+// shells the script. Never throws, never notifies — the caller owns all messaging. The
+// `PERK_CLIPBOARD_CMD` env seam: unset → the platform default; empty → disabled (the test seam);
+// non-empty → a custom copier.
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ExecHost } from "./coldDoor.ts";
+
+/**
+ * Resolve the clipboard-copy shell script for `platform` + the `PERK_CLIPBOARD_CMD` override. The
+ * script copies the file named by `$1`; returns `null` for "don't copy".
+ *
+ * - `envCmd === ""` → `null` (the test seam / explicit opt-out);
+ * - `envCmd` non-empty → `<envCmd> < "$1"` (custom override — receives the file path as `$1`);
+ * - `darwin` → `pbcopy < "$1"`;
+ * - `linux`/other POSIX → a `command -v` chain (`wl-copy` → `xclip` → `xsel`), else `exit 127`;
+ * - `win32` → `null` (no POSIX `sh`; the print+launch fallback covers it).
+ */
+export function resolveClipboardScript(
+  platform: string,
+  envCmd: string | undefined,
+): string | null {
+  if (envCmd !== undefined) {
+    if (envCmd === "") return null;
+    return `${envCmd} < "$1"`;
+  }
+  if (platform === "darwin") return `pbcopy < "$1"`;
+  if (platform === "win32") return null;
+  return (
+    'if command -v wl-copy >/dev/null 2>&1; then wl-copy < "$1"; ' +
+    'elif command -v xclip >/dev/null 2>&1; then xclip -selection clipboard < "$1"; ' +
+    'elif command -v xsel >/dev/null 2>&1; then xsel --clipboard --input < "$1"; ' +
+    "else exit 127; fi"
+  );
+}
+
+/**
+ * Copy `text` to the OS clipboard, best-effort. Resolves the script from `process.platform` +
+ * `process.env.PERK_CLIPBOARD_CMD`; a `null` script (win32, or the disabled seam) short-circuits
+ * to `false` without shelling. Otherwise stages `text` in a temp file and runs
+ * `sh -c <script> sh <file>` with a 3s cap (guards a display-less `xclip` hanging). Returns
+ * `true` iff the copier exited 0 and was not killed. Any throw → `false`. Never rejects, never
+ * notifies.
+ */
+export async function copyToClipboard(
+  pi: ExecHost,
+  ctx: { cwd: string; signal?: AbortSignal },
+  text: string,
+): Promise<boolean> {
+  const script = resolveClipboardScript(process.platform, process.env.PERK_CLIPBOARD_CMD);
+  if (script === null) return false;
+  let dir: string | undefined;
+  try {
+    dir = mkdtempSync(join(tmpdir(), "perk-clip-"));
+    const file = join(dir, "clip.txt");
+    writeFileSync(file, text, "utf8");
+    const res = await pi.exec("sh", ["-c", script, "sh", file], {
+      cwd: ctx.cwd,
+      signal: ctx.signal,
+      timeout: 3000,
+    });
+    return res.code === 0 && !res.killed;
+  } catch {
+    return false;
+  } finally {
+    if (dir !== undefined) {
+      try {
+        rmSync(dir, { recursive: true, force: true });
+      } catch {
+        // best-effort cleanup — a leaked temp file is harmless
+      }
+    }
+  }
+}