@codyswann/lisa 4.85.0 → 4.86.0

package/plugins/lisa/.codex-plugin/skills/lisa-session-manager/scripts/queue-github.mjs

@@ -0,0 +1,117 @@
+/**
+ * The GitHub fetches behind the session-manager `queue` subcommand, split out
+ * of cli-queue.mjs to keep it under the line budget (#4555): the Ready tier
+ * ({@link fetchGithubQueue}) and the backlog tier ({@link fetchGithubBacklog}).
+ * Both read with `gh api --paginate --slurp`, so every page is read or the
+ * command fails, and both run gh with the scrubbed worker env.
+ * @module session-manager/queue-github
+ */
+import { normalizeGithubIssue } from "../../../scripts/ready-queue-order.mjs";
+import { resolveRole } from "../../../scripts/resolve-lifecycle-role.mjs";
+import { CliError, mustRun } from "./cli-runtime.mjs";
+import { parseJson } from "./json-input.mjs";
+import { scrubWorkerEnv } from "./workers.mjs";
+
+const OWNER_REPO = /^[\w.-]+\/[\w.-]+$/;
+
+/**
+ * The GitHub repo to read: `--github-repo`, else github.org/github.repo.
+ * @param {object} ctx - CLI context
+ * @param {{global?: object, local?: object}} project - Loaded project
+ * @returns {string} `owner/repo`
+ */
+function githubRepo(ctx, project) {
+  const merged = { ...project.global?.github, ...project.local?.github };
+  const repo =
+    ctx.values["github-repo"] ??
+    (merged.org && merged.repo ? `${merged.org}/${merged.repo}` : "");
+  if (!OWNER_REPO.test(repo)) {
+    throw new CliError(
+      "No GitHub repo: set github.org and github.repo, or pass --github-repo <owner/repo>.",
+      2
+    );
+  }
+  return repo;
+}
+
+/**
+ * Every string leaf of an object (label names, including env-keyed `done`).
+ * @param {unknown} value - Config subtree
+ * @returns {string[]} Leaves
+ */
+function stringLeaves(value) {
+  if (typeof value === "string") return value ? [value] : [];
+  if (!value || typeof value !== "object") return [];
+  return Object.values(value).flatMap(stringLeaves);
+}
+
+/**
+ * Fetch every open GitHub issue carrying no lifecycle label (build or PRD),
+ * all pages: the GitHub backlog tier.
+ * @param {object} ctx - CLI context
+ * @param {{global?: object, local?: object}} project - Loaded project
+ * @returns {{ items: object[], pages: number }} Normalized items
+ */
+export function fetchGithubBacklog(ctx, project) {
+  const repo = githubRepo(ctx, project);
+  const lifecycle = new Set(
+    [project.global?.github?.labels, project.local?.github?.labels]
+      .flatMap(labels => [
+        ...stringLeaves(labels?.build),
+        ...stringLeaves(labels?.prd),
+      ])
+      .map(label => label.toLowerCase())
+  );
+  const stdout = mustRun(
+    "gh",
+    [
+      "api",
+      "--paginate",
+      "--slurp",
+      `repos/${repo}/issues?state=open&per_page=100`,
+    ],
+    { env: scrubWorkerEnv(ctx.env) }
+  );
+  const pages = parseJson(stdout, "gh api output");
+  const rows = Array.isArray(pages) ? pages.flat() : [];
+  return {
+    items: rows
+      .map(row => normalizeGithubIssue(row, { repo }))
+      .filter(Boolean)
+      .filter(
+        item => !item.labels.some(label => lifecycle.has(label.toLowerCase()))
+      ),
+    pages: Array.isArray(pages) ? pages.length : 0,
+  };
+}
+
+/**
+ * Fetch every open GitHub issue carrying the ready label, all pages.
+ * @param {object} ctx - CLI context
+ * @param {{global?: object, local?: object}} project - Loaded project
+ * @returns {{ items: object[], pages: number }} Normalized items
+ */
+export function fetchGithubQueue(ctx, project) {
+  const repo = githubRepo(ctx, project);
+  const role = resolveRole({
+    role: "ready",
+    vendor: "github",
+    intent: "read",
+    local: project.local,
+    global: project.global,
+  });
+  const label = ctx.values.label ?? role.value;
+  if (!label) throw new CliError(role.message, 2);
+  const endpoint =
+    `repos/${repo}/issues?state=open&labels=${encodeURIComponent(label)}` +
+    `&per_page=100`;
+  const stdout = mustRun("gh", ["api", "--paginate", "--slurp", endpoint], {
+    env: scrubWorkerEnv(ctx.env),
+  });
+  const pages = parseJson(stdout, "gh api output");
+  const rows = Array.isArray(pages) ? pages.flat() : [];
+  return {
+    items: rows.map(row => normalizeGithubIssue(row, { repo })).filter(Boolean),
+    pages: Array.isArray(pages) ? pages.length : 0,
+  };
+}

