@codyswann/lisa 4.84.11 → 4.86.0

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

@@ -0,0 +1,248 @@
+/**
+ * The Telegram bot token held in the project's secrets provider (#4555).
+ *
+ * Before this, `store-token` wrote the token in plaintext to
+ * `<notify.stateDir>/.env`: the only Lisa-managed secret outside the secrets
+ * contract. When the project declares a secrets provider (`secrets.provider`
+ * set and not `env`), the token instead lives in that provider under one
+ * per-project name ({@link telegramSecretName}), and nothing is written to
+ * disk:
+ * - `store-token` stores it there: from a leftover plaintext file (migration)
+ *   or from the operator's prompt or clipboard. It reads the secret back and
+ *   compares hashes, and only then deletes the file.
+ * - `start` resolves it once and hands it to tmux on stdin, never argv. A
+ *   plaintext file left behind stops `start` with the exact command that
+ *   migrates it. An unreachable, rate-limited or slow provider is a failure
+ *   (exit 1) with retry guidance, never a fallback to a stale file.
+ * With no provider configured the old `.env` path in token.mjs is unchanged.
+ *
+ * Every provider call goes through `lisa-secrets-access` (`surfaces.mjs` for
+ * the config, `providers.mjs` for reads and writes), behind an injectable
+ * adapter so tests run against a fake vault. The token is never returned to
+ * the CLI, put in a message, or logged: errors carry fixed reason text, never
+ * a provider's raw error, since a failed write's error can quote its argv.
+ *
+ * The adapter and provider-error handling live in token-provider.mjs and the
+ * plaintext-file migration helpers in token-migrate.mjs; this module keeps
+ * the two flows and re-exports what the CLI imports.
+ * @module session-manager/token-store
+ */
+import * as nodeFs from "node:fs";
+
+import {
+  TOKEN_VAR,
+  TokenStoreError,
+  assertMigratable,
+  digest,
+  holdsToken,
+  keepExisting,
+  readEnvFile,
+  removeAfterVerify,
+  setupError,
+} from "./token-migrate.mjs";
+import { guarded } from "./token-provider.mjs";
+import { validateBotToken } from "./token.mjs";
+
+export { TokenStoreError } from "./token-migrate.mjs";
+export {
+  classifyProviderFailure,
+  defaultSecretsAdapter,
+  loadTokenSecrets,
+} from "./token-provider.mjs";
+
+/** Providers whose secrets live in a project that a create must name. */
+const PROJECT_SCOPED = new Set(["bitwarden"]);
+
+/** The usage note stored with the secret (format: note-format.mjs). */
+const NOTE = [
+  "Telegram bot token for a Lisa session manager, stored by its store-token command and read only by its start command.",
+  "scope: one Telegram bot - whoever holds it can read and send that bot's messages",
+  "owner: lisa-session-manager",
+].join("\n");
+
+/**
+ * The provider secret name for one manager: `TELEGRAM_BOT_TOKEN_<NAME>`, with
+ * the manager name upper-snaked. The `TELEGRAM_` prefix keeps
+ * `scrubWorkerEnv` stripping it from every worker's environment.
+ * @param {string} managerName - `sessionManager.name`, e.g. `lisa-1a2b-manager`
+ * @returns {string} e.g. `TELEGRAM_BOT_TOKEN_LISA_1A2B_MANAGER`
+ */
+export function telegramSecretName(managerName) {
+  const suffix = String(managerName)
+    .toUpperCase()
+    .replaceAll(/[^A-Z0-9]+/g, "_");
+  return `${TOKEN_VAR}_${suffix}`;
+}
+
+/**
+ * Refuse a name the project's `secrets.require` allowlist does not declare:
+ * the provider would never hand it to this project.
+ * @param {{ require?: string[] | null }} cfg - Secrets config
+ * @param {string} name - Secret name
+ */
+function assertDeclared(cfg, name) {
+  if (Array.isArray(cfg.require) && !cfg.require.includes(name)) {
+    throw setupError(
+      `${name} is not declared in secrets.require in .lisa.config.json, so ` +
+        `this project may not read it. Add "${name}" to secrets.require, ` +
+        `then run this again.`
+    );
+  }
+}
+
+/**
+ * The provider project a new secret goes in: `--vault-project`, else the one
+ * project `secrets.narrow.projectIds` names, else the one project every
+ * visible secret lives in. Exit 2 rather than guess.
+ * @param {object} cfg - Secrets config
+ * @param {Array<{ projectId: string | null }>} rows - Visible secrets
+ * @param {{ name: string, vaultProject?: string }} input - Secret and flag
+ * @returns {string | undefined} Project id (undefined: provider has none)
+ */
+function chooseProject(cfg, rows, { name, vaultProject }) {
+  if (!PROJECT_SCOPED.has(cfg.provider)) return undefined;
+  const narrowed = cfg.narrow?.projectIds ?? [];
+  if (vaultProject) {
+    if (narrowed.length > 0 && !narrowed.includes(vaultProject)) {
+      throw setupError(
+        `--vault-project ${vaultProject} is not in secrets.narrow.projectIds, ` +
+          `so ${name} would be stored where this project cannot read it.`
+      );
+    }
+    return vaultProject;
+  }
+  if (narrowed.length === 1) return narrowed[0];
+  const seen = [...new Set(rows.map(row => row.projectId).filter(Boolean))];
+  if (seen.length === 1) return seen[0];
+  throw setupError(
+    `Cannot tell which ${cfg.provider} project to store ${name} in ` +
+      `(${seen.length} projects are visible). Run store-token again with ` +
+      `--vault-project <project id>.`
+  );
+}
+
+/**
+ * Store the bot token in the secrets provider: look it up, take it from the
+ * plaintext file (migration) or `readToken` (prompt or clipboard), create or
+ * replace it, read it back and compare hashes, and only then delete the
+ * file. An existing secret is kept unless `replace`.
+ * @param {{ cfg: object, adapter: object, name: string, stateDir: string,
+ *   replace?: boolean, vaultProject?: string,
+ *   readToken: () => Promise<{ token?: string, clear?: () => boolean,
+ *     stored?: boolean, reason?: string, message?: string }>,
+ *   fs?: object }} input - Config, adapter, secret
+ *   name, resolved state dir, flags, the token reader and an fs seam
+ * @returns {Promise<object>} `{stored:true,storage:"provider",...}`, or the
+ *   reader's `{stored:false,...}` outcome
+ */
+export async function storeTokenInProvider(input) {
+  const { cfg, adapter, name, replace = false, fs = nodeFs } = input;
+  const where = {
+    provider: cfg.provider,
+    name,
+    retry:
+      `Could not store the Telegram bot token in ${cfg.provider}: <reason>. ` +
+      `Nothing was stored and any plaintext token file was kept. Wait a ` +
+      `minute and run store-token again.`,
+  };
+  assertDeclared(cfg, name);
+  const file = readEnvFile(input.stateDir, fs);
+  assertMigratable(file);
+  await guarded(() => adapter.preflight(cfg), where);
+  const rows = await guarded(() => adapter.list(cfg), where);
+  const existing = rows.find(row => row.key === name);
+  if (existing && !replace) {
+    return keepExisting(existing, file, { cfg, name, fs });
+  }
+
+  const read = holdsToken(file)
+    ? { token: file.token }
+    : await input.readToken();
+  if (read.token === undefined) return read;
+  const projectId = existing ? undefined : chooseProject(cfg, rows, input);
+  await guarded(
+    () =>
+      existing
+        ? adapter.replace(cfg, { id: existing.id, value: read.token })
+        : adapter.create(cfg, {
+            name,
+            value: read.token,
+            projectId,
+            note: NOTE,
+          }),
+    where
+  );
+  const after = (await guarded(() => adapter.list(cfg), where)).find(
+    row => row.key === name
+  );
+  if (after === undefined || digest(after.value) !== digest(read.token)) {
+    throw new TokenStoreError(
+      `Reading ${name} back from ${cfg.provider} did not return what was ` +
+        `written, so the token is not proven stored. Any plaintext token ` +
+        `file was kept. Run store-token again.`,
+      1
+    );
+  }
+  return {
+    stored: true,
+    storage: "provider",
+    provider: cfg.provider,
+    secret: name,
+    verified: true,
+    ...removeAfterVerify(file, fs),
+    ...(read.clear ? { clipboardCleared: read.clear() } : {}),
+  };
+}
+
+/**
+ * Resolve the bot token for `start`, once, from the provider. Refuses (exit
+ * 2) a leftover plaintext file that holds a token line, naming `fixCommand`
+ * (the `store-token` call that migrates it; an empty or comment-only file
+ * holds nothing to migrate and does not stop `start`), an undeclared or
+ * missing secret, and a value that is not
+ * bot-token shaped; fails (exit 1) when the provider is unreachable,
+ * rate-limited or slow, saying nothing was started.
+ * @param {{ cfg: object, adapter: object, name: string, stateDir: string,
+ *   fixCommand: string, fs?: object }} input - Config, adapter, secret name,
+ *   resolved state dir, the migrating command and an fs seam
+ * @returns {Promise<string>} The token, for the tmux stdin line only
+ */
+export async function resolveTelegramToken(input) {
+  const { cfg, adapter, name, fixCommand, fs = nodeFs } = input;
+  assertDeclared(cfg, name);
+  const file = readEnvFile(input.stateDir, fs);
+  if (holdsToken(file)) {
+    throw setupError(
+      `A plaintext Telegram bot token file is still at ${file.path}. With a ` +
+        `secrets provider configured the token must live in ` +
+        `${cfg.provider} only. Nothing was started. Move it there (this ` +
+        `stores the token, verifies it and deletes the file), then run start ` +
+        `again:\n  ${fixCommand}`
+    );
+  }
+  const where = {
+    provider: cfg.provider,
+    name,
+    retry:
+      `Could not read the Telegram bot token from ${cfg.provider}: ` +
+      `<reason>. Nothing was started. Wait a minute and run start again; if ` +
+      `it keeps failing, check ${cfg.provider}'s status and this machine's ` +
+      `network.`,
+  };
+  await guarded(() => adapter.preflight(cfg), where);
+  const rows = await guarded(() => adapter.list(cfg), where);
+  const hit = rows.find(row => row.key === name);
+  if (!hit?.value) {
+    throw setupError(
+      `${cfg.provider} has no secret named ${name}, so the manager has no ` +
+        `bot token. Nothing was started. Store it with:\n  ${fixCommand}`
+    );
+  }
+  if (!validateBotToken(hit.value)) {
+    throw setupError(
+      `${name} in ${cfg.provider} does not look like a Telegram bot token. ` +
+        `Nothing was started. Run store-token --replace to store the right one.`
+    );
+  }
+  return hit.value;
+}

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

