claude-code-session-manager 0.27.0 → 0.29.0

package/plugins/session-manager-dev/skills/security-review/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: security-review
+description: >-
+  Check for common security vulnerabilities before shipping code — focus on what
+  actually gets exploited (OWASP Top 10: injection, auth, secrets, access control),
+  not compliance theater. Use before committing code that handles user input, auth,
+  or data storage; when adding API endpoints or external integrations; when
+  reviewing dependencies; or when asked to do a security review. Keywords: security,
+  vulnerability, OWASP, injection, auth, secrets, review.
+---
+
+# Security Review
+
+## Overview
+
+Check for common security vulnerabilities before shipping code. Focus on what actually gets exploited, not compliance theater.
+
+## When to Use
+
+- Before committing code that handles user input, auth, or data storage
+- When adding new API endpoints or external integrations
+- When reviewing dependencies or updating packages
+- When asked to do a security review
+
+## OWASP Top 10 Checklist
+
+### Injection (SQL, NoSQL, OS Command, LDAP)
+- All user input parameterized or escaped before use in queries
+- No string concatenation in SQL/NoSQL queries
+- No `eval()`, `exec()`, `shell=True`, or `child_process.exec()` with user input
+- ORM/query builder used instead of raw queries where possible
+
+### Broken Authentication
+- Passwords hashed with bcrypt/argon2 (never MD5/SHA1)
+- Session tokens are random, long, and expire
+- MFA available for sensitive operations
+- No credentials in URLs, logs, or error messages
+
+### Sensitive Data Exposure
+- No secrets in code, config files, or git history (.env, API keys, tokens)
+- Data encrypted at rest (AES-256) and in transit (TLS)
+- Sensitive fields excluded from logs and API responses
+- PII handled according to data classification
+
+### XSS (Cross-Site Scripting)
+- All output HTML-encoded by default (React JSX handles this)
+- No `dangerouslySetInnerHTML` or `v-html` without sanitization
+- Content-Security-Policy headers set
+- User input never inserted into `<script>` tags or event handlers
+
+### Broken Access Control
+- Every API endpoint checks authentication AND authorization
+- No direct object references without ownership verification
+- CORS configured to specific allowed origins (not `*`)
+- Rate limiting on auth and sensitive endpoints
+
+### Security Misconfiguration
+- No default credentials or debug modes in production
+- Error messages don't leak stack traces or internal details
+- HTTP security headers set (HSTS, X-Frame-Options, X-Content-Type-Options)
+- Unnecessary features and endpoints disabled
+
+### CSRF (Cross-Site Request Forgery)
+- State-changing requests use CSRF tokens or SameSite cookies
+- POST/PUT/DELETE endpoints reject requests without valid tokens
+
+## Dependency Check
+
+```bash
+# Node.js
+npm audit
+# Check for known vulnerabilities
+npx audit-ci --moderate
+
+# Python
+pip-audit
+safety check
+```
+
+Flag: outdated packages with known CVEs, unmaintained dependencies, packages with suspiciously few downloads or recent ownership transfers.
+
+## Secrets Scan
+
+Look for accidentally committed secrets:
+- API keys, tokens, passwords in source files
+- `.env` files not in `.gitignore`
+- Hardcoded connection strings
+- Private keys or certificates
+
+## Input Validation Rules
+
+- Validate at system boundaries (API endpoints, form handlers, file uploads)
+- Reject unexpected input types and sizes
+- Whitelist over blacklist
+- Validate on the server, never trust client-only validation
+
+## When Reporting Issues
+
+Classify findings:
+- **Critical**: Exploitable now, data at risk (injection, auth bypass, exposed secrets)
+- **High**: Exploitable with effort (XSS, CSRF, broken access control)
+- **Medium**: Defense-in-depth gap (missing headers, weak config)
+- **Low**: Best practice deviation (could become a problem later)
+
+Always provide the fix, not just the finding.

package/src/main/__tests__/scheduler-autofix-select.test.cjs

