claude-code-session-manager 0.75.3 → 0.76.0

package/scripts/lib/activeSessions.cjs

@@ -11,8 +11,28 @@
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const { KIND_CONFIG: WORKTREE_KIND_CONFIG } = require('../../src/main/lib/gitWorktree.cjs');
 
 const HOME = os.homedir();
+const TMPDIR = os.tmpdir();
+
+// The last-resort drop targets for addCwd's tmp guard.
+//   - exactDropCwds: dropped only on an EXACT match — os.tmpdir() itself
+//     (e.g. `/tmp`). NOT a prefix match: this codebase's own test suite
+//     routinely stubs HOME to a tmp dir and nests a fake project cwd
+//     underneath it, a legitimate, unrelated use of os.tmpdir() that a
+//     blanket prefix match would wrongly drop.
+//   - prefixDropRoots: dropped on an exact match OR any nested path — the two
+//     managed worktree roots (both live under os.tmpdir() per gitWorktree
+//     .cjs's KIND_CONFIG). Nothing but managed worktree checkouts is ever
+//     created under these roots, so a prefix match here is safe. A resolvable
+//     worktree (managed or user-made, anywhere on disk) is already handled by
+//     worktreeMainRootOf above; this guard only catches what that resolution
+//     could not — e.g. a bare, .git-less worktree-root directory.
+const TMP_DROP_ROOTS = {
+  exactDropCwds: [TMPDIR],
+  prefixDropRoots: [WORKTREE_KIND_CONFIG.job.root, WORKTREE_KIND_CONFIG.epic.root],
+};
 
 // Transcript reads only need the last line with a `cwd` field — a few dozen
 // lines is always enough. 64 KB keeps peak RSS proportionate.
@@ -37,16 +57,93 @@ const MAX_CWDS = 50;
 // signal survives instead of being silently lost.
 const OPS_DIRNAME = 'session-manager-operations';
 
