@codyswann/lisa 4.85.0 → 4.86.1

package/plugins/lisa/skills/lisa-session-manager/scripts/config.mjs

@@ -30,8 +30,10 @@ export { detectRepoLayout, detectRepos, draftHints } from "./repo-detect.mjs";
 /**
  * Documented defaults for every optional key.
  *
- * `name` and `notify.stateDir` have none: both are per-project, and a shared
- * default for either is how two projects end up fighting over one bot.
+ * `notify.provider` defaults to `"none"`: a notification channel is optional
+ * (#4555), and an absent `notify` block means the manager runs without one.
+ * `name` and `notify.stateDir` have no default: both are per-project, and a
+ * shared default for either is how two projects end up fighting over one bot.
  * `buildDefaultBlock` derives them from the project slug at setup time.
  */
 export const SESSION_MANAGER_DEFAULTS = Object.freeze({
@@ -48,9 +50,24 @@ export const SESSION_MANAGER_DEFAULTS = Object.freeze({
     maxAttempts: 3,
     requestionHours: 4,
   }),
-  notify: Object.freeze({ provider: "telegram" }),
+  notify: Object.freeze({ provider: "none" }),
 });
 
+/** The `notify` choices `buildDefaultBlock` (and `init-config --notify`) take. */
+export const NOTIFY_CHOICES = Object.freeze(["none", "telegram"]);
+
+/**
+ * The notification provider a resolved (or raw) block runs with.
+ * @param {{ notify?: { provider?: unknown } } | null | undefined} config
+ *   Resolved or raw `sessionManager` block.
+ * @returns {string} `"telegram"`, `"none"`, or whatever unsupported value
+ *   was declared (validation refuses it).
+ */
+export function notifyProvider(config) {
+  const provider = config?.notify?.provider;
+  return provider === undefined || provider === null ? "none" : provider;
+}
+
 /**
  * @typedef {{ root: string, entries: Record<string, { hints: string[] }> }} ReposBlock
  * @typedef {{ maxWorkers: number, gbPerWorker: number, reserveGb: number,
@@ -75,7 +92,7 @@ export const SESSION_MANAGER_DEFAULTS = Object.freeze({
  *   repos?: ReposBlock,
  *   capacity: CapacityBlock,
  *   stall: StallBlock,
- *   notify: { provider: string, stateDir: string },
+ *   notify: { provider: string, stateDir?: string },
  * }} SessionManagerBlock
  */
 
