claude-code-session-manager 0.75.3 → 0.77.0

package/scripts/render-project-pages.cjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// Bash-invocable CLI wrapping the Stage 0 renderer (render.tsx →
+// scripts/render-project-pages/dist/renderer.cjs, built by
+// `npm run build:project-pages`). Requires that build to have already run —
+// this script does NOT bundle on the fly, since PRD authoring standards
+// forbid unbounded/slow steps inside a headless job.
+//
+// Usage:
+//   node scripts/render-project-pages.cjs <summary.json> <picks.json> <output dir> <generatedAt>
+//
+// generatedAt (4th arg, required) is an ISO 8601 timestamp string the CALLER
+// stamps — Date.now() is unavailable in some execution contexts (e.g.
+// workflow scripts) that may drive this CLI, so this script never generates
+// its own timestamp. This is the "accept generatedAt as a 4th CLI arg"
+// option from the PRD's two documented choices (the alternative — omitting
+// generatedAt from manifest.json entirely — was not taken).
+//
+// Writes <output dir>/home.html, marketing.html, feature.html,
+// architecture.html, brief.html, and manifest.json ({ generatedAt }).
+//
+// Path arguments are used as-is (no allowedRoots validation like
+// config.cjs's validatePath) — this is a standalone local dev/ops script run
+// by a trusted human or agent shell, not an IPC-reachable surface, so it's
+// out of scope for that guard by design.
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function fail(message) {
+  console.error(`render-project-pages: ${message}`);
+  process.exit(1);
+}
+
+function main() {
+  const [summaryPath, picksPath, outDir, generatedAt] = process.argv.slice(2);
+  if (!summaryPath || !picksPath || !outDir || !generatedAt) {
+    fail('usage: node scripts/render-project-pages.cjs <summary.json> <picks.json> <output dir> <generatedAt>');
+  }
+  if (Number.isNaN(Date.parse(generatedAt))) {
+    fail(`generatedAt must be an ISO 8601 timestamp, got: ${generatedAt}`);
+  }
+
+  const bundlePath = path.join(__dirname, 'render-project-pages', 'dist', 'renderer.cjs');
+  if (!fs.existsSync(bundlePath)) {
+    fail(`build bundle not found at ${bundlePath} — run "npm run build:project-pages" first`);
+  }
+
+  let renderProjectPages;
+  try {
+    ({ renderProjectPages } = require(bundlePath));
+  } catch (err) {
+    fail(`failed to load ${bundlePath}: ${err.message}`);
+  }
+
+  const summary = JSON.parse(fs.readFileSync(summaryPath, 'utf8'));
+  const picks = JSON.parse(fs.readFileSync(picksPath, 'utf8'));
+
+  const pages = renderProjectPages(summary, picks);
+
+  fs.mkdirSync(outDir, { recursive: true });
+  for (const lens of ['home', 'marketing', 'feature', 'architecture', 'brief']) {
+    fs.writeFileSync(path.join(outDir, `${lens}.html`), pages[lens]);
+  }
+  fs.writeFileSync(path.join(outDir, 'manifest.json'), JSON.stringify({ generatedAt }, null, 2));
+
+  console.log(`Wrote home.html, marketing.html, feature.html, architecture.html, brief.html, manifest.json to ${outDir}`);
+}
+
+main();

package/scripts/scheduler-mcp-server.cjs

@@ -11,6 +11,11 @@
  *   feedback_list_projects()       -> GET  /admin/feedback/targets
  *   feedback_open_session({ ... }) -> POST /admin/feedback/open-session
  *
+ *   project_home_get_contract({ cwd? })              -> GET  /admin/project-home/contract
+ *   project_home_validate_summary({ cwd?, summary }) -> POST /admin/project-home/validate-summary
+ *   project_home_render({ cwd?, summary, picks })    -> POST /admin/project-home/render
+ *   project_home_status({ cwd? })                    -> GET  /admin/project-home/status
+ *
  * This is a separate process from the Electron app — it only ever reaches
  * it over the token-authed loopback HTTP API in admin-api.json, never by
  * requiring scheduler.cjs/localAdminHttp.cjs directly. The admin server IS the