+// Bound on the ancestor walk in worktreeMainRootOf — well past any real
+// filesystem depth, purely to guarantee termination without relying on
+// reaching '/' (e.g. a symlink loop or an unusually deep path).
+const MAX_WORKTREE_WALK = 40;
+
+const WORKTREES_MARKER = `${path.sep}.git${path.sep}worktrees${path.sep}`;
+
+/**
+ * worktreeMainRootOf(cwd) → the main tree's root when cwd sits inside a
+ * linked `git worktree` (job/epic worktrees under os.tmpdir(), or a
+ * user-made one anywhere). Walks UP from cwd looking for a `.git` entry:
+ *   - `.git` is a FILE (linked worktree) whose first line is
+ *     `gitdir: <main>/.git/worktrees/<name>` → returns <main>.
+ *   - `.git` is a DIRECTORY (already the main tree) → returns that ancestor.
+ *   - nothing found within MAX_WORKTREE_WALK levels → returns null.
+ * Pure fs, synchronous, never throws — any unexpected shape (garbled file,
+ * unreadable entry, gitdir path without the worktrees marker) yields null so
+ * the caller leaves the cwd unchanged rather than guessing.
+ */
+function worktreeMainRootOf(cwd) {
+  let dir = cwd;
+  for (let i = 0; i < MAX_WORKTREE_WALK; i++) {
+    const gitPath = path.join(dir, '.git');
+    let stat;
+    try {
+      stat = fs.statSync(gitPath);
+    } catch {
+      stat = null;
+    }
+    if (stat) {
+      if (stat.isDirectory()) return dir;
+      if (stat.isFile()) {
+        let body;
+        try {
+          body = fs.readFileSync(gitPath, 'utf8');
+        } catch {
+          return null;
+        }
+        const firstLine = body.split('\n', 1)[0].trim();
+        const prefix = 'gitdir:';
+        if (!firstLine.startsWith(prefix)) return null;
+        const gitdir = firstLine.slice(prefix.length).trim();
+        const markerIdx = gitdir.indexOf(WORKTREES_MARKER);
+        if (markerIdx <= 0) return null;
+        const candidateMain = gitdir.slice(0, markerIdx);
+        const worktreeName = gitdir.slice(markerIdx + WORKTREES_MARKER.length).split(path.sep)[0];
+        // Round-trip verification: gitdir's content is a plain file that
+        // anything on disk could have written (e.g. a nested `.git` file
+        // tracked inside an untrusted repo), so it must not be trusted to
+        // redirect callers to an arbitrary attacker-chosen absolute path.
+        // A genuine linked worktree's admin dir back-references the exact
+        // `.git` FILE we are resolving via its own `gitdir` pointer file —
+        // require that round trip before accepting candidateMain.
+        if (!worktreeName) return null;
+        const adminGitdirFile = path.join(candidateMain, '.git', 'worktrees', worktreeName, 'gitdir');
+        let backRef;
+        try {
+          backRef = fs.readFileSync(adminGitdirFile, 'utf8').trim();
+        } catch {
+          return null;
+        }
+        if (path.resolve(backRef) !== path.resolve(gitPath)) return null;
+        return candidateMain;
+      }
+      return null;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
 /**
  * projectRootOf(cwd) → the project root for a cwd that may sit inside an ops
- * tree. Returns cwd unchanged when it does not. Only the FIRST occurrence
- * matters — a nested stray ops root is itself the bug, never a project.
+ * tree and/or a linked git worktree. Returns cwd unchanged when neither
+ * applies. Only the FIRST ops-dir occurrence matters — a nested stray ops
+ * root is itself the bug, never a project. The ops-dir truncation runs
+ * first, then the worktree resolution, so a cwd deep inside a worktree's OWN
+ * ops tree still lands on the real project's main root.
  */
 function projectRootOf(cwd) {
   const parts = cwd.split(path.sep);
   const i = parts.indexOf(OPS_DIRNAME);
-  if (i <= 0) return cwd;
-  return parts.slice(0, i).join(path.sep) || path.sep;
+  const truncated = i > 0 ? (parts.slice(0, i).join(path.sep) || path.sep) : cwd;
+  const mainRoot = worktreeMainRootOf(truncated);
+  return mainRoot || truncated;
 }
 
 /**
@@ -85,11 +182,13 @@ function readTailLines(filePath, maxBytes) {
  *   Complexity: O(P × L) over P project dirs, each bounded-tail read (64 KB).
  *
  * opts (for testing):
- *   projectsDir  — override the default ~/.claude/projects path
+ *   projectsDir   — override the default ~/.claude/projects path
+ *   tmpDropRoots  — override the tmp guard's drop roots (default TMP_DROP_ROOTS)
  */
 function activeProjectCwds(maxAgeMin = 90, {
   projectsDir = path.join(HOME, '.claude', 'projects'),
   maxCwds = MAX_CWDS,
+  tmpDropRoots = TMP_DROP_ROOTS,
 } = {}) {
   // maxAgeMin === Infinity means "every project ever seen, no recency filter"
   // (allProjectCwds below). Date.now() - Infinity is -Infinity, which every
@@ -111,6 +210,17 @@ function activeProjectCwds(maxAgeMin = 90, {
     // whole per-project state off these strings — a project is a cwd, and a
     // cwd is an absolute path.
     if (!path.isAbsolute(cwd)) return;
+    // Drop-guard of last resort: a cwd that is (or sits inside) a known
+    // worktree-scratch root after projectRootOf's normalization is one
+    // worktreeMainRootOf could not resolve to a main tree — never a real
+    // project.
+    if (tmpDropRoots.exactDropCwds.includes(cwd)) return;
+    const isUnderPrefixDropRoot = tmpDropRoots.prefixDropRoots.some((root) => {
+      if (cwd === root) return true;
+      const rel = path.relative(root, cwd);
+      return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+    });
+    if (isUnderPrefixDropRoot) return;
     if (seen.has(cwd) || result.length >= maxCwds) return;
     // Must exist AND be a directory — a transcript naming a since-deleted
     // path, or a file, is not a project.
@@ -178,4 +288,4 @@ function allProjectCwds(opts = {}) {
   return activeProjectCwds(Infinity, { maxCwds: 500, ...opts });
 }
 
-module.exports = { activeProjectCwds, allProjectCwds, projectRootOf };
+module.exports = { activeProjectCwds, allProjectCwds, projectRootOf, worktreeMainRootOf };

package/scripts/scheduler-mcp-server.cjs

@@ -29,11 +29,33 @@ const {
   CallToolRequestSchema,
 } = require('@modelcontextprotocol/sdk/types.js');
 const { PRD_WORK_TYPES } = require('../src/main/lib/workTypeLibrary.cjs');
+const { MCP_TOOL_CATALOG, MCP_RECIPES, composeDescription } = require('../src/main/lib/mcpToolCatalog.cjs');
+
+const CATALOG_BY_NAME = new Map(MCP_TOOL_CATALOG.map((entry) => [entry.name, entry]));
+
+function descriptionFor(toolName) {
+  const entry = CATALOG_BY_NAME.get(toolName);
+  if (!entry) throw new Error(`mcpToolCatalog.cjs has no entry for tool "${toolName}"`);
+  return composeDescription(entry);
+}
 
 const TOKEN_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'admin-api.json');
 
+// Defined once so every failure path points to the same next call, verbatim
+// — never paste this sentence at each return site (PRD: session_manager_help).
+const HELP_POINTER = ' — call session_manager_help for the correct usage';
+
+function withPointer(text) {
+  const str = String(text);
+  return str.endsWith(HELP_POINTER) ? str : str + HELP_POINTER;
+}
+
+function errorResult(text) {
+  return { content: [{ type: 'text', text: withPointer(text) }], isError: true };
+}
+
 const NOT_RUNNING_ERROR =
-  'session-manager app is not running (admin API unreachable) — start it first';
+  `session-manager app is not running (admin API unreachable) — start it first${HELP_POINTER}`;
 
 async function readAdminConfig() {
   const raw = await fsp.readFile(TOKEN_PATH, 'utf8');
@@ -68,56 +90,56 @@ async function adminRequest(method, urlPath, body) {
   return json;
 }
 
+// session_manager_help's live half. The catalog/recipes below are static and
+// answerable purely in-process (no admin API needed), but "is this MCP
+// server actually wired up for THIS project" needs the admin API's
+// checkDelegationReadiness result — that's genuinely unavailable when the
+// app is down, so this must degrade to a reported-unavailable state rather
+// than throwing NOT_RUNNING_ERROR and failing the whole help call.
+async function fetchReadiness() {
+  // SM_PROJECT_ROOT (when present) is a trusted hint for the real project
+  // root — forwarded so a worktree/ops-internal process.cwd() still reports
+  // the real project's readiness. See projectRootResolve.cjs.
+  const cwd = process.env.SM_PROJECT_ROOT || process.cwd();
+  try {
+    const qs = new URLSearchParams({ cwd });
+    const result = await adminRequest('GET', `/admin/mcp/readiness?${qs.toString()}`);
+    if (result?.ok === false) {
+      return { available: false, cwd, reason: result.error ?? 'readiness check failed' };
+    }
+    return { available: true, cwd, ok: result.ready, checks: result.checks };
+  } catch (e) {
+    return { available: false, cwd, reason: e?.message ?? String(e) };
+  }
+}
+
 const TOOLS = [
   {
     name: 'scheduler_reset_job',
-    description: "Reset a stuck scheduler job by slug via the session-manager app's admin API. "
-      + 'Refuses a job whose status is already "completed" unless force:true is passed — resetting '
-      + 'a completed job re-executes already-shipped work.',
+    description: descriptionFor('scheduler_reset_job'),
     inputSchema: {
       type: 'object',
       properties: {
         slug: { type: 'string', description: 'PRD slug of the job to reset' },
         force: { type: 'boolean', description: 'Required to reset a job whose status is already "completed"' },
+        cwd: { type: 'string', description: 'Optional: the PRD project cwd, narrows/speeds the search' },
       },
       required: ['slug'],
     },
   },
   {
     name: 'scheduler_list_jobs',
-    description: "List scheduler jobs via the session-manager app's admin API.",
+    description: descriptionFor('scheduler_list_jobs'),
     inputSchema: { type: 'object', properties: {} },
   },
   {
     name: 'scheduler_create_prd',
-    description:
-      "THE ONLY SANCTIONED WAY to author a PRD. Write a new PRD file via the session-manager "
-      + "app's admin API. Server-side validates the frontmatter, atomically allocates the NN "
-      + 'parallel-group number, appends the engineering standards, and writes the PRD file to '
-      + "disk. This tool ONLY writes the file — it does not create a scheduler queue row. The "
-      + 'queue row is derived automatically by the scheduler\'s next reconcile pass (typically '
-      + 'within ~1 minute); the response has `enqueued: false` for exactly this reason. Every '
-      + 'PRD must join an EXISTING, already-human-approved Epic (pass sourcePromptId) — this '
-      + 'tool never mints a new one, and refuses the write if no Epic can be resolved. '
-      + 'TWO DISTINCT FAILURE MODES if this tool is not usable — do not conflate them: '
-      + '(a) this tool call is PRESENT in your tool list but ERRORS as app-not-running / admin '
-      + 'API unreachable — that is the ONLY case where hand-authoring the PRD file directly on '
-      + 'disk is an acceptable DEGRADED, LAST-RESORT fallback; the caller MUST say so explicitly '
-      + 'and visibly in its report (which file, why the tool was unreachable, that it needs '
-      + 'verification) since the server-side validation, atomic NN allocation, and '
-      + 'Epic-existence check this tool performs did not run for that file. '
-      + '(b) this tool is ABSENT from your tool list entirely — you were never offered it, so '
-      + 'there is no error to catch. That means the session-manager-scheduler MCP server is not '
-      + 'registered for this project: a MISCONFIGURATION, not an offline app. In that case DO '
-      + 'NOT hand-write any PRD file — stop and tell the human the MCP server is not registered '
-      + '(fix: `claude mcp add session-manager-scheduler --scope user -- node '
-      + '<session-manager-repo>/scripts/scheduler-mcp-server.cjs`, once at user scope covers '
-      + 'every project). See /develop.',
+    description: descriptionFor('scheduler_create_prd'),
     inputSchema: {
       type: 'object',
       properties: {
         title: { type: 'string', description: 'One-line human-readable title' },
-        cwd: { type: 'string', description: 'Absolute path to the target project (where claude -p will run)' },
+        cwd: { type: 'string', description: 'Absolute path to the target project (where claude -p will run). Optional inside an Epic session — the server resolves the real project from the calling session (originClaudeSessionId/sourcePromptId) when omitted.' },
         estimateMinutes: { type: 'number', description: 'Integer wall-clock estimate in minutes' },
         goal: { type: 'string', description: '2-4 sentences: what the executor will build and why' },
         acceptanceCriteria: {
@@ -137,17 +159,12 @@ const TOOLS = [
           description: 'Optional: the work type of THIS PRD — independent of the parent Epic\'s own tag. An Epic is the plan; a PRD is one unit of work inside it, and a single plan may legitimately contain several different work types. Never derived or inherited from the Epic.',
         },
       },
-      required: ['title', 'cwd', 'estimateMinutes', 'goal', 'acceptanceCriteria', 'implementationNotes'],
+      required: ['title', 'estimateMinutes', 'goal', 'acceptanceCriteria', 'implementationNotes'],
     },
   },
   {
     name: 'scheduler_list_prds',
-    description: "THE ONLY SUPPORTED WAY to list scheduled PRDs (live + archived) via the session-manager app's admin API. "
-      + 'Each entry includes its real job status (pending/running/completed/failed/needs_review, or null if not yet '
-      + 'queued/reconciled). Optionally filter by project cwd, Epic id, and/or status. Results are paginated (default '
-      + 'limit 100, max 500) sorted by slug ascending — check `hasMore`/`total` in the response before assuming you '
-      + "received every PRD; page further with `offset`. Default fields are compact (no parallelGroup/estimateMinutes/"
-      + 'sourcePromptId/epicId/archivedStatus) — pass fields:"full" to restore them.',
+    description: descriptionFor('scheduler_list_prds'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -162,8 +179,7 @@ const TOOLS = [
   },
   {
     name: 'scheduler_get_prd',
-    description: "THE ONLY SUPPORTED WAY to read one PRD's full body + parsed frontmatter (live or archived) via the "
-      + "session-manager app's admin API.",
+    description: descriptionFor('scheduler_get_prd'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -175,11 +191,7 @@ const TOOLS = [
   },
   {
     name: 'scheduler_update_prd',
-    description: "THE ONLY SUPPORTED WAY to edit a NOT-yet-running PRD's frontmatter and/or body via the session-manager "
-      + 'app\'s admin API. Refuses once a queue row exists for the slug and its status is anything but "pending" '
-      + '(running/completed/failed/needs_review) — editing the spec under a live or already-finished executor is refused, '
-      + 'not silently applied. Only recognized frontmatter keys (title, cwd, estimateMinutes, parallelGroup, '
-      + 'sourcePromptId, sourceTabId, tag) may be patched; unrecognized keys (e.g. dependsOn) round-trip unchanged.',
+    description: descriptionFor('scheduler_update_prd'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -205,34 +217,31 @@ const TOOLS = [
   },
   {
     name: 'scheduler_archive_prd',
-    description: "THE ONLY SUPPORTED WAY to archive one or more PRDs (move to prds-archived/) via the session-manager "
-      + "app's admin API.",
+    description: descriptionFor('scheduler_archive_prd'),
     inputSchema: {
       type: 'object',
       properties: {
         slugs: { type: 'array', items: { type: 'string' }, description: 'Slugs to archive' },
+        cwd: { type: 'string', description: 'Optional: the PRDs\' project cwd, narrows/speeds the search for every slug in this batch' },
       },
       required: ['slugs'],
     },
   },
   {
     name: 'scheduler_cancel_job',
-    description: "THE ONLY SUPPORTED WAY to cancel a not-yet-terminal scheduler job via the session-manager app's admin "
-      + 'API. A running job is SIGTERM\'d; a pending job is simply retired. There is no "cancelled" job status, so a '
-      + 'cancelled job lands as "failed" with an error naming the cause. Refuses a slug whose job is already terminal '
-      + '(completed/failed/needs_review) — nothing to cancel.',
+    description: descriptionFor('scheduler_cancel_job'),
     inputSchema: {
       type: 'object',
       properties: {
         slug: { type: 'string', description: 'PRD slug of the job to cancel' },
+        cwd: { type: 'string', description: 'Optional: the PRD project cwd, narrows/speeds the search' },
       },
       required: ['slug'],
     },
   },
   {
     name: 'scheduler_retag_prd',
-    description: "THE ONLY SUPPORTED WAY to rewrite a PRD's parallelGroup and/or estimateMinutes frontmatter (and, if "
-      + "parallelGroup changes, its NN- filename prefix) via the session-manager app's admin API.",
+    description: descriptionFor('scheduler_retag_prd'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -255,10 +264,7 @@ const TOOLS = [
   },
   {
     name: 'chat_send_prompt',
-    description:
-      "Push a prompt into an already-open tab's chat queue via the session-manager app's admin "
-      + 'API. The renderer resolves the tab (must currently be open) and runs the prompt through '
-      + 'the same queued-vs-immediate path as a manual send. No-ops if the tab is unknown/closed.',
+    description: descriptionFor('chat_send_prompt'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -270,31 +276,12 @@ const TOOLS = [
   },
   {
     name: 'feedback_list_projects',
-    description:
-      'List the OTHER projects on this machine that can receive feedback (i.e. that Session Manager '
-      + 'already manages — they have a session-manager-operations/ directory). Call this FIRST when you '
-      + 'need the exact `toCwd` for feedback_open_session and are not certain of it — never guess a path. '
-      + 'A project missing from this list has simply never been opened in Session Manager; ask the human '
-      + 'to open it once rather than inventing a path.',
+    description: descriptionFor('feedback_list_projects'),
     inputSchema: { type: 'object', properties: {} },
   },
   {
     name: 'feedback_open_session',
-    description:
-      'THE ONLY SANCTIONED WAY to hand a finding from THIS project to a DIFFERENT project. Opens a new '
-      + "PROPOSED session in the receiving project's own Sessions queue, carrying your report as its "
-      + 'opening prompt and stamped with where it came from. Session Manager performs the cross-folder '
-      + 'write; you never write another project\'s files yourself. '
-      + 'WHAT THIS DOES NOT DO: it does not start anything, queue a PRD, or spend a token. The session '
-      + 'lands as `proposed` and runs only if a human in the RECEIVING project presses "Approve & start". '
-      + 'There is no callback and no reply channel — do not wait for an answer, and do not tell the user '
-      + 'the other project has "been fixed" or "is working on it". Report only that the proposal was '
-      + 'delivered. '
-      + 'WHEN NOT TO USE IT: for work in the project you are ALREADY in, run /develop inside the Epic you '
-      + 'are already in — this tool refuses toCwd === fromCwd outright. '
-      + 'Write the report for a reader who has never seen your project: state the symptom, where you '
-      + 'observed it, what you expected, and (if you know) the file in THEIR repo that looks responsible. '
-      + 'Never assume they can see your code.',
+    description: descriptionFor('feedback_open_session'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -329,6 +316,17 @@ const TOOLS = [
       required: ['toCwd', 'fromCwd', 'title', 'body'],
     },
   },
+  {
+    name: 'session_manager_help',
+    description: descriptionFor('session_manager_help'),
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tool: { type: 'string', description: 'Optional: a tool name — returns that one catalog entry, including exampleArgs' },
+        topic: { type: 'string', description: 'Optional: a recipe id — returns that recipe\'s step-by-step instructions' },
+      },
+    },
+  },
 ];
 
 const server = new Server(
@@ -338,16 +336,21 @@ const server = new Server(
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
+// Named + exported (see module.exports below) so mcpToolCatalog.test.cjs's
+// sibling can exercise session_manager_help's argument handling directly —
+// mocking node:fs/promises + global.fetch to drive adminRequest — without
+// booting a stdio transport.
+async function handleCallTool(request) {
   const { name, arguments: args } = request.params;
   try {
     if (name === 'scheduler_reset_job') {
       const slug = args && typeof args.slug === 'string' ? args.slug : null;
       if (!slug) {
-        return { content: [{ type: 'text', text: 'missing required argument: slug' }], isError: true };
+        return errorResult('missing required argument: slug');
       }
       const force = args && args.force === true;
-      const result = await adminRequest('POST', '/admin/scheduler/reset-job', { slug, force });
+      const cwd = args && typeof args.cwd === 'string' ? args.cwd : undefined;
+      const result = await adminRequest('POST', '/admin/scheduler/reset-job', { slug, force, cwd });
       return { content: [{ type: 'text', text: JSON.stringify(result) }] };
     }
     if (name === 'scheduler_list_jobs') {
@@ -375,7 +378,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (name === 'scheduler_get_prd') {
       const slug = args && typeof args.slug === 'string' ? args.slug : null;
       if (!slug) {
-        return { content: [{ type: 'text', text: 'missing required argument: slug' }], isError: true };
+        return errorResult('missing required argument: slug');
       }
       const qs = new URLSearchParams({ slug });
       if (args?.cwd) qs.set('cwd', args.cwd);
@@ -385,7 +388,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (name === 'scheduler_update_prd') {
       const slug = args && typeof args.slug === 'string' ? args.slug : null;
       if (!slug) {
-        return { content: [{ type: 'text', text: 'missing required argument: slug' }], isError: true };
+        return errorResult('missing required argument: slug');
       }
       const result = await adminRequest('POST', '/admin/scheduler/update-prd', args);
       return { content: [{ type: 'text', text: JSON.stringify(result) }] };
@@ -393,23 +396,25 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (name === 'scheduler_archive_prd') {
       const slugs = Array.isArray(args?.slugs) ? args.slugs : null;
       if (!slugs || slugs.length === 0) {
-        return { content: [{ type: 'text', text: 'missing required argument: slugs' }], isError: true };
+        return errorResult('missing required argument: slugs');
       }
-      const result = await adminRequest('POST', '/admin/scheduler/archive-prd', { slugs });
+      const cwd = args && typeof args.cwd === 'string' ? args.cwd : undefined;
+      const result = await adminRequest('POST', '/admin/scheduler/archive-prd', { slugs, cwd });
       return { content: [{ type: 'text', text: JSON.stringify(result) }] };
     }
     if (name === 'scheduler_cancel_job') {
       const slug = args && typeof args.slug === 'string' ? args.slug : null;
       if (!slug) {
-        return { content: [{ type: 'text', text: 'missing required argument: slug' }], isError: true };
+        return errorResult('missing required argument: slug');
       }
-      const result = await adminRequest('POST', '/admin/scheduler/cancel-job', { slug });
+      const cwd = args && typeof args.cwd === 'string' ? args.cwd : undefined;
+      const result = await adminRequest('POST', '/admin/scheduler/cancel-job', { slug, cwd });
       return { content: [{ type: 'text', text: JSON.stringify(result) }] };
     }
     if (name === 'scheduler_retag_prd') {
       const items = Array.isArray(args?.items) ? args.items : null;
       if (!items || items.length === 0) {
-        return { content: [{ type: 'text', text: 'missing required argument: items' }], isError: true };
+        return errorResult('missing required argument: items');
       }
       const result = await adminRequest('POST', '/admin/scheduler/retag-prd', { items });
       return { content: [{ type: 'text', text: JSON.stringify(result) }] };
@@ -425,6 +430,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       if (!payload.sourcePromptId && process.env.SM_CHAT_SESSION_ID) {
         payload.originClaudeSessionId = process.env.SM_CHAT_SESSION_ID;
       }
+      // SM_PROJECT_ROOT (chatRunner.cjs/pty.cjs/scheduler.cjs's job spawn) —
+      // a trusted hint for the real project cwd, forwarded so the admin route
+      // can resolve it even when the caller omitted cwd or passed a worktree
+      // pwd. See projectRootResolve.cjs's resolveProjectContext.
+      if (process.env.SM_PROJECT_ROOT) {
+        payload.originProjectRoot = process.env.SM_PROJECT_ROOT;
+      }
       const result = await adminRequest('POST', '/admin/scheduler/create-prd', payload);
       // Never say "queued" — this tool only writes the PRD file; the queue
       // row is derived by the scheduler's next reconcile pass, not by this
@@ -441,7 +453,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (name === 'feedback_open_session') {
       for (const key of ['toCwd', 'fromCwd', 'title', 'body']) {
         if (!args || typeof args[key] !== 'string' || !args[key].trim()) {
-          return { content: [{ type: 'text', text: `missing required argument: ${key}` }], isError: true };
+          return errorResult(`missing required argument: ${key}`);
         }
       }
       // Same fallback shape as scheduler_create_prd: forward this process's
@@ -452,6 +464,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       if (!payload.fromEpicId && process.env.SM_CHAT_SESSION_ID) {
         payload.originClaudeSessionId = process.env.SM_CHAT_SESSION_ID;
       }
+      // See scheduler_create_prd's own SM_PROJECT_ROOT forwarding above.
+      if (process.env.SM_PROJECT_ROOT) {
+        payload.originProjectRoot = process.env.SM_PROJECT_ROOT;
+      }
       const result = await adminRequest('POST', '/admin/feedback/open-session', payload);
       // Never say "sent", "filed" or "fixed" — this call delivers a PROPOSAL
       // that a human in the other project must still approve.
@@ -464,23 +480,66 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const tabId = args && typeof args.tabId === 'string' ? args.tabId : null;
       const prompt = args && typeof args.prompt === 'string' ? args.prompt : null;
       if (!tabId || !prompt) {
-        return { content: [{ type: 'text', text: 'missing required arguments: tabId, prompt' }], isError: true };
+        return errorResult('missing required arguments: tabId, prompt');
       }
       const result = await adminRequest('POST', '/admin/chat/send-prompt', { tabId, prompt });
       return { content: [{ type: 'text', text: JSON.stringify(result) }] };
     }
-    return { content: [{ type: 'text', text: `unknown tool: ${name}` }], isError: true };
+    if (name === 'session_manager_help') {
+      const toolName = args && typeof args.tool === 'string' ? args.tool : null;
+      const topic = args && typeof args.topic === 'string' ? args.topic : null;
+
+      const response = {};
+
+      if (toolName) {
+        const entry = CATALOG_BY_NAME.get(toolName);
+        if (!entry) {
+          const valid = MCP_TOOL_CATALOG.map((e) => e.name);
+          return errorResult(`unknown tool "${toolName}" for session_manager_help — valid tool names: ${valid.join(', ')}`);
+        }
+        response.tool = entry;
+      }
+
+      if (topic) {
+        const recipe = MCP_RECIPES.find((r) => r.id === topic);
+        if (!recipe) {
+          const valid = MCP_RECIPES.map((r) => r.id);
+          return errorResult(`unknown topic "${topic}" for session_manager_help — valid topic ids: ${valid.join(', ')}`);
+        }
+        response.recipe = recipe;
+      }
+
+      if (!toolName && !topic) {
+        response.tools = MCP_TOOL_CATALOG.map((e) => ({ name: e.name, group: e.group, purpose: e.purpose }));
+        response.recipes = MCP_RECIPES.map((r) => ({ id: r.id, title: r.title }));
+      }
+
+      response.readiness = await fetchReadiness();
+
+      return { content: [{ type: 'text', text: JSON.stringify(response) }] };
+    }
+    return errorResult(`unknown tool: ${name}`);
   } catch (e) {
-    return { content: [{ type: 'text', text: e?.message ?? String(e) }], isError: true };
+    return errorResult(e?.message ?? String(e));
   }
-});
+}
+
+server.setRequestHandler(CallToolRequestSchema, handleCallTool);
 
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
 
-main().catch((e) => {
-  process.stderr.write(`scheduler-mcp-server fatal: ${e?.stack ?? e}\n`);
-  process.exit(1);
-});
+// Guarded so mcpToolCatalog.test.cjs can `require()` this file to read TOOLS
+// (for both-directions name-parity) without opening a stdio transport as a
+// require-time side effect — only the real `node scripts/scheduler-mcp-server.cjs`
+// invocation satisfies require.main === module.
+if (require.main === module) {
+  main().catch((e) => {
+    process.stderr.write(`scheduler-mcp-server fatal: ${e?.stack ?? e}\n`);
+    process.exit(1);
+  });
+}
+
+module.exports = { TOOLS, handleCallTool, HELP_POINTER, NOT_RUNNING_ERROR };