@codyswann/lisa 4.81.2 → 4.81.4

package/plugins/lisa-agy/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-agy/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>]

package/plugins/lisa-agy/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(", ")}).`,
+  };
+}

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

@@ -11,12 +11,12 @@
  * registry populates defaults into every project, and the manager starts
  * yolo-mode sessions; it must exist only where an operator wrote it.
  *
- * Pure apart from `detectRepos`, whose filesystem calls are injectable.
+ * Pure. Repo detection, which reads the filesystem, lives in repo-detect.mjs
+ * and is re-exported here so callers keep one import.
  * @module session-manager/config
  */
 
-import { existsSync, readdirSync } from "node:fs";
-import { isAbsolute, join, resolve, sep } from "node:path";
+import { isAbsolute, resolve, sep } from "node:path";
 
 import {
   mergeConfigLayers as mergeLayers,
@@ -25,6 +25,7 @@ import {
 } from "../../lisa-secrets-access/scripts/validate-config.mjs";
 
 export { parseLoopInterval, validateSessionManager };
+export { detectRepos, draftHints } from "./repo-detect.mjs";
 
 /**
  * Documented defaults for every optional key.
@@ -122,33 +123,6 @@ export function resolveSessionManagerConfig(globalConfig, localConfig) {
   };
 }
 
-/**
- * List the Lisa-configured child repos of a multi-repo project.
- *
- * A child counts only when it carries its own `.lisa.config.json`: workers run
- * `/lisa:implement` inside it, which needs that file, and a stray directory
- * under `projects/` is not something to route tickets into.
- * @param {string} root Project root.
- * @param {{
- *   reposRoot?: string,
- *   fs?: { existsSync: (p: string) => boolean,
- *     readdirSync: (p: string, o: { withFileTypes: true }) =>
- *       Array<{ name: string, isDirectory: () => boolean }> },
- * }} [options] Repos root (default `projects`) and filesystem seam.
- * @returns {string[]} Child directory names, sorted.
- */
-export function detectRepos(root, options = {}) {
-  const fs = options.fs ?? { existsSync, readdirSync };
-  const base = join(root, options.reposRoot ?? DEFAULT_REPOS_ROOT);
-  if (!fs.existsSync(base)) return [];
-  return fs
-    .readdirSync(base, { withFileTypes: true })
-    .filter(entry => entry.isDirectory() && SAFE_SEGMENT.test(entry.name))
-    .filter(entry => fs.existsSync(join(base, entry.name, ".lisa.config.json")))
-    .map(entry => entry.name)
-    .sort();
-}
-
 /**
  * Turn a project name into a slug the validator accepts.
  * @param {string} projectSlug Project name, possibly with dots or capitals.
@@ -177,13 +151,18 @@ function normalizeSlug(projectSlug) {
  * Defaults are written out rather than left implicit, so an operator sees
  * every knob in the file they will edit. With no detected repos the block has
  * no `repos` key, which is what makes a project single-repo. Each detected
- * repo's hints start as its own name: valid, and an obvious prompt to add real
- * ones.
- * @param {{ projectSlug: string, detectedRepos?: string[] }} input Project
- *   slug and the output of `detectRepos`.
+ * repo's hints are its drafted hints when given (`draftHints`), else its own
+ * name: valid either way, and setup asks the operator to review them.
+ * @param {{ projectSlug: string, detectedRepos?: string[],
+ *   hints?: Record<string, string[]> }} input Project slug, the output of
+ *   `detectRepos`, and drafted hints per repo.
  * @returns {SessionManagerBlock} A block `validateSessionManager` accepts.
  */
-export function buildDefaultBlock({ projectSlug, detectedRepos = [] }) {
+export function buildDefaultBlock({
+  projectSlug,
+  detectedRepos = [],
+  hints = {},
+}) {
   const slug = normalizeSlug(projectSlug);
   const repos = [...detectedRepos].sort();
   return {
@@ -194,7 +173,10 @@ export function buildDefaultBlock({ projectSlug, detectedRepos = [] }) {
           repos: {
             root: DEFAULT_REPOS_ROOT,
             entries: Object.fromEntries(
-              repos.map(name => [name, { hints: [name] }])
+              repos.map(name => [
+                name,
+                { hints: hints[name]?.length ? [...hints[name]] : [name] },
+              ])
             ),
           },
         }

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

@@ -43,6 +43,7 @@ export {
   buildStoreTokenCommand,
   loadPromptSecret,
   storeToken,
+  storeTokenFromClipboard,
   validateBotToken,
   writeTokenFile,
 } from "./token.mjs";

package/plugins/lisa-agy/skills/lisa-session-manager/scripts/repo-detect.mjs

@@ -0,0 +1,205 @@
+/**
+ * Which children of a multi-repo project's repos root are real, routable
+ * repos, and a first draft of the hints the manager routes on.
+ *
+ * A host's `projects/` dir collects more than one checkout per repo: linked
+ * worktrees agents made for a ticket (`.git` is a FILE pointing back at the
+ * main clone), and whole second clones of the same remote (`api-se1234`).
+ * Each carries the repo's own `.lisa.config.json`, so counting config files
+ * alone proposed 110 routed repos for a project with 4 (CodySwannGT/lisa#4465)
+ * and the operator had to prune them by hand. A worker routed into a stale
+ * ticket worktree builds on the wrong branch, so the detector keeps one
+ * checkout per remote: the one named after the repo when there is one.
+ *
+ * Every filesystem call goes through an injectable seam.
+ * @module session-manager/repo-detect
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/** One path segment that cannot climb out of, or hide inside, its parent. */
+const SAFE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/** `url = <value>` inside the `[remote "origin"]` section of a git config. */
+const ORIGIN_SECTION = /^\s*\[remote\s+"origin"\]\s*$/;
+const ANY_SECTION = /^\s*\[/;
+const URL_LINE = /^\s*url\s*=\s*(\S+)\s*$/;
+
+/**
+ * Well-known dependencies and the hint each one implies. Order is the order
+ * hints are listed in. A key ending in `/` matches every package under that
+ * scope.
+ */
+const DEPENDENCY_HINTS = Object.freeze([
+  ["@nestjs/", "NestJS"],
+  ["typeorm", "TypeORM"],
+  ["prisma", "Prisma"],
+  ["@prisma/client", "Prisma"],
+  ["@apollo/server", "GraphQL API"],
+  ["graphql", "GraphQL"],
+  ["express", "Express"],
+  ["fastify", "Fastify"],
+  ["serverless", "Serverless"],
+  ["expo", "Expo"],
+  ["react-native", "React Native"],
+  ["next", "Next.js"],
+  ["react", "React"],
+  ["vue", "Vue"],
+  ["@angular/core", "Angular"],
+  ["@apollo/client", "Apollo client"],
+  ["aws-cdk-lib", "AWS CDK"],
+  ["@pulumi/pulumi", "Pulumi"],
+  ["@langchain/langgraph", "LangGraph"],
+  ["@langchain/core", "LangChain"],
+  ["@anthropic-ai/sdk", "Claude API"],
+  ["@aws-sdk/client-bedrock-runtime", "Bedrock"],
+  ["phaser", "Phaser"],
+  ["@playwright/test", "Playwright"],
+]);
+
+/** The default filesystem seam. */
+const NODE_FS = { existsSync, readdirSync, readFileSync, statSync };
+
+/**
+ * Reduce a git remote URL to `host/owner/repo` so the SSH and HTTPS spellings
+ * of one remote compare equal. Returns null for anything unparseable.
+ * @param {string} url - Remote URL as written in `.git/config`
+ * @returns {string | null} Normalized identity, lowercased
+ */
+export function normalizeRemote(url) {
+  const trimmed = String(url ?? "").trim();
+  const scp = /^[^@/]+@([^:/]+):(.+)$/.exec(trimmed);
+  const parsed = scp
+    ? null
+    : /^[a-z+]+:\/\/(?:[^@/]+@)?([^/:]+)(?::\d+)?\/(.+)$/i.exec(trimmed);
+  const match = scp ?? parsed;
+  if (!match) return null;
+  const repoPath = match[2].replace(/\/+$/, "").replace(/\.git$/, "");
+  return repoPath ? `${match[1]}/${repoPath}`.toLowerCase() : null;
+}
+
+/**
+ * The `origin` URL from a clone's `.git/config`, or null.
+ * @param {string} dir - Child directory
+ * @param {typeof NODE_FS} fs - Filesystem seam
+ * @returns {string | null} Raw URL
+ */
+function readOrigin(dir, fs) {
+  let text;
+  try {
+    text = fs.readFileSync(join(dir, ".git", "config"), "utf8");
+  } catch {
+    return null;
+  }
+  let inOrigin = false;
+  for (const line of text.split(/\r?\n/)) {
+    if (ANY_SECTION.test(line)) inOrigin = ORIGIN_SECTION.test(line);
+    const url = inOrigin ? URL_LINE.exec(line) : null;
+    if (url) return url[1];
+  }
+  return null;
+}
+
+/** The `gitdir:` line of a linked worktree points into `.git/worktrees/`. */
+const WORKTREE_GITDIR = /^gitdir:\s*\S*[\\/]worktrees[\\/]/m;
+
+/**
+ * Whether `<dir>` is a linked worktree: its `.git` is a file whose `gitdir:`
+ * points into another clone's `worktrees/`. A `.git` file that points
+ * anywhere else (a submodule, `--separate-git-dir`) may be the only checkout
+ * of its repo, so it is kept.
+ * @param {string} dir - Child directory
+ * @param {typeof NODE_FS} fs - Filesystem seam
+ * @returns {boolean} True for a linked worktree
+ */
+function isLinkedWorktree(dir, fs) {
+  const marker = join(dir, ".git");
+  try {
+    if (!fs.statSync(marker).isFile()) return false;
+    return WORKTREE_GITDIR.test(fs.readFileSync(marker, "utf8"));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Keep one child per remote: the one whose name is the remote's repo name,
+ * else the lexically first. Children with no readable origin are each kept.
+ * @param {Array<{ name: string, remote: string | null }>} children - Sorted
+ * @returns {string[]} Kept names, sorted
+ */
+function onePerRemote(children) {
+  const groups = new Map();
+  const kept = [];
+  for (const child of children) {
+    if (child.remote === null) kept.push(child.name);
+    else groups.set(child.remote, [...(groups.get(child.remote) ?? []), child]);
+  }
+  for (const [remote, members] of groups) {
+    const repoName = remote.split("/").at(-1);
+    const named = members.find(
+      member => member.name.toLowerCase() === repoName
+    );
+    kept.push((named ?? members[0]).name);
+  }
+  return kept.sort();
+}
+
+/**
+ * List the routable child repos of a multi-repo project.
+ *
+ * A child counts only when it carries its own `.lisa.config.json` (workers
+ * run `/lisa:implement` inside it, which needs that file), is not a linked
+ * worktree, and is the chosen checkout of its remote.
+ * @param {string} root - Project root
+ * @param {{ reposRoot?: string, fs?: Partial<typeof NODE_FS> }} [options] -
+ *   Repos root (default `projects`) and filesystem seam
+ * @returns {string[]} Child directory names, sorted
+ */
+export function detectRepos(root, options = {}) {
+  const fs = { ...NODE_FS, ...options.fs };
+  const base = join(root, options.reposRoot ?? "projects");
+  if (!fs.existsSync(base)) return [];
+  const children = fs
+    .readdirSync(base, { withFileTypes: true })
+    .filter(entry => entry.isDirectory() && SAFE_SEGMENT.test(entry.name))
+    .map(entry => ({ name: entry.name, dir: join(base, entry.name) }))
+    .filter(child => fs.existsSync(join(child.dir, ".lisa.config.json")))
+    .filter(child => !isLinkedWorktree(child.dir, fs))
+    .map(child => ({
+      name: child.name,
+      remote: normalizeRemote(readOrigin(child.dir, fs) ?? ""),
+    }))
+    .sort((a, b) => (a.name < b.name ? -1 : 1));
+  return onePerRemote(children);
+}
+
+/**
+ * Draft routing hints for one child: its name, then a hint per well-known
+ * dependency in its `package.json`. Only a draft; setup asks the operator to
+ * review it. A child with no `package.json`, or none of the known
+ * dependencies, keeps just its name.
+ * @param {string} dir - Child directory
+ * @param {string} name - Child name (always the first hint)
+ * @param {{ fs?: Partial<typeof NODE_FS> }} [options] - Filesystem seam
+ * @returns {string[]} Hints, de-duplicated, name first
+ */
+export function draftHints(dir, name, options = {}) {
+  const fs = { ...NODE_FS, ...options.fs };
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(join(dir, "package.json"), "utf8"));
+  } catch {
+    return [name];
+  }
+  const deps = Object.keys({
+    ...manifest?.dependencies,
+    ...manifest?.devDependencies,
+  });
+  const hints = DEPENDENCY_HINTS.filter(([key]) =>
+    key.endsWith("/")
+      ? deps.some(dep => dep.startsWith(key))
+      : deps.includes(key)
+  ).map(([, hint]) => hint);
+  return [...new Set([name, ...hints])];
+}