@codyswann/lisa 4.81.3 → 4.81.5

package/plugins/lisa-copilot/skills/lisa-secrets-access/scripts/validate-config.mjs

@@ -727,6 +727,35 @@ function findCredentials(value, path) {
   );
 }
 
+/**
+ * Validate `sessionManager.operatorIds`: the people the manager works for,
+ * whose assigned items it dispatches first. Matched against the assignee the
+ * way "me" is, so the GitHub entry is a login, not the numeric id
+ * `trustedAuthorIds` takes. An empty list reads as configured but names no
+ * one, so it is refused like an empty `trustedAuthorIds`.
+ * @param {unknown} ids The value, if present.
+ * @returns {string[]} Problems found.
+ */
+function validateOperatorIds(ids) {
+  if (ids === undefined) return [];
+  if (
+    !Array.isArray(ids) ||
+    !ids.every(id => typeof id === "string" && id.trim() !== "")
+  ) {
+    return [
+      `sessionManager.operatorIds must be an array of tracker user ids as ` +
+        `strings, matched against the assignee: the GitHub login, the Jira ` +
+        `accountId or the Linear user id.`,
+    ];
+  }
+  return ids.length === 0
+    ? [
+        `sessionManager.operatorIds must name at least one person. Remove ` +
+          `the key instead if the manager works only for its own identity.`,
+      ]
+    : [];
+}
+
 /**
  * Validate the opt-in `sessionManager` block.
  *
@@ -786,6 +815,7 @@ export function validateSessionManager(block) {
             `if every author's item may be dispatched.`,
         ]
       : []),
+    ...validateOperatorIds(block.operatorIds),
     ...findCredentials(block, "sessionManager"),
   ];
 }

package/plugins/lisa-copilot/skills/lisa-session-manager/SKILL.md

@@ -23,9 +23,9 @@ channels (Telegram) and cross-session messaging (`SendMessage`, `crossSessionInb
 | Runtime | lisa-setup-session-manager | lisa-session-manager (manager) | `managedBy=` |
 |---|---|---|---|
 | Claude Code | supported | supported (reference). Needs `claude` ≥ 2.1.224, `tmux`, `bun` | supported |
-| Codex | config, token and runbook are supported. `start` launches a Claude Code manager, so it works when the `claude` CLI is installed | the skill ships, but `cycle` refuses to run here (no `/loop`, channels or `SendMessage`); tell the operator to run `start` | rejected with the gap message |
+| Codex | config, token (prompt or `--from-clipboard`), runbook, `trust-status` and `coexistence` are supported. `trust-status` reads Claude Code's trust record, which is the one that matters (workers are Claude Code); accepting trust needs the `claude` CLI. `coexistence` sees only run logs, so also list Codex automations. `start` launches a Claude Code manager, so it works when the `claude` CLI is installed | the skill ships, but `cycle` refuses to run here (no `/loop`, channels or `SendMessage`); tell the operator to run `start` | rejected with the gap message |
 | Cursor / Antigravity (agy) / Copilot / Devin | same as Codex | same as Codex | rejected |
-| OpenCode | config and token are supported; script resolution relies on the npm rung, so `queue` and `record-cycle` need the npm package | gap | rejected |
+| OpenCode | same setup subcommands as Codex, but script resolution relies on the npm rung: the CLI imports plugin-level scripts the skill-folder copy lacks, so every subcommand needs the npm package | gap | rejected |
 
 On any runtime other than Claude Code, `cycle` stops with: "The session manager runs on Claude Code
 only (background sessions, channels, cross-session messaging). Run `/lisa:session-manager start`
@@ -66,7 +66,12 @@ the manager.
   claims go through `lisa-tracker-claim`. Never call a vendor API around them.
 - **"Me".** Resolve once per manager run and store it with `ledger control --me <id>`: GitHub
   `gh api user --jq .login`; Jira the accountId from the `lisa-atlassian-access` identity probe;
-  Linear `viewer.id` through `lisa-linear-access`.
+  Linear `viewer.id` through `lisa-linear-access`. "Me" is whoever the tracker credential belongs
+  to, which is often an agent account.
+- **Operators.** `sessionManager.operatorIds` names the people the manager works for (the same
+  kind of id as "me": GitHub login, Jira accountId, Linear user id). Their assigned items come
+  first, then items assigned to "me", then unassigned. Items assigned to anyone else are never
+  dispatched. Never treat an operator's item as someone else's.
 - **Workers** start only through `spawn`. The worker prompt is exactly
   `/lisa:implement <REF> managedBy=<manager-name>`; `lisa-implement` owns what `managedBy=` means.
   Never start a worker another way, and never reuse a worker for another item or a new attempt.
@@ -207,8 +212,8 @@ Skip while `capacity` reports `paused`. Otherwise:
      Raw Jira issues carry `key` and `fields` (summary, priority, assignee, created, labels,
      description, reporter, issuetype, subtasks); raw Linear nodes carry identifier, title, priority,
      createdAt, assignee, labels, description, creator and children with their state type.
-   - `ordered` is the dispatch order (mine, then unassigned, then priority, then age). `excluded`
-     needs no action.
+   - `ordered` is the dispatch order: assigned to an operator, then to "me", then unassigned; each
+     group by priority, then age. `excluded` needs no action.
 2. **While `capacity` says `can_spawn`** and items remain, take the next item that has no pending
    question in the ledger:
    1. Read it fully (`lisa-tracker-read`): title, description, labels, project, parent, comments.
@@ -223,9 +228,11 @@ Skip while `capacity` reports `paused`. Otherwise:
       `cd "$(node "$SM/session-manager.mjs" repo-dir --repo <key> --raw --project-root "$ROOT")"`
       (omit `--repo` on a single-repo project), invoke `lisa-tracker-claim <ref>`, then
       `cd "$ROOT" && pwd` and confirm the path. Continue only on `claimed` or `reused` with the
-      assignee equal to "me"; anything else means skip. Then re-read the item with
-      `lisa-tracker-read`: if the re-read shows a different assignee, or shows the state did not
-      change to the `claimed` role, skip it (someone else holds it, or the claim did not land).
+      assignee equal to "me" or to one of `sessionManager.operatorIds` (the claim assigns only an
+      unassigned item, so an operator's item keeps the operator); anything else means skip. Then
+      re-read the item with `lisa-tracker-read`: if the re-read shows an assignee that is neither
+      "me" nor an operator, or shows the state did not change to the `claimed` role, skip it
+      (someone else holds it, or the claim did not land).
       Never spawn on the claim's word alone.
    4. **Spawn.** `spawn <ref> [--repo <key>]`.
       - exit 0: post `[<REF>] started in <repo> (<name>)` to Telegram.

package/plugins/lisa-copilot/skills/lisa-session-manager/references/runbook-template.md

@@ -18,9 +18,10 @@ session list from `claude agents`; and the project's own Telegram chat.
 
 ## Candidate selection
 
-Leaf items in the `ready` role, ordered: assigned to the operator, then unassigned, then by priority,
-then oldest. Items assigned to someone else, containers, human-held items and (when configured)
-items by untrusted authors are skipped. As many as the machine has capacity for.
+Leaf items in the `ready` role, ordered: assigned to an operator (`sessionManager.operatorIds`),
+then to the manager's own tracker identity, then unassigned; within each, by priority, then oldest.
+Items assigned to someone else, containers, human-held items and (when configured) items by
+untrusted authors are skipped. As many as the machine has capacity for.
 
 ## Scope/bounds
 

package/plugins/lisa-copilot/skills/lisa-session-manager/scripts/cli-manager.mjs

@@ -1,6 +1,7 @@
 /**
- * Manager and setup subcommands of the session-manager CLI: start, stop,
- * status, repo-dir, validate, init-config and store-token.
+ * Manager subcommands of the session-manager CLI: start, stop, status,
+ * repo-dir and validate. The setup ones (init-config, store-token,
+ * trust-status, coexistence) live in cli-setup.mjs.
  *
  * `start` hosts the manager in tmux. It refuses (exit 2) unless the bot
  * token file exists with owner-only permissions in the project's own state
@@ -11,15 +12,11 @@
  * manager's tmux session: workers hold claimed work and keep running.
  * @module session-manager/cli-manager
  */
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import path from "node:path";
-
 import {
   CliError,
   EXIT,
   GLOBAL_CONFIG_FILE,
   asSetupError,
-  asSetupErrorAsync,
   intFlag,
   listAgents,
   loadProject,
@@ -28,12 +25,8 @@ import {
   requireLisaRepo,
   run,
 } from "./cli-runtime.mjs";
-import { buildDefaultBlock, detectRepos, resolveRepoDir } from "./config.mjs";
-import {
-  defaultProjectSlug,
-  probeOwnSession,
-  sessionSurvives,
-} from "./isolation.mjs";
+import { resolveRepoDir } from "./config.mjs";
+import { probeOwnSession, sessionSurvives } from "./isolation.mjs";
 import {
   assertTokenPresent,
   buildForegroundCommand,
@@ -41,7 +34,6 @@ import {
   buildManagerLaunch,
   buildStopManager,
   resolveStateDir,
-  storeToken as storeTokenFile,
 } from "./launch.mjs";
 import { readLedger } from "./ledger.mjs";
 import { parseWorkerName, scrubWorkerEnv } from "./workers.mjs";
@@ -208,69 +200,6 @@ export function validate(ctx) {
   };
 }
 
-/**
- * `init-config [--slug <slug>] [--write]`: the default block for this
- * project, written to `.lisa.config.json` only with `--write` and only when
- * no block exists. Non-secret fields only; the token never goes here.
- * @param {object} ctx - CLI context
- * @returns {{ json: object }} `{written,block,...}`
- */
-export function initConfig(ctx) {
-  const { global } = loadProject(ctx.root);
-  if (global?.sessionManager) {
-    return {
-      json: { written: false, reason: "exists", block: global.sessionManager },
-    };
-  }
-  const slug =
-    ctx.values.slug ?? defaultProjectSlug(ctx.root, global?.github?.repo);
-  const block = asSetupError(() =>
-    buildDefaultBlock({
-      projectSlug: slug,
-      detectedRepos: detectRepos(ctx.root),
-    })
-  );
-  if (!ctx.values.write) return { json: { written: false, block } };
-
-  const file = path.join(ctx.root, GLOBAL_CONFIG_FILE);
-  if (!existsSync(file)) {
-    throw new CliError(
-      `${file} does not exist; set up Lisa in this project first.`,
-      EXIT.SETUP
-    );
-  }
-  const current = JSON.parse(readFileSync(file, "utf8"));
-  writeFileSync(
-    file,
-    `${JSON.stringify({ ...current, sessionManager: block }, null, 2)}\n`
-  );
-  return { json: { written: true, path: file, block } };
-}
-
-/**
- * `store-token [--replace]`: prompt for the bot token on the operator's
- * terminal and write `<stateDir>/.env`. An existing token is kept (exit 2)
- * unless `--replace` is given. With no TTY it prints the command the operator
- * must run themselves and exits 0 with `stored:false`.
- * @param {object} ctx - CLI context
- * @returns {Promise<{ json: object, exitCode: number }>} Outcome
- */
-export async function storeToken(ctx) {
-  const config = requireConfig(ctx);
-  const result = await asSetupErrorAsync(() =>
-    storeTokenFile({
-      stateDir: config.notify?.stateDir,
-      scriptsDir: ctx.scriptsDir,
-      projectRoot: ctx.root,
-      replace: ctx.values.replace === true,
-      env: ctx.env,
-      homedir: ctx.homedir,
-    })
-  );
-  const refused = result.stored === false && result.reason !== "no-tty";
-  return { json: result, exitCode: refused ? EXIT.SETUP : EXIT.OK };
-}
-
 /**
  * `status`: is the manager's tmux session up, and what does the ledger say
  * about each worker it dispatched.

package/plugins/lisa-copilot/skills/lisa-session-manager/scripts/cli-queue.mjs

@@ -123,9 +123,11 @@ function readEnvelopeQueue(ctx, tracker) {
 }
 
 /**
- * `queue --tracker <github|jira|linear>`: the Ready queue, mine first.
+ * `queue --tracker <github|jira|linear>`: the Ready queue, the operator's
+ * items first (`sessionManager.operatorIds`), then mine, then unassigned.
  * @param {object} ctx - CLI context
- * @returns {Promise<{ json: object }>} `{tracker,me,total,pages,ordered,excluded}`
+ * @returns {Promise<{ json: object }>}
+ *   `{tracker,me,operators,total,pages,ordered,excluded}`
  */
 export async function queue(ctx) {
   const tracker = ctx.values.tracker;
@@ -139,10 +141,14 @@ export async function queue(ctx) {
       ? fetchGithubQueue(ctx, project)
       : readEnvelopeQueue(ctx, tracker);
   const me = ctx.values.me ?? (await readLedger(ctx.root)).control.me ?? null;
+  const operators = config?.operatorIds ?? [];
   const order = orderReadyQueue(items, {
     me,
+    operators,
     trustedAuthorIds: config?.trustedAuthorIds ?? undefined,
     humanNeededLabel: humanNeededLabel(project, tracker),
   });
-  return { json: { tracker, me, total: items.length, pages, ...order } };
+  return {
+    json: { tracker, me, operators, total: items.length, pages, ...order },
+  };
 }

package/plugins/lisa-copilot/skills/lisa-session-manager/scripts/cli-runtime.mjs

@@ -126,6 +126,7 @@ function validationView(config) {
     ...config,
     repos: config.repos ?? undefined,
     trustedAuthorIds: config.trustedAuthorIds ?? undefined,
+    operatorIds: config.operatorIds,
   };
 }
 

package/plugins/lisa-copilot/skills/lisa-session-manager/scripts/cli-setup.mjs

@@ -0,0 +1,165 @@
+/**
+ * Setup subcommands of the session-manager CLI: init-config, store-token,
+ * trust-status and coexistence. Each one answers a question
+ * `lisa-setup-session-manager` would otherwise put to the operator, so setup
+ * asks only what a script cannot find out.
+ * @module session-manager/cli-setup
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import {
+  CliError,
+  EXIT,
+  GLOBAL_CONFIG_FILE,
+  asSetupError,
+  asSetupErrorAsync,
+  loadProject,
+  requireConfig,
+} from "./cli-runtime.mjs";
+import {
+  buildDefaultBlock,
+  detectRepos,
+  draftHints,
+  resolveRepoDir,
+} from "./config.mjs";
+import { defaultProjectSlug } from "./isolation.mjs";
+import {
+  storeToken as storeTokenFile,
+  storeTokenFromClipboard,
+} from "./launch.mjs";
+import {
+  coexistence as readCoexistence,
+  trustStatus as readTrust,
+} from "./setup-checks.mjs";
+
+/**
+ * `init-config [--slug <slug>] [--write]`: the default block for this
+ * project, written to `.lisa.config.json` only with `--write` and only when
+ * no block exists. Non-secret fields only; the token never goes here. Repos
+ * are the routable children `detectRepos` finds (linked worktrees and second
+ * clones of one remote left out), each with drafted hints.
+ * @param {object} ctx - CLI context
+ * @returns {{ json: object }} `{written,block,...}`
+ */
+export function initConfig(ctx) {
+  const { global } = loadProject(ctx.root);
+  if (global?.sessionManager) {
+    return {
+      json: { written: false, reason: "exists", block: global.sessionManager },
+    };
+  }
+  const slug =
+    ctx.values.slug ?? defaultProjectSlug(ctx.root, global?.github?.repo);
+  const detectedRepos = detectRepos(ctx.root);
+  const hints = Object.fromEntries(
+    detectedRepos.map(name => [
+      name,
+      draftHints(path.join(ctx.root, "projects", name), name),
+    ])
+  );
+  const block = asSetupError(() =>
+    buildDefaultBlock({ projectSlug: slug, detectedRepos, hints })
+  );
+  if (!ctx.values.write) return { json: { written: false, block } };
+
+  const file = path.join(ctx.root, GLOBAL_CONFIG_FILE);
+  if (!existsSync(file)) {
+    throw new CliError(
+      `${file} does not exist; set up Lisa in this project first.`,
+      EXIT.SETUP
+    );
+  }
+  const current = JSON.parse(readFileSync(file, "utf8"));
+  writeFileSync(
+    file,
+    `${JSON.stringify({ ...current, sessionManager: block }, null, 2)}\n`
+  );
+  return { json: { written: true, path: file, block } };
+}
+
+/**
+ * `store-token [--replace] [--from-clipboard]`: store the bot token in the
+ * project's state dir. By default it prompts on the operator's terminal (echo
+ * off); with no TTY it prints the two commands that work instead and exits 0
+ * with `stored:false`. `--from-clipboard` reads the system clipboard and needs
+ * no TTY. An existing token is kept (exit 2) unless `--replace` is given.
+ * @param {object} ctx - CLI context
+ * @returns {Promise<{ json: object, exitCode: number }>} Outcome
+ */
+export async function storeToken(ctx) {
+  const config = requireConfig(ctx);
+  const input = {
+    stateDir: config.notify?.stateDir,
+    scriptsDir: ctx.scriptsDir,
+    projectRoot: ctx.root,
+    replace: ctx.values.replace === true,
+    env: ctx.env,
+    homedir: ctx.homedir,
+  };
+  const result = ctx.values["from-clipboard"]
+    ? asSetupError(() => storeTokenFromClipboard(input))
+    : await asSetupErrorAsync(() => storeTokenFile(input));
+  const refused = result.stored === false && result.reason !== "no-tty";
+  return { json: result, exitCode: refused ? EXIT.SETUP : EXIT.OK };
+}
+
+/**
+ * Every directory a worker can start in: each routed repo, or the root on a
+ * single-repo project.
+ * @param {object} ctx - CLI context
+ * @param {object} config - Resolved block
+ * @returns {string[]} Absolute directories
+ */
+function workerDirs(ctx, config) {
+  const keys = Object.keys(config.repos?.entries ?? {});
+  if (keys.length === 0) return [ctx.root];
+  return keys.map(key =>
+    asSetupError(() => resolveRepoDir(config, key, ctx.root))
+  );
+}
+
+/**
+ * `trust-status`: whether Claude Code has recorded workspace trust for each
+ * worker directory. Exit 0 either way; setup asks the operator only about the
+ * rows that are not `trusted: true`.
+ * @param {object} ctx - CLI context
+ * @returns {{ json: object }} `{file,dirs:[{dir,trusted}],needsTrust}`
+ */
+export function trustStatus(ctx) {
+  const config = requireConfig(ctx);
+  const report = readTrust({
+    dirs: workerDirs(ctx, config),
+    env: ctx.env,
+    homedir: ctx.homedir,
+  });
+  return {
+    json: {
+      ...report,
+      needsTrust: report.dirs
+        .filter(row => row.trusted !== true)
+        .map(row => row.dir),
+    },
+  };
+}
+
+/**
+ * `coexistence`: what this project's run logs say about the scheduled intake
+ * loops that compete with the manager. Exit 0 either way.
+ * @param {object} ctx - CLI context
+ * @returns {{ json: object }} `{windowHours,loops:[...],live}`
+ */
+export function coexistence(ctx) {
+  const config = requireConfig(ctx);
+  const report = readCoexistence({
+    root: ctx.root,
+    now: ctx.now(),
+    stall: config.stall,
+  });
+  return {
+    json: {
+      ...report,
+      live: report.loops.filter(row => row.recent).map(row => row.loop),
+    },
+  };
+}

package/plugins/lisa-copilot/skills/lisa-session-manager/scripts/cli-usage.mjs

@@ -61,12 +61,19 @@ Manager
   stop       tmux kill-session -t =<name> only, and only for a session started
              in this root (exit 2 otherwise); workers keep running.
              stdout {status:"stopped"|"not-running",name}.
-  store-token [--replace]
+  store-token [--replace] [--from-clipboard]
              Prompts for the bot token on the terminal (echo off) and writes
              <stateDir>/.env. Exit 2 when a token is already there, unless
-             --replace. With no TTY: exit 0, stdout {stored:false,
-             reason:"no-tty",command} where command is the line the operator
-             runs in their own terminal. Bad input: exit 2.
+             --replace. With no TTY (an agent's Bash, and Claude Code's !
+             prefix too): exit 0, stdout {stored:false,reason:"no-tty",
+             message,command,clipboardCommand}; command is the line the
+             operator runs in a separate terminal app.
+             --from-clipboard reads the token from the clipboard instead
+             (pbpaste; wl-paste, xclip or xsel on Linux), needs no TTY, and
+             clears the clipboard after a successful store. stdout
+             {stored:true,path,clipboardCleared}. The token is never printed.
+             Bad input, empty clipboard or no clipboard tool: exit 2,
+             {stored:false,reason,message}.
 
 Config and routing
   repo-dir [--repo <key>] [--raw]
@@ -75,10 +82,27 @@ Config and routing
   validate   stdout {valid,errors}; exit 2 when invalid or absent.
   init-config [--slug <slug>] [--write]
              stdout {written,block[,reason:"exists"][,path]}. Detects
-             projects/*/.lisa.config.json. Default slug: <github.repo or
-             folder name>-<first 6 hex of sha256(realpath(root))>; --slug is
-             used as given. --write adds the block to .lisa.config.json,
-             never overwriting an existing one.
+             projects/*/.lisa.config.json, skipping linked worktrees (.git is
+             a file) and keeping one child per origin remote (the one named
+             after the repo, else the first by name). Each repo's hints are a
+             draft: its name, then one per well-known package.json dependency
+             (e.g. @nestjs/* -> NestJS, expo -> Expo, aws-cdk-lib -> AWS CDK).
+             Default slug: <github.repo or folder name>-<first 6 hex of
+             sha256(realpath(root))>; --slug is used as given. --write adds
+             the block to .lisa.config.json, never overwriting an existing one.
+  trust-status
+             stdout {file,dirs:[{dir,trusted:true|false|"unknown"}],
+             needsTrust:[dir]}: whether Claude Code has recorded workspace
+             trust (hasTrustDialogAccepted in $CLAUDE_CONFIG_DIR/.claude.json,
+             else ~/.claude.json) for each worker dir. "unknown" when that
+             file cannot be read. Read-only; never accepts trust.
+  coexistence
+             stdout {windowHours,loops:[{loop,log,lastRun:{ts,outcome}|null,
+             recent}],live:[loop]} for intake-tickets and intake-repair, from
+             .lisa/automations/runs/<loop>.jsonl. recent = last run within
+             windowHours (2 x stall.noOutputMinutes x stall.maxAttempts, at
+             least 24h). Run logs only: the runtime's scheduler is the
+             authority on whether a loop is still scheduled.
 
 Per cycle
   queue --tracker github [--me <id>] [--label <name>] [--github-repo <o/r>]
@@ -87,7 +111,10 @@ Per cycle
   queue --tracker jira|linear --input <file> [--me <id>]
       <file> = {complete:true,pages,items:[raw vendor issues]}; exit 2 unless
       complete is exactly true.
-      Both print {tracker,me,total,pages,ordered,excluded:[{ref,reason}]}.
+      Both print {tracker,me,operators,total,pages,ordered,excluded:[{ref,
+      reason}]}. ordered: items assigned to sessionManager.operatorIds
+      first, then to --me, then unassigned; each group by priority, then age.
+      Items assigned to anyone else are excluded (assigned-to-other).
       --me defaults to the ledger's control.me.
   ledger get [<ref>]
   ledger record-spawn <ref> --worker <name> [--session-id <id>] [--repo <key>]

package/plugins/lisa-copilot/skills/lisa-session-manager/scripts/clipboard.mjs

@@ -0,0 +1,119 @@
+/**
+ * Read and clear the system clipboard, for `store-token --from-clipboard`.
+ *
+ * `store-token` prompts on a TTY with echo off, and an agent's Bash has no
+ * TTY. Neither does Claude Code's `!` prefix, which is the first thing an
+ * operator inside Claude Code tries, so the only working route used to be a
+ * separate terminal app (CodySwannGT/lisa#4465). The clipboard is the route an
+ * operator reaches for instead: they copy the token from BotFather and the
+ * agent stores it without ever seeing it.
+ *
+ * What is read is a secret. It is returned to the caller and never placed in
+ * an error message, a log line or a return value of anything else here.
+ * @module session-manager/clipboard
+ */
+import { spawnSync } from "node:child_process";
+
+/** Upper bound for one clipboard tool call. */
+const TOOL_TIMEOUT_MS = 5000;
+
+/**
+ * Clipboard tools per platform, tried in order: the first one that runs is
+ * used for both reading and clearing.
+ */
+const TOOLS = Object.freeze({
+  darwin: [{ name: "pbpaste", read: ["pbpaste"], clear: ["pbcopy"] }],
+  linux: [
+    {
+      name: "wl-paste",
+      read: ["wl-paste", "--no-newline"],
+      clear: ["wl-copy", "--clear"],
+    },
+    {
+      name: "xclip",
+      read: ["xclip", "-o", "-selection", "clipboard"],
+      clear: ["xclip", "-i", "-selection", "clipboard"],
+    },
+    {
+      name: "xsel",
+      read: ["xsel", "--clipboard", "--output"],
+      clear: ["xsel", "--clipboard", "--clear"],
+    },
+  ],
+});
+
+/**
+ * Run one tool with empty stdin.
+ *
+ * A clear (`capture: false`) discards the tool's output instead of piping it:
+ * `xclip -i` forks a background selection owner, and a child holding an
+ * inherited pipe makes `spawnSync` wait out the whole timeout. Any spawn
+ * error (a timeout included) is a failure, never a success.
+ * @param {string[]} argv - Command and arguments
+ * @param {{ capture?: boolean }} [options] - Whether to capture stdout
+ * @returns {{ status: number | null, stdout: string, missing: boolean }}
+ *   Outcome; `missing` when the binary is not on PATH
+ */
+function runTool([command, ...args], { capture = true } = {}) {
+  const result = spawnSync(command, args, {
+    input: "",
+    encoding: "utf8",
+    timeout: TOOL_TIMEOUT_MS,
+    stdio: ["pipe", capture ? "pipe" : "ignore", "ignore"],
+  });
+  return {
+    status: result.error ? null : result.status,
+    stdout: result.stdout ?? "",
+    missing: result.error?.code === "ENOENT",
+  };
+}
+
+/**
+ * Read the clipboard with the first available tool for `platform`.
+ * @param {{ platform?: string, run?: typeof runTool }} [seams] - Platform and
+ *   the tool runner
+ * @returns {{ ok: true, text: string, clear: () => boolean } |
+ *   { ok: false, reason: "unsupported" | "unavailable" | "failed",
+ *     message: string }} The text and a function that clears the clipboard
+ *   (true when it did), or why nothing was read
+ */
+export function readClipboard(seams = {}) {
+  const platform = seams.platform ?? process.platform;
+  const run = seams.run ?? runTool;
+  const tools = TOOLS[platform];
+  if (!tools) {
+    return {
+      ok: false,
+      reason: "unsupported",
+      message: `Reading the clipboard is not supported on ${platform}.`,
+    };
+  }
+  const failed = [];
+  for (const tool of tools) {
+    const result = run(tool.read);
+    if (result.missing) continue;
+    // An installed tool can still fail where another works (wl-paste on an
+    // X11 session), so a failure moves on to the next tool.
+    if (result.status !== 0) {
+      failed.push(`${tool.name} exited ${result.status}`);
+      continue;
+    }
+    return {
+      ok: true,
+      text: result.stdout,
+      clear: () => run(tool.clear, { capture: false }).status === 0,
+    };
+  }
+  if (failed.length > 0) {
+    return {
+      ok: false,
+      reason: "failed",
+      message: `${failed.join("; ")}; nothing was read.`,
+    };
+  }
+  return {
+    ok: false,
+    reason: "unavailable",
+    message: `No clipboard tool found (tried ${tools.map(t => t.name).join(", ")}).`,
+  };
+}