@@ -29,11 +34,41 @@ 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}`;
+
+// Same resolution fetchReadiness() below uses: a project-home-builder session
+// running inside an Epic worktree still targets the real project cwd, not
+// the worktree's own pwd.
+function resolveCwdArg(args) {
+  if (args && typeof args.cwd === 'string' && args.cwd) return args.cwd;
+  return process.env.SM_PROJECT_ROOT || process.cwd();
+}
 
 async function readAdminConfig() {
   const raw = await fsp.readFile(TOKEN_PATH, 'utf8');
@@ -68,56 +103,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: {
@@ -134,20 +169,23 @@ const TOOLS = [
         tag: {
           type: 'string',
           enum: PRD_WORK_TYPES,
-          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.',
+          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.',
+        },
+        agentType: {
+          type: 'string',
+          description: 'Optional: WHO executes this PRD — the persona name (a file at ~/.claude/agents/<name>.md, e.g. "dev-lead") the executor should adopt. Distinct from `tag` (what kind of work); this is who does it. Defaults to "dev-lead" when omitted. Rejected at write time if the name does not resolve to a readable persona file.',
+        },
+        quietMachine: {
+          type: 'boolean',
+          description: 'Optional: set true only when this PRD\'s acceptance criteria are wall-clock/timing measurements (frame time, performance fences) that CPU contention from concurrent jobs would invalidate. The scheduler dispatches it only once zero other jobs are running machine-wide, and holds every other job off the whole slot pool for its run — a whole-machine exclusive lease, not a per-project one. If the machine never goes quiet within the configured wait window (default 30 minutes), it dispatches anyway and is marked degraded. Opt-in only; omit for ordinary PRDs.',
         },
       },
-      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 +200,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 +212,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: {
@@ -196,6 +229,8 @@ const TOOLS = [
             sourcePromptId: { type: 'string' },
             sourceTabId: { type: 'string' },
             tag: { type: 'string', enum: PRD_WORK_TYPES },
+            agentType: { type: 'string', description: 'WHO executes this PRD (persona name) — patchable after creation too, see scheduler_create_prd' },
+            quietMachine: { type: 'boolean', description: 'Optional: the exclusive machine-wide quiet lease flag (see scheduler_create_prd) — patchable after creation too' },
           },
         },
         body: { type: 'string', description: 'Optional: full replacement body (everything after the frontmatter)' },
@@ -205,34 +240,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 +287,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 +299,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 +339,62 @@ const TOOLS = [
       required: ['toCwd', 'fromCwd', 'title', 'body'],
     },
   },
+  {
+    name: 'project_home_get_contract',
+    description: descriptionFor('project_home_get_contract'),
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cwd: { type: 'string', description: "Optional: absolute path to the target project. Defaults to the calling session's own project root (SM_PROJECT_ROOT or process.cwd()) when omitted." },
+      },
+    },
+  },
+  {
+    name: 'project_home_validate_summary',
+    description: descriptionFor('project_home_validate_summary'),
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cwd: { type: 'string', description: "Optional: absolute path to the target project. Defaults to the calling session's own project root when omitted." },
+        summary: { type: 'object', description: 'ProjectPageSummary object matching the summarySchema from project_home_get_contract' },
+      },
+      required: ['summary'],
+    },
+  },
+  {
+    name: 'project_home_render',
+    description: descriptionFor('project_home_render'),
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cwd: { type: 'string', description: "Optional: absolute path to the target project. Defaults to the calling session's own project root when omitted." },
+        summary: { type: 'object', description: 'ProjectPageSummary object matching the summarySchema from project_home_get_contract' },
+        picks: { type: 'object', description: 'ProjectPagePicks object (lensId -> slotId -> variantId) matching the picksSchema from project_home_get_contract' },
+      },
+      required: ['summary', 'picks'],
+    },
+  },
+  {
+    name: 'project_home_status',
+    description: descriptionFor('project_home_status'),
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cwd: { type: 'string', description: "Optional: absolute path to the target project. Defaults to the calling session's own project root when omitted." },
+      },
+    },
+  },
+  {
+    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 +404,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 +446,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 +456,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,28 +464,45 @@ 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) }] };
     }
     if (name === 'scheduler_create_prd') {
+      // Hard refusal at the authoring boundary (issue #11, list C1): a
+      // headless scheduled executor performs its own acceptance criteria and
+      // never queues follow-on work — PRD 460 called /develop from inside its
+      // run, spawned a duplicate PRD, and exited 0 having done nothing. The
+      // standards prose already says so; this makes the harness enforce it.
+      // scheduler.cjs stamps SM_SCHEDULER_JOB_SLUG on every job spawn and
+      // SM_SCHEDULER_JOB_MAY_QUEUE=1 only for personas whose whole job is
+      // decomposition (architect), so a planning PRD still can.
+      if (process.env.SM_SCHEDULER_JOB_SLUG && process.env.SM_SCHEDULER_JOB_MAY_QUEUE !== '1') {
+        return errorResult(
+          `refused: scheduler_create_prd was called from inside headless scheduled job '${process.env.SM_SCHEDULER_JOB_SLUG}'. `
+          + 'A PRD executor performs its own acceptance criteria directly and never queues follow-on work (self-queue failure class). '
+          + 'If more work is genuinely needed, say so in your final result text — the authoring Epic decides whether to queue it.',
+        );
+      }
       // If the caller (the model) didn't pass sourcePromptId, forward this
       // process's own SM_CHAT_SESSION_ID (set by chatRunner.cjs on the
       // parent claude -p process this MCP server inherited its env from) so
@@ -425,6 +513,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 +536,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 +547,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 +563,97 @@ 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 === 'project_home_get_contract') {
+      const cwd = resolveCwdArg(args);
+      const qs = new URLSearchParams({ cwd });
+      const result = await adminRequest('GET', `/admin/project-home/contract?${qs.toString()}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    }
+    if (name === 'project_home_validate_summary') {
+      if (!args || typeof args.summary !== 'object' || args.summary === null) {
+        return errorResult('missing required argument: summary');
+      }
+      const cwd = resolveCwdArg(args);
+      const result = await adminRequest('POST', '/admin/project-home/validate-summary', { cwd, summary: args.summary });
+      return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    }
+    if (name === 'project_home_render') {
+      if (!args || typeof args.summary !== 'object' || args.summary === null) {
+        return errorResult('missing required argument: summary');
+      }
+      if (typeof args.picks !== 'object' || args.picks === null) {
+        return errorResult('missing required argument: picks');
+      }
+      const cwd = resolveCwdArg(args);
+      const result = await adminRequest('POST', '/admin/project-home/render', { cwd, summary: args.summary, picks: args.picks });
+      return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    }
+    if (name === 'project_home_status') {
+      const cwd = resolveCwdArg(args);
+      const qs = new URLSearchParams({ cwd });
+      const result = await adminRequest('GET', `/admin/project-home/status?${qs.toString()}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    }
+    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 };