@@ -5,30 +5,40 @@
  * reachable), and never put in argv, a return value, an error message or a
  * log line. An existing token is replaced only on request. Split out of
  * launch.mjs, which re-exports everything here.
+ *
+ * The `.env` file is the storage only when the project has no secrets
+ * provider; with one, token-store.mjs stores the token there instead and
+ * reuses the prompt and clipboard readers (#4555).
+ *
+ * Validation, the prompt and clipboard readers and the printed `store-token`
+ * command live in token-read.mjs, re-exported here, to keep this module under
+ * the line budget.
  * @module token
  */
 import { randomUUID } from "node:crypto";
 import * as nodeFs from "node:fs";
 import path from "node:path";
 
-import { readClipboard } from "./clipboard.mjs";
 import { LaunchError, resolveStateDir } from "./state-dir.mjs";
+import {
+  readTokenFromClipboard,
+  readTokenFromPrompt,
+  shellQuote,
+  validateBotToken,
+} from "./token-read.mjs";
 
-/** The shape of a BotFather token: `<bot id>:<secret>`. */
-const BOT_TOKEN_PATTERN = /^\d+:[A-Za-z0-9_-]{30,}$/;
+export {
+  buildStoreTokenCommand,
+  loadPromptSecret,
+  readTokenFromClipboard,
+  readTokenFromPrompt,
+  shellQuote,
+  validateBotToken,
+} from "./token-read.mjs";
 
 /** The plugin reads its token from this file in the state dir. */
 const TOKEN_FILE_NAME = ".env";
 
-/**
- * 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);
-}
-
 /**
  * Write `<stateDir>/.env` as `TELEGRAM_BOT_TOKEN=<token>`.
  *
@@ -64,65 +74,6 @@ export function writeTokenFile(stateDir, token, seams = {}) {
   return { path: target };
 }
 
-/**
- * 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
- */
-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.
- * @param {{ scriptsDir: string, projectRoot: string, replace?: boolean }}
- *   input - Script and project locations, and whether to carry `--replace`
- * @returns {string} One shell line
- */
-export function buildStoreTokenCommand({
-  scriptsDir,
-  projectRoot,
-  replace,
-  fromClipboard = false,
-}) {
-  const script = shellQuote(path.join(scriptsDir, "session-manager.mjs"));
-  const flags =
-    (replace ? " --replace" : "") + (fromClipboard ? " --from-clipboard" : "");
-  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 ->).",
-});
-
 /**
  * Refuse to overwrite an existing token unless `replace` was asked for: a
  * second project that shares this state dir by mistake would otherwise
@@ -161,31 +112,17 @@ export function storeTokenFromClipboard(input) {
   const { replace = false, io = {} } = input;
   const stateDir = resolveStateDir(input.stateDir, input);
   assertReplaceable(stateDir, replace, 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 };
-  const written = writeTokenFile(stateDir, token, io);
-  return { stored: true, ...written, clipboardCleared: clip.clear() };
+  const read = readTokenFromClipboard(io);
+  if (read.token === undefined) return read;
+  const written = writeTokenFile(stateDir, read.token, io);
+  return { stored: true, ...written, clipboardCleared: read.clear() };
 }
 
 /**
- * Prompt for the bot token on the operator's terminal and store it.
- *
- * An existing token is never overwritten without `replace`. 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.
+ * Prompt for the bot token on the operator's terminal and store it in
+ * `<stateDir>/.env`. An existing token is never overwritten without
+ * `replace`; with no TTY it returns the commands that work instead (see
+ * {@link readTokenFromPrompt}).
  * @param {{ stateDir: string, scriptsDir: string, projectRoot: string,
  *   replace?: boolean, env?: Record<string, string | undefined>,
  *   homedir?: string, io?: { canPrompt?: () => boolean,
@@ -200,33 +137,15 @@ export async function storeToken(input) {
   const { scriptsDir, projectRoot, replace = false, io = {} } = input;
   const stateDir = resolveStateDir(input.stateDir, input);
   assertReplaceable(stateDir, replace, io);
-  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({ scriptsDir, projectRoot, replace }),
-      clipboardCommand: buildStoreTokenCommand({
-        scriptsDir,
-        projectRoot,
-        replace,
-        fromClipboard: true,
-      }),
-    };
-  }
-  const typed = promptSecret(
-    `Paste the Telegram bot token for ${stateDir} (input is hidden): `
-  );
-  if (!typed) {
-    return { stored: false, reason: "empty", message: "Nothing entered." };
-  }
-  if (!validateBotToken(typed)) return { ...INVALID };
-  return { stored: true, ...writeTokenFile(stateDir, typed, io) };
+  const read = await readTokenFromPrompt({
+    label: stateDir,
+    scriptsDir,
+    projectRoot,
+    replace,
+    io,
+  });
+  if (read.token === undefined) return read;
+  return { stored: true, ...writeTokenFile(stateDir, read.token, io) };
 }
 
 /**

package/plugins/lisa/.codex-plugin/skills/lisa-setup-session-manager/SKILL.md

@@ -3,14 +3,19 @@ name: lisa-setup-session-manager
 description: "Set up the local session…"
 allowed-tools: ["Bash", "Read", "Write", "Skill", "AskUserQuestion"]
 ---
-Set up the local session manager for this project: writes the non-secret `sessionManager` block to `.lisa.config.json` (detecting a multi-repo layout: repos under `projects/`, or directly under the project root), stores the project's own Telegram bot token outside the repo, checks the Telegram plugin is installed but not enabled at user scope, keeps the manager's state out of git, seeds the checked-in runbook, starts the manager in tmux, walks the operator through pairing, and finishes with doctor's session-manager check. Idempotent.
+Set up the local session manager for this project: writes the non-secret `sessionManager` block to `.lisa.config.json` (detecting a multi-repo layout: repos under `projects/`, or directly under the project root), optionally sets up a Telegram notification channel (the project's own bot token stored in its secrets provider, or outside the repo when none is configured, with a leftover plaintext token file migrated into the provider, the Telegram plugin installed but not enabled at user scope, pairing; skipped entirely with no channel, the default), keeps the manager's state out of git, seeds the checked-in runbook, starts the manager in tmux, and finishes with doctor's session-manager check. Idempotent.
 
 
 # Setup session manager
 
-After this skill the project has a `sessionManager` block, a bot token in its own state directory, a
-runbook at `.lisa/automations/session-manager.runbook.md`, and a running manager paired with the
-operator's Telegram chat. Re-running is safe: every step keeps what is already there.
+After this skill the project has a `sessionManager` block, a runbook at
+`.lisa/automations/session-manager.runbook.md`, and a running manager. Telegram is optional: with it,
+the project also has its own bot token (in the project's secrets provider when one is configured,
+else in its own state directory) and a manager paired with the operator's
+Telegram chat; with no channel (the default), Steps 3 and 4 and the pairing in Step 9 are skipped,
+and questions wait in the manager's ledger, where `status` shows them, and on the item itself,
+which the manager marks human-needed while it keeps dispatching other work. Re-running is safe: every
+step keeps what is already there.
 
 The manager itself always runs on Claude Code (see `lisa-session-manager` "Runtime parity"). Setup
 can run from any agent that can reach the scripts; `start` launches the Claude Code manager.
@@ -42,15 +47,23 @@ writes `$SM`, and pass `--project-root "$ROOT"` (the absolute project root) on e
 
 ## Step 2: Write the config block
 
-1. Preview: `node "$SM/session-manager.mjs" init-config --project-root "$ROOT"`. It detects
+0. Ask the operator whether they want Telegram notifications: worker questions and status on their
+   phone, through a bot they create for this project. Say plainly that it is optional: without it
+   the manager runs normally, and questions wait in its ledger (shown by `status`) instead of
+   reaching a phone. Their answer is `<notify>`: `telegram` or `none` (the default).
+1. Preview: `node "$SM/session-manager.mjs" init-config --notify <notify> --project-root "$ROOT"`.
+   It detects
    `projects/*/.lisa.config.json`, or, when `projects/` holds none, the root's own children that
    have a `.lisa.config.json` and their own `.git` (written as `repos.root: "."`). It proposes
-   `name`, `interval`, `repos`, `capacity`, `stall` and a per-project `notify.stateDir`. Repo
+   `name`, `interval`, `repos`, `capacity`, `stall` and `notify`: `{"provider":"none"}`, or with
+   `--notify telegram` the telegram provider and a per-project `notify.stateDir`. Repo
    detection leaves out linked worktrees and keeps one checkout per remote, so ticket worktrees and
    second clones are not proposed. Show the block to the operator and ask whether any repo is
    missing or should not be routed.
 2. Write it: the same command with `--write`. It adds only non-secret fields and never overwrites an
-   existing block (`reason: "exists"` means keep it).
+   existing block (`reason: "exists"` means keep it). To add Telegram to an existing block later,
+   set `notify` to `{"provider":"telegram","stateDir":"~/.claude/channels/telegram-<project>"}`
+   (the `<project>` part as `init-config --notify telegram` would derive it) and re-run this skill.
 3. Each repo's `hints` are a draft: its name plus one per well-known dependency (`NestJS`, `Expo`,
    `AWS CDK`, ...). Ask the operator to correct them and add the areas that identify the repo
    (e.g. `api`: `["NestJS","migrations"]`, `web`: `["Expo","screens"]`), and whether to
@@ -70,6 +83,12 @@ writes `$SM`, and pass `--project-root "$ROOT"` (the absolute project root) on e
    "me", spelled as the tracker API returns it: the GitHub **login** (`gh api users/<login> --jq
    .login`), the Jira `accountId`, or the Linear user id (the operator's entry in the team's member
    list, or `viewer.id` only when the operator runs the lookup with their own credential).
+   **Recommend setting it in every setup**, even a single-user one: it is also who may answer a
+   human-needed question by replying on the item. With neither `operatorIds` nor
+   `trustedAuthorIds` set, the manager reads no answer off the item at all, because the tracker
+   credential's identity is the one the workers and the manager post as, so its comments cannot be
+   told apart from a human's answer. The operator then answers only at the terminal, with the
+   `answerCommand` that `status` lists. Say so plainly.
 5. Ask whether to set `sessionManager.backlogPickup` to `true` (default off). When the Ready queue
    is exhausted and a worker slot is still free, the manager then looks at backlog items (open
    leaves in no lifecycle role) that nobody else is assigned to, that are not human-held and have
@@ -81,12 +100,45 @@ writes `$SM`, and pass `--project-root "$ROOT"` (the absolute project root) on e
 
 ## Step 3: Store the bot token
 
+Only when `sessionManager.notify.provider` is `telegram`. With no channel (`none`, or no `notify`
+block) there is no token: skip Steps 3 and 4 and go to Step 5.
+
 The operator creates a bot with @BotFather, one per project. Then run
 `node "$SM/session-manager.mjs" store-token --project-root "$ROOT"`.
 
+Where the token goes depends on the project's secrets provider (`secrets.provider` in
+`.lisa.config.json`, read through `lisa-secrets-access`):
+
+- **A provider is configured** (`secrets.provider` set and not `env`): the token is stored in it as
+  `TELEGRAM_BOT_TOKEN_<NAME>` (the manager name upper-snaked, e.g. `lisa-1a2b-manager` →
+  `TELEGRAM_BOT_TOKEN_LISA_1A2B_MANAGER`) and nothing is written to disk. `start` resolves it from
+  there each time. If `secrets.require` is declared, add that name to it first, or `store-token`
+  exits 2 saying so.
+  - **Migration.** If an older setup left a plaintext `<notify.stateDir>/.env`, `store-token`
+    moves it: it stores the token, reads it back and compares, and only then deletes the file. It
+    needs no prompt. Report it as "moved the bot token from `<path>` into `<provider>` and deleted
+    the file" (the `migratedFrom` and `deleted` fields), never with the value.
+  - `alreadyStored: true`: the provider already holds it; nothing to do. A matching leftover file
+    is deleted too.
+  - Exit 2 naming `--vault-project`: the provider project is ambiguous. Ask the operator which
+    project, then re-run with `--vault-project <id>`.
+  - Exit 2 because the file holds a different token or other keys: say what `message` reports and
+    let the operator decide (`--replace` makes the file's token the stored one).
+  - Exit 1 (provider unreachable or rate-limited): nothing was stored and the file was kept. Wait a
+    minute and run it again.
+  - A provider Lisa cannot write to (anything but Bitwarden today): the message asks the operator
+    to create `TELEGRAM_BOT_TOKEN_<NAME>` in the provider themselves; then re-run `store-token`,
+    which verifies it and deletes any plaintext copy.
+- **No provider configured**: the token is written to `<notify.stateDir>/.env` (mode 0600) as
+  before. Tell the operator that this is a plaintext file, that doctor will warn about it, and that
+  configuring a secrets provider and re-running `store-token` moves it there.
+
+Outcomes either way:
+
 - `stored: true`: done.
-- Exit 2 because a token already exists: keep it (re-running setup is safe). Only when the operator
-  says the stored token is wrong or belongs to another project, re-run with `store-token --replace`.
+- With no provider, exit 2 because a token already exists: keep it (re-running setup is safe). Only
+  when the operator says the stored token is wrong or belongs to another project, re-run with
+  `store-token --replace`.
 - `reason: "no-tty"` (an agent's Bash has no terminal): offer the operator both routes, and say
   plainly that Claude Code's `!` prefix has no terminal either, so it fails the same way:
   - **Clipboard (simplest):** they copy the token from the BotFather chat and tell you; then run
@@ -98,11 +150,13 @@ The operator creates a bot with @BotFather, one per project. Then run
 - `empty` / `invalid`: say what was wrong and ask again.
 
 Never ask for the token in chat, never echo, log or commit it, and never put it in
-`.lisa.config.json`. It lives only in `<notify.stateDir>/.env`.
+`.lisa.config.json`. It lives only in the secrets provider, or in `<notify.stateDir>/.env` when
+no provider is configured. Never read it back from either to check it: `store-token` already
+verified the stored copy.
 
 ## Step 4: Telegram plugin scope
 
-Read `claude plugin list --json` and look at the `telegram@claude-plugins-official` entries.
+Only when `notify.provider` is `telegram`. Read `claude plugin list --json` and look at the `telegram@claude-plugins-official` entries.
 
 - **Not installed:** ask the operator to install it with
   `claude plugin install telegram@claude-plugins-official -s user`, then re-check.
@@ -175,11 +229,17 @@ project), on every machine that runs the manager:
    bypass-permissions worker runs. Ask the operator for the IDs, add them, re-run `validate`, then
    continue. `lisa doctor` fails on the same condition.
 1. `node "$SM/session-manager.mjs" start --project-root "$ROOT"`. `started` and `already-running`
-   are both fine. Exit 2 names what is missing (usually the token from Step 3), or that a tmux
-   session of the same name belongs to another project root, or that the manager
-   exited right after starting. For the last, ask the operator to run the printed foreground command
-   in their own terminal: claude prints its own error there. Fix it, then run `start` again.
-2. Walk the operator through pairing, in their own terminal:
+   are both fine. With no channel it needs no token, plugin or pairing and launches without
+   `--channels`. Exit 2 names what is missing (with Telegram, usually the token from Step 3, or a
+   plaintext `.env` left over beside a secrets provider: run the `store-token` command the message
+   names, which migrates it, then `start` again), or that a tmux session of the same name belongs
+   to another project root, or that the manager exited right after starting. For the last, ask the
+   operator to run the printed foreground command in their own terminal: claude prints its own
+   error there (with a provider, the line fetches the token itself; it never holds the value). Fix
+   it, then run `start` again. Exit 1 saying "Nothing was started" means the secrets provider could
+   not be reached or rate-limited the read: wait a minute and run `start` again.
+2. Only with Telegram (`notify` is `telegram` in the `start` output); with no channel there is no
+   pairing, so skip to Step 10. Walk the operator through pairing, in their own terminal:
    1. `tmux attach -t <name>` (the `attach` value from the output).
    2. Send any message to the bot in a private chat. The bot replies with a pairing code.
    3. In the attached manager session: `/telegram:access pair <code>`.
@@ -193,10 +253,13 @@ Telegram message asked for it. Every allowlisted sender effectively has shell ac
 ## Step 10: Verify
 
 Run `lisa doctor` (or `npx @codyswann/lisa doctor` when the `lisa` CLI is not on the PATH) and
-confirm the "Session manager Telegram isolation?" check is green. Fix every warning it names, then
+confirm the "Session manager notifications?" check is green. With no channel its detail is
+`notifications: none`, and it skips every Telegram check. Fix every warning it names, then
 `node "$SM/session-manager.mjs" status --project-root "$ROOT"` should show the manager running.
 
-Report: the config block written (or kept), where the token lives (the path, never the value), the
-plugin scope result, the runbook path, which repo dirs were already trusted and which the operator
+Report: the config block written (or kept), the notification channel (`telegram` or `none`), and
+with Telegram where the token lives (the provider and secret name, or the file path; never the
+value), whether a plaintext `.env` was migrated and deleted, and the plugin scope result, the
+runbook path, which repo dirs were already trusted and which the operator
 accepted trust in, what the competing-loop check found, the manager's tmux session name, and the
 doctor result.

package/plugins/lisa/commands/session-manager.md

@@ -1,5 +1,5 @@
 ---
-description: "Run the local session manager: one dispatch-and-relay cycle (the /loop prompt), or start, stop or show the tmux-hosted manager. Dispatches Ready work items to fresh background worker sessions and relays their questions over the project's Telegram bot. Claude Code only; configure it with /lisa:setup:session-manager."
+description: "Run the local session manager: one dispatch-and-relay cycle (the /loop prompt), or start, stop or show the tmux-hosted manager. Dispatches Ready work items to fresh background worker sessions and relays their questions over the project's Telegram bot when one is configured (Telegram is optional). Claude Code only; configure it with /lisa:setup:session-manager."
 allowed-tools: ["Skill"]
 argument-hint: "[cycle|start|stop|status]"
 ---

package/plugins/lisa/commands/setup/session-manager.md

@@ -1,5 +1,5 @@
 ---
-description: "Set up the local session manager for this project: write the sessionManager config block, store the project's own Telegram bot token, check the Telegram plugin scope, seed the runbook, start the manager in tmux, walk through pairing, and run doctor's session-manager check."
+description: "Set up the local session manager for this project: write the sessionManager config block, optionally set up Telegram notifications (store the project's own bot token in its secrets provider, migrating any plaintext token file, check the plugin scope, walk through pairing; skipped with no channel, the default), seed the runbook, start the manager in tmux, and run doctor's session-manager check."
 allowed-tools: ["Skill"]
 ---