@josstei/maestro 1.6.4-rc.1

package/src/agents/zos-sysprog.md

@@ -0,0 +1,134 @@
+---
+name: zos-sysprog
+description: "z/OS systems programming specialist for JCL, USS, SMP/E, RACF, subsystem diagnostics, and batch scheduling. Use when the task requires JCL authoring or review, z/OS Unix System Services setup, SMP/E maintenance, RACF profile review, or diagnosing SYSLOG/OPERLOG issues. For example: writing a JCL restart procedure, planning an SMP/E PTF install, or reviewing RACF dataset profiles for least privilege."
+color: slate
+tools: [read_file, list_directory, glob, grep_search, run_shell_command, google_web_search, read_many_files, write_todos, ask_user, web_fetch]
+tools.gemini: [read_file, list_directory, glob, grep_search, run_shell_command, google_web_search, read_many_files, write_todos, ask_user, web_fetch]
+tools.claude: [Read, Bash, Glob, Grep, WebSearch, WebFetch, TaskCreate, TaskUpdate, TaskList]
+max_turns: 20
+temperature: 0.2
+timeout_mins: 8
+capabilities: read_shell
+---
+<!-- @feature exampleBlocks -->
+<example>
+Context: User needs JCL or job scheduling reviewed.
+user: "Review this JCL for our nightly batch; it keeps ABENDing on step 3 with S0C4"
+assistant: "I'll check the DCB attributes, dataset allocation, REGION size, and step conditional logic, then cross-reference the S0C4 against the compile listing to locate the failing module."
+<commentary>
+z/OS Sysprog is appropriate for JCL/ABEND diagnostics and resource allocation issues.
+</commentary>
+</example>
+
+<example>
+Context: User needs a RACF review for a new application.
+user: "Review the RACF profiles for our new app's datasets and started task"
+assistant: "I'll audit dataset profiles for least privilege, check the STC identity's OMVS segment and UID, verify generic profile coverage, and flag any UACC above NONE."
+<commentary>
+z/OS Sysprog handles RACF review and security posture for z/OS resources.
+</commentary>
+</example>
+<!-- @end-feature -->
+
+You are a **z/OS Systems Programmer** specializing in mainframe system services: JCL, JES, USS, SMP/E, RACF, and subsystem operations. You keep the platform stable and changes auditable.
+
+**Methodology:**
+- Read SYSLOG/OPERLOG messages with the explicit message ID; do not paraphrase
+- Confirm the LPAR, sysplex, and subsystem context before suggesting actions
+- Prefer generic RACF profiles over discrete ones; maintain least privilege
+- Test SMP/E and JCL changes in the development LPAR with the same maintenance stream
+- Document restart points in JCL; never assume a job runs end-to-end
+- Treat SMF and audit logs as forensic records; never truncate or suppress
+
+**Work Areas:**
+- JCL authoring and review: job streams, procs, conditional (IF/THEN/ELSE, COND)
+- JES2/JES3 job management, output classes, spool administration
+- USS (z/OS Unix System Services): BPXPRMxx, file system management, OMVS segments
+- SMP/E: APPLY/ACCEPT, HOLDDATA, SYSMOD lifecycle, CSI management
+- RACF: dataset profiles, general resource classes, STARTED class, OMVS segments, UACC review
+- Subsystem operations: CICS, IMS, DB2, MQ — start/stop, parm libraries
+- Diagnostics: SVC dumps, SLIP traps, IPCS, SYSLOG/OPERLOG analysis
+
+**Constraints:**
+- Read-only + shell for diagnostics (TSO, USS); do not execute privileged commands or apply SMP/E without explicit approval
+- Never grant RACF UACC above NONE on production datasets
+- Never bypass SMP/E by installing maintenance outside the managed stream
+- All JCL changes preserve restart and rerun capability
+- Follow the shop's dataset naming and JOB card standards exactly
+
+## Decision Frameworks
+
+### ABEND Diagnosis Protocol
+1. Capture the ABEND code, REASON CODE, PSW, and failing module from SYSOUT/JESJCL
+2. For S0Cx: map to the protection exception type (S0C1 operation, S0C4 protection, S0C7 data) and locate the failing PSW in the compile listing or load module
+3. For Sxxx with a user code: look up the application's documented abend dictionary
+4. For SMS/VSAM abends: inspect DCB attributes, dataset allocation, and catalog state
+5. Propose the smallest change that addresses the root cause; avoid wholesale JCL rewrites
+
+### JCL Review Checklist
+For every production JCL:
+- JOB card has correct class, CLASS, MSGCLASS, REGION, NOTIFY, and accounting
+- DD statements have complete DCB where needed; GDG generations used for mutable datasets
+- COND / IF-THEN-ELSE guards destructive steps
+- Restart parameter (RESTART= or step-level RD=) defined
+- SYSOUT routed to the agreed output class
+- No hard-coded passwords, userids, or production volume serials
+
+### RACF Profile Review
+For every resource:
+1. Check UACC — must be NONE on production datasets and general resources
+2. Check WARNING mode — should be OFF outside of a documented migration window
+3. Check the access list — prefer groups over discrete user IDs
+4. Generic profile coverage — every discrete profile should be justified
+5. OMVS segment presence on IDs that use USS; UID/GID assigned by the registry, not ad-hoc
+
+### SMP/E Change Protocol
+1. Read the associated HOLDDATA and cover letter before RECEIVE
+2. APPLY CHECK on the development LPAR; resolve holds and requisites
+3. APPLY on development; validate subsystems restart cleanly
+4. Schedule ACCEPT only after a stability window has passed
+5. Maintain backout via SMP/E RESTORE; do not hand-edit target libraries
+
+### Batch Restart Design
+- Every multi-step job defines a restart point at each checkpoint
+- Restart does not rerun completed steps that are non-idempotent
+- Datasets that must be reset on restart are explicitly allocated on the restart step
+- The operations runbook documents the restart procedure with JCL parameters
+
+## Anti-Patterns
+
+- Setting UACC(READ) or UACC(UPDATE) on production datasets
+- Granting ALTER access on production datasets to application users
+- Hand-editing SMP/E target libraries to apply urgent fixes
+- Using RD=R on jobs with non-idempotent steps (data would be double-processed)
+- Suppressing SYSOUT to reduce storage without an alternative audit trail
+- Running destructive utilities (DFDSS DUMP with DELETE, IEHPROGM SCRATCH) without a backup
+
+## Downstream Consumers
+
+- `cobol-engineer`: Needs region size, dataset allocation, and JCL template for new batch programs
+- `db2-dba`: Needs STC identity, resource-class profiles, and subsystem parm library pointers
+- `security-engineer`: Needs RACF audit evidence and SMF record availability for external review
+
+## Output Contract
+
+When completing your task, conclude with a **Handoff Report** containing two parts:
+
+## Task Report
+- **Status**: success | partial | failure
+- **Objective Achieved**: [One sentence restating the task objective and whether it was fully met]
+- **Files Created**: [Absolute paths with one-line purpose each, or "none"]
+- **Files Modified**: [Absolute paths with one-line summary of what changed and why, or "none"]
+- **Files Deleted**: [Absolute paths with rationale, or "none"]
+- **Decisions Made**: [Choices made that were not explicitly specified in the delegation prompt, with rationale for each, or "none"]
+- **Validation**: pass | fail | skipped
+- **Validation Output**: [Command output or "N/A"]
+- **Errors**: [List with type, description, and resolution status, or "none"]
+- **Scope Deviations**: [Anything asked but not completed, or additional necessary work discovered but not performed, or "none"]
+
+## Downstream Context
+- **Key Interfaces Introduced**: [Type signatures and file locations, or "none"]
+- **Patterns Established**: [New patterns that downstream agents must follow for consistency, or "none"]
+- **Integration Points**: [Where and how downstream work should connect to this output, or "none"]
+- **Assumptions**: [Anything assumed that downstream agents should verify, or "none"]
+- **Warnings**: [Gotchas, edge cases, or fragile areas downstream agents should be aware of, or "none"]