@@ -0,0 +1,95 @@
+/**
+ * scheduler-autofix-select.test.cjs — unit tests for selectAutoFixTargets.
+ *
+ * Run: timeout 120 node --test src/main/__tests__/scheduler-autofix-select.test.cjs
+ */
+
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { selectAutoFixTargets } = require('../scheduler.cjs');
+
+const noSiblingOnDisk = () => false;
+
+function makeJob(overrides = {}) {
+  return {
+    slug: '05-my-feature',
+    status: 'needs_review',
+    runId: '2026-06-16T10-00-00-000Z',
+    parallelGroup: 5,
+    ...overrides,
+  };
+}
+
+test('selects a fresh needs_review job', () => {
+  const jobs = [makeJob()];
+  const result = selectAutoFixTargets(jobs, { fixSlugExists: noSiblingOnDisk });
+  assert.strictEqual(result.length, 1);
+  assert.strictEqual(result[0].slug, '05-my-feature');
+});
+
+test('excludes job with autoFixAttempted: true', () => {
+  const jobs = [makeJob({ autoFixAttempted: true })];
+  const result = selectAutoFixTargets(jobs, { fixSlugExists: noSiblingOnDisk });
+  assert.strictEqual(result.length, 0);
+});
+
+test('excludes a fix-plan slug (05-fix-foo)', () => {
+  const jobs = [makeJob({ slug: '05-fix-foo' })];
+  const result = selectAutoFixTargets(jobs, { fixSlugExists: noSiblingOnDisk });
+  assert.strictEqual(result.length, 0);
+});
+
+test('excludes a failed job', () => {
+  const jobs = [makeJob({ status: 'failed' })];
+  const result = selectAutoFixTargets(jobs, { fixSlugExists: noSiblingOnDisk });
+  assert.strictEqual(result.length, 0);
+});
+
+test('excludes a completed job', () => {
+  const jobs = [makeJob({ status: 'completed' })];
+  const result = selectAutoFixTargets(jobs, { fixSlugExists: noSiblingOnDisk });
+  assert.strictEqual(result.length, 0);
+});
+
+test('excludes a job missing runId', () => {
+  const jobs = [makeJob({ runId: null })];
+  const result = selectAutoFixTargets(jobs, { fixSlugExists: noSiblingOnDisk });
+  assert.strictEqual(result.length, 0);
+});
+
+test('excludes when fix sibling exists on disk', () => {
+  const jobs = [makeJob()];
+  // fixSlug = '05-fix-my-feature'
+  const result = selectAutoFixTargets(jobs, { fixSlugExists: (s) => s === '05-fix-my-feature' });
+  assert.strictEqual(result.length, 0);
+});
+
+test('excludes when fix sibling already in the queue', () => {
+  const sibling = { slug: '05-fix-my-feature', status: 'pending', runId: null };
+  const jobs = [makeJob(), sibling];
+  const result = selectAutoFixTargets(jobs, { fixSlugExists: noSiblingOnDisk });
+  assert.strictEqual(result.length, 0);
+});
+
+test('fixSlug uses padded parallelGroup and strips leading digits from slug', () => {
+  const jobs = [makeJob({ slug: '07-some-task', parallelGroup: 7 })];
+  // Expected fixSlug: '07-fix-some-task'
+  const seen = [];
+  selectAutoFixTargets(jobs, {
+    fixSlugExists: (s) => { seen.push(s); return false; },
+  });
+  assert.strictEqual(seen[0], '07-fix-some-task');
+});
+
+test('defaults parallelGroup to 99 when absent', () => {
+  const jobs = [makeJob({ slug: '05-my-feature', parallelGroup: undefined })];
+  const seen = [];
+  selectAutoFixTargets(jobs, {
+    fixSlugExists: (s) => { seen.push(s); return false; },
+  });
+  assert.strictEqual(seen[0], '99-fix-my-feature');
+});
+
+console.log('scheduler-autofix-select tests: PASS');

package/src/main/__tests__/scheduler-autopromote.test.cjs