package/plugins/lisa/.codex-plugin/skills/lisa-session-manager/scripts/session-manager.mjs

@@ -18,7 +18,11 @@
  * background sessions (`claude --bg`, `claude agents`), cross-session
  * messaging and channels, which no other supported agent has. Codex, Cursor,
  * OpenCode, Antigravity, Copilot and Devin can run the setup-time subcommands
- * (init-config, store-token, trust-status, coexistence, validate, start), and
+ * (init-config, store-token into the configured secrets provider,
+ * trust-status, coexistence, validate, start), `status` (pending questions
+ * and their answerCommand) and `answer` (an operator answering a pending
+ * question at the terminal), from the Claude Code plugin install or the npm
+ * package only (never the Codex overlay copy), and
  * `start` hosts a Claude Code manager in tmux whatever agent ran it. Note that
  * trust-status reads Claude Code's own trust record, which is the one that
  * matters: workers are always Claude Code. They cannot run a manager cycle
@@ -41,6 +45,7 @@ import {
   recordCycle,
   route,
 } from "./cli-cycle.mjs";
+import { answer, itemAnswer, markPlan } from "./cli-human.mjs";
 import { repoDir, start, status, stop, validate } from "./cli-manager.mjs";
 import { queue } from "./cli-queue.mjs";
 import { CliError, EXIT } from "./cli-runtime.mjs";