package/src/config/setting-resolver.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const path = require('path');
+const { parseEnvFile } = require('../core/env-file-parser');
+
+function resolveSetting(varName, projectRoot) {
+  const envValue = process.env[varName];
+  if (envValue !== undefined && envValue !== '') return envValue;
+
+  if (typeof projectRoot === 'string' && projectRoot.length > 0) {
+    const projectEnv = parseEnvFile(path.join(projectRoot, '.env'));
+    if (projectEnv[varName] !== undefined && projectEnv[varName] !== '') {
+      return projectEnv[varName];
+    }
+  }
+
+  // Intentionally bypasses the runtime-config abstraction: setting
+  // resolution runs before a runtime is selected, so it cannot ask a
+  // runtime-config for `env.extensionPath`. MAESTRO_EXTENSION_PATH is
+  // the documented canonical override; CLAUDE_PLUGIN_ROOT is kept as a
+  // fallback because Claude injects it automatically from the plugin
+  // loader.
+  const extensionRoot = process.env.MAESTRO_EXTENSION_PATH || process.env.CLAUDE_PLUGIN_ROOT;
+  if (extensionRoot) {
+    const extEnv = parseEnvFile(path.join(extensionRoot, '.env'));
+    if (extEnv[varName] !== undefined && extEnv[varName] !== '') return extEnv[varName];
+  }
+
+  return undefined;
+}
+
+module.exports = { resolveSetting };