@@ -0,0 +1,33 @@
+/**
+ * scheduler-autopromote.test.cjs — unit tests for isPromotableOriginal.
+ *
+ * Run: timeout 120 node --test src/main/__tests__/scheduler-autopromote.test.cjs
+ */
+
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { isPromotableOriginal } = require('../scheduler.cjs');
+
+test('isPromotableOriginal: failed → true', () => {
+  assert.strictEqual(isPromotableOriginal('failed'), true);
+});
+
+test('isPromotableOriginal: needs_review → true', () => {
+  assert.strictEqual(isPromotableOriginal('needs_review'), true);
+});
+
+test('isPromotableOriginal: completed → false', () => {
+  assert.strictEqual(isPromotableOriginal('completed'), false);
+});
+
+test('isPromotableOriginal: running → false', () => {
+  assert.strictEqual(isPromotableOriginal('running'), false);
+});
+
+test('isPromotableOriginal: pending → false', () => {
+  assert.strictEqual(isPromotableOriginal('pending'), false);
+});
+
+console.log('scheduler-autopromote tests: PASS');

package/src/main/index.cjs

@@ -26,6 +26,7 @@ const watchers = require('./watchers.cjs');
 const teams = require('./teams.cjs');
 const queueOps = require('./queueOps.cjs');
 const pluginInstall = require('./pluginInstall.cjs');
+const { seedDevPlugin } = require('./seedDevPlugin.cjs');
 const otel = require('./otel.cjs');
 const otelSettings = require('./otelSettings.cjs');
 const { registerHistoryAggregatorHandlers } = require('./historyAggregator.cjs');