@@ -68,7 +73,7 @@ const COMMANDS = {
   stop: { run: stop, options: {}, positionals: 0 },
   "store-token": {
     run: storeToken,
-    options: { replace: flag, "from-clipboard": flag },
+    options: { replace: flag, "from-clipboard": flag, "vault-project": text },
     positionals: 0,
   },
   "trust-status": { run: trustStatus, options: {}, positionals: 0 },
@@ -81,7 +86,7 @@ const COMMANDS = {
   validate: { run: validate, options: {}, positionals: 0 },
   "init-config": {
     run: initConfig,
-    options: { slug: text, write: flag },
+    options: { slug: text, write: flag, notify: text },
     positionals: 0,
   },
   queue: {
@@ -106,6 +111,9 @@ const COMMANDS = {
     options: { input: text, ref: text },
     positionals: 0,
   },
+  "mark-plan": { run: markPlan, options: { kind: text }, positionals: 1 },
+  answer: { run: answer, options: {}, positionals: 1 },
+  "item-answer": { run: itemAnswer, options: {}, positionals: 1 },
   "record-cycle": {
     run: recordCycle,
     options: {
@@ -125,10 +133,14 @@ const LEDGER_SPECS = {
     positionals: 1,
   },
   "set-question": {
-    options: { "telegram-message-id": text, sender: text },
+    options: { "telegram-message-id": text, sender: text, kind: text },
     positionals: 1,
   },
-  "clear-question": { options: {}, positionals: 1 },
+  marked: {
+    options: { "marker-type": text, marker: text, "comment-id": text },
+    positionals: 1,
+  },
+  "clear-question": { options: { "reset-attempts": flag }, positionals: 1 },
   finish: { options: { status: text, sender: text }, positionals: 1 },
   "validation-failed": { options: { "updated-at": text }, positionals: 1 },
   "validation-cleared": { options: {}, positionals: 1 },

package/plugins/lisa/.codex-plugin/skills/lisa-session-manager/scripts/token-migrate.mjs

@@ -0,0 +1,180 @@
+/**
+ * Migrating the old plaintext Telegram bot token file into the secrets
+ * provider (#4555): reading `<notify.stateDir>/.env`, deciding whether it
+ * may be deleted, and the refusals `store-token` and `start` share.
+ *
+ * Split from token-store.mjs, which keeps the provider calls. The two sides
+ * of the migration must agree on what counts as a leftover token, or an
+ * operator is sent round a loop: `start` refuses only a file that really
+ * holds a `TELEGRAM_BOT_TOKEN` line ({@link holdsToken}), and `store-token`
+ * deletes a file with no token and nothing else in it (empty, or comments
+ * only) once the provider holds a verified secret ({@link removable}).
+ *
+ * Values are never kept beyond the comparison, returned in a message or
+ * logged; a file's other keys are reported by name only.
+ * @module session-manager/token-migrate
+ */
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+import { validateBotToken } from "./token.mjs";
+
+/** The plugin's plaintext token file in the state dir (the old storage). */
+export const TOKEN_FILE = ".env";
+
+/** The variable the Telegram plugin reads its token from. */
+export const TOKEN_VAR = "TELEGRAM_BOT_TOKEN";
+
+/** One `KEY=value` line of a dotenv file, optionally `export`ed. */
+const ENV_LINE = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
+
+/** A refusal or failure carrying the exit code the CLI should use. */
+export class TokenStoreError extends Error {
+  /**
+   * @param {string} message - Operator-readable reason; never a value
+   * @param {number} exitCode - 1 (failure, retry) or 2 (setup)
+   */
+  constructor(message, exitCode) {
+    super(message);
+    this.name = "TokenStoreError";
+    this.exitCode = exitCode;
+  }
+}
+
+/**
+ * Exit 2: something the operator has to change.
+ * @param {string} message - Reason
+ * @returns {TokenStoreError} Error
+ */
+export const setupError = message => new TokenStoreError(message, 2);
+
+/**
+ * sha256 of a value, for comparing a written secret with its read-back.
+ * @param {string} value - Value
+ * @returns {string} Hex digest
+ */
+export function digest(value) {
+  return createHash("sha256").update(String(value)).digest("hex");
+}
+
+/**
+ * Read the plaintext token file, if there is one: its token, and the names
+ * of anything else in it (values are never kept or reported).
+ * @param {string} stateDir - Resolved state dir
+ * @param {Pick<import("node:fs"), "existsSync" | "readFileSync">} fs - Seam
+ * @returns {{ path: string, token: string | undefined, others: string[] } |
+ *   null} The file, or null when absent
+ */
+export function readEnvFile(stateDir, fs) {
+  const file = path.join(stateDir, TOKEN_FILE);
+  if (!fs.existsSync(file)) return null;
+  const entries = fs
+    .readFileSync(file, "utf8")
+    .split(/\r?\n/)
+    .map((line, at) => ({ line: line.trim(), at }))
+    .filter(({ line }) => line !== "" && !line.startsWith("#"))
+    .map(({ line, at }) => ({ match: ENV_LINE.exec(line), at }));
+  const token = entries.find(({ match }) => match?.[1] === TOKEN_VAR)?.match;
+  return {
+    path: file,
+    token: token ? token[2].replace(/^(['"])(.*)\1$/, "$2") : undefined,
+    others: entries
+      .filter(({ match }) => match?.[1] !== TOKEN_VAR)
+      .map(({ match, at }) => match?.[1] ?? `an unrecognised line ${at + 1}`),
+  };
+}
+
+/**
+ * Whether a token file really holds a token: what `start` refuses.
+ * @param {ReturnType<typeof readEnvFile>} file - The file, if any
+ * @returns {boolean} True for a `TELEGRAM_BOT_TOKEN` line
+ */
+export function holdsToken(file) {
+  return file !== null && file.token !== undefined;
+}
+
+/**
+ * Whether a file holds nothing at all (empty, blank or comments only), so
+ * `store-token` may delete it once the provider holds a verified secret.
+ * @param {ReturnType<typeof readEnvFile>} file - The file, if any
+ * @returns {boolean} True for a removable empty file
+ */
+export function removable(file) {
+  return file !== null && file.token === undefined && file.others.length === 0;
+}
+
+/**
+ * Refuse a plaintext file that cannot be migrated as it is.
+ * @param {ReturnType<typeof readEnvFile>} file - The file, if any
+ */
+export function assertMigratable(file) {
+  if (file === null) return;
+  if (file.others.length > 0) {
+    throw setupError(
+      `${file.path} holds ${file.others.join(", ")} besides ${TOKEN_VAR}, so ` +
+        `it cannot be deleted after the token moves. Move the rest out of it, ` +
+        `then run store-token again. Nothing was changed.`
+    );
+  }
+  if (file.token !== undefined && !validateBotToken(file.token)) {
+    throw setupError(
+      `${file.path} holds a ${TOKEN_VAR} that does not look like a Telegram ` +
+        `bot token. Fix or delete the file, then run store-token again. ` +
+        `Nothing was changed.`
+    );
+  }
+}
+
+/**
+ * Delete the plaintext file after the provider's copy is verified, and say
+ * so: `migratedFrom` when its token moved, `deleted` whenever it went.
+ * @param {ReturnType<typeof readEnvFile>} file - The file, if any
+ * @param {Pick<import("node:fs"), "rmSync">} fs - Seam
+ * @returns {{ migratedFrom?: string, deleted?: true }} What was removed
+ */
+export function removeAfterVerify(file, fs) {
+  if (holdsToken(file)) {
+    fs.rmSync(file.path);
+    return { migratedFrom: file.path, deleted: true };
+  }
+  if (removable(file)) {
+    fs.rmSync(file.path);
+    return { deleted: true };
+  }
+  return {};
+}
+
+/**
+ * The result for a secret the provider already holds (no write): a matching
+ * or empty plaintext file is deleted; one holding a different token is kept
+ * and refused.
+ * @param {{ value: string }} existing - The stored secret
+ * @param {ReturnType<typeof readEnvFile>} file - The plaintext file, if any
+ * @param {{ cfg: object, name: string, fs: object }} input - Context
+ * @returns {object} Outcome
+ */
+export function keepExisting(existing, file, { cfg, name, fs }) {
+  const result = {
+    stored: true,
+    storage: "provider",
+    provider: cfg.provider,
+    secret: name,
+    verified: true,
+    alreadyStored: true,
+  };
+  if (!validateBotToken(existing.value)) {
+    throw setupError(
+      `${name} in ${cfg.provider} does not look like a Telegram bot token. ` +
+        `Run store-token --replace to store the right one.`
+    );
+  }
+  if (holdsToken(file) && digest(file.token) !== digest(existing.value)) {
+    throw setupError(
+      `${file.path} holds a different token from the one ${cfg.provider} ` +
+        `already stores as ${name}. Nothing was changed. To make the file's ` +
+        `token the stored one, run store-token --replace; to keep the stored ` +
+        `one, delete ${file.path}.`
+    );
+  }
+  return { ...result, ...removeAfterVerify(file, fs) };
+}

package/plugins/lisa/.codex-plugin/skills/lisa-session-manager/scripts/token-provider.mjs

@@ -0,0 +1,150 @@
+/**
+ * Talking to the secrets provider for the Telegram bot token (#4555): the
+ * adapter over `lisa-secrets-access` (`surfaces.mjs` for the config,
+ * `providers.mjs` for reads and writes), whether a provider is configured at
+ * all, and turning a provider error into fixed operator text.
+ *
+ * Split from token-store.mjs, which keeps the store and resolve flows. The
+ * adapter is injectable so tests run against a fake vault. A provider's raw
+ * error is matched, never repeated: a failed write's error can quote its
+ * argv, which holds the value.
+ * @module session-manager/token-provider
+ */
+import { TokenStoreError, setupError } from "./token-migrate.mjs";
+
+/** A provider error that names a rate limit (HTTP 429). */
+const RATE_LIMITED = /\b429\b|too many requests|rate.?limit/i;
+
+/** The bootstrap prefix whose CLI each provider runs, for the preflight. */
+const CLI_PREFIX = { bitwarden: "BWS_ACCESS_TOKEN", doppler: "DOPPLER_TOKEN" };
+
+/** Operator-facing reasons, by {@link classifyProviderFailure} kind. */
+const REASONS = {
+  "rate-limited": "it rate-limited the request (429 Too Many Requests)",
+  "timed-out": "it did not answer in time",
+  unavailable: "it could not be reached or refused the request",
+};
+
+/**
+ * What went wrong talking to the provider, read from the error's code and
+ * text only (the text is matched, never repeated).
+ * @param {unknown} error - Caught value
+ * @returns {"setup" | "missing-cli" | "timed-out" | "rate-limited" |
+ *   "unsupported" | "duplicate" | "unavailable"} Kind
+ */
+export function classifyProviderFailure(error) {
+  const text = `${error?.message ?? ""} ${error?.stderr ?? ""}`;
+  if (error?.kind === "setup") return "setup";
+  if (error?.code === "ENOENT") return "missing-cli";
+  if (error?.code === "ETIMEDOUT" || /at its own deadline/.test(text)) {
+    return "timed-out";
+  }
+  if (RATE_LIMITED.test(text)) return "rate-limited";
+  if (/has no (bulk read|create|write) implemented/.test(text)) {
+    return "unsupported";
+  }
+  if (/duplicate secret key/.test(text)) return "duplicate";
+  return "unavailable";
+}
+
+/**
+ * Turn a provider error into a {@link TokenStoreError} with fixed text.
+ * @param {unknown} error - Caught value
+ * @param {{ provider: string, name: string, retry: string }} where - The
+ *   provider, the secret, and the retry advice for a transient failure
+ * @returns {TokenStoreError} Error
+ */
+export function providerError(error, { provider, name, retry }) {
+  const kind = classifyProviderFailure(error);
+  if (kind === "setup") return setupError(String(error.message));
+  if (kind === "missing-cli") {
+    return setupError(
+      `The ${provider} command-line tool is not on PATH. Install it with ` +
+        `/lisa:setup:workstation, then try again.`
+    );
+  }
+  if (kind === "unsupported") {
+    return setupError(
+      `Lisa cannot read or write ${name} in provider "${provider}" yet. ` +
+        `Create ${name} in ${provider} yourself, then run store-token to ` +
+        `verify it and remove any plaintext copy.`
+    );
+  }
+  if (kind === "duplicate") {
+    return setupError(
+      `${provider} shows more than one secret with the same name, so Lisa ` +
+        `will not guess which is ${name}. Remove the duplicate in ${provider}.`
+    );
+  }
+  return new TokenStoreError(`${retry.replace("<reason>", REASONS[kind])}`, 1);
+}
+
+/**
+ * The lazily-loaded secrets adapter over `lisa-secrets-access`, by path
+ * relative to this file (the way token.mjs loads prompt-secret.mjs).
+ * @returns {Promise<{ readConfig: Function, preflight: Function,
+ *   list: Function, create: Function, replace: Function }>} Adapter
+ */
+export async function defaultSecretsAdapter() {
+  const base = new URL("../../lisa-secrets-access/scripts/", import.meta.url);
+  const [surfaces, providers] = await Promise.all([
+    import(new URL("surfaces.mjs", base).href),
+    import(new URL("providers.mjs", base).href),
+  ]);
+  return {
+    readConfig: (root, env) => surfaces.readConfig(root, env),
+    preflight: cfg => {
+      const prefix = CLI_PREFIX[cfg.provider];
+      if (prefix && providers.providerCliPresent(prefix) === false) {
+        throw Object.assign(new Error("missing"), { code: "ENOENT" });
+      }
+      try {
+        providers.bootstrapToken(cfg.bootstrap);
+      } catch (error) {
+        throw Object.assign(new Error(error.message), { kind: "setup" });
+      }
+    },
+    list: cfg =>
+      [...providers.normalizeRows(providers.fetchRaw(cfg), cfg.narrow)].map(
+        ([key, row]) => ({ key, ...row })
+      ),
+    create: (cfg, secret) => providers.createSecret(cfg, secret),
+    replace: (cfg, { id, value }) => providers.writeSecret(cfg, id, value),
+  };
+}
+
+/**
+ * The project's secrets config and adapter, or `null` when no provider is
+ * configured (no `secrets` block, or `provider: "env"`): then the token stays
+ * in the state dir's `.env` file.
+ * @param {string} root - Project root
+ * @param {Record<string, string | undefined>} env - Environment
+ * @param {object} [adapter] - Injected adapter (tests)
+ * @returns {Promise<{ cfg: object, adapter: object } | null>} Provider mode
+ */
+export async function loadTokenSecrets(root, env, adapter) {
+  const secrets = adapter ?? (await defaultSecretsAdapter());
+  let cfg;
+  try {
+    cfg = secrets.readConfig(root, env);
+  } catch (error) {
+    throw setupError(`Could not read the secrets config: ${error.message}`);
+  }
+  const configured =
+    typeof cfg?.provider === "string" && cfg.provider !== "env";
+  return configured ? { cfg, adapter: secrets } : null;
+}
+
+/**
+ * Call the adapter, turning a provider error into a {@link TokenStoreError}.
+ * @param {() => unknown} call - Adapter call
+ * @param {{ provider: string, name: string, retry: string }} where - Context
+ * @returns {Promise<unknown>} The call's result
+ */
+export async function guarded(call, where) {
+  try {
+    return await call();
+  } catch (error) {
+    throw providerError(error, where);
+  }
+}

package/plugins/lisa/.codex-plugin/skills/lisa-session-manager/scripts/token-read.mjs

@@ -0,0 +1,166 @@
+/**
+ * Reading the Telegram bot token from the operator, and the shell lines that
+ * name the `store-token` command: token shape validation, the echo-off
+ * prompt, the clipboard reader, and the command printed when there is no TTY.
+ * Nothing here writes a file or prints the token. Split out of token.mjs to
+ * keep it under the line budget (#4555); token.mjs re-exports every export,
+ * and token-store.mjs reuses the readers for the secrets-provider path.
+ * @module token-read
+ */
+import path from "node:path";
+
+import { readClipboard } from "./clipboard.mjs";
+
+/** The shape of a BotFather token: `<bot id>:<secret>`. */
+const BOT_TOKEN_PATTERN = /^\d+:[A-Za-z0-9_-]{30,}$/;
+
+/**
+ * Whether `token` looks like a BotFather bot token.
+ * @param {unknown} token - Candidate
+ * @returns {boolean} True for `<digits>:<30+ of [A-Za-z0-9_-]>`
+ */
+export function validateBotToken(token) {
+  return typeof token === "string" && BOT_TOKEN_PATTERN.test(token);
+}
+
+/**
+ * Load `promptSecret`/`canPrompt` from the secrets-access skill, by path
+ * relative to this file, the same way other skills reach it. Lazy so the
+ * argv builders never pay for it.
+ * @returns {Promise<{ promptSecret: Function, canPrompt: Function }>} Module
+ */
+export function loadPromptSecret() {
+  return import(
+    new URL(
+      "../../lisa-secrets-access/scripts/prompt-secret.mjs",
+      import.meta.url
+    ).href
+  );
+}
+
+/**
+ * Quote one word for a POSIX shell.
+ * @param {string} word - Word to quote
+ * @returns {string} Single-quoted word
+ */
+export function shellQuote(word) {
+  const escaped = String(word).replaceAll("'", String.raw`'\''`);
+  return `'${escaped}'`;
+}
+
+/**
+ * The command an operator pastes into their own terminal to store the token,
+ * for when the caller (an agent's Bash) has no TTY to prompt on. `start`
+ * also names it when a plaintext token file is left over, since the same
+ * command migrates that file into the secrets provider (#4555).
+ * @param {{ scriptsDir: string, projectRoot: string, replace?: boolean,
+ *   fromClipboard?: boolean, vaultProject?: string }} input - Script and
+ *   project locations, and the flags to carry
+ * @returns {string} One shell line
+ */
+export function buildStoreTokenCommand({
+  scriptsDir,
+  projectRoot,
+  replace,
+  fromClipboard = false,
+  vaultProject,
+}) {
+  const script = shellQuote(path.join(scriptsDir, "session-manager.mjs"));
+  const flags =
+    (replace ? " --replace" : "") +
+    (fromClipboard ? " --from-clipboard" : "") +
+    (vaultProject ? ` --vault-project ${shellQuote(vaultProject)}` : "");
+  return `node ${script} store-token${flags} --project-root ${shellQuote(projectRoot)}`;
+}
+
+/** Why `store-token` cannot prompt here, and the two ways forward. */
+const NO_TTY_HINT =
+  "No terminal to prompt on, and Claude Code's ! prefix has no TTY either. " +
+  "Run `command` in a separate terminal app, or copy the token from " +
+  "BotFather and run `clipboardCommand`.";
+
+/** The `invalid` outcome; names the expected shape, never the input. */
+const INVALID = Object.freeze({
+  stored: false,
+  reason: "invalid",
+  message:
+    "That does not look like a Telegram bot token " +
+    "(expected <digits>:<30 or more letters, digits, _ or ->).",
+});
+
+/**
+ * Read a well-formed bot token from the system clipboard, with no TTY.
+ *
+ * The token is returned only to the caller that stores it, with a `clear`
+ * function to call after a successful store, so a failed attempt leaves the
+ * operator's copy in place to retry with. An invalid value is reported by
+ * shape, never echoed.
+ * @param {{ readClipboard?: typeof readClipboard }} [io] - Seams
+ * @returns {{ token: string, clear: () => boolean } |
+ *   { stored: false, reason: "empty" | "invalid" | "unsupported" |
+ *     "unavailable" | "failed", message: string }} Token, or why not
+ */
+export function readTokenFromClipboard(io = {}) {
+  const clip = (io.readClipboard ?? readClipboard)();
+  if (!clip.ok) {
+    return { stored: false, reason: clip.reason, message: clip.message };
+  }
+  const token = clip.text.trim();
+  if (!token) {
+    return {
+      stored: false,
+      reason: "empty",
+      message: "The clipboard is empty.",
+    };
+  }
+  if (!validateBotToken(token)) return { ...INVALID };
+  return { token, clear: clip.clear };
+}
+
+/**
+ * Prompt for a well-formed bot token on the operator's terminal (echo off).
+ *
+ * With no TTY this does not prompt and does not fail: it returns the exact
+ * command for the operator to run in a separate terminal app, and the
+ * `--from-clipboard` form of it, because an agent's Bash (and Claude Code's
+ * `!` prefix) can never answer a prompt and a hung setup looks like a slow
+ * one.
+ * @param {{ label: string, scriptsDir: string, projectRoot: string,
+ *   replace?: boolean, vaultProject?: string, io?: {
+ *   canPrompt?: () => boolean, promptSecret?: (message: string) => string } }}
+ *   input - What the token is for (shown in the prompt), locations, the
+ *   flags the printed commands carry, and seams
+ * @returns {Promise<{ token: string } |
+ *   { stored: false, reason: "no-tty", message: string, command: string,
+ *     clipboardCommand: string } |
+ *   { stored: false, reason: "empty" | "invalid", message: string }>} Token,
+ *   or why not
+ */
+export async function readTokenFromPrompt(input) {
+  const { label, io = {} } = input;
+  const loaded =
+    io.canPrompt && io.promptSecret ? null : await loadPromptSecret();
+  const canPrompt = io.canPrompt ?? (() => loaded.canPrompt());
+  const promptSecret = io.promptSecret ?? loaded.promptSecret;
+
+  if (!canPrompt()) {
+    return {
+      stored: false,
+      reason: "no-tty",
+      message: NO_TTY_HINT,
+      command: buildStoreTokenCommand(input),
+      clipboardCommand: buildStoreTokenCommand({
+        ...input,
+        fromClipboard: true,
+      }),
+    };
+  }
+  const typed = promptSecret(
+    `Paste the Telegram bot token for ${label} (input is hidden): `
+  );
+  if (!typed) {
+    return { stored: false, reason: "empty", message: "Nothing entered." };
+  }
+  if (!validateBotToken(typed)) return { ...INVALID };
+  return { token: typed };
+}