claude-code-session-manager 0.47.1 → 0.49.0

package/dist/index.html

@@ -7,10 +7,10 @@
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
     <link href="https://fonts.googleapis.com/css2?family=Newsreader:ital,opsz,wght@0,6..72,400;0,6..72,500;0,6..72,600;0,6..72,700;1,6..72,400&family=Geist:wght@300;400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
-    <script type="module" crossorigin src="./assets/index--6k5kE62.js"></script>
+    <script type="module" crossorigin src="./assets/index-DkdVY_yL.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/monaco-editor-BW5C4Iv1.js">
     <link rel="stylesheet" crossorigin href="./assets/monaco-editor-BTnBOi8r.css">
-    <link rel="stylesheet" crossorigin href="./assets/index-B6DLwpeA.css">
+    <link rel="stylesheet" crossorigin href="./assets/index-CBdP0BTs.css">
   </head>
   <body class="bg-bg text-fg font-sans antialiased">
     <div id="root"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-session-manager",
-  "version": "0.47.1",
+  "version": "0.49.0",
   "description": "Local cockpit for the Claude Code CLI — multi-tab terminal, full config surface, scheduler, voice dictation, and live observability.",
   "type": "module",
   "main": "src/main/index.cjs",

package/plugins/session-manager-dev/skills/builder/0-diff/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: builder:diff
+description: Step 0 of builder — determine everything on HEAD that hasn't been published yet. Prefer the project's actual npm registry state over git tags, since a tag can exist without a matching publish (or vice versa); fall back to the last git tag when there's no resolvable package name or no network.
+---
+
+# builder:diff
+
+Resolve what "already published" means for this project, then list every commit on `HEAD`
+since that point.
+
+## 1. Resolve the build target
+
+Read `session-manager-operations/architecture/build-target.json` via
+`resolveBuildTarget(cwd)` in `src/main/lib/buildTarget.cjs` (falls back to `package.json`'s
+`name` if no explicit config exists). If `buildTarget.cjs` isn't present yet in this repo,
+read `package.json`'s `name` field directly and note in the final report that the config
+reader was missing — this does not block the pipeline.
+
+## 2. Determine the last published point
+
+Preferred: `npm view <packageName> version` — the actual registry state, not just a local
+tag. This catches the case where a tag was pushed but the publish itself failed partway
+(the tag would lie; the registry won't).
+
+Fallback (no network, or `npm view` 404s because the package was never published): use the
+last git tag instead — `git describe --tags --abbrev=0`.
+
+## 3. Diff
+
+```
+git log <last-published-version-or-tag>..HEAD --oneline
+```
+
+If `npm view` returned a version not tagged locally, resolve its tag first (`git tag -l
+'v<version>'`); if no matching local tag exists, fall back to comparing against
+`git describe --tags --abbrev=0` and note the discrepancy in the report.
+
+## Output
+
+- The resolved package name and last-published version/tag (and which method resolved it —
+  registry or git tag).
+- The full commit list (subject lines) since that point.
+- If the list is empty: stop here and report "nothing to publish" — do not proceed to
+  `builder:classify-and-bump`.

package/plugins/session-manager-dev/skills/builder/1-classify-and-bump/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: builder:classify-and-bump
+description: Step 1 of builder — parse conventional-commit prefixes from the commit list produced by builder:diff and decide the semver bump. Never guess when the history doesn't follow the convention — ask the user instead.
+---
+
+# builder:classify-and-bump
+
+Classify every commit subject from `builder:diff`'s output and pick the highest-severity
+bump that applies.
+
+## Rules (conventional commits)
+
+- Any commit containing `BREAKING CHANGE:` in its body, or a `!:` right after the type/scope
+  (e.g. `feat(api)!:`) → **major**.
+- Any `feat:`/`feat(scope):` commit (and no breaking marker above) → **minor**.
+- Any `fix:`/`fix(scope):` commit (and nothing higher) → **patch**.
+- `chore:`, `docs:`, `refactor:`, `test:`, `ci:` etc. with no `fix`/`feat`/breaking commit
+  alongside them → **patch** (matches this project's own convention — see recent history,
+  e.g. `chore(release): bump to v0.47.1` following a patch-only commit set).
+
+Take the **highest** bump implied by the whole commit list (one `feat:` among ten `fix:`
+commits still means minor; one breaking marker anywhere means major).
+
+## When commits don't follow the convention
+
+If a meaningful fraction of the commit list has no recognizable `type:` prefix at all (not
+just an unconventional scope — genuinely no prefix, e.g. a bare "wip" or "updates"), **do
+not guess**. Say so explicitly and ask the user which bump to apply, listing the
+unclassifiable commits. This mirrors `pr-review-sweep:classify`'s needs-decision carve-out —
+guessing wrong here ships an incorrect semver bump that's hard to walk back once published.
+
+## Output
+
+- The bump kind: `patch` | `minor` | `major`.
+- The commit list grouped by which rule matched each one (for the eventual report step).
+- If ambiguous: the question posed to the user instead of a bump kind, and the pipeline
+  pauses here until answered.

package/plugins/session-manager-dev/skills/builder/2-gate/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: builder:gate
+description: Step 2 of builder — run typecheck and unit tests, both time-bounded, as the hard pre-publish gate. A failing gate stops the pipeline; builder:publish never runs on a red gate.
+---
+
+# builder:gate
+
+Run this project's own check commands against `HEAD` exactly as they run in CI/manually —
+no shortcuts, no `--skip` flags.
+
+```
+timeout 180 npm run typecheck
+timeout 300 npm run test:unit
+```
+
+(Adjust bounds per project if `CLAUDE.md` documents different timing expectations — these
+values match session-manager's own commands: `tsc --noEmit` and `vitest run`.) Always wrap
+in `timeout` — an unbounded gate command is exactly the kind of stuck-job failure mode
+`PRD_AUTHORING.md` warns about elsewhere in this repo; a hang here should surface as a
+timeout, not run forever.
+
+## On failure
+
+Stop immediately. Do not proceed to `builder:publish`. Report:
+- which command failed (typecheck or test:unit)
+- the actual failure output (not just "gate failed")
+- that no version bump, tag, or publish happened
+
+## On success
+
+Proceed to `builder:publish` with no pause for reconfirmation — see the orchestrator's hard
+rules on this.
+
+## Output
+
+- `PASS` or `FAIL` per command.
+- Full failure output on `FAIL`, empty on `PASS`.

package/plugins/session-manager-dev/skills/builder/3-publish/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: builder:publish
+description: Step 3 of builder — the ISOLATED WORKTREE publish technique. Bumps the version, tags, then does the actual build+publish from a clean git worktree checked out at that tag so the live/dirty working directory is never touched by prepublishOnly's build step. Every command below was run for real 4 times in the session that originated this skill (session-manager v0.45.1 → v0.47.1).
+---
+
+# builder:publish
+
+A dirty working tree in the main repo is **not** a blocker for this step — that's the whole
+point of the isolated-worktree technique. Run the sequence below in order, without pausing
+to ask for reconfirmation once `builder:gate` has passed.
+
+## Procedure (exact order — verified across 4 real publishes)
+
+1. **Bump the version, package.json only:**
+   ```
+   npm version <bump> --no-git-tag-version
+   ```
+   (`<bump>` is the kind decided by `builder:classify-and-bump` — `patch`/`minor`/`major`.)
+   `--no-git-tag-version` matters: it updates `package.json`/`package-lock.json` without
+   creating a git tag yet, so the tag step below can carry a proper message.
+
+2. **Stage only the two version files — never `-A`:**
+   ```
+   git add package.json package-lock.json
+   ```
+
+3. **Commit, with a message listing the commits this release covers:**
+   ```
+   git commit -m "chore(release): bump to v<version>
+
+   - <commit 1 subject>
+   - <commit 2 subject>
+   - ..."
+   ```
+
+4. **Tag the release commit:**
+   ```
+   git tag v<version>
+   ```
+
+5. **Create the isolated worktree from that tag:**
+   ```
+   git worktree add /tmp/sm-publish-v<version> v<version>
+   ```
+
+6. **Move into the worktree and build clean:**
+   ```
+   cd /tmp/sm-publish-v<version>
+   npm ci
+   npm run typecheck
+   ```
+   `npm ci` gives a fully clean `node_modules` from the lockfile — no leftover local state
+   from the dirty main repo can leak into the published artifact.
+
+7. **Publish from inside the worktree:**
+   ```
+   npm publish
+   ```
+   This project's `prepublishOnly` script runs `vite build` — because step 6 already `cd`'d
+   into `/tmp/sm-publish-v<version>`, that build runs **inside the clean worktree**, never
+   touching (or being affected by) the live/dirty working directory back in the main repo.
+   This is the entire reason the worktree exists: it decouples "what's uncommitted in my
+   editor right now" from "what gets built and shipped."
+
+8. **Back in the main repo, push:**
+   ```
+   cd <main repo path>
+   git push origin main
+   git push origin v<version>
+   ```
+
+9. **Clean up the worktree:**
+   ```
+   git worktree remove /tmp/sm-publish-v<version> --force
+   ```
+
+10. **Verify the publish actually landed on the registry:**
+    ```
+    npm view <packageName> version
+    npm view <packageName> dist-tags
+    ```
+    Confirm the reported version matches `<version>` and `latest` points to it (unless the
+    project intentionally publishes to a different dist-tag).
+
+## On any step failing
+
+Stop at that step. Do not proceed. Report which step failed and its output. If the worktree
+was already created (step 5+), leave it in place if its state is relevant evidence for
+diagnosing the failure; otherwise remove it (step 9) before reporting, so a retry doesn't
+collide with a stale `/tmp/sm-publish-v<version>` path.
+
+## Output
+
+- Version published.
+- Confirmation the worktree was removed.
+- `npm view` output proving the registry has the new version and correct dist-tag.
+- Confirmation both `git push` calls succeeded (main + tag).

package/plugins/session-manager-dev/skills/builder/4-report/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: builder:report
+description: Step 4 of builder — summarize the completed (or stopped) publish run in one report — version bumped, commits covered, npm dist-tag verified, git push confirmed.
+---
+
+# builder:report
+
+Produce one concise summary of what happened, whether the pipeline reached publish or
+stopped early.
+
+## On a successful publish
+
+Report:
+- **Version**: previous → new (and bump kind: patch/minor/major).
+- **Commits covered**: the full list from `builder:diff`, grouped by the classification
+  `builder:classify-and-bump` assigned.
+- **Gate result**: typecheck + test:unit, both PASS.
+- **npm verification**: `npm view <packageName> version` and `dist-tags` output, confirming
+  the registry matches.
+- **Git state**: both `git push origin main` and `git push origin v<version>` confirmed;
+  worktree removed.
+
+## On an early stop (no diff, failed gate, ambiguous bump, or a publish-step failure)
+
+Report exactly which step stopped the pipeline and why:
+- `builder:diff` — "nothing to publish" (no commits since last release).
+- `builder:classify-and-bump` — the question posed to the user, still unanswered.
+- `builder:gate` — which command failed and its output.
+- `builder:publish` — which numbered step failed, its output, and whether a worktree or
+  local tag was left behind that a retry needs to account for.
+
+## Output
+
+One report, plain text, suitable for pasting into an Epic/PRD completion note or relaying
+directly to the user — no separate file is written by this step.

package/plugins/session-manager-dev/skills/builder/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: builder
+description: Watch the current project's git history against its published npm package and drive the next publish — diff HEAD against the last release, classify + bump the version from conventional-commit prefixes, gate on typecheck/tests, publish from an isolated git worktree (never the live working directory), then report. Orchestrates 5 nested sub-skills (builder:diff, :classify-and-bump, :gate, :publish, :report). Use when the user says "/builder", "publish", "release", "cut a release", "bump the version", "ship to npm", or asks whether there's anything unpublished.
+---
+
+# builder (orchestrator)
+
+Global, project-agnostic release pipeline — works against whatever npm package the current
+project publishes (resolved via `src/main/lib/buildTarget.cjs`'s `resolveBuildTarget()`, or
+by reading `package.json` directly if that file isn't present yet). Codified from a real
+session that ran this exact sequence 4 times by hand, publishing session-manager
+v0.45.1 → v0.47.1 to npm — this skill turns that proven manual procedure into a reusable one.
+
+**Naming convention** (same as `pr-review-sweep` and `issue-address`): sub-skill directories
+are prefixed `0-`, `1-`, ... in execution order, so a plain directory listing sorts in DAG
+order without opening any file. The invocable `name:` field stays a clean colon-scoped
+identifier (`builder:diff`) without the numeric prefix.
+
+## Pipeline DAG
+
+```
+┌───────────────────────┐
+│ 0. builder:diff            │  HEAD vs. last published version (npm view, else last git tag)
+└───────────────────────┘
+      │ commit list since last release (empty → stop, nothing to do)
+      ▼
+┌───────────────────────────┐
+│ 1. builder:classify-and-bump   │  conventional-commit prefixes → patch/minor/major
+└───────────────────────────┘     (non-conventional history → ask, don't guess)
+      │ bump kind decided
+      ▼
+┌───────────────────────┐
+│ 2. builder:gate            │  npm run typecheck + npm run test:unit, both bounded
+└───────────────────────┘
+   PASS │              │ FAIL
+        ▼              ▼
+┌───────────────────────┐   STOP — report failing gate, do not publish
+│ 3. builder:publish         │  ISOLATED WORKTREE technique (see that step's own file)
+└───────────────────────┘
+      │ version bumped, tagged, pushed, published, dist-tag verified
+      ▼
+┌───────────────────────┐
+│ 4. builder:report          │  version, commits covered, dist-tag, push confirmation
+└───────────────────────┘
+```
+
+| Step | Input | Output | On failure/empty |
+|---|---|---|---|
+| 0. `builder:diff` | current project cwd | commit list since last published version (or last git tag) | no commits since last release → stop, report "nothing to publish" |
+| 1. `builder:classify-and-bump` | commit list | bump kind (`patch`/`minor`/`major`) | commits don't follow conventional-commit style → say so, ask the user rather than guessing |
+| 2. `builder:gate` | working tree at HEAD | typecheck + unit test result | either fails → stop, report the failure, do not publish |
+| 3. `builder:publish` | bump kind, gate-passed HEAD | published npm package, pushed tag + main | any step fails → stop, report which step and the worktree's state (don't leave it behind uncleaned unless it's evidence of the failure) |
+| 4. `builder:report` | publish result | one summary: version bumped, commits covered, npm dist-tag verified, git push confirmed | n/a |
+
+## Hard rules — read before running any step
+
+- **A dirty working tree in the main repo is NOT a blocker.** The isolated-worktree
+  technique in `builder:publish` sidesteps it entirely — `npm ci` + `vite build` +
+  `npm publish` all run inside a clean worktree checked out from the just-created tag, never
+  touching the live/dirty repo. Don't hold the pipeline waiting for a clean tree; that
+  guidance is superseded by this skill.
+- **Once a diff is found and the gate passes, run the full sequence through to publish
+  without pausing for reconfirmation.** This was confirmed by the user across 4 consecutive
+  manual runs in the session that originated this skill — asking "should I publish now?"
+  after the gate is green is exactly the friction this skill exists to remove.
+- **The gate is a hard stop.** A failing `typecheck` or `test:unit` run means step 3 never
+  executes — no publish, no version bump, no tag. Report the failure and stop.
+- **Never guess a version bump from unconventional commit messages.** If the commit list
+  doesn't cleanly map to `fix:`/`feat:`/`BREAKING CHANGE:` prefixes, `builder:classify-and-bump`
+  asks the user which bump to apply rather than inferring one.
+
+## Why nested skills instead of one inline sequence
+
+Each step is its own file so it shows up as its own invocation in whatever surface tracks
+skill/tool calls, and so a step can be changed (a different gate command, a new registry
+target) without touching the others — same rationale as `pr-review-sweep` and
+`issue-address`.
+
+## What this skill is not
+
+- Not a decision-maker on *whether* to release — it assumes the user (or an Epic) already
+  wants the next diff shipped. If there's genuine ambiguity about scope, `builder:classify-and-bump`
+  is the one step that pauses to ask.
+- Not a registry-agnostic tool — `builder:publish` is npm-specific (see `buildTarget.cjs`'s
+  `registry` field for future non-npm targets; out of scope for this version).
+- Not wired to any UI button — invoking this skill is the only entry point today.

package/src/main/__tests__/agentLibrary.test.cjs

@@ -0,0 +1,133 @@
+/**
+ * agentLibrary.test.cjs — unit tests for the Agent Library nav page's
+ * backend: enumerating global `~/.claude/agents/*.md` personas and
+ * detecting per-project `.claude/agents/<name>.md` overlays among
+ * currently-open tabs.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/agentLibrary.test.cjs
+ */
+
+import { test, expect, afterEach } from 'vitest';
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const { listPersonas, openProjects, parseTools } = require('../agentLibrary.cjs');
+
+const tmpDirs = [];
+afterEach(async () => {
+  while (tmpDirs.length) {
+    const d = tmpDirs.pop();
+    await fsp.rm(d, { recursive: true, force: true });
+  }
+});
+
+async function mkTmp(prefix) {
+  const d = await fsp.mkdtemp(path.join(os.tmpdir(), prefix));
+  tmpDirs.push(d);
+  return d;
+}
+
+// listPersonas/openProjects take injectable deps; tests pass an identity
+// validatePath since the fixture dirs live under os.tmpdir(), not the real
+// home directory config.cjs's validatePath would otherwise enforce.
+const identityValidatePath = (p) => p;
+
+test('parseTools splits + trims a comma-separated tools frontmatter value', () => {
+  expect(parseTools('Read, Grep, Glob, Bash')).toEqual(['Read', 'Grep', 'Glob', 'Bash']);
+  expect(parseTools('')).toEqual([]);
+  expect(parseTools(undefined)).toEqual([]);
+});
+
+test('openProjects dedups by cwd and uses the last path segment as name', async () => {
+  const loadSessions = async () => ({
+    tabs: [
+      { cwd: '/home/u/Projects/alpha' },
+      { cwd: '/home/u/Projects/beta/' },
+      { cwd: '/home/u/Projects/alpha' }, // duplicate — should collapse
+      { cwd: null }, // malformed — should be skipped
+    ],
+  });
+  const projects = await openProjects({ loadSessions });
+  expect(projects).toEqual([
+    { cwd: '/home/u/Projects/alpha', name: 'alpha' },
+    { cwd: '/home/u/Projects/beta/', name: 'beta' },
+  ]);
+});
+
+test('listPersonas returns [] when the global agents dir does not exist', async () => {
+  const missingDir = path.join(os.tmpdir(), 'sm-agent-library-does-not-exist-' + Date.now());
+  const personas = await listPersonas({
+    globalDir: missingDir,
+    loadSessions: async () => ({ tabs: [] }),
+    validatePath: identityValidatePath,
+  });
+  expect(personas).toEqual([]);
+});
+
+test('listPersonas parses frontmatter and reports overridingProjects for open tabs with a local overlay', async () => {
+  const globalDir = await mkTmp('sm-agent-library-global-');
+  await fsp.writeFile(
+    path.join(globalDir, 'builder.md'),
+    [
+      '---',
+      'name: builder',
+      'description: Watch git history and drive the next publish.',
+      'tools: Read, Grep, Glob, Bash',
+      '---',
+      '',
+      'You are the Builder agent.',
+      '',
+    ].join('\n'),
+  );
+  await fsp.writeFile(
+    path.join(globalDir, 'debugger.md'),
+    ['---', 'name: debugger', 'description: Diagnose a failing test.', '---', '', 'Body.', ''].join('\n'),
+  );
+
+  const projectWithOverlay = await mkTmp('sm-agent-library-project-a-');
+  await fsp.mkdir(path.join(projectWithOverlay, '.claude', 'agents'), { recursive: true });
+  await fsp.writeFile(
+    path.join(projectWithOverlay, '.claude', 'agents', 'builder.md'),
+    '---\nname: builder\n---\nProject-specific overlay.\n',
+  );
+
+  const projectWithoutOverlay = await mkTmp('sm-agent-library-project-b-');
+
+  const loadSessions = async () => ({
+    tabs: [{ cwd: projectWithOverlay }, { cwd: projectWithoutOverlay }],
+  });
+
+  const personas = await listPersonas({ globalDir, loadSessions, validatePath: identityValidatePath });
+  expect(personas).toHaveLength(2);
+
+  const byName = Object.fromEntries(personas.map((p) => [p.name, p]));
+  expect(byName.builder.description).toBe('Watch git history and drive the next publish.');
+  expect(byName.builder.tools).toEqual(['Read', 'Grep', 'Glob', 'Bash']);
+  expect(byName.builder.body).toContain('You are the Builder agent.');
+  expect(byName.builder.overridingProjects).toEqual([path.basename(projectWithOverlay)]);
+
+  expect(byName.debugger.overridingProjects).toEqual([]);
+});
+
+test('listPersonas skips a project cwd that validatePath rejects, rather than throwing', async () => {
+  const globalDir = await mkTmp('sm-agent-library-global-');
+  await fsp.writeFile(path.join(globalDir, 'builder.md'), '---\nname: builder\n---\nBody.\n');
+
+  const rejectedProject = await mkTmp('sm-agent-library-project-rejected-');
+  await fsp.mkdir(path.join(rejectedProject, '.claude', 'agents'), { recursive: true });
+  await fsp.writeFile(path.join(rejectedProject, '.claude', 'agents', 'builder.md'), 'overlay\n');
+
+  const loadSessions = async () => ({ tabs: [{ cwd: rejectedProject }] });
+  // Simulate config.cjs's validatePath throwing for anything under the
+  // rejected project (as it would for a cwd outside the allowed-roots set)
+  // while still allowing the global agents dir itself to resolve.
+  const selectiveValidatePath = (p) => {
+    if (p.startsWith(rejectedProject)) throw new Error('outside allowed boundaries');
+    return p;
+  };
+
+  const personas = await listPersonas({ globalDir, loadSessions, validatePath: selectiveValidatePath });
+  expect(personas).toHaveLength(1);
+  expect(personas[0].overridingProjects).toEqual([]);
+});

package/src/main/agentLibrary.cjs

@@ -0,0 +1,115 @@
+'use strict';
+
+/**
+ * agentLibrary.cjs — read-only enumeration of agent personas for the
+ * "Agent Library" nav page (Home face only).
+ *
+ * Global agent definitions live at `~/.claude/agents/*.md`. Per Claude Code's
+ * own precedence rules, a project can overlay a same-named agent at
+ * `<project-cwd>/.claude/agents/<name>.md`, which wins over the global
+ * definition when both exist. This module reports, for every global agent,
+ * which of the currently-open TABs (per sessionsStore's persisted tab list —
+ * the same source of truth the renderer keeps in sync on every open/close)
+ * has such an overlay.
+ *
+ * All filesystem paths are routed through config.cjs's validatePath so this
+ * feature can't be used to read outside the home-dir boundary already
+ * enforced everywhere else in the app.
+ */
+
+const fsp = require('node:fs/promises');
+const fsSync = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { splitFrontmatter } = require('./lib/prdFrontmatter.cjs');
+const configMgr = require('./config.cjs');
+const sessionsStore = require('./sessionsStore.cjs');
+
+/** Parses the frontmatter `tools` field ("Read, Grep, Glob, Bash") into a list. */
+function parseTools(raw) {
+  if (!raw) return [];
+  return raw.split(',').map((t) => t.trim()).filter(Boolean);
+}
+
+/**
+ * Currently-open project tabs, deduped by cwd, as `{ cwd, name }` — `name`
+ * is the last path segment (matches the `projectNameFromCwd` convention used
+ * by the Scheduler's ProjectTag primitive). `loadSessions` is injectable
+ * (mirrors scheduler.cjs's notifyOriginatingTab) so tests can exercise the
+ * dedup/naming logic without touching the real persisted tabs.json.
+ */
+async function openProjects({ loadSessions = sessionsStore.load } = {}) {
+  const { tabs } = await loadSessions();
+  const seen = new Set();
+  const projects = [];
+  for (const t of tabs ?? []) {
+    if (!t || typeof t.cwd !== 'string' || !t.cwd || seen.has(t.cwd)) continue;
+    seen.add(t.cwd);
+    projects.push({ cwd: t.cwd, name: path.basename(t.cwd.replace(/\/+$/, '')) || t.cwd });
+  }
+  return projects;
+}
+
+/**
+ * Lists every global agent persona plus which open projects overlay it.
+ * Deps are injectable so tests can point `globalDir` at a fixture directory
+ * and `loadSessions` at a fake tab list without touching the real
+ * `~/.claude/agents` or `tabs.json`.
+ */
+async function listPersonas({
+  globalDir = path.join(os.homedir(), '.claude', 'agents'),
+  loadSessions = sessionsStore.load,
+  validatePath = configMgr.validatePath,
+} = {}) {
+  let files;
+  try {
+    files = (await fsp.readdir(globalDir)).filter((f) => f.endsWith('.md'));
+  } catch (e) {
+    if (e.code === 'ENOENT') return [];
+    throw e;
+  }
+
+  const projects = await openProjects({ loadSessions });
+  const personas = [];
+
+  for (const file of files.sort()) {
+    const fallbackName = file.replace(/\.md$/, '');
+    let real;
+    try {
+      real = validatePath(path.join(globalDir, file));
+    } catch {
+      continue; // out of bounds — shouldn't happen for a home-relative path
+    }
+    let text;
+    try {
+      text = await fsp.readFile(real, 'utf8');
+    } catch {
+      continue;
+    }
+    const { fm, body } = splitFrontmatter(text);
+
+    const overridingProjects = [];
+    for (const p of projects) {
+      let overlayReal;
+      try {
+        overlayReal = validatePath(path.join(p.cwd, '.claude', 'agents', file));
+      } catch {
+        continue; // project cwd outside allowed roots — skip rather than throw
+      }
+      if (fsSync.existsSync(overlayReal)) overridingProjects.push(p.name);
+    }
+
+    personas.push({
+      name: fm.name || fallbackName,
+      description: fm.description || null,
+      tools: parseTools(fm.tools),
+      path: real,
+      body: body.trim(),
+      overridingProjects,
+    });
+  }
+
+  return personas;
+}
+
+module.exports = { listPersonas, openProjects, parseTools };

package/src/main/index.cjs

@@ -30,6 +30,8 @@ const { createAdminHttp } = require('./lib/localAdminHttp.cjs');
 const prdCreate = require('./lib/prdCreate.cjs');
 const chatRunner = require('./chatRunner.cjs');
 const promptSessionEvents = require('./promptSessionEvents.cjs');
+const agentLibrary = require('./agentLibrary.cjs');
+const { resolveBuildTarget } = require('./lib/buildTarget.cjs');
 const adminHttp = createAdminHttp();
 scheduler.registerAdminRoutes(adminHttp);
 prdCreate.registerAdminRoute(adminHttp, scheduler.remote);
@@ -445,6 +447,11 @@ ipcMain.handle('app:launch-mode', () => ({
 // `claude mcp list`. Read-only, single in-flight call — no polling.
 ipcMain.handle('mcp:status', () => probeMcpStatus());
 
+// Agent Library nav page (Home face only): global `~/.claude/agents/*.md`
+// personas plus, per currently-open project tab, whether that project
+// overlays the same agent name at `<cwd>/.claude/agents/<name>.md`. Read-only.
+ipcMain.handle('agents:list-personas', () => agentLibrary.listPersonas());
+
 ipcMain.handle('app:engage-rules-path', () => process.env.SESSION_MANAGER_ENGAGE_RULES || null);
 
 // Boot diagnostics — renderer polls these to surface toasts when `claude` isn't
@@ -681,6 +688,13 @@ ipcMain.handle('app:git-branch', validated(schemas.appGitBranch, async ({ cwd })
   });
 }));
 
+// Resolves a project's publish target for 'build'-tagged Epics — see
+// lib/buildTarget.cjs. Null means the Build toolbar button should be disabled
+// (no explicit config, no auto-discoverable publishable package.json).
+ipcMain.handle('build:resolve-target', validated(schemas.buildResolveTarget, ({ cwd }) => {
+  return resolveBuildTarget(cwd);
+}));
+
 // Containment check for the open-in-{editor,finder,terminal} handlers lives
 // in lib/insideHome.cjs — single chokepoint for the /home/bilkoEVIL prefix-trap.
 // Editor / finder / terminal logic lives in lib/openExternalApp.cjs.