package/src/core/agent-registry.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const { toSnakeCase } = require('../lib/naming');
+const agentRegistryData = require('../generated/agent-registry.json');
+
+const KNOWN_AGENTS = Object.freeze(
+  agentRegistryData.map((entry) => toSnakeCase(entry.name))
+);
+
+const AGENT_CAPABILITIES = Object.freeze(
+  Object.fromEntries(
+    agentRegistryData.map((entry) => [toSnakeCase(entry.name), entry.capabilities])
+  )
+);
+
+function normalizeAgentName(name) {
+  if (typeof name !== 'string') return '';
+  return toSnakeCase(name.toLowerCase());
+}
+
+const AGENT_PATTERNS = KNOWN_AGENTS.map((agent) => {
+  const escaped = agent.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const aliasPattern = escaped.replace(/_/g, '[-_]');
+  return {
+    agent,
+    patterns: [
+      new RegExp(`(?:delegate|transfer|hand\\s*off|dispatch|invoke)\\s+(?:to\\s+)?(?:the\\s+)?${aliasPattern}\\b`),
+      new RegExp(`@${aliasPattern}\\b`),
+    ],
+  };
+});
+
+function detectAgentFromPrompt(prompt) {
+  if (typeof prompt === 'string') {
+    const headerMatch = prompt.match(/(?:^|\n)\s*agent:\s*([a-z0-9_-]+)/i);
+    const headerAgent = normalizeAgentName(headerMatch?.[1] || '');
+    if (headerAgent && KNOWN_AGENTS.includes(headerAgent)) {
+      return headerAgent;
+    }
+  }
+
+  const envAgent = normalizeAgentName(process.env.MAESTRO_CURRENT_AGENT);
+  if (envAgent && KNOWN_AGENTS.includes(envAgent)) return envAgent;
+
+  if (!prompt) return '';
+
+  const lower = prompt.toLowerCase();
+  for (const { agent, patterns } of AGENT_PATTERNS) {
+    if (patterns.some((p) => p.test(lower))) {
+      return agent;
+    }
+  }
+
+  return '';
+}
+
+function getAgentCapability(name) {
+  const normalized = normalizeAgentName(name);
+  return AGENT_CAPABILITIES[normalized] || null;
+}
+
+function canCreateFiles(name) {
+  const cap = getAgentCapability(name);
+  return cap === 'read_write' || cap === 'full';
+}
+
+module.exports = { KNOWN_AGENTS, AGENT_CAPABILITIES, normalizeAgentName, detectAgentFromPrompt, getAgentCapability, canCreateFiles };

package/src/core/canonical-source.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function hasCanonicalSrcRoot(candidateRoot) {
+  return fs.existsSync(path.join(candidateRoot, 'src', 'mcp', 'maestro-server.js'));
+}
+
+function resolveCanonicalProjectRoot(startDir = process.cwd()) {
+  let current = path.resolve(startDir);
+
+  while (true) {
+    if (hasCanonicalSrcRoot(current)) {
+      return current;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      throw new Error(`Unable to locate canonical src/ from "${startDir}"`);
+    }
+
+    current = parent;
+  }
+}
+
+function resolveCanonicalSrcRoot(startDir = process.cwd()) {
+  return path.join(resolveCanonicalProjectRoot(startDir), 'src');
+}
+
+function requireFromCanonicalSrc(relativePath, startDir = process.cwd()) {
+  return require(path.join(resolveCanonicalSrcRoot(startDir), relativePath));
+}
+
+module.exports = {
+  requireFromCanonicalSrc,
+  resolveCanonicalProjectRoot,
+  resolveCanonicalSrcRoot,
+};

package/src/core/env-file-parser.js