@@ -160,10 +177,14 @@ function normalizeSlug(projectSlug) {
  * name: valid either way, and setup asks the operator to review them.
  * `reposRoot` is where the repos were found (`detectRepoLayout`): `projects`
  * by default, or `.` when they sit directly under the project root.
+ * `notify` is the operator's channel choice: `"none"` (the default) writes
+ * `{provider:"none"}` and no state dir; `"telegram"` adds the per-project
+ * state dir derived from the slug.
  * @param {{ projectSlug: string, detectedRepos?: string[],
- *   hints?: Record<string, string[]>, reposRoot?: string }} input Project
- *   slug, the output of `detectRepos`, drafted hints per repo, and the repos
- *   root they were found under.
+ *   hints?: Record<string, string[]>, reposRoot?: string,
+ *   notify?: string }} input Project slug, the output of `detectRepos`,
+ *   drafted hints per repo, the repos root they were found under, and the
+ *   notification channel.
  * @returns {SessionManagerBlock} A block `validateSessionManager` accepts.
  */
 export function buildDefaultBlock({
@@ -171,7 +192,14 @@ export function buildDefaultBlock({
   detectedRepos = [],
   hints = {},
   reposRoot = DEFAULT_REPOS_ROOT,
+  notify = SESSION_MANAGER_DEFAULTS.notify.provider,
 }) {
+  if (!NOTIFY_CHOICES.includes(notify)) {
+    throw new Error(
+      `notify ${JSON.stringify(notify)} is not supported. Use one of: ` +
+        `${NOTIFY_CHOICES.join(", ")}.`
+    );
+  }
   const slug = normalizeSlug(projectSlug);
   const repos = [...detectedRepos].sort();
   return {
@@ -192,10 +220,10 @@ export function buildDefaultBlock({
       : {}),
     capacity: { ...SESSION_MANAGER_DEFAULTS.capacity },
     stall: { ...SESSION_MANAGER_DEFAULTS.stall },
-    notify: {
-      provider: SESSION_MANAGER_DEFAULTS.notify.provider,
-      stateDir: `~/.claude/channels/telegram-${slug}`,
-    },
+    notify:
+      notify === "telegram"
+        ? { provider: notify, stateDir: `~/.claude/channels/telegram-${slug}` }
+        : { provider: notify },
   };
 }
 

package/plugins/lisa/skills/lisa-session-manager/scripts/human-answer.mjs

@@ -0,0 +1,162 @@
+/**
+ * Reading a human's answer back off a work item (CodySwannGT/lisa#4555,
+ * part 3). Pure: no I/O, no clock, no config reads.
+ *
+ * Tracker text is untrusted, and in a single-user setup the operator's
+ * tracker identity is also the one the workers and the manager post as. So
+ * an operator-id match alone proves nothing: {@link isMachineAuthoredComment}
+ * runs first and is the ONE place that decides a comment is a machine's.
+ * It excludes a comment that opens with a Lisa or Claude machine tag
+ * (`[claude-sync] …`, `[lisa-…] …`), holds a `[lisa-` marker or a
+ * `<!-- lisa:` marker, says "Written by Claude", or carries the Claude Code
+ * attribution footer; and any comment whose id the manager recorded as one it
+ * posted itself (`ledger marked --comment-id`), whatever it says. Markdown
+ * blockquote lines are ignored before the markers are tested, so a human's
+ * "Quote reply" of the question (or of a machine comment) is still a human's
+ * answer, and an ordinary reply such as `[x] option 1` is not a machine tag
+ * (#4561). Only then is the author matched, on stable ids only: a GitHub
+ * login or numeric id, a Jira accountId, a Linear user id, never a display
+ * name or email, which anyone can set. The text is carried as data.
+ *
+ * The question the answer must follow is the comment whose id the manager
+ * recorded last; with no recorded id, the latest comment that STARTS with
+ * the question marker and is by an allowed answerer. A marker merely quoted,
+ * or posted by anyone else, never moves that anchor, so nobody can hide an
+ * answer by posting the marker after it.
+ * @module session-manager/human-answer
+ */
+import { QUESTION_MARKER } from "./human-needed.mjs";
+
+/** Body markers that make a comment a machine's, never a human's answer. */
+const MACHINE_MARKERS = [
+  /^\s*\[(lisa|claude)-[a-z0-9-]*\]/i,
+  /\[lisa-/i,
+  /<!--\s*lisa:/i,
+  /Written by Claude/i,
+  /Generated with Claude Code/i,
+  /🤖 Generated with/,
+];
+
+/** A Markdown blockquote line: quoted text, never the commenter's own. */
+const QUOTE_LINE = /^\s*>/;
+
+/** The comment fields that carry its tracker id. */
+const COMMENT_ID_KEYS = ["id", "node_id"];
+
+/** The author fields that are stable ids, never settable display text. */
+const STABLE_ID_KEYS = ["login", "id", "accountId"];
+
+/**
+ * The string or number values of `keys` on `value`, as strings.
+ * @param {unknown} value - Object to read
+ * @param {readonly string[]} keys - Keys to read
+ * @returns {string[]} Values
+ */
+function idsOf(value, keys) {
+  if (value === null || typeof value !== "object") return [];
+  return keys
+    .map(key => value[key])
+    .filter(id => typeof id === "string" || typeof id === "number")
+    .map(String);
+}
+
+/**
+ * The comment body, whatever the tracker calls it.
+ * @param {Record<string, unknown>} comment - One comment
+ * @returns {string} Body text
+ */
+function bodyOf(comment) {
+  const body = comment?.body ?? comment?.text ?? "";
+  return typeof body === "string" ? body : "";
+}
+
+/**
+ * The comment body without its Markdown blockquote lines.
+ * @param {string} text - Body text
+ * @returns {string} The commenter's own text
+ */
+function unquoted(text) {
+  return text
+    .split("\n")
+    .filter(line => !QUOTE_LINE.test(line))
+    .join("\n");
+}
+
+/**
+ * Whether a comment was written by a machine (an agent, a Lisa flow, or the
+ * manager itself) and so can never be a human's answer.
+ * @param {Record<string, unknown>} comment - One tracker comment
+ * @param {{managerCommentIds?: readonly (string|number)[]}} [options] - Ids
+ *   of comments the manager posted (from the ledger)
+ * @returns {boolean} True for a machine's comment
+ */
+export function isMachineAuthoredComment(comment, options = {}) {
+  const mine = new Set((options.managerCommentIds ?? []).map(String));
+  if (idsOf(comment, COMMENT_ID_KEYS).some(id => mine.has(id))) return true;
+  const text = unquoted(bodyOf(comment));
+  return MACHINE_MARKERS.some(pattern => pattern.test(text));
+}
+
+/**
+ * Index of the question comment an answer must follow: the comment whose id
+ * the manager recorded last, when it recorded any; otherwise the latest
+ * comment that starts with the question marker and is by an allowed author.
+ * @param {Record<string, unknown>[]} rows - Comments, chronological
+ * @param {readonly (string|number)[]} managerCommentIds - Recorded ids
+ * @param {(row: Record<string, unknown>) => string|undefined} authorOf -
+ *   The row's allowed stable author id, if any
+ * @returns {number} Index, or -1 when there is no question comment
+ */
+function questionIndex(rows, managerCommentIds, authorOf) {
+  if (managerCommentIds.length > 0) {
+    const latest = String(managerCommentIds.at(-1));
+    return rows.findLastIndex(row =>
+      idsOf(row, COMMENT_ID_KEYS).includes(latest)
+    );
+  }
+  return rows.findLastIndex(
+    row =>
+      bodyOf(row).trimStart().startsWith(QUESTION_MARKER) &&
+      authorOf(row) !== undefined
+  );
+}
+
+/**
+ * Pick the human's answer from an item's comments: the first comment after
+ * the manager's latest question comment ({@link questionIndex}) that is not
+ * a machine's ({@link isMachineAuthoredComment}), has text of its own
+ * outside quoted lines (a comment made only of `>` lines quotes someone
+ * else and answers nothing), and whose author's stable id is allowed. Comments are taken in the order given (chronological).
+ * @param {{comments: unknown, allowed: readonly string[],
+ *   managerCommentIds?: readonly (string|number)[]}} input - The item's
+ *   comments, the answerer ids, and the ids the manager posted
+ * @returns {{answer: {text: string, author: string, at: string|null} | null,
+ *   reason: string}} The answer, or null with why there is none
+ */
+export function pickItemAnswer({ comments, allowed, managerCommentIds = [] }) {
+  if (!Array.isArray(comments)) {
+    throw new Error('stdin must be JSON {"comments":[...]}');
+  }
+  const rows = comments.filter(row => row && typeof row === "object");
+  const allow = new Set(allowed.map(String));
+  const authorOf = row =>
+    idsOf(row.author ?? row.user, STABLE_ID_KEYS).find(id => allow.has(id));
+  const asked = questionIndex(rows, managerCommentIds, authorOf);
+  if (asked === -1) return { answer: null, reason: "no-question-comment" };
+  const reply = rows
+    .slice(asked + 1)
+    .filter(row => !isMachineAuthoredComment(row, { managerCommentIds }))
+    .find(
+      row => authorOf(row) !== undefined && unquoted(bodyOf(row)).trim() !== ""
+    );
+  if (!reply) return { answer: null, reason: "no-answer-yet" };
+  const at = reply.createdAt ?? reply.created ?? reply.created_at ?? null;
+  return {
+    answer: {
+      text: bodyOf(reply).trim(),
+      author: authorOf(reply),
+      at: typeof at === "string" ? at : null,
+    },
+    reason: "answered",
+  };
+}

package/plugins/lisa/skills/lisa-session-manager/scripts/human-needed.mjs

@@ -0,0 +1,198 @@
+/**
+ * "Mark and move on" (CodySwannGT/lisa#4555, part 3): what the manager writes
+ * on a work item that cannot progress without a human, and how it reads the
+ * human's answer back off the item. Pure: no I/O, no clock, no config reads.
+ *
+ * Four cases need a human: a worker's question, an ambiguous repo route, an
+ * item `exhausted` after `stall.maxAttempts`, and a design or product
+ * decision. In each the manager marks the item with the configured
+ * human-needed marker, posts the question on the item with enough context to
+ * answer it there, records it pending in the ledger, and keeps dispatching
+ * other work. One item waiting on a person never stops the queue.
+ *
+ * The marker is the tracker's configured human-needed label; with no label
+ * for the tracker it is the configured `blocked` role. An `exhausted` item is
+ * also moved to the `blocked` role, because no worker is building it any
+ * more. Names always come from config, never from this file.
+ *
+ * Reading the answer back off the item lives in human-answer.mjs.
+ * @module session-manager/human-needed
+ */
+
+/** The four reasons an item can need a human. */
+export const HUMAN_NEEDED_KINDS = Object.freeze([
+  "worker-question",
+  "repo-route",
+  "exhausted",
+  "decision",
+]);
+
+/** Marks the manager's question comment, so its answer can be found after it. */
+export const QUESTION_MARKER = "[lisa-session-manager-question]";
+
+/** What each kind is called in the comment's first line. */
+const KIND_TITLES = {
+  "worker-question": "the worker building it has a question",
+  "repo-route": "it is not clear which repository it belongs to",
+  exhausted: "every automatic attempt to build it stopped without finishing",
+  decision: "it needs a design or product decision",
+};
+
+/**
+ * Credential shapes refused in question and answer text. Best effort: a match
+ * is refused, a miss is not proof the text is safe. A secret belongs in the
+ * project's secrets provider, never in a tracker comment or the ledger.
+ */
+const CREDENTIAL_SHAPES = [
+  ["Telegram bot token", /\b\d{8,10}:[A-Za-z0-9_-]{30,}\b/],
+  ["GitHub token", /\b(?:gh[pousr]_[A-Za-z0-9]{30,}|github_pat_\w{30,})/],
+  ["AWS access key", /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/],
+  ["Slack token", /\bxox[abprs]-[A-Za-z0-9-]{10,}/],
+  ["API key", /\bsk-(?:ant-)?[A-Za-z0-9_-]{20,}/],
+  ["private key", /-----BEGIN [A-Z ]*PRIVATE KEY-----/],
+  ["bearer token", /\bbearer\s+[A-Za-z0-9._~+/=-]{20,}/i],
+];
+
+/**
+ * The name of the first credential shape found in `text`, or null.
+ * @param {string} text - Question or answer text
+ * @returns {string | null} Shape name
+ */
+export function findCredentialShape(text) {
+  const found = CREDENTIAL_SHAPES.find(([, pattern]) => pattern.test(text));
+  return found ? found[0] : null;
+}
+
+/**
+ * The short label an operator starts a Telegram answer with: `#12` for a
+ * GitHub ref (`owner/repo#12`), the key itself for Jira and Linear.
+ * @param {string} ref - Item ref
+ * @returns {string} Answer label
+ */
+export function answerLabel(ref) {
+  const hash = ref.lastIndexOf("#");
+  return hash > 0 ? ref.slice(hash) : ref;
+}
+
+/**
+ * The comment the manager posts on the item. It names the ref, the reason,
+ * the question verbatim, and every way to answer, in plain English with
+ * nothing a reader has to paste and no local path. A reply on the item is
+ * offered only when someone may answer there (`answerers`): with no
+ * operator or trusted author configured, replies are never picked up.
+ * @param {{ref: string, kind: string, text: string, label: string,
+ *   markerText: string, channel: boolean, answerers: boolean}} input - What
+ *   to say
+ * @returns {string} Comment body
+ */
+function questionComment({
+  ref,
+  kind,
+  text,
+  label,
+  markerText,
+  channel,
+  answerers,
+}) {
+  const ways = [
+    answerers
+      ? `- Reply in a comment on this item, in plain words (do not start it with a bracketed tag). The session manager reads the first reply from an operator or trusted author on its next cycle.`
+      : `- Replies on this item are not picked up: no operator or trusted author is configured for the session manager.`,
+    `- On the machine running the session manager, run \`session-manager.mjs status\` and use the \`answerCommand\` it lists for this item.`,
+    ...(channel
+      ? [`- Or on Telegram: \`Answer with: ${label} <your answer>\`.`]
+      : []),
+  ];
+  return [
+    `${QUESTION_MARKER} ${ref} needs a human: ${KIND_TITLES[kind]}.`,
+    "",
+    text,
+    "",
+    "How to answer:",
+    ...ways,
+    "",
+    `The session manager keeps working on other items meanwhile. Once the answer is delivered it removes ${markerText} and says so here.`,
+  ].join("\n");
+}
+
+/**
+ * The marker for an item: the human-needed label, else the `blocked` role.
+ * @param {string | undefined} label - Configured human-needed label
+ * @param {string | undefined} blocked - Configured `blocked` role value
+ * @returns {{type: "label"|"role", value: string}} Marker
+ */
+function chooseMarker(label, blocked) {
+  if (label) return { type: "label", value: label };
+  if (blocked) return { type: "role", value: blocked };
+  throw new Error(
+    "no human-needed label and no blocked role is configured for this tracker; configure one (see the config-resolution rule) so the manager can mark the item"
+  );
+}
+
+/**
+ * Plan how to mark one item human-needed. Throws (a setup refusal) on an
+ * unknown kind, empty or credential-shaped text, no marker, or an `exhausted`
+ * item with no `blocked` role to move it to.
+ * @param {{ref: string, kind: string, text: string, label?: string,
+ *   blocked?: string, channel?: boolean, answerers?: boolean}} input - The
+ *   item, why, the question, the configured human-needed label and `blocked`
+ *   role value, whether a notification channel exists, and whether anyone
+ *   (operatorIds / trustedAuthorIds) may answer on the item
+ * @returns {{ref: string, kind: string, marker: {type: string, value: string},
+ *   move?: {role: "blocked", value: string}, comment: string,
+ *   answerWith: {item: string|null, cli: string, channel: string|null}}} Plan
+ */
+export function planMark({
+  ref,
+  kind,
+  text,
+  label,
+  blocked,
+  channel = false,
+  answerers = true,
+}) {
+  if (!HUMAN_NEEDED_KINDS.includes(kind)) {
+    throw new Error(`--kind must be one of: ${HUMAN_NEEDED_KINDS.join(", ")}.`);
+  }
+  const question = String(text ?? "").trim();
+  if (question === "") throw new Error("the question or reason is empty");
+  const shape = findCredentialShape(question);
+  if (shape) {
+    throw new Error(
+      `the text looks like it holds a credential (${shape}); it would be posted on the item. Remove it and keep secrets in the secrets provider.`
+    );
+  }
+  const marker = chooseMarker(label, blocked);
+  if (kind === "exhausted" && !blocked) {
+    throw new Error(
+      "an exhausted item moves to the blocked role, and none is configured for this tracker"
+    );
+  }
+  const move =
+    kind === "exhausted" ? { role: "blocked", value: blocked } : undefined;
+  const short = answerLabel(ref);
+  const markerText =
+    marker.type === "label"
+      ? `the \`${marker.value}\` label`
+      : `the hold (it moves the item out of \`${marker.value}\`)`;
+  return {
+    ref,
+    kind,
+    marker,
+    ...(move ? { move } : {}),
+    comment: questionComment({
+      ref,
+      kind,
+      text: question,
+      label: short,
+      markerText,
+      channel,
+      answerers,
+    }),
+    answerWith: {
+      item: answerers ? `a comment on ${ref}` : null,
+      cli: `the answerCommand that session-manager.mjs status lists for ${ref} (answer on stdin)`,
+      channel: channel ? `Answer with: ${short} <your answer>` : null,
+    },
+  };
+}

package/plugins/lisa/skills/lisa-session-manager/scripts/json-input.mjs

@@ -0,0 +1,34 @@
+/**
+ * JSON input for the session-manager CLI: parse text or read a file named by
+ * a flag, exiting 2 with the source named when it is not valid JSON. Split
+ * out of cli-queue.mjs to keep it under the line budget (#4555); cli-queue.mjs
+ * re-exports both, so callers keep their import.
+ * @module session-manager/json-input
+ */
+import { readFileSync } from "node:fs";
+
+import { CliError, asSetupError } from "./cli-runtime.mjs";
+
+/**
+ * Parse JSON, or exit 2 naming the source.
+ * @param {string} text - JSON text
+ * @param {string} source - Where it came from
+ * @returns {any} Parsed value
+ */
+export function parseJson(text, source) {
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new CliError(`${source} is not valid JSON: ${error.message}`, 2);
+  }
+}
+
+/**
+ * Read a JSON file named by a flag, or exit 2.
+ * @param {string} file - Path
+ * @returns {any} Parsed value
+ */
+export function readJsonFile(file) {
+  const text = asSetupError(() => readFileSync(file, "utf8"));
+  return parseJson(text, file);
+}

package/plugins/lisa/skills/lisa-session-manager/scripts/launch-shell.mjs

@@ -0,0 +1,115 @@
+/**
+ * The two shell-facing renderings of the manager's tmux launch, split out of
+ * launch.mjs to keep it under the line budget (#4555):
+ * - {@link buildForegroundCommand}: the display-only line an operator runs to
+ *   start the manager in the foreground and see claude's own error;
+ * - {@link buildSourcedLaunch}: the `tmux start-server ; source-file -` call
+ *   that carries secret session variables (the Telegram bot token) on stdin,
+ *   never in argv.
+ *
+ * Both take the argv `buildManagerLaunch` returned. Everything here is pure:
+ * nothing reads the environment or runs a process. launch.mjs re-exports
+ * every export, so callers keep one import.
+ * @module launch-shell
+ */
+import { LaunchError } from "./state-dir.mjs";
+
+/** A `'` inside a single-quoted shell word: close, escaped quote, reopen. */
+const ESCAPED_QUOTE = "'\\''";
+
+/** An argument a POSIX shell reads back unchanged without quotes. */
+const SHELL_SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/;
+
+/**
+ * Quote one argument for a POSIX shell, for display only.
+ * @param {string} value - Argument
+ * @returns {string} Single-quoted argument
+ */
+function shellQuote(value) {
+  return `'${value.replaceAll("'", ESCAPED_QUOTE)}'`;
+}
+
+/**
+ * The shell line an operator runs to start the manager in the foreground,
+ * from the tmux argv `buildManagerLaunch` (launch.mjs) returned: same cwd, the same
+ * two session variables, the same claude argv. `start` prints it when the
+ * tmux session dies at once, because tmux closes the window and claude's own
+ * error goes with it. It is display text only and is never executed here.
+ * The token is not in the argv, so it is not in this line either. When the
+ * token comes from a secrets provider, `shellVars` adds it as a command the
+ * operator's own shell runs (`$(node …/resolve-secret.mjs get <NAME>)`), so
+ * the line names the secret and never holds its value (#4555).
+ * @param {readonly string[]} argv - Result of `buildManagerLaunch` (launch.mjs)
+ * @param {Record<string, string>} [shellVars] - Extra variables, each value
+ *   double-quoted so the operator's shell expands it
+ * @returns {string} One shell line
+ */
+export function buildForegroundCommand(argv, shellVars = {}) {
+  const claudeAt = argv.indexOf("claude");
+  const head = argv.slice(0, claudeAt);
+  const cwd = head[head.indexOf("-c") + 1];
+  const vars = head
+    .filter((_, index) => head[index - 1] === "-e")
+    .map(entry => {
+      const at = entry.indexOf("=");
+      return `${entry.slice(0, at)}=${shellQuote(entry.slice(at + 1))}`;
+    });
+  const expanded = Object.entries(shellVars).map(
+    ([name, value]) => `${name}="${value}"`
+  );
+  const command = argv
+    .slice(claudeAt)
+    .map(arg => (SHELL_SAFE.test(arg) ? arg : shellQuote(arg)));
+  return `cd ${shellQuote(cwd)} && ${[...vars, ...expanded, ...command].join(" ")}`;
+}
+
+/**
+ * Quote one word for tmux's command parser: single quotes, inside which
+ * nothing is special, and `'"'"'` for a quote (close, a double-quoted quote,
+ * reopen; tmux joins adjacent quoted runs into one word).
+ * @param {string} word - Word
+ * @returns {string} Quoted word
+ */
+export function tmuxQuote(word) {
+  return `'${String(word).replaceAll("'", `'"'"'`)}'`;
+}
+
+/**
+ * The tmux call that starts the manager with secret session variables
+ * (the Telegram bot token from the secrets provider, #4555) that must never
+ * reach argv, where `ps` shows them to every user on the host.
+ *
+ * `tmux start-server ; source-file -` reads the `new-session` command from
+ * stdin, so the argv holds no value. The `-e` variables join the session's
+ * own environment only, the same as the ones `buildManagerLaunch` (launch.mjs)
+ * already passes. A newline in any word would end the command early and run
+ * the rest as a second tmux command, so it is refused.
+ * @param {readonly string[]} argv - Result of `buildManagerLaunch` (launch.mjs)
+ * @param {Record<string, string>} sessionVars - Extra session variables
+ * @returns {{ argv: string[], input: string }} argv for `spawnSync("tmux")`
+ *   and the line for its stdin
+ */
+export function buildSourcedLaunch(argv, sessionVars) {
+  if (argv[0] !== "new-session") {
+    throw new LaunchError("buildSourcedLaunch needs a new-session argv.");
+  }
+  const claudeAt = argv.indexOf("claude");
+  const words = [
+    ...argv.slice(0, claudeAt),
+    ...Object.entries(sessionVars).flatMap(([name, value]) => [
+      "-e",
+      `${name}=${value}`,
+    ]),
+    ...argv.slice(claudeAt),
+  ];
+  if (words.some(word => /[\r\n]/.test(word))) {
+    throw new LaunchError(
+      "A launch argument contains a newline, which would end the tmux " +
+        "command early. Nothing was started."
+    );
+  }
+  return {
+    argv: ["start-server", ";", "source-file", "-"],
+    input: `${words.map(tmuxQuote).join(" ")}\n`,
+  };
+}