@jaggerxtrm/specialists 3.13.0 → 3.14.1

package/dist/index.js

@@ -17561,6 +17561,7 @@ var init_schema = __esm(() => {
     max_retries: numberType().int().min(0).default(0),
     interactive: booleanType().default(false),
     stdout_limit_bytes: numberType().int().positive().optional(),
+    prompt_limit_bytes: numberType().int().positive().optional(),
     response_format: enumType(["text", "json", "markdown"]).default("text"),
     output_type: enumType(["codegen", "analysis", "review", "synthesis", "orchestration", "workflow", "research", "custom"]).default("custom"),
     permission_required: enumType(["READ_ONLY", "LOW", "MEDIUM", "HIGH"]).default("READ_ONLY"),
@@ -19156,8 +19157,8 @@ function resolveCurrentBranch(cwd = process.cwd()) {
 var init_job_root = () => {};
 
 // src/specialist/observability-sqlite.ts
-import { existsSync as existsSync5, readFileSync as readFileSync3, statSync } from "fs";
-import { join as join5 } from "path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync3, readFileSync as readFileSync3, statSync } from "fs";
+import { dirname as dirname3, join as join5 } from "path";
 function loadBunDatabase() {
   if (_probed)
     return _BunDatabase;
@@ -21220,23 +21221,30 @@ function hasRunCompleteEvent(jobId, cwd = process.cwd()) {
   }
   return false;
 }
-function createObservabilitySqliteClient(cwd = process.cwd()) {
+function openObservabilitySqliteClient(dbPath) {
   if (!loadBunDatabase())
     return null;
-  const location = resolveObservabilityDbLocation(cwd);
-  if (!existsSync5(location.dbPath))
-    return null;
   try {
     const Ctor = loadBunDatabase();
-    const initDb = new Ctor(location.dbPath);
+    const initDb = new Ctor(dbPath);
     initDb.run(`PRAGMA busy_timeout=${BUSY_TIMEOUT_MS}`);
     initSchema(initDb);
     initDb.close();
-    return new SqliteClient(location.dbPath);
+    return new SqliteClient(dbPath);
   } catch {
     return null;
   }
 }
+function createObservabilitySqliteClient(cwd = process.cwd()) {
+  const location = resolveObservabilityDbLocation(cwd);
+  if (!existsSync5(location.dbPath))
+    return null;
+  return openObservabilitySqliteClient(location.dbPath);
+}
+function createObservabilitySqliteClientAtPath(dbPath) {
+  mkdirSync3(dirname3(dbPath), { recursive: true });
+  return openObservabilitySqliteClient(dbPath);
+}
 var _BunDatabase = null, _probed = false, BUSY_TIMEOUT_MS = 5000, MAX_RETRY_ATTEMPTS = 5, BASE_RETRY_DELAY_MS = 50, STALE_CLAIM_AGE_MS = 60000;
 var init_observability_sqlite = __esm(() => {
   init_observability_db();
@@ -23023,7 +23031,7 @@ var init_runner = __esm(() => {
 
 // src/specialist/hooks.ts
 import { appendFile, mkdir } from "fs/promises";
-import { dirname as dirname3 } from "path";
+import { dirname as dirname4 } from "path";
 
 class HookEmitter {
   tracePath;
@@ -23031,7 +23039,7 @@ class HookEmitter {
   ready;
   constructor(options) {
     this.tracePath = options.tracePath;
-    this.ready = mkdir(dirname3(options.tracePath), { recursive: true }).then(() => {});
+    this.ready = mkdir(dirname4(options.tracePath), { recursive: true }).then(() => {});
   }
   async emit(hook, invocationId, specialistName, specialistVersion, payload) {
     await this.ready;
@@ -23085,11 +23093,11 @@ __export(exports_version, {
 });
 import { createRequire } from "module";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import { dirname as dirname4, join as join7 } from "path";
+import { dirname as dirname5, join as join7 } from "path";
 import { existsSync as existsSync8 } from "fs";
 async function run2() {
   const req = createRequire(import.meta.url);
-  const here = dirname4(fileURLToPath2(import.meta.url));
+  const here = dirname5(fileURLToPath2(import.meta.url));
   const bundlePkgPath = join7(here, "..", "package.json");
   const sourcePkgPath = join7(here, "..", "..", "package.json");
   let pkg;
@@ -24219,7 +24227,7 @@ import {
   closeSync,
   existsSync as existsSync10,
   fsyncSync,
-  mkdirSync as mkdirSync3,
+  mkdirSync as mkdirSync4,
   openSync,
   readdirSync as readdirSync2,
   readFileSync as readFileSync8,
@@ -24656,7 +24664,7 @@ class Supervisor {
     return join9(this.resolvedJobsDir, "..", "ready");
   }
   writeReadyMarker(id) {
-    mkdirSync3(this.readyDir(), { recursive: true });
+    mkdirSync4(this.readyDir(), { recursive: true });
     writeFileSync3(join9(this.readyDir(), id), "", "utf-8");
   }
   withComputedLiveness(status) {
@@ -24787,7 +24795,7 @@ class Supervisor {
     if (!this.isJobFileOutputEnabled)
       return;
     const normalizedStatus = this.withStatusLineageDefaults(id, data);
-    mkdirSync3(this.jobDir(id), { recursive: true });
+    mkdirSync4(this.jobDir(id), { recursive: true });
     const path = this.statusPath(id);
     const tmp = path + ".tmp";
     writeFileSync3(tmp, JSON.stringify(normalizedStatus, null, 2), "utf-8");
@@ -24949,8 +24957,8 @@ class Supervisor {
     const id = crypto.randomUUID().slice(0, 6);
     const dir = this.jobDir(id);
     const startedAtMs = Date.now();
-    mkdirSync3(dir, { recursive: true });
-    mkdirSync3(this.readyDir(), { recursive: true });
+    mkdirSync4(dir, { recursive: true });
+    mkdirSync4(this.readyDir(), { recursive: true });
     const nodeId = runOptions.variables?.node_id ?? runOptions.variables?.SPECIALISTS_NODE_ID;
     const variablesKeys = Object.keys(runOptions.variables ?? {});
     const activatedSkills = (runOptions.variables?.activated_skills ?? runOptions.variables?.skills_activated ?? "").split(",").map((skill) => skill.trim()).filter((skill) => skill.length > 0);
@@ -25228,7 +25236,7 @@ ${appendError}
       try {
         const output = await resumeFn(task);
         latestOutput = output;
-        mkdirSync3(this.jobDir(id), { recursive: true });
+        mkdirSync4(this.jobDir(id), { recursive: true });
         writeFileSync3(this.resultPath(id), output, "utf-8");
         try {
           this.withSqliteOperation("upsertResult:resume_turn", (client) => client.upsertResult(id, output));
@@ -25636,7 +25644,7 @@ ${appendError}
       });
       latestOutput = result.output;
       if (this.isJobFileOutputEnabled) {
-        mkdirSync3(this.jobDir(id), { recursive: true });
+        mkdirSync4(this.jobDir(id), { recursive: true });
         writeFileSync3(this.resultPath(id), latestOutput, "utf-8");
       }
       const elapsed = Math.round((Date.now() - startedAtMs) / 1000);
@@ -26624,9 +26632,9 @@ var exports_init = {};
 __export(exports_init, {
   run: () => run7
 });
-import { copyFileSync, cpSync, existsSync as existsSync12, lstatSync, mkdirSync as mkdirSync4, readdirSync as readdirSync4, readFileSync as readFileSync10, readlinkSync, renameSync as renameSync2, symlinkSync, unlinkSync, writeFileSync as writeFileSync4 } from "fs";
+import { copyFileSync, cpSync, existsSync as existsSync12, lstatSync, mkdirSync as mkdirSync5, readdirSync as readdirSync4, readFileSync as readFileSync10, readlinkSync, renameSync as renameSync2, symlinkSync, unlinkSync, writeFileSync as writeFileSync4 } from "fs";
 import { spawnSync as spawnSync9 } from "child_process";
-import { basename as basename4, dirname as dirname5, join as join11, relative, resolve as resolve6 } from "path";
+import { basename as basename4, dirname as dirname6, join as join11, relative, resolve as resolve6 } from "path";
 function ok(msg) {
   console.log(`  ${green4("\u2713")} ${msg}`);
 }
@@ -26680,7 +26688,7 @@ function migrateLegacySpecialists(cwd, scope) {
     return;
   const targetDir = join11(cwd, ".specialists", scope);
   if (!existsSync12(targetDir)) {
-    mkdirSync4(targetDir, { recursive: true });
+    mkdirSync5(targetDir, { recursive: true });
   }
   const files = readdirSync4(sourceDir).filter((f) => f.endsWith(".specialist.json") || f.endsWith(".specialist.json"));
   if (files.length === 0)
@@ -26717,7 +26725,7 @@ function copyCanonicalSpecialists(cwd) {
     return;
   }
   if (!existsSync12(targetDir)) {
-    mkdirSync4(targetDir, { recursive: true });
+    mkdirSync5(targetDir, { recursive: true });
   }
   let copied = 0;
   let refreshed = 0;
@@ -26752,7 +26760,7 @@ function copyCanonicalMandatoryRules(cwd) {
     return;
   }
   if (!existsSync12(targetDir)) {
-    mkdirSync4(targetDir, { recursive: true });
+    mkdirSync5(targetDir, { recursive: true });
   }
   let copied = 0;
   let refreshed = 0;
@@ -26787,7 +26795,7 @@ function copyCanonicalNodeConfigs(cwd) {
     return;
   }
   if (!existsSync12(targetDir)) {
-    mkdirSync4(targetDir, { recursive: true });
+    mkdirSync5(targetDir, { recursive: true });
   }
   let copied = 0;
   let refreshed = 0;
@@ -26823,8 +26831,8 @@ function installProjectHooks(cwd) {
     skip("no hook files found in package");
     return;
   }
-  mkdirSync4(targetDir, { recursive: true });
-  mkdirSync4(claudeHooksDir, { recursive: true });
+  mkdirSync5(targetDir, { recursive: true });
+  mkdirSync5(claudeHooksDir, { recursive: true });
   let copied = 0;
   let skippedCopies = 0;
   let linked = 0;
@@ -26849,7 +26857,7 @@ function installProjectHooks(cwd) {
         rewiredLinks++;
         continue;
       }
-      const currentTarget = resolve6(dirname5(claudeHookPath), readlinkSync(claudeHookPath));
+      const currentTarget = resolve6(dirname6(claudeHookPath), readlinkSync(claudeHookPath));
       if (currentTarget !== xtrmDest) {
         unlinkSync(claudeHookPath);
         symlinkSync(relativeTarget, claudeHookPath);
@@ -26877,7 +26885,7 @@ function ensureProjectHookWiring(cwd) {
   const settingsPath = join11(cwd, ".claude", "settings.json");
   const settingsDir = join11(cwd, ".claude");
   if (!existsSync12(settingsDir)) {
-    mkdirSync4(settingsDir, { recursive: true });
+    mkdirSync5(settingsDir, { recursive: true });
   }
   const settings = loadJson(settingsPath, {});
   if (!settings.hooks || typeof settings.hooks !== "object") {
@@ -26913,10 +26921,10 @@ function ensureProjectHookWiring(cwd) {
 }
 function ensureRootSymlink(rootPath, expectedTargetPath) {
   if (!existsSync12(rootPath)) {
-    mkdirSync4(dirname5(rootPath), { recursive: true });
-    const relTarget = relative(dirname5(rootPath), expectedTargetPath);
+    mkdirSync5(dirname6(rootPath), { recursive: true });
+    const relTarget = relative(dirname6(rootPath), expectedTargetPath);
     symlinkSync(relTarget, rootPath);
-    ok(`created ${basename4(dirname5(rootPath))}/${basename4(rootPath)} \u2192 ${relTarget}`);
+    ok(`created ${basename4(dirname6(rootPath))}/${basename4(rootPath)} \u2192 ${relTarget}`);
     return;
   }
   const stats = lstatSync(rootPath);
@@ -26924,7 +26932,7 @@ function ensureRootSymlink(rootPath, expectedTargetPath) {
     throw new Error(`${rootPath} must be a symlink to ${expectedTargetPath}. Aborting.`);
   }
   const linkTarget = readlinkSync(rootPath);
-  const resolvedTarget = resolve6(dirname5(rootPath), linkTarget);
+  const resolvedTarget = resolve6(dirname6(rootPath), linkTarget);
   const resolvedExpected = resolve6(expectedTargetPath);
   if (resolvedTarget === resolvedExpected) {
     return;
@@ -26935,9 +26943,9 @@ function ensureRootSymlink(rootPath, expectedTargetPath) {
   ];
   if (legacyTargets.includes(resolvedTarget)) {
     unlinkSync(rootPath);
-    const relTarget = relative(dirname5(rootPath), expectedTargetPath);
+    const relTarget = relative(dirname6(rootPath), expectedTargetPath);
     symlinkSync(relTarget, rootPath);
-    ok(`rewired ${basename4(dirname5(rootPath))}/${basename4(rootPath)} \u2192 ${relTarget}`);
+    ok(`rewired ${basename4(dirname6(rootPath))}/${basename4(rootPath)} \u2192 ${relTarget}`);
     return;
   }
   throw new Error(`${rootPath} points to ${linkTarget}, expected ${expectedTargetPath}. Aborting.`);
@@ -26958,7 +26966,7 @@ function ensureActiveSkillSymlink(defaultSkillPath, activeLinkPath) {
   if (!stats.isSymbolicLink()) {
     throw new Error(`${activeLinkPath} already exists and is not a symlink.`);
   }
-  const currentTarget = resolve6(dirname5(activeLinkPath), readlinkSync(activeLinkPath));
+  const currentTarget = resolve6(dirname6(activeLinkPath), readlinkSync(activeLinkPath));
   if (currentTarget !== resolve6(defaultSkillPath)) {
     throw new Error(`${activeLinkPath} points to an unexpected target.`);
   }
@@ -26980,8 +26988,8 @@ function installProjectSkills(cwd, syncSkills) {
   }
   const defaultRoot = join11(cwd, ".xtrm", "skills", "default");
   const activeRoot = join11(cwd, ".xtrm", "skills", "active");
-  mkdirSync4(defaultRoot, { recursive: true });
-  mkdirSync4(activeRoot, { recursive: true });
+  mkdirSync5(defaultRoot, { recursive: true });
+  mkdirSync5(activeRoot, { recursive: true });
   ensureRootSymlink(join11(cwd, ".claude", "skills"), activeRoot);
   ensureRootSymlink(join11(cwd, ".pi", "skills"), activeRoot);
   let copied = 0;
@@ -27012,7 +27020,7 @@ function createSpecialistsDirs(cwd) {
   let created = 0;
   for (const dir of [defaultDir, userDir]) {
     if (!existsSync12(dir)) {
-      mkdirSync4(dir, { recursive: true });
+      mkdirSync5(dir, { recursive: true });
       created++;
     }
   }
@@ -27028,7 +27036,7 @@ function createRuntimeDirs(cwd) {
   let created = 0;
   for (const dir of runtimeDirs) {
     if (!existsSync12(dir)) {
-      mkdirSync4(dir, { recursive: true });
+      mkdirSync5(dir, { recursive: true });
       created++;
     }
   }
@@ -27161,7 +27169,7 @@ function validateInitPostconditions(cwd) {
       continue;
     }
     const expectedTarget = resolve6(xtrmHooksDir, hookFile);
-    const resolvedTarget = resolve6(dirname5(claudeHookPath), readlinkSync(claudeHookPath));
+    const resolvedTarget = resolve6(dirname6(claudeHookPath), readlinkSync(claudeHookPath));
     if (resolvedTarget !== expectedTarget) {
       warnings.push(`.claude/hooks/${hookFile} points to unexpected target`);
     }
@@ -27215,7 +27223,7 @@ function validateInitPostconditions(cwd) {
       warnings.push(`${relative(cwd, symlink.linkPath)} is not a symlink`);
       continue;
     }
-    const resolvedTarget = resolve6(dirname5(symlink.linkPath), readlinkSync(symlink.linkPath));
+    const resolvedTarget = resolve6(dirname6(symlink.linkPath), readlinkSync(symlink.linkPath));
     if (resolvedTarget !== resolve6(symlink.expectedTarget)) {
       warnings.push(`${relative(cwd, symlink.linkPath)} points to an unexpected target`);
     }
@@ -27392,8 +27400,8 @@ var exports_db = {};
 __export(exports_db, {
   run: () => run9
 });
-import { existsSync as existsSync13, mkdirSync as mkdirSync5, readdirSync as readdirSync5, readFileSync as readFileSync11, writeFileSync as writeFileSync5 } from "fs";
-import { dirname as dirname6, join as join12, resolve as resolve7 } from "path";
+import { existsSync as existsSync13, mkdirSync as mkdirSync6, readdirSync as readdirSync5, readFileSync as readFileSync11, writeFileSync as writeFileSync5 } from "fs";
+import { dirname as dirname7, join as join12, resolve as resolve7 } from "path";
 function formatBytes(bytes) {
   if (bytes < 1024)
     return `${bytes} B`;
@@ -28053,8 +28061,8 @@ function runBenchmarkExport(options) {
       });
     }
     rows.sort((a, b) => a.task_id.localeCompare(b.task_id) || a.executor_job_id.localeCompare(b.executor_job_id));
-    const outputDirectory = dirname6(options.outputPath);
-    mkdirSync5(outputDirectory, { recursive: true });
+    const outputDirectory = dirname7(options.outputPath);
+    mkdirSync6(outputDirectory, { recursive: true });
     const jsonl = rows.map((row) => JSON.stringify(row)).join(`
 `);
     writeFileSync5(options.outputPath, rows.length > 0 ? `${jsonl}
@@ -28145,6 +28153,19 @@ var init_db = __esm(() => {
 import { spawn as spawn3 } from "child_process";
 import { createHash as createHash3, randomUUID } from "crypto";
 import { readFileSync as readFileSync12 } from "fs";
+import { isAbsolute as isAbsolute2, relative as relative2, resolve as resolve8 } from "path";
+function isPathWithinRoot(candidatePath, rootPath) {
+  const candidate = resolve8(candidatePath);
+  const root = resolve8(rootPath);
+  const rel = relative2(root, candidate);
+  return rel === "" || rel.length > 0 && !rel.startsWith("..") && !isAbsolute2(rel);
+}
+function assertSkillPathWithinRoots(field, path, roots) {
+  const allowed = roots.some((root) => isPathWithinRoot(path, root));
+  if (!allowed) {
+    throw new CompatGuardError(field, `skill path '${path}' not under any --allow-skills-roots entry`);
+  }
+}
 function hasUnsubstitutedVariables(template, variables) {
   const matches = template.match(/\$([a-zA-Z_][a-zA-Z0-9_]*)/g) ?? [];
   for (const match of matches) {
@@ -28163,8 +28184,8 @@ function compatGuard(spec, trust) {
   if (execution.permission_required !== "READ_ONLY")
     throw new CompatGuardError("execution.permission_required", "permission_required must be READ_ONLY");
   const hasScripts = (spec.specialist.skills?.scripts?.length ?? 0) > 0;
-  if (hasScripts && !trust?.allowLocalScripts) {
-    throw new CompatGuardError("skills.scripts", "scripts not allowed (enable with --allow-local-scripts)");
+  if (hasScripts) {
+    throw new CompatGuardError("skills.scripts", "local scripts are not supported in script-class specialists");
   }
   const hasPaths = (spec.specialist.skills?.paths?.length ?? 0) > 0;
   const hasSkillInherit = Boolean(spec.specialist.prompt.skill_inherit);
@@ -28174,26 +28195,34 @@ function compatGuard(spec, trust) {
   if (hasSkillInherit && !trust?.allowSkills) {
     throw new CompatGuardError("prompt.skill_inherit", "skills not allowed (enable with --allow-skills)");
   }
-  if (hasPaths && trust?.allowSkills && trust.allowSkillsRoots && trust.allowSkillsRoots.length > 0) {
+  if (trust?.allowSkills && trust.allowSkillsRoots && trust.allowSkillsRoots.length > 0) {
     const paths = spec.specialist.skills?.paths ?? [];
-    for (const path of paths) {
-      const allowed = trust.allowSkillsRoots.some((root) => path.startsWith(root));
-      if (!allowed) {
-        throw new CompatGuardError("skills.paths", `skill path '${path}' not under any --allow-skills-roots entry`);
-      }
+    for (const path of paths)
+      assertSkillPathWithinRoots("skills.paths", path, trust.allowSkillsRoots);
+    if (typeof spec.specialist.prompt.skill_inherit === "string") {
+      assertSkillPathWithinRoots("prompt.skill_inherit", spec.specialist.prompt.skill_inherit, trust.allowSkillsRoots);
     }
   }
 }
+function collectSkillPathEntries(spec) {
+  return [
+    ...(spec.specialist.skills?.paths ?? []).map((path) => ({ path, source: "skills.paths" })),
+    ...typeof spec.specialist.prompt.skill_inherit === "string" ? [{ path: spec.specialist.prompt.skill_inherit, source: "prompt.skill_inherit" }] : []
+  ];
+}
+function collectSkillPaths(spec) {
+  return collectSkillPathEntries(spec).map((entry) => entry.path);
+}
 function computeSkillSources(spec) {
-  const paths = spec.specialist.skills?.paths ?? [];
+  const entries = collectSkillPathEntries(spec);
   const sources = [];
-  for (const path of paths) {
+  for (const { path, source } of entries) {
     try {
       const content = readFileSync12(path);
       const sha256 = createHash3("sha256").update(content).digest("hex");
-      sources.push({ path, sha256 });
+      sources.push({ path, sha256, source });
     } catch {
-      sources.push({ path, sha256: "unreadable" });
+      sources.push({ path, sha256: "unreadable", source });
     }
   }
   return sources;
@@ -28204,6 +28233,34 @@ function renderTaskTemplate(template, variables) {
     throw new Error(`Missing template variable: ${missing}`);
   return renderTemplate(template, variables);
 }
+function truncateForPrompt(value, limitBytes) {
+  if (Buffer.byteLength(value, "utf8") <= limitBytes)
+    return value;
+  return `${value.slice(0, limitBytes)}
+... truncated ...`;
+}
+function buildJsonOutputContract(spec) {
+  if (spec.specialist.execution.response_format !== "json")
+    return;
+  const schema = spec.specialist.prompt.output_schema;
+  const required2 = Array.isArray(schema?.required) ? schema.required.filter((value) => typeof value === "string") : [];
+  const lines = [
+    "Output contract:",
+    "- Return only valid JSON. Do not include Markdown fences, prose, or commentary."
+  ];
+  if (required2.length > 0)
+    lines.push(`- Include these required top-level keys: ${required2.join(", ")}.`);
+  if (schema)
+    lines.push(`- JSON schema: ${truncateForPrompt(JSON.stringify(schema), 4096)}`);
+  return lines.join(`
+`);
+}
+function applyOutputContract(prompt, spec) {
+  const contract = buildJsonOutputContract(spec);
+  return contract ? `${prompt}
+
+${contract}` : prompt;
+}
 function mapErrorType(message) {
   if (message.includes("Specialist not found"))
     return "specialist_not_found";
@@ -28211,6 +28268,8 @@ function mapErrorType(message) {
     return "specialist_load_error";
   if (message.includes("Missing template variable"))
     return "template_variable_missing";
+  if (message.includes("prompt too large"))
+    return "prompt_too_large";
   if (message.includes("output too large"))
     return "output_too_large";
   if (message.includes("auth") || message.includes("403") || message.includes("401"))
@@ -28278,6 +28337,18 @@ function writeTraceRow(client, specialist, model, traceId, output2, durationMs,
     onAuditFailure?.(error2);
   }
 }
+function resolvePromptLimitBytes(spec) {
+  return spec.specialist.execution.prompt_limit_bytes ?? resolveEnvPromptLimitBytes() ?? DEFAULT_PROMPT_LIMIT_BYTES;
+}
+function resolveEnvPromptLimitBytes() {
+  const raw = process.env.SPECIALISTS_SCRIPT_PROMPT_LIMIT_BYTES;
+  if (raw === undefined)
+    return;
+  const envLimit = Number(raw);
+  if (!Number.isFinite(envLimit) || envLimit <= 0)
+    return;
+  return Math.floor(envLimit);
+}
 function resolveAssistantTextLimitBytes(spec) {
   return spec.specialist.execution.stdout_limit_bytes ?? resolveEnvAssistantTextLimitBytes() ?? DEFAULT_ASSISTANT_TEXT_LIMIT_BYTES;
 }
@@ -28293,8 +28364,9 @@ function resolveEnvAssistantTextLimitBytes() {
   return Math.floor(envLimit);
 }
 function openObservabilityClient(options) {
-  const dbPath = options.observabilityDbPath ?? options.projectDir;
-  return createObservabilitySqliteClient(dbPath);
+  if (options.observabilityDbPath)
+    return createObservabilitySqliteClientAtPath(options.observabilityDbPath);
+  return createObservabilitySqliteClient(options.projectDir);
 }
 function resolveScriptSpecialistName(name) {
   if (name === "changelog-keeper")
@@ -28308,9 +28380,28 @@ async function runScriptSpecialist(input2, options) {
     const resolvedSpecialist = resolveScriptSpecialistName(input2.specialist);
     const spec = await options.loader.get(resolvedSpecialist);
     compatGuard(spec, options.trust);
+    const skillPaths = options.trust?.allowSkills ? collectSkillPaths(spec) : [];
     const skillSources = options.trust?.allowSkills ? computeSkillSources(spec) : undefined;
     const template = input2.template ?? spec.specialist.prompt.task_template;
-    const prompt = renderTaskTemplate(template, input2.variables ?? {});
+    const prompt = applyOutputContract(renderTaskTemplate(template, input2.variables ?? {}), spec);
+    const modelCandidates = collectModelCandidates(input2, spec, options);
+    const promptLimitBytes = resolvePromptLimitBytes(spec);
+    const promptBytes = Buffer.byteLength(prompt, "utf8");
+    if (promptBytes > promptLimitBytes) {
+      return {
+        success: false,
+        error: `prompt too large: ${promptBytes} bytes exceeds limit ${promptLimitBytes} bytes`,
+        error_type: "prompt_too_large",
+        meta: {
+          specialist: resolvedSpecialist,
+          requested_specialist: input2.requested_specialist ?? input2.specialist,
+          resolved_specialist: resolvedSpecialist,
+          model: modelCandidates[0],
+          duration_ms: Date.now() - startedAt,
+          trace_id: traceId
+        }
+      };
+    }
     if (process.env.SPECIALISTS_SCRIPT_STUB_OUTPUT) {
       return {
         success: true,
@@ -28326,11 +28417,11 @@ async function runScriptSpecialist(input2, options) {
       };
     }
     const timeoutMs = input2.timeout_ms ?? spec.specialist.execution.timeout_ms ?? 120000;
-    const modelCandidates = collectModelCandidates(input2, spec, options);
     const assistantTextLimitBytes = resolveAssistantTextLimitBytes(spec);
     const attempts = [];
     for (const model of modelCandidates) {
-      const attempt = await runSingleAttempt(prompt, model, input2.thinking_level ?? spec.specialist.execution.thinking_level, timeoutMs, assistantTextLimitBytes, options);
+      const systemPrompt = spec.specialist.prompt.system || undefined;
+      const attempt = await runSingleAttempt(prompt, model, input2.thinking_level ?? spec.specialist.execution.thinking_level, timeoutMs, assistantTextLimitBytes, options, systemPrompt, skillPaths);
       attempts.push(attempt);
       const parsed = classifyAttempt(attempt);
       if (parsed.retryable)
@@ -28373,14 +28464,23 @@ function collectModelCandidates(input2, spec, options) {
   const candidates = [input2.model_override, spec.specialist.execution.model, spec.specialist.execution.fallback_model, options.fallbackModel].filter((value) => typeof value === "string" && value.length > 0);
   return [...new Set(candidates)];
 }
-function runSingleAttempt(prompt, model, thinkingLevel, timeoutMs, assistantTextLimitBytes, options) {
-  return new Promise((resolve8, reject) => {
-    const args = ["--mode", "json", "--no-session", "--no-extensions", "--no-tools", "--model", model];
+function runSingleAttempt(prompt, model, thinkingLevel, timeoutMs, assistantTextLimitBytes, options, systemPrompt, skillPaths = []) {
+  return new Promise((resolve9, reject) => {
+    const args = ["--mode", "json", "--no-session", "--no-extensions", "--no-tools", "--offline", "--no-context-files", "--no-prompt-templates", "--no-themes"];
+    if (skillPaths.length === 0)
+      args.push("--no-skills");
+    for (const skillPath of skillPaths)
+      args.push("--skill", skillPath);
+    args.push("--model", model);
     if (thinkingLevel)
       args.push("--thinking", thinkingLevel);
-    args.push(prompt);
-    const pi = spawn3("pi", args, { stdio: ["ignore", "pipe", "pipe"] });
+    if (systemPrompt)
+      args.push("--system-prompt", systemPrompt);
+    const pi = spawn3("pi", args, { stdio: ["pipe", "pipe", "pipe"], cwd: options.projectDir ?? process.cwd() });
     options.onChild?.(pi);
+    pi.stdin?.on("error", () => {});
+    pi.stdin?.write(prompt);
+    pi.stdin?.end();
     let stderr = "";
     let timedOut = false;
     let outputTooLarge = false;
@@ -28449,7 +28549,7 @@ function runSingleAttempt(prompt, model, thinkingLevel, timeoutMs, assistantText
     pi.on("error", reject);
     pi.on("close", (code) => {
       clearTimeout(timer);
-      resolve8({
+      resolve9({
         model,
         text: assistantText,
         stderr,
@@ -28486,7 +28586,7 @@ function classifyAttempt(attempt) {
 function isRetryableModelFailure(stderr, text) {
   return stderr.includes("0 tokens") || stderr.includes("quota") || stderr.includes("rate limit") || stderr.includes("403") || stderr.includes("401") || stderr.includes("insufficient_quota") || !text && !stderr.trim();
 }
-var CompatGuardError, DEFAULT_PENDING_LINE_LIMIT_BYTES, DEFAULT_ASSISTANT_TEXT_LIMIT_BYTES, DEFAULT_STDERR_LIMIT_BYTES;
+var CompatGuardError, DEFAULT_PENDING_LINE_LIMIT_BYTES, DEFAULT_ASSISTANT_TEXT_LIMIT_BYTES, DEFAULT_STDERR_LIMIT_BYTES, DEFAULT_PROMPT_LIMIT_BYTES;
 var init_script_runner = __esm(() => {
   init_observability_sqlite();
   CompatGuardError = class CompatGuardError extends Error {
@@ -28500,6 +28600,7 @@ var init_script_runner = __esm(() => {
   DEFAULT_PENDING_LINE_LIMIT_BYTES = 16 * 1024 * 1024;
   DEFAULT_ASSISTANT_TEXT_LIMIT_BYTES = 4 * 1024 * 1024;
   DEFAULT_STDERR_LIMIT_BYTES = 1 * 1024 * 1024;
+  DEFAULT_PROMPT_LIMIT_BYTES = 4 * 1024 * 1024;
 });
 
 // src/cli/validate.ts
@@ -28652,7 +28753,7 @@ var exports_edit = {};
 __export(exports_edit, {
   run: () => run11
 });
-import { existsSync as existsSync15, mkdirSync as mkdirSync6, readFileSync as readFileSync13, writeFileSync as writeFileSync6 } from "fs";
+import { existsSync as existsSync15, mkdirSync as mkdirSync7, readFileSync as readFileSync13, writeFileSync as writeFileSync6 } from "fs";
 import { join as join13 } from "path";
 function loadPresets() {
   const paths = [
@@ -29090,7 +29191,7 @@ function createUserFork(source, targetName) {
   if (source.scope === "user")
     return source;
   const targetDir = join13(process.cwd(), ".specialists", "user");
-  mkdirSync6(targetDir, { recursive: true });
+  mkdirSync7(targetDir, { recursive: true });
   const targetFile = join13(targetDir, `${targetName}.specialist.json`);
   const doc2 = readJsonFile2(source.filePath);
   doc2.specialist = doc2.specialist ?? {};
@@ -29400,7 +29501,7 @@ __export(exports_config, {
 });
 import { readFileSync as readFileSync14 } from "fs";
 import { spawnSync as spawnSync10 } from "child_process";
-import { dirname as dirname7, join as join15 } from "path";
+import { dirname as dirname8, join as join15 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 function usage2() {
   return [
@@ -29446,7 +29547,7 @@ function getGitTopLevel(projectDir) {
   return result.stdout.trim() || undefined;
 }
 function getRuntimePackageVersion() {
-  const runtimeDir = dirname7(fileURLToPath3(import.meta.url));
+  const runtimeDir = dirname8(fileURLToPath3(import.meta.url));
   const packageJsonPath = runtimeDir.includes("/dist/") ? join15(runtimeDir, "..", "package.json") : join15(runtimeDir, "..", "..", "package.json");
   return readPackageVersion(packageJsonPath);
 }
@@ -29585,8 +29686,8 @@ var init_config = __esm(() => {
 });
 
 // src/specialist/worktree.ts
-import { existsSync as existsSync16, symlinkSync as symlinkSync2, mkdirSync as mkdirSync7 } from "fs";
-import { join as join16, resolve as resolve8 } from "path";
+import { existsSync as existsSync16, symlinkSync as symlinkSync2, mkdirSync as mkdirSync8 } from "fs";
+import { join as join16, resolve as resolve9 } from "path";
 import { spawnSync as spawnSync11, execFileSync as execFileSync2 } from "child_process";
 function deriveBranchName(beadId, specialistName) {
   return `feature/${beadId}-${slugify(specialistName)}`;
@@ -29619,11 +29720,11 @@ function provisionWorktree(options) {
   const branch = deriveBranchName(options.beadId, options.specialistName);
   const existingPath = findExistingWorktree(branch, cwd);
   if (existingPath) {
-    return { branch, worktreePath: resolve8(existingPath), reused: true };
+    return { branch, worktreePath: resolve9(existingPath), reused: true };
   }
   const worktreeBase = options.worktreeBase ?? join16(commonRoot, ".worktrees", options.beadId);
   const worktreeName = deriveWorktreeName(options.beadId, options.specialistName);
-  const worktreePath = resolve8(join16(worktreeBase, worktreeName));
+  const worktreePath = resolve9(join16(worktreeBase, worktreeName));
   createWorktreeViaBd(worktreePath, branch, commonRoot);
   symlinkPiNpmCache(commonRoot, worktreePath);
   return { branch, worktreePath, reused: false };
@@ -29634,7 +29735,7 @@ function symlinkPiNpmCache(commonRoot, worktreePath) {
   if (!existsSync16(source) || existsSync16(target))
     return;
   try {
-    mkdirSync7(join16(worktreePath, ".pi"), { recursive: true });
+    mkdirSync8(join16(worktreePath, ".pi"), { recursive: true });
     symlinkSync2(source, target);
   } catch {}
 }
@@ -29674,12 +29775,12 @@ var init_worktree = __esm(() => {
 });
 
 // src/specialist/epic-reconciler.ts
-import { mkdirSync as mkdirSync8, openSync as openSync2, readFileSync as readFileSync15, rmSync as rmSync2, writeFileSync as writeFileSync7 } from "fs";
+import { mkdirSync as mkdirSync9, openSync as openSync2, readFileSync as readFileSync15, rmSync as rmSync2, writeFileSync as writeFileSync7 } from "fs";
 import { join as join17 } from "path";
 function buildEpicLockPath(epicId) {
   const location = resolveObservabilityDbLocation();
   const lockDir = join17(location.dbDirectory, "locks");
-  mkdirSync8(lockDir, { recursive: true });
+  mkdirSync9(lockDir, { recursive: true });
   return join17(lockDir, `epic-${epicId}.lock`);
 }
 function withEpicAdvisoryLock(epicId, action) {
@@ -31021,13 +31122,13 @@ async function parseArgs7(argv) {
     process.exit(1);
   }
   if (!prompt && !beadId && !process.stdin.isTTY) {
-    prompt = await new Promise((resolve9) => {
+    prompt = await new Promise((resolve10) => {
       let buf = "";
       process.stdin.setEncoding("utf-8");
       process.stdin.on("data", (chunk) => {
         buf += chunk;
       });
-      process.stdin.on("end", () => resolve9(buf.trim()));
+      process.stdin.on("end", () => resolve10(buf.trim()));
     });
   }
   if (!prompt && !beadId && !reuseJobId) {
@@ -31700,8 +31801,8 @@ class JobControl {
       }
     };
     let resolveJobId;
-    const jobIdPromise = new Promise((resolve9) => {
-      resolveJobId = resolve9;
+    const jobIdPromise = new Promise((resolve10) => {
+      resolveJobId = resolve10;
     });
     this.supervisor = new Supervisor({
       runner: this.runner,
@@ -31766,7 +31867,7 @@ class JobControl {
       if (deadline !== undefined && Date.now() >= deadline) {
         throw new Error(`Timed out waiting for terminal status for job ${jobId}`);
       }
-      await new Promise((resolve9) => setTimeout(resolve9, backoffMs));
+      await new Promise((resolve10) => setTimeout(resolve10, backoffMs));
       backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS);
     }
   }
@@ -31945,7 +32046,7 @@ function hashOutput(output2, salt) {
   return createHash4("sha256").update(value).digest("hex");
 }
 function sleep2(ms) {
-  return new Promise((resolve9) => setTimeout(resolve9, ms));
+  return new Promise((resolve10) => setTimeout(resolve10, ms));
 }
 function toContextHealth(contextPct) {
   if (contextPct === null)
@@ -33861,7 +33962,7 @@ __export(exports_node, {
 import { existsSync as existsSync19, readFileSync as readFileSync19, readdirSync as readdirSync7 } from "fs";
 import { randomUUID as randomUUID2 } from "crypto";
 import { spawnSync as spawnSync14 } from "child_process";
-import { basename as basename5, join as join21, resolve as resolve9 } from "path";
+import { basename as basename5, join as join21, resolve as resolve10 } from "path";
 function parseNodeArgs(argv) {
   const command = argv[0];
   const supportedCommands = new Set(["run", "list", "promote", "members", "memory", "stop", "spawn-member", "create-bead", "complete", "wait-phase"]);
@@ -34050,7 +34151,7 @@ function toNodeName(filePath) {
 function discoverNodeConfigs(cwd) {
   const discoveredByName = new Map;
   for (const directory of NODE_DISCOVERY_DIRS) {
-    const absoluteDir = resolve9(cwd, directory.path);
+    const absoluteDir = resolve10(cwd, directory.path);
     if (!existsSync19(absoluteDir))
       continue;
     const files = readdirSync7(absoluteDir).filter((fileName) => fileName.endsWith(NODE_CONFIG_SUFFIX));
@@ -34072,7 +34173,7 @@ function getNodeDiscoverySummary() {
 `);
 }
 function resolveNodeConfigPath(cwd, input2) {
-  const explicitPath = resolve9(cwd, input2);
+  const explicitPath = resolve10(cwd, input2);
   if (existsSync19(explicitPath)) {
     return { name: toNodeName(explicitPath), path: explicitPath, source: "repo" };
   }
@@ -34625,7 +34726,7 @@ async function handleNodeAction(args) {
           if (deadline !== null && Date.now() >= deadline) {
             throw new Error(`Timed out waiting for phase '${args.phaseId}' members: ${memberKeys.join(", ")}`);
           }
-          await new Promise((resolve10) => setTimeout(resolve10, 500));
+          await new Promise((resolve11) => setTimeout(resolve11, 500));
         }
       } finally {
         sqliteClient.close();
@@ -35497,8 +35598,8 @@ var init_epic = __esm(() => {
 
 // src/cli/version-check.ts
 import { spawnSync as spawnSync16 } from "child_process";
-import { existsSync as existsSync20, mkdirSync as mkdirSync9, readFileSync as readFileSync20, writeFileSync as writeFileSync9 } from "fs";
-import { dirname as dirname8, join as join22 } from "path";
+import { existsSync as existsSync20, mkdirSync as mkdirSync10, readFileSync as readFileSync20, writeFileSync as writeFileSync9 } from "fs";
+import { dirname as dirname9, join as join22 } from "path";
 import { createRequire as createRequire3 } from "module";
 function readBundledPackageVersion(requireFn = require3) {
   for (const candidate of ["../package.json", "../../package.json"]) {
@@ -35532,7 +35633,7 @@ function readCachedVersionCheck() {
   return readCache();
 }
 function writeCache(cache) {
-  mkdirSync9(dirname8(CACHE_PATH), { recursive: true });
+  mkdirSync10(dirname9(CACHE_PATH), { recursive: true });
   writeFileSync9(CACHE_PATH, `${JSON.stringify(cache, null, 2)}
 `, "utf8");
 }
@@ -38105,7 +38206,7 @@ async function followMerged(sqliteClient, jobsDir, options) {
   }
   const lastPrintedEventKey = new Map;
   const seenMetaKey = new Map;
-  await new Promise((resolve10) => {
+  await new Promise((resolve11) => {
     const interval = setInterval(() => {
       const currentJobIds = listMatchingJobIds(sqliteClient, jobsDir, options);
       const statusByJobId = new Map;
@@ -38193,7 +38294,7 @@ async function followMerged(sqliteClient, jobsDir, options) {
         });
         if (completedJobs.size === trackedJobs.size || allTrackedTerminal) {
           clearInterval(interval);
-          resolve10();
+          resolve11();
         }
       }
     }, 750);
@@ -38959,7 +39060,7 @@ async function waitForProcessExit(pid, timeoutMs) {
   while (Date.now() < deadline) {
     if (!isProcessAlive(pid))
       return true;
-    await new Promise((resolve10) => setTimeout(resolve10, 100));
+    await new Promise((resolve11) => setTimeout(resolve11, 100));
   }
   return !isProcessAlive(pid);
 }
@@ -39134,7 +39235,7 @@ var init_attach = () => {};
 
 // src/specialist/drift-detector.ts
 import { existsSync as existsSync28, readFileSync as readFileSync29, readdirSync as readdirSync13, rmSync as rmSync4 } from "fs";
-import { join as join31, resolve as resolve10, relative as relative2 } from "path";
+import { join as join31, resolve as resolve11, relative as relative3 } from "path";
 function listFiles(root) {
   if (!existsSync28(root))
     return [];
@@ -39154,7 +39255,7 @@ function listFiles(root) {
   return out;
 }
 function relPath(path, base) {
-  return relative2(base, path) || ".";
+  return relative3(base, path) || ".";
 }
 function makeFinding(repoRoot, kind, scope, path, canonicalPath, bytesEqual) {
   const rel = relPath(path, repoRoot);
@@ -39172,8 +39273,8 @@ function detectDriftForRepo(repoRoot) {
     if (!asset.canonicalDir)
       continue;
     const scopes = [
-      { scope: "default", dir: resolve10(repoRoot, asset.managedDir) },
-      { scope: "user", dir: resolve10(repoRoot, ".specialists/user") }
+      { scope: "default", dir: resolve11(repoRoot, asset.managedDir) },
+      { scope: "user", dir: resolve11(repoRoot, ".specialists/user") }
     ];
     for (const { scope, dir } of scopes) {
       if (!existsSync28(dir))
@@ -39210,10 +39311,10 @@ function detectDriftUnderRoot(root) {
       visit2(join31(dir, entry.name));
     }
   };
-  visit2(resolve10(root));
+  visit2(resolve11(root));
   const summary = repos.flatMap((r) => r.findings);
   return {
-    root: resolve10(root),
+    root: resolve11(root),
     repos,
     summary: {
       repos: repos.length,
@@ -39249,7 +39350,7 @@ var exports_prune_stale_defaults = {};
 __export(exports_prune_stale_defaults, {
   run: () => run26
 });
-import { resolve as resolve11 } from "path";
+import { resolve as resolve12 } from "path";
 function parseArgs11(argv) {
   let dryRun = false;
   let root = process.cwd();
@@ -39264,7 +39365,7 @@ function parseArgs11(argv) {
       const value = argv[i + 1];
       if (!value || value.startsWith("--"))
         throw new Error("--root requires a value");
-      root = resolve11(value);
+      root = resolve12(value);
       i += 1;
       continue;
     }
@@ -39545,8 +39646,8 @@ __export(exports_doctor, {
 });
 import { createHash as createHash5 } from "crypto";
 import { spawnSync as spawnSync22 } from "child_process";
-import { existsSync as existsSync29, lstatSync as lstatSync2, mkdirSync as mkdirSync10, readdirSync as readdirSync14, readFileSync as readFileSync30, readlinkSync as readlinkSync2, writeFileSync as writeFileSync12 } from "fs";
-import { dirname as dirname9, join as join32, relative as relative3, resolve as resolve12 } from "path";
+import { existsSync as existsSync29, lstatSync as lstatSync2, mkdirSync as mkdirSync11, readdirSync as readdirSync14, readFileSync as readFileSync30, readlinkSync as readlinkSync2, writeFileSync as writeFileSync12 } from "fs";
+import { dirname as dirname10, join as join32, relative as relative4, resolve as resolve13 } from "path";
 function ok3(msg) {
   console.log(`  ${green14("\u2713")} ${msg}`);
 }
@@ -39643,20 +39744,20 @@ function checkHooks() {
   for (const name of HOOK_NAMES) {
     const canonicalPath = join32(HOOKS_DIR, name);
     if (!existsSync29(canonicalPath)) {
-      fail4(`${relative3(CWD, canonicalPath)}  ${red7("missing")}`);
+      fail4(`${relative4(CWD, canonicalPath)}  ${red7("missing")}`);
       fix("specialists init");
       allPresent = false;
     } else {
-      ok3(relative3(CWD, canonicalPath));
+      ok3(relative4(CWD, canonicalPath));
     }
     const claudeHookPath = join32(CLAUDE_HOOKS_DIR, name);
     const symlinkState = isSymlinkTo(claudeHookPath, canonicalPath);
     if (symlinkState.ok) {
-      ok3(`${relative3(CWD, claudeHookPath)} -> ${relative3(dirname9(claudeHookPath), canonicalPath)}`);
+      ok3(`${relative4(CWD, claudeHookPath)} -> ${relative4(dirname10(claudeHookPath), canonicalPath)}`);
       continue;
     }
     allPresent = false;
-    const relHookPath = relative3(CWD, claudeHookPath);
+    const relHookPath = relative4(CWD, claudeHookPath);
     if (symlinkState.reason === "missing") {
       fail4(`${relHookPath} missing`);
     } else if (symlinkState.reason === "not-symlink") {
@@ -39738,7 +39839,7 @@ function collectFileHashes(rootDir) {
       }
       if (!entry.isFile())
         continue;
-      const relPath2 = relative3(rootDir, fullPath);
+      const relPath2 = relative4(rootDir, fullPath);
       hashes.set(relPath2, hashFile(fullPath));
     }
   };
@@ -39759,8 +39860,8 @@ function isSymlinkTo(linkPath, expectedTargetPath) {
     return { ok: false, reason: "not-symlink" };
   try {
     const rawTarget = readlinkSync2(linkPath);
-    const resolvedTarget = resolve12(dirname9(linkPath), rawTarget);
-    const resolvedExpected = resolve12(expectedTargetPath);
+    const resolvedTarget = resolve13(dirname10(linkPath), rawTarget);
+    const resolvedExpected = resolve13(expectedTargetPath);
     if (resolvedTarget !== resolvedExpected) {
       return { ok: false, reason: "wrong-target", target: rawTarget };
     }
@@ -39820,7 +39921,7 @@ function checkSkillDrift() {
   for (const scope of ["claude", "pi"]) {
     const activeRoot = join32(XTRM_ACTIVE_SKILLS_DIR, scope);
     if (!existsSync29(activeRoot)) {
-      fail4(`${relative3(CWD, activeRoot)}/ missing`);
+      fail4(`${relative4(CWD, activeRoot)}/ missing`);
       fix("specialists init --sync-skills");
       linksOk = false;
       continue;
@@ -39833,7 +39934,7 @@ function checkSkillDrift() {
       if (state.ok)
         continue;
       linksOk = false;
-      const relLink = relative3(CWD, activeLinkPath);
+      const relLink = relative4(CWD, activeLinkPath);
       if (state.reason === "missing") {
         fail4(`${relLink} missing`);
       } else if (state.reason === "not-symlink") {
@@ -39854,11 +39955,11 @@ function checkSkillDrift() {
   for (const check2 of skillRootChecks) {
     const state = isSymlinkTo(check2.root, check2.expected);
     if (state.ok) {
-      ok3(`${relative3(CWD, check2.root)} -> ${relative3(dirname9(check2.root), check2.expected)}`);
+      ok3(`${relative4(CWD, check2.root)} -> ${relative4(dirname10(check2.root), check2.expected)}`);
       continue;
     }
     rootLinksOk = false;
-    const relRoot = relative3(CWD, check2.root);
+    const relRoot = relative4(CWD, check2.root);
     if (state.reason === "missing") {
       fail4(`${relRoot} missing`);
     } else if (state.reason === "not-symlink") {
@@ -39874,12 +39975,12 @@ function checkSkillDrift() {
 }
 function checkManagedMirror(label, sourceDir, mirrorDir, fixHint) {
   if (!existsSync29(sourceDir)) {
-    warn3(`${label} source missing: ${relative3(CWD, sourceDir)}`);
+    warn3(`${label} source missing: ${relative4(CWD, sourceDir)}`);
     fix(fixHint);
     return false;
   }
   if (!existsSync29(mirrorDir)) {
-    fail4(`${label} mirror missing: ${relative3(CWD, mirrorDir)}`);
+    fail4(`${label} mirror missing: ${relative4(CWD, mirrorDir)}`);
     fix(fixHint);
     return false;
   }
@@ -39975,7 +40076,7 @@ function checkRuntimeDirs() {
     for (const [subDir, label] of [[jobsDir, "jobs"], [readyDir, "ready"]]) {
       if (!existsSync29(subDir)) {
         warn3(`.specialists/${label}/ missing \u2014 auto-creating`);
-        mkdirSync10(subDir, { recursive: true });
+        mkdirSync11(subDir, { recursive: true });
         ok3(`.specialists/${label}/ created`);
       } else {
         ok3(`.specialists/${label}/ present`);
@@ -40057,7 +40158,7 @@ function parseDoctorArgs(argv) {
       const value = argv[i + 1];
       if (!value || value.startsWith("--"))
         throw new Error("--root requires a value");
-      opts.root = resolve12(value);
+      opts.root = resolve13(value);
       i += 1;
       continue;
     }
@@ -40478,10 +40579,13 @@ __export(exports_serve, {
   run: () => run30,
   recordAuditFailure: () => recordAuditFailure,
   evaluateReadiness: () => evaluateReadiness2,
-  createReadinessState: () => createReadinessState
+  createReadinessState: () => createReadinessState,
+  checkPiHelpForFlags: () => checkPiHelpForFlags
 });
 import { createServer } from "http";
+import { randomUUID as randomUUID3 } from "crypto";
 import { once } from "events";
+import { spawnSync as spawnSync23 } from "child_process";
 import { access, readdir as readdir2, readFile as readFile5, constants } from "fs/promises";
 import { existsSync as existsSync31 } from "fs";
 import { homedir as homedir3 } from "os";
@@ -40539,13 +40643,23 @@ async function evaluateReadiness2(opts) {
   } catch {
     return { ready: false, reason: "db_not_writable" };
   }
+  let warning;
+  const canaryMode = opts.piCanaryMode ?? "off";
+  if (canaryMode !== "off" && opts.piCanaryCheck) {
+    const canaryFailure = await opts.piCanaryCheck();
+    if (canaryFailure) {
+      if (canaryMode === "require")
+        return { ready: false, reason: canaryFailure };
+      warning = canaryFailure;
+    }
+  }
   const userDir = join34(opts.projectDir, ".specialists", "user");
   const userDirResult = await checkUserDirSpecs(userDir);
   if (userDirResult === "empty")
     return { ready: false, reason: "empty_user_dir" };
   if (userDirResult === "invalid")
     return { ready: false, reason: "invalid_spec_in_user_dir" };
-  return { ready: true };
+  return warning ? { ready: true, warning } : { ready: true };
 }
 function parseArgs12(argv) {
   let port = 8000;
@@ -40553,12 +40667,17 @@ function parseArgs12(argv) {
   let queueTimeoutMs = 5000;
   let shutdownGraceMs = 30000;
   let projectDir = process.cwd();
+  let dbPath;
   let fallbackModel;
   let auditFailureThreshold = 5;
   let allowSkills = false;
   let allowSkillsRoots = [];
-  let allowLocalScripts = false;
   let reloadPollMs = 0;
+  let readinessCanaryMode = "off";
+  const readinessRequiredPiFlags = [];
+  let readinessCanarySpecialist;
+  let readinessCanaryTimeoutMs = 5000;
+  let logLevel = "info";
   for (let i = 0;i < argv.length; i++) {
     const token = argv[i];
     if (token === "--port" && argv[i + 1])
@@ -40571,6 +40690,8 @@ function parseArgs12(argv) {
       shutdownGraceMs = Number(argv[++i]);
     else if ((token === "--project-dir" || token === "--user-dir") && argv[i + 1])
       projectDir = argv[++i];
+    else if (token === "--db-path" && argv[i + 1])
+      dbPath = argv[++i];
     else if (token === "--fallback-model" && argv[i + 1])
       fallbackModel = argv[++i];
     else if (token === "--audit-failure-threshold" && argv[i + 1])
@@ -40580,16 +40701,51 @@ function parseArgs12(argv) {
     else if (token === "--allow-skills-roots" && argv[i + 1])
       allowSkillsRoots = argv[++i].split(":").filter(Boolean);
     else if (token === "--allow-local-scripts")
-      allowLocalScripts = true;
+      throw new Error("--allow-local-scripts is not supported for script-class specialists");
     else if (token === "--reload-poll-ms" && argv[i + 1])
       reloadPollMs = Number(argv[++i]);
+    else if (token === "--readiness-canary" && argv[i + 1]) {
+      const mode = argv[++i];
+      if (mode === "off" || mode === "warn" || mode === "require")
+        readinessCanaryMode = mode;
+    } else if (token === "--readiness-required-pi-flag" && argv[i + 1])
+      readinessRequiredPiFlags.push(argv[++i]);
+    else if (token === "--readiness-canary-specialist" && argv[i + 1])
+      readinessCanarySpecialist = argv[++i];
+    else if (token === "--readiness-canary-timeout-ms" && argv[i + 1])
+      readinessCanaryTimeoutMs = Number(argv[++i]);
+    else if (token === "--log-level" && argv[i + 1]) {
+      const value = argv[++i];
+      if (value === "off" || value === "info" || value === "debug")
+        logLevel = value;
+      else
+        throw new Error("--log-level must be one of: off, info, debug");
+    }
   }
-  return { port, concurrency, queueTimeoutMs, shutdownGraceMs, projectDir, fallbackModel, auditFailureThreshold, allowSkills, allowSkillsRoots, allowLocalScripts, reloadPollMs };
+  return { port, concurrency, queueTimeoutMs, shutdownGraceMs, projectDir, dbPath, fallbackModel, auditFailureThreshold, allowSkills, allowSkillsRoots, reloadPollMs, readinessCanaryMode, readinessRequiredPiFlags, readinessCanarySpecialist, readinessCanaryTimeoutMs, logLevel };
+}
+function checkPiHelpForFlags(flags = DEFAULT_REQUIRED_PI_FLAGS) {
+  const result = spawnSync23("pi", ["--help"], { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+  if (result.error || result.status === 127)
+    return "pi_binary_missing";
+  const help = `${result.stdout ?? ""}
+${result.stderr ?? ""}`;
+  const missing = flags.find((flag2) => !help.includes(flag2));
+  return missing ? "pi_flag_missing" : undefined;
 }
 function sendJson(res, statusCode, body) {
   res.writeHead(statusCode, { "content-type": "application/json" });
   res.end(JSON.stringify(body));
 }
+function emitGenerateLog(logLevel, entry) {
+  if (logLevel === "off")
+    return;
+  console.log(JSON.stringify({ level: logLevel, ts: new Date().toISOString(), ...entry }));
+}
+function shortLogError(value, limit = 240) {
+  const message = value instanceof Error ? value.message : String(value);
+  return message.length <= limit ? message : `${message.slice(0, limit)}\u2026`;
+}
 async function readBody(req) {
   const chunks = [];
   for await (const chunk of req)
@@ -40604,7 +40760,7 @@ async function waitForSlot(limit, timeoutMs, getActive) {
   while (getActive() >= limit) {
     if (Date.now() - startedAt >= timeoutMs)
       return false;
-    await new Promise((resolve13) => setTimeout(resolve13, 25));
+    await new Promise((resolve14) => setTimeout(resolve14, 25));
   }
   return true;
 }
@@ -40612,13 +40768,30 @@ async function startServe(argv = process.argv.slice(3)) {
   const args = parseArgs12(argv);
   const loader = new SpecialistLoader({ projectDir: args.projectDir });
   const dbLocation = resolveObservabilityDbLocation(args.projectDir);
-  ensureObservabilityDbFile(dbLocation);
-  const db = createObservabilitySqliteClient(args.projectDir);
+  const dbPath = args.dbPath ?? dbLocation.dbPath;
+  const db = args.dbPath ? createObservabilitySqliteClientAtPath(args.dbPath) : (() => {
+    ensureObservabilityDbFile(dbLocation);
+    return createObservabilitySqliteClient(args.projectDir);
+  })();
   const readinessState = createReadinessState();
   const userDir = join34(args.projectDir, ".specialists", "user");
   const hotReload = createUserDirWatcher({ loader, userDir, pollMs: args.reloadPollMs });
   let active = 0;
   const children = new Set;
+  const piCanaryCheck = async () => {
+    const requiredFlags = args.readinessRequiredPiFlags.length > 0 ? args.readinessRequiredPiFlags : DEFAULT_REQUIRED_PI_FLAGS;
+    const compatibilityFailure = checkPiHelpForFlags(requiredFlags);
+    if (compatibilityFailure)
+      return compatibilityFailure;
+    if (!args.readinessCanarySpecialist)
+      return;
+    const result = await runScriptSpecialist({ specialist: args.readinessCanarySpecialist, trace: false, timeout_ms: args.readinessCanaryTimeoutMs }, {
+      loader,
+      fallbackModel: args.fallbackModel,
+      observabilityDbPath: args.projectDir
+    });
+    return result.success ? undefined : "pi_smoke_failed";
+  };
   const server = createServer(async (req, res) => {
     if (req.url === "/healthz")
       return sendJson(res, 200, { ok: true });
@@ -40626,11 +40799,13 @@ async function startServe(argv = process.argv.slice(3)) {
       const result = await evaluateReadiness2({
         state: readinessState,
         projectDir: args.projectDir,
-        dbPath: dbLocation.dbPath,
-        auditFailureThreshold: args.auditFailureThreshold
+        dbPath,
+        auditFailureThreshold: args.auditFailureThreshold,
+        piCanaryMode: args.readinessCanaryMode,
+        piCanaryCheck
       });
       if (result.ready) {
-        return sendJson(res, 200, { ready: true, db_write_failures_total: readinessState.dbWriteFailuresTotal });
+        return sendJson(res, 200, { ready: true, ...result.warning ? { warning: result.warning } : {}, db_write_failures_total: readinessState.dbWriteFailuresTotal });
       }
       return sendJson(res, 503, {
         ready: false,
@@ -40640,27 +40815,65 @@ async function startServe(argv = process.argv.slice(3)) {
     }
     if (req.method !== "POST" || req.url !== "/v1/generate")
       return sendJson(res, 404, { success: false, error: "not_found", error_type: "internal" });
-    if (readinessState.shuttingDown)
+    const requestStartedAt = Date.now();
+    const method = req.method ?? "POST";
+    const path = req.url ?? "/v1/generate";
+    const requestTraceId = randomUUID3();
+    if (readinessState.shuttingDown) {
+      emitGenerateLog(args.logLevel, {
+        trace_id: requestTraceId,
+        specialist: "unknown",
+        status: "internal",
+        duration_ms: Date.now() - requestStartedAt,
+        prompt_bytes: 0,
+        method,
+        path,
+        error: "shutting_down"
+      });
       return sendJson(res, 503, { success: false, error: "shutting_down", error_type: "internal" });
+    }
     const entered = await waitForSlot(args.concurrency, args.queueTimeoutMs, () => active);
-    if (!entered)
+    if (!entered) {
+      emitGenerateLog(args.logLevel, {
+        trace_id: requestTraceId,
+        specialist: "unknown",
+        status: "quota",
+        duration_ms: Date.now() - requestStartedAt,
+        prompt_bytes: 0,
+        method,
+        path,
+        error: "too_many_requests"
+      });
       return sendJson(res, 429, { success: false, error: "too_many_requests", error_type: "quota" });
+    }
     active++;
     const work = (async () => {
+      let promptBytes = 0;
+      let requestedSpecialist = "unknown";
       try {
         const raw = await readBody(req);
+        promptBytes = Buffer.byteLength(raw, "utf8");
         let parsed;
         try {
           parsed = JSON.parse(raw);
         } catch {
+          const duration_ms2 = Date.now() - requestStartedAt;
+          const trace_id = requestTraceId;
+          emitGenerateLog(args.logLevel, { trace_id, specialist: "unknown", status: "invalid_json", duration_ms: duration_ms2, prompt_bytes: promptBytes, method, path, error: "malformed_request" });
           return sendJson(res, 400, { success: false, error: "malformed_request", error_type: "invalid_json" });
         }
-        if (!isValidRequest(parsed))
+        if (!isValidRequest(parsed)) {
+          const duration_ms2 = Date.now() - requestStartedAt;
+          const trace_id = requestTraceId;
+          emitGenerateLog(args.logLevel, { trace_id, specialist: "unknown", status: "invalid_json", duration_ms: duration_ms2, prompt_bytes: promptBytes, method, path, error: "malformed_request" });
           return sendJson(res, 400, { success: false, error: "malformed_request", error_type: "invalid_json" });
+        }
+        requestedSpecialist = parsed.specialist;
         const result = await runScriptSpecialist(parsed, {
           loader,
+          projectDir: args.projectDir,
           fallbackModel: args.fallbackModel,
-          observabilityDbPath: args.projectDir,
+          ...args.dbPath ? { observabilityDbPath: args.dbPath } : {},
           onChild: (child) => {
             children.add(child);
             child.once("exit", () => children.delete(child));
@@ -40668,11 +40881,37 @@ async function startServe(argv = process.argv.slice(3)) {
           onAuditFailure: () => recordAuditFailure(readinessState),
           trust: {
             allowSkills: args.allowSkills,
-            allowSkillsRoots: args.allowSkillsRoots,
-            allowLocalScripts: args.allowLocalScripts
+            allowSkillsRoots: args.allowSkillsRoots
           }
         });
+        const duration_ms = Date.now() - requestStartedAt;
+        const meta = result.meta ?? {};
+        emitGenerateLog(args.logLevel, {
+          trace_id: meta.trace_id ?? requestTraceId,
+          specialist: meta.specialist ?? (typeof parsed === "object" && parsed !== null ? String(parsed.specialist ?? "unknown") : "unknown"),
+          resolved_specialist: meta.resolved_specialist,
+          model: meta.model,
+          status: result.success ? "success" : result.error_type,
+          duration_ms: meta.duration_ms ?? duration_ms,
+          prompt_bytes: promptBytes,
+          method,
+          path,
+          ...result.success ? {} : { error: shortLogError(result.error) }
+        });
         return sendJson(res, 200, result);
+      } catch (error2) {
+        emitGenerateLog(args.logLevel, {
+          trace_id: requestTraceId,
+          specialist: requestedSpecialist,
+          status: "internal",
+          duration_ms: Date.now() - requestStartedAt,
+          prompt_bytes: promptBytes,
+          method,
+          path,
+          error: shortLogError(error2)
+        });
+        if (!res.headersSent)
+          return sendJson(res, 500, { success: false, error: "internal_error", error_type: "internal" });
       } finally {
         active--;
       }
@@ -40703,7 +40942,7 @@ async function startServe(argv = process.argv.slice(3)) {
 async function run30(argv = process.argv.slice(3)) {
   await startServe(argv);
 }
-var AUDIT_WINDOW_MS = 60000;
+var AUDIT_WINDOW_MS = 60000, DEFAULT_REQUIRED_PI_FLAGS;
 var init_serve = __esm(() => {
   init_loader();
   init_script_runner();
@@ -40711,6 +40950,7 @@ var init_serve = __esm(() => {
   init_observability_db();
   init_schema();
   init_serve_hot_reload();
+  DEFAULT_REQUIRED_PI_FLAGS = ["--mode", "--no-session", "--no-extensions", "--no-tools", "--no-context-files", "--no-skills", "--no-prompt-templates", "--no-themes"];
 });
 
 // src/cli/script.ts
@@ -40721,7 +40961,7 @@ __export(exports_script, {
   parseArgs: () => parseArgs13,
   mapExitCode: () => mapExitCode
 });
-import { spawnSync as spawnSync23 } from "child_process";
+import { spawnSync as spawnSync24 } from "child_process";
 function parseVar(entry) {
   const index = entry.indexOf("=");
   if (index <= 0)
@@ -40824,7 +41064,7 @@ function printResult(result, json) {
   console.error(result.error);
 }
 function runUnderLock(lockPath, argv) {
-  const flock = spawnSync23("flock", ["-n", lockPath, "env", "SP_SCRIPT_NO_LOCK=1", process.execPath, process.argv[1], "script", ...argv], {
+  const flock = spawnSync24("flock", ["-n", lockPath, "env", "SP_SCRIPT_NO_LOCK=1", process.execPath, process.argv[1], "script", ...argv], {
     encoding: "utf-8",
     stdio: "inherit"
   });
@@ -40840,7 +41080,11 @@ async function run31(argv = process.argv.slice(3)) {
     process.exit(runUnderLock(args.singleInstance, argv));
   }
   const loader = new SpecialistLoader({ projectDir: args.projectDir });
-  const result = await runScriptSpecialist(buildRequest(args), { loader, projectDir: args.projectDir, observabilityDbPath: args.dbPath ?? args.projectDir });
+  const result = await runScriptSpecialist(buildRequest(args), {
+    loader,
+    projectDir: args.projectDir,
+    ...args.dbPath ? { observabilityDbPath: args.dbPath } : {}
+  });
   printResult(result, args.json);
   process.exit(mapExitCode(result));
 }
@@ -41013,7 +41257,7 @@ var init_help = __esm(() => {
 });
 
 // src/index.ts
-import { spawnSync as spawnSync24 } from "child_process";
+import { spawnSync as spawnSync25 } from "child_process";
 
 // node_modules/zod/v4/core/core.js
 var NEVER2 = Object.freeze({
@@ -49423,7 +49667,7 @@ async function run33() {
     if (wantsHelp()) {
       console.log([
         "",
-        "Usage: specialists serve [--port <n>] [--concurrency <n>] [--shutdown-grace-ms <n>] [--project-dir <path>]",
+        "Usage: specialists serve [--port <n>] [--concurrency <n>] [--shutdown-grace-ms <n>] [--project-dir <path>] [--db-path <observability.db>] [--readiness-canary off|warn|require] [--log-level off|info|debug]",
         "",
         "HTTP wrapper for script-class specialists.",
         "",
@@ -49459,7 +49703,7 @@ async function run33() {
   }
   if (sub === "release") {
     console.error("Deprecated. Use `xt release prepare/publish`. This alias will be removed in v4.0.");
-    const result = spawnSync24("xt", ["release", ...process.argv.slice(3)], { stdio: "inherit" });
+    const result = spawnSync25("xt", ["release", ...process.argv.slice(3)], { stdio: "inherit" });
     if (result.error) {
       console.error(`Failed to run xt release: ${result.error.message}`);
       process.exit(1);