@@ -948,6 +949,12 @@ app.whenReady().then(async () => {
   scheduler.init().catch((e) => {
     logs.writeLine({ scope: 'scheduler', level: 'error', message: 'init failed', meta: { error: e?.message } });
   });
+  // First-boot default: install the bundled session-manager-dev plugin (its 10
+  // dev skills) from the app's own marketplace. One-shot + idempotent; never
+  // throws. SM_SEED_DEV_PLUGIN_DISABLE=1 to opt out.
+  seedDevPlugin({ logger: console }).catch((e) => {
+    logs.writeLine({ scope: 'seed-dev-plugin', level: 'error', message: 'seed failed', meta: { error: e?.message } });
+  });
   webRemote.init().catch((e) => {
     logs.writeLine({ scope: 'webRemote', level: 'error', message: 'init failed', meta: { error: e?.message } });
   });

package/src/main/ipcSchemas.cjs

@@ -358,8 +358,18 @@ const repoAnalyze = z.object({
 // Plugin install: mirrors pluginInstall.cjs SLUG_RE + length cap. Defense in
 // depth — install() re-checks; the schema rejects earlier.
 const PLUGIN_SLUG_RE = /^[a-z0-9\-/]+$/;
+const PLUGIN_MKT_ADD_RE = /^[A-Za-z0-9][A-Za-z0-9._\-]*\/[A-Za-z0-9._\-]+$/;
 const pluginsInstall = z.object({
   slug: z.string().regex(PLUGIN_SLUG_RE).min(1).max(128),
+  // Optional non-official marketplace: registered via `plugin marketplace add`
+  // before install. pluginInstall.cjs re-validates (defense in depth).
+  marketplace: z.object({
+    // `owner/repo`, or the literal `bundled` sentinel (app's own packaged
+    // marketplace — pluginInstall.cjs resolves it to an absolute path).
+    add: z.string().min(1).max(200)
+      .refine((v) => v === 'bundled' || PLUGIN_MKT_ADD_RE.test(v), 'invalid marketplace source'),
+    name: z.string().regex(PLUGIN_SLUG_RE).min(1).max(128),
+  }).optional(),
 }).passthrough();
 const pluginsAbort = z.object({
   slug: z.string().regex(PLUGIN_SLUG_RE).min(1).max(128),

package/src/main/lib/credentials.cjs

@@ -4,10 +4,55 @@ const fsp = require('node:fs/promises');
 const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
-const { spawn } = require('node:child_process');
+const { spawn, execFileSync } = require('node:child_process');
 const { cleanChildEnv } = require('./cleanEnv.cjs');
 
 const CREDS_PATH = path.join(os.homedir(), '.claude', '.credentials.json');
+
+// macOS stores Claude Code credentials in the login Keychain, not on disk —
+// there is no ~/.claude/.credentials.json there. The Keychain item is a
+// generic password under this service whose secret is the same JSON blob
+// ({ claudeAiOauth: { accessToken, … } }) the Linux/WSL file holds.
+const KEYCHAIN_SERVICE = 'Claude Code-credentials';
+
+/** Read the raw credential JSON string from the macOS Keychain, or null. */
+function readKeychainRaw() {
+  if (process.platform !== 'darwin') return null;
+  try {
+    const out = execFileSync(
+      'security',
+      ['find-generic-password', '-s', KEYCHAIN_SERVICE, '-w'],
+      { encoding: 'utf8', timeout: 10_000, stdio: ['ignore', 'pipe', 'ignore'] },
+    );
+    const trimmed = out.trim();
+    return trimmed.length ? trimmed : null;
+  } catch {
+    return null; // not found / locked — caller treats as "no creds here"
+  }
+}
+
+/** Discover the account the Keychain item is stored under (for write-back). */
+function keychainAccount() {
+  try {
+    const out = execFileSync(
+      'security',
+      ['find-generic-password', '-s', KEYCHAIN_SERVICE],
+      { encoding: 'utf8', timeout: 10_000, stdio: ['ignore', 'pipe', 'ignore'] },
+    );
+    const m = out.match(/"acct"<blob>="([^"]*)"/);
+    if (m && m[1]) return m[1];
+  } catch { /* fall through to login user */ }
+  return os.userInfo().username;
+}
+
+/** Write the credential JSON back into the Keychain (-U upserts in place). */
+function writeKeychainRaw(value) {
+  execFileSync(
+    'security',
+    ['add-generic-password', '-U', '-s', KEYCHAIN_SERVICE, '-a', keychainAccount(), '-w', value],
+    { timeout: 10_000, stdio: 'ignore' },
+  );
+}
 const REFRESH_LOG_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'credential-refresh.log');
 const REFRESH_LOG_MAX_BYTES = 100 * 1024;
 
@@ -16,17 +61,42 @@ const REFRESH_LOG_MAX_BYTES = 100 * 1024;
 // allowing the caller to fall back gracefully.
 const OAUTH_TOKEN_URL = 'https://claude.ai/api/auth/oauth/token';
 
+/** Parse a raw credential JSON blob (from file or Keychain) into a result. */
+function parseCredsRaw(raw, source) {
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (e) {
+    return { kind: 'config', message: `cannot parse ${source} credentials: ${e.message}` };
+  }
+  const oa = data?.claudeAiOauth;
+  if (!oa?.accessToken) return { kind: 'config', message: `missing accessToken in ${source} credentials` };
+  return { kind: 'ok', creds: oa, raw: data, source };
+}
+
 async function readCredentials() {
+  // 1) File — Linux / WSL (and macOS in the rare case a file exists).
   try {
     const raw = await fsp.readFile(CREDS_PATH, 'utf8');
-    const data = JSON.parse(raw);
-    const oa = data?.claudeAiOauth;
-    if (!oa?.accessToken) return { kind: 'config', message: 'missing accessToken in credentials file' };
-    return { kind: 'ok', creds: oa, raw: data };
+    return parseCredsRaw(raw, 'file');
   } catch (e) {
-    if (e?.code === 'ENOENT') return { kind: 'config', message: 'credentials file not found' };
-    return { kind: 'config', message: `cannot read credentials: ${e.message}` };
+    if (e?.code !== 'ENOENT') {
+      return { kind: 'config', message: `cannot read credentials: ${e.message}` };
+    }
+    // ENOENT — fall through to the macOS Keychain before giving up.
   }
+
+  // 2) macOS Keychain — the canonical store on darwin (no file there).
+  if (process.platform === 'darwin') {
+    const kc = readKeychainRaw();
+    if (kc) return parseCredsRaw(kc, 'keychain');
+    return {
+      kind: 'config',
+      message: `credentials not found (no ${CREDS_PATH}; no Keychain item "${KEYCHAIN_SERVICE}" — run \`claude\` to log in)`,
+    };
+  }
+
+  return { kind: 'config', message: 'credentials file not found' };
 }
 
 function expiresAtMs(creds) {
@@ -49,8 +119,14 @@ function isExpiringSoon(creds, withinMs = 5 * 60_000) {
   return ms !== null && ms - Date.now() < withinMs;
 }
 
-async function writeCredentials(rawData, freshOauth) {
+async function writeCredentials(rawData, freshOauth, source = 'file') {
   const next = { ...rawData, claudeAiOauth: { ...rawData.claudeAiOauth, ...freshOauth } };
+  if (source === 'keychain') {
+    // macOS: upsert back into the Keychain. Sync + may throw — caller catches
+    // and falls back to the `claude --version` CLI refresh path.
+    writeKeychainRaw(JSON.stringify(next));
+    return;
+  }
   const tmp = `${CREDS_PATH}.${process.pid}.${Date.now()}.tmp`;
   await fsp.writeFile(tmp, JSON.stringify(next, null, 2), { encoding: 'utf8', mode: 0o600 });
   try { await fsp.chmod(tmp, 0o600); } catch { /* umask may have already set it */ }
@@ -130,7 +206,7 @@ function tryCliFallback() {
 async function refreshIfNeeded(forceRefresh = false) {
   const cr = await readCredentials();
   if (cr.kind !== 'ok') return cr;
-  const { creds, raw } = cr;
+  const { creds, raw, source } = cr;
 
   if (!forceRefresh && !isExpiringSoon(creds)) {
     return { kind: 'ok', creds };
@@ -144,7 +220,7 @@ async function refreshIfNeeded(forceRefresh = false) {
 
   if (oauthResult.kind === 'ok') {
     try {
-      await writeCredentials(raw, oauthResult.fresh);
+      await writeCredentials(raw, oauthResult.fresh, source);
       const freshCr = await readCredentials();
       if (freshCr.kind === 'ok') {
         appendRefreshLog({ event: 'oauth_refresh_written_ok' });
@@ -188,4 +264,13 @@ async function refreshIfNeeded(forceRefresh = false) {
   return { kind: 'unsupported', message: 'Auto-refresh failed; token still valid for now', creds };
 }
 
-module.exports = { readCredentials, expiresAtMs, isExpired, isExpiringSoon, refreshIfNeeded };
+module.exports = {
+  readCredentials,
+  expiresAtMs,
+  isExpired,
+  isExpiringSoon,
+  refreshIfNeeded,
+  parseCredsRaw,
+  KEYCHAIN_SERVICE,
+  CREDS_PATH,
+};

package/src/main/pluginInstall.cjs

@@ -20,13 +20,29 @@ const { ipcMain } = require('electron');
 const pty = require('node-pty');
 const path = require('node:path');
 const os = require('node:os');
+const fs = require('node:fs');
 const { cleanChildEnv } = require('./lib/cleanEnv.cjs');
 const { resolveClaudeBin } = require('./lib/claudeBin.cjs');
 const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
 const { schemas } = require('./ipcSchemas.cjs');
 
 const SLUG_RE = /^[a-z0-9\-/]+$/;
+// Marketplace name: same shape as a plugin slug. Marketplace source (`add`):
+// a GitHub `owner/repo` (case-sensitive) or a dotted/hyphenated path segment.
+// Deliberately excludes whitespace, flags (leading `-`), and shell metachars.
+const MKT_NAME_RE = /^[a-z0-9\-/]+$/;
+const MKT_ADD_RE = /^[A-Za-z0-9][A-Za-z0-9._\-]*\/[A-Za-z0-9._\-]+$/;
+// Sentinel: register the marketplace that ships inside this app's own files
+// (the npx distribution). Resolved to an absolute path in-process so the
+// renderer never supplies a filesystem path. Works offline — no GitHub/npm.
+const BUNDLED_ADD = 'bundled';
 const MAX_LINE_BYTES = 16 * 1024;
+
+/** Absolute path to the packaged marketplace root (package dir holding
+ *  `.claude-plugin/marketplace.json`). src/main/ → ../../ */
+function bundledMarketplaceDir() {
+  return path.join(__dirname, '..', '..');
+}
 const KILL_AFTER_MS = 5 * 60 * 1000; // 5 min hard ceiling per install
 const KILL_GRACE_MS = 5_000;          // SIGTERM → SIGKILL escalation window
 
@@ -41,52 +57,51 @@ function send(channel, payload) {
   sendIfAlive(mainWindow, channel, payload);
 }
 
-function install({ slug }) {
-  if (typeof slug !== 'string' || !SLUG_RE.test(slug) || slug.length > 128) {
-    return Promise.resolve({ ok: false, exitCode: -1, error: 'invalid slug' });
-  }
-  if (inFlight.has(slug)) {
-    return Promise.resolve({ ok: false, exitCode: -1, error: 'install already in progress' });
-  }
+function childEnv() {
+  const home = os.homedir();
+  const extraPath = [
+    path.join(home, '.local', 'bin'),
+    path.join(home, '.npm-global', 'bin'),
+    '/usr/local/bin',
+    '/usr/bin',
+    '/bin',
+  ].join(':');
+  return cleanChildEnv({
+    PATH: `${extraPath}:${process.env.PATH || ''}`,
+    TERM: 'xterm-256color',
+    FORCE_COLOR: '0', // strip ANSI so the renderer doesn't have to.
+  });
+}
 
+/**
+ * Run one `claude plugin …` pty step, streaming output under `slug` and
+ * resolving with the exit code. `register`/`unregister` thread the live proc
+ * into the inFlight map so plugins:abort can kill whichever step is current.
+ */
+function runStep({ slug, args, register, unregister }) {
   return new Promise((resolve) => {
-    const home = os.homedir();
-    const extraPath = [
-      path.join(home, '.local', 'bin'),
-      path.join(home, '.npm-global', 'bin'),
-      '/usr/local/bin',
-      '/usr/bin',
-      '/bin',
-    ].join(':');
-    const env = cleanChildEnv({
-      PATH: `${extraPath}:${process.env.PATH || ''}`,
-      TERM: 'xterm-256color',
-      FORCE_COLOR: '0', // strip ANSI so the renderer doesn't have to.
-    });
-
     const claudeBin = resolveClaudeBin();
     let proc;
     try {
-      proc = pty.spawn(claudeBin, ['plugin', 'install', slug], {
+      proc = pty.spawn(claudeBin, args, {
         name: 'xterm-256color',
         cols: 120,
         rows: 30,
-        cwd: home,
-        env,
+        cwd: os.homedir(),
+        env: childEnv(),
       });
     } catch (err) {
       resolve({ ok: false, exitCode: -1, error: `spawn failed: ${err?.message ?? String(err)}` });
       return;
     }
 
-    inFlight.set(slug, proc);
+    register(proc);
 
     let lineBuf = '';
     let settled = false;
 
     const killTimer = setTimeout(() => {
       try { proc.kill('SIGTERM'); } catch { /* */ }
-      // Escalate to SIGKILL after KILL_GRACE_MS if the pty hasn't exited.
       const escalate = setTimeout(() => {
         try { proc.kill('SIGKILL'); } catch { /* already dead */ }
       }, KILL_GRACE_MS);
@@ -96,11 +111,11 @@ function install({ slug }) {
 
     // Belt-and-suspenders: if onExit never fires (broken pty event path after
     // SIGKILL — analogous to anthropics/claude-code #61735's unreachable pts),
-    // force-release the inFlight lock so the slug isn't permanently stuck.
+    // force-resolve so the step (and its inFlight lock) isn't permanently stuck.
     const deadman = setTimeout(() => {
       if (settled) return;
       settled = true;
-      inFlight.delete(slug);
+      unregister();
       resolve({ ok: false, exitCode: -1, error: 'install hung — pty onExit never fired' });
     }, KILL_AFTER_MS + KILL_GRACE_MS + 30_000);
     if (deadman.unref) deadman.unref();
@@ -113,7 +128,6 @@ function install({ slug }) {
         lineBuf = lineBuf.slice(nl + 1);
         send('plugins:install-progress', { slug, line });
       }
-      // Guard runaway buffers without newlines.
       if (lineBuf.length > MAX_LINE_BYTES) {
         send('plugins:install-progress', { slug, line: lineBuf });
         lineBuf = '';
@@ -129,13 +143,81 @@ function install({ slug }) {
         send('plugins:install-progress', { slug, line: lineBuf });
         lineBuf = '';
       }
-      inFlight.delete(slug);
+      unregister();
       const code = typeof exitCode === 'number' ? exitCode : -1;
       resolve({ ok: code === 0, exitCode: code });
     });
   });
 }
 
+/**
+ * Install a plugin. Without `marketplace`, runs `claude plugin install <slug>`
+ * (official catalog is pre-registered). With `marketplace: { add, name }`,
+ * first runs `claude plugin marketplace add <add>` to register the source, then
+ * installs `<slug>@<name>` — this is what a non-official plugin (e.g. the
+ * bundled session-manager-dev) needs on a fresh machine.
+ */
+async function install({ slug, marketplace }) {
+  if (typeof slug !== 'string' || !SLUG_RE.test(slug) || slug.length > 128) {
+    return { ok: false, exitCode: -1, error: 'invalid slug' };
+  }
+  let mkt = null;
+  if (marketplace != null) {
+    const { add, name } = marketplace;
+    const addValid = typeof add === 'string' && add.length <= 200 &&
+      (add === BUNDLED_ADD || MKT_ADD_RE.test(add));
+    if (!addValid || typeof name !== 'string' || !MKT_NAME_RE.test(name) || name.length > 128) {
+      return { ok: false, exitCode: -1, error: 'invalid marketplace' };
+    }
+    // Resolve the `bundled` sentinel to the app's own packaged marketplace dir.
+    let addArg = add;
+    if (add === BUNDLED_ADD) {
+      const dir = bundledMarketplaceDir();
+      if (!fs.existsSync(path.join(dir, '.claude-plugin', 'marketplace.json'))) {
+        return { ok: false, exitCode: -1, error: 'bundled marketplace not found' };
+      }
+      addArg = dir;
+    }
+    mkt = { add: addArg, name };
+  }
+  if (inFlight.has(slug)) {
+    return { ok: false, exitCode: -1, error: 'install already in progress' };
+  }
+
+  // Reserve the slug for the whole sequence; each step swaps in its live proc.
+  inFlight.set(slug, null);
+  const register = (proc) => inFlight.set(slug, proc);
+  const release = () => inFlight.delete(slug);
+  // Between steps the slug stays reserved (set to null) so a concurrent call
+  // can't slip in; runStep's unregister only clears the per-step proc handle.
+  const unregisterStep = () => inFlight.set(slug, null);
+
+  try {
+    if (mkt) {
+      const added = await runStep({
+        slug,
+        args: ['plugin', 'marketplace', 'add', mkt.add],
+        register,
+        unregister: unregisterStep,
+      });
+      // Tolerate "already added" — the add command exits non-zero when the
+      // marketplace is already registered; fall through to install regardless.
+      if (!added.ok) {
+        send('plugins:install-progress', { slug, line: `[marketplace add exit ${added.exitCode} — continuing to install]` });
+      }
+    }
+    const installTarget = mkt ? `${slug}@${mkt.name}` : slug;
+    return await runStep({
+      slug,
+      args: ['plugin', 'install', installTarget],
+      register,
+      unregister: unregisterStep,
+    });
+  } finally {
+    release();
+  }
+}
+
 function registerPluginInstallHandlers() {
   ipcMain.handle('plugins:install', async (_e, payload) => {
     // safeParse to preserve the existing `{ ok:false, exitCode:-1, error }`
@@ -145,7 +227,7 @@ function registerPluginInstallHandlers() {
     if (!parsed.success) {
       return { ok: false, exitCode: -1, error: 'invalid slug' };
     }
-    return install({ slug: parsed.data.slug });
+    return install({ slug: parsed.data.slug, marketplace: parsed.data.marketplace });
   });
 
   // plugins:abort — send SIGKILL to a stuck install and release the inFlight
@@ -164,4 +246,4 @@ function registerPluginInstallHandlers() {
   });
 }
 
-module.exports = { registerPluginInstallHandlers, attachWindow };
+module.exports = { registerPluginInstallHandlers, attachWindow, install, bundledMarketplaceDir };