@@ -0,0 +1,82 @@
+'use strict';
+
+const { readFileSafe } = require('../lib/io');
+
+function trimQuotes(value) {
+  if ((value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+function stripInlineComment(value) {
+  let activeQuote = '';
+  for (let i = 0; i < value.length; i++) {
+    const ch = value[i];
+    if (activeQuote) {
+      if (ch === activeQuote && value[i - 1] !== '\\') {
+        activeQuote = '';
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      activeQuote = ch;
+      continue;
+    }
+    if (ch === '#' && i > 0 && /\s/.test(value[i - 1])) {
+      return value.slice(0, i).trimEnd();
+    }
+  }
+  return value;
+}
+
+function parseEnvFile(filePath) {
+  const result = {};
+  const content = readFileSafe(filePath, null);
+  if (content === null) {
+    return result;
+  }
+  const lines = content.split('\n');
+  let i = 0;
+  while (i < lines.length) {
+    const trimmed = lines[i].trim();
+    if (!trimmed || trimmed.startsWith('#')) { i++; continue; }
+    const stripped = trimmed.replace(/^export\s+/, '');
+    const eqIndex = stripped.indexOf('=');
+    if (eqIndex === -1) { i++; continue; }
+    const key = stripped.slice(0, eqIndex);
+    if (!key) { i++; continue; }
+    let rawValue = stripped.slice(eqIndex + 1);
+
+    // Multi-line: value starts with " but has no closing " on the same line
+    if (rawValue.startsWith('"') && rawValue.indexOf('"', 1) === -1) {
+      const valueParts = [rawValue.slice(1)];
+      i++;
+      let closed = false;
+      while (i < lines.length) {
+        const nextLine = lines[i];
+        if (nextLine.endsWith('"') && !nextLine.endsWith('\\"')) {
+          valueParts.push(nextLine.slice(0, -1));
+          closed = true;
+          break;
+        }
+        valueParts.push(nextLine);
+        i++;
+      }
+      if (!closed) {
+        console.warn(`env-file-parser: unclosed quote for key "${key}", treating accumulated content as value`);
+      }
+      result[key] = valueParts.join('\n');
+      i++;
+      continue;
+    }
+
+    rawValue = stripInlineComment(rawValue);
+    result[key] = trimQuotes(rawValue);
+    i++;
+  }
+  return result;
+}
+
+module.exports = { parseEnvFile };

package/src/core/feature-blocks.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const FEATURE_BLOCK_REGEX =
+  /^[ \t]*<!-- @feature (\S+) -->\n([\s\S]*?)^[ \t]*<!-- @end-feature -->\n?/gm;
+
+const COLLAPSED_NEWLINE_REGEX = /\n{3,}/g;
+
+/**
+ * @param {string} content - Markdown content potentially containing feature blocks
+ * @param {Record<string, boolean>} features - Map of feature flag names to boolean inclusion values
+ * @param {{ mode?: 'strict' | 'lenient' }} [opts] - Configuration options
+ * @returns {string} Content with feature blocks resolved and excess newlines collapsed
+ * @throws {Error} In strict mode, when a feature flag is not present in the features object
+ */
+function stripFeatureBlocks(content, features, opts) {
+  const mode = (opts && opts.mode) || 'strict';
+
+  const replaced = content.replace(
+    FEATURE_BLOCK_REGEX,
+    (_match, flagName, body) => {
+      if (!(flagName in features)) {
+        if (mode === 'strict') {
+          throw new Error(`Unknown feature flag: "${flagName}"`);
+        }
+        return '';
+      }
+      return features[flagName] ? body : '';
+    }
+  );
+
+  return replaced.replace(COLLAPSED_NEWLINE_REGEX, '\n\n');
+}
+
+module.exports = { stripFeatureBlocks };

package/src/core/logger.js

@@ -0,0 +1,12 @@
+'use strict';
+
+function log(level, message) {
+  process.stderr.write(`[${level}] maestro: ${message}\n`);
+}
+
+function fatal(message) {
+  process.stderr.write(`ERROR: ${message}\n`);
+  process.exit(1);
+}
+
+module.exports = { log, fatal };

package/src/core/markdown-state.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const FRONTMATTER_PATTERN = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
+
+/**
+ * Serializes structured data and a body string into the
+ * JSON-frontmatter format used by session state files.
+ *
+ * @param {Object} data - JSON-serializable data for the frontmatter block
+ * @param {string} [body] - Optional body content placed after the closing delimiter
+ * @returns {string} The formatted session state string
+ */
+function serialize(data, body) {
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n${body || ''}`;
+}
+
+/**
+ * Parses a session state string containing JSON frontmatter and an optional body.
+ *
+ * @param {string} content - Raw session state content with `---` delimiters
+ * @returns {{ data: Object, body: string }} Parsed frontmatter data and body content
+ * @throws {Error} When no frontmatter delimiters are found in the content
+ */
+function parse(content) {
+  const match = content.match(FRONTMATTER_PATTERN);
+  if (!match) {
+    throw new Error('No YAML frontmatter found in session state');
+  }
+
+  return {
+    data: JSON.parse(match[1]),
+    body: match[2],
+  };
+}
+
+module.exports = { serialize, parse };

package/src/core/policy-rules.js

@@ -0,0 +1,32 @@
+'use strict';
+
+/**
+ * Canonical policy rules for Maestro command safety enforcement.
+ * Used by:
+ *   - claude/scripts/policy-enforcer.js (Claude Code PreToolUse hook)
+ *   - policies/maestro.toml (Gemini CLI policy pack — generated separately)
+ *
+ * Rule shapes:
+ *   { matchType: 'prefix' | 'regex' | 'word', pattern: string, reason: string }
+ */
+
+const DENY_RULES = Object.freeze([
+  { matchType: 'prefix', pattern: 'rm -rf', reason: 'Recursive force delete' },
+  { matchType: 'prefix', pattern: 'rm -fr', reason: 'Recursive force delete (flag reorder)' },
+  { matchType: 'prefix', pattern: 'sudo rm -rf', reason: 'Privileged recursive force delete' },
+  { matchType: 'prefix', pattern: 'sudo rm -fr', reason: 'Privileged recursive force delete (flag reorder)' },
+  { matchType: 'prefix', pattern: 'git reset --hard', reason: 'Discards uncommitted changes' },
+  { matchType: 'prefix', pattern: 'git checkout --', reason: 'Discards uncommitted file changes' },
+  { matchType: 'prefix', pattern: 'git clean -fd', reason: 'Removes untracked files permanently' },
+  { matchType: 'prefix', pattern: 'git clean -df', reason: 'Removes untracked files permanently (flag reorder)' },
+  { matchType: 'prefix', pattern: 'git clean -xfd', reason: 'Removes untracked and ignored files permanently' },
+  { matchType: 'prefix', pattern: 'git clean -xdf', reason: 'Removes untracked and ignored files permanently (flag reorder)' },
+  { matchType: 'regex', pattern: '<<', reason: 'Heredoc corrupts structured content (YAML, Markdown, JSON) — use write_file instead' },
+]);
+
+const ASK_RULES = Object.freeze([
+  { matchType: 'word', pattern: 'tee', reason: 'Writes to file and stdout' },
+  { matchType: 'regex', pattern: '\\s>>?\\s|\\s>>?$|^>>?\\s|\\d>>?\\s', reason: 'Shell output redirection' },
+]);
+
+module.exports = { DENY_RULES, ASK_RULES };

package/src/core/project-root-resolver.js

@@ -0,0 +1,184 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { fileURLToPath } = require('node:url');
+
+const { isExtensionCachePath } = require('../mcp/contracts/cache-path-rejector');
+const { MaestroError } = require('../lib/errors');
+
+class WorkspaceResolutionError extends MaestroError {
+  constructor(message, { code = 'WORKSPACE_RESOLUTION_FAILED', details = null } = {}) {
+    super(message, { code, details });
+    this.name = 'WorkspaceResolutionError';
+  }
+}
+
+function resolveGitRoot(baseDir) {
+  return execSync('git rev-parse --show-toplevel', {
+    cwd: baseDir,
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  }).trim();
+}
+
+function resolveExistingRoot(candidate) {
+  if (!candidate || candidate.includes('${')) {
+    return null;
+  }
+
+  const resolvedCandidate = path.resolve(candidate);
+  if (!fs.existsSync(resolvedCandidate)) {
+    return null;
+  }
+
+  try {
+    return resolveGitRoot(resolvedCandidate);
+  } catch {
+    return resolvedCandidate;
+  }
+}
+
+function resolveProjectRootFromCandidates(candidates) {
+  for (const candidate of candidates) {
+    const resolvedRoot = resolveExistingRoot(candidate);
+    if (resolvedRoot) {
+      return resolvedRoot;
+    }
+  }
+
+  return null;
+}
+
+function extractClientRootCandidates(clientRoots) {
+  if (!Array.isArray(clientRoots)) {
+    return [];
+  }
+
+  const candidates = [];
+  for (const clientRoot of clientRoots) {
+    const uri =
+      typeof clientRoot === 'string'
+        ? clientRoot
+        : clientRoot && typeof clientRoot.uri === 'string'
+          ? clientRoot.uri
+          : null;
+
+    if (!uri) {
+      continue;
+    }
+
+    try {
+      const parsed = new URL(uri);
+      if (parsed.protocol !== 'file:') {
+        continue;
+      }
+
+      candidates.push(fileURLToPath(parsed));
+    } catch {
+      continue;
+    }
+  }
+
+  return candidates;
+}
+
+function resolveProjectRootFromEnv(env, cwd) {
+  const candidates = [
+    env.MAESTRO_WORKSPACE_PATH,
+    env.CLAUDE_PROJECT_DIR,
+    env.PWD,
+    env.INIT_CWD,
+  ];
+
+  const resolvedRoot = resolveProjectRootFromCandidates(candidates);
+  if (resolvedRoot) {
+    return resolvedRoot;
+  }
+
+  return resolveExistingRoot(cwd) || path.resolve(cwd);
+}
+
+function resolveProjectRootForRuntime(runtimeConfig = {}, options = {}) {
+  const env = options.env || process.env;
+  const cwd = options.cwd || process.cwd();
+  const workspaceEnvName =
+    runtimeConfig && runtimeConfig.env ? runtimeConfig.env.workspacePath : null;
+  const explicitWorkspacePath =
+    workspaceEnvName && env[workspaceEnvName] ? env[workspaceEnvName] : null;
+
+  const explicitRoot = resolveExistingRoot(explicitWorkspacePath);
+  if (explicitRoot) {
+    return explicitRoot;
+  }
+
+  const clientRoot = resolveProjectRootFromCandidates(
+    extractClientRootCandidates(options.clientRoots)
+  );
+  if (clientRoot) {
+    return clientRoot;
+  }
+
+  return resolveProjectRootFromEnv(env, cwd);
+}
+
+function resolveProjectRoot() {
+  return resolveProjectRootFromEnv(process.env, process.cwd());
+}
+
+/**
+ * Assert that a tool handler was invoked with a resolved workspace root.
+ * Used by handlers that cannot function without a workspace (session state,
+ * reconciliation, complexity assessment). The dispatcher calls this centrally
+ * when `requiresWorkspace` is declared on the tool schema; handlers may also
+ * call it directly for defense in depth.
+ *
+ * @param {string|null|undefined} projectRoot - resolved project root or nullish
+ * @param {string} toolName - tool name for the error message
+ * @throws {WorkspaceResolutionError} when projectRoot is absent
+ */
+function requireWorkspaceRoot(projectRoot, toolName) {
+  if (typeof projectRoot === 'string' && projectRoot.length > 0) {
+    return projectRoot;
+  }
+  throw new WorkspaceResolutionError(
+    `${toolName} requires an initialized workspace. Call initialize_workspace(workspace_path=...) first.`,
+    { code: 'WORKSPACE_NOT_INITIALIZED', details: { tool_name: toolName } }
+  );
+}
+
+function requireExplicitWorkspaceRoot({ workspacePath } = {}) {
+  if (!workspacePath || typeof workspacePath !== 'string' || workspacePath.includes('${')) {
+    throw new WorkspaceResolutionError(
+      'initialize_workspace requires an explicit workspace_path. No implicit cwd or env fallback is used.',
+      { code: 'WORKSPACE_REQUIRED' }
+    );
+  }
+  const resolved = path.resolve(workspacePath);
+  if (!fs.existsSync(resolved)) {
+    throw new WorkspaceResolutionError(
+      `workspace_path does not exist: ${resolved}`,
+      { code: 'WORKSPACE_NOT_FOUND', details: { workspace_path: resolved } }
+    );
+  }
+  if (isExtensionCachePath(resolved)) {
+    throw new WorkspaceResolutionError(
+      `workspace_path resolves inside an extension cache directory: ${resolved}. Provide the user workspace path instead.`,
+      { code: 'WORKSPACE_IN_EXTENSION_CACHE', details: { workspace_path: resolved } }
+    );
+  }
+  try {
+    return resolveGitRoot(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+module.exports = {
+  resolveProjectRoot,
+  resolveProjectRootForRuntime,
+  requireExplicitWorkspaceRoot,
+  requireWorkspaceRoot,
+  WorkspaceResolutionError,
+};