@jaggerxtrm/specialists 3.10.0 → 3.12.0

package/dist/lib.js

@@ -6906,7 +6906,8 @@ var require_public_api = __commonJS((exports) => {
 
 // src/specialist/script-runner.ts
 import { spawn } from "node:child_process";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
+import { readFileSync as readFileSync2 } from "node:fs";
 
 // src/specialist/templateEngine.ts
 function renderTemplate(template, variables) {
@@ -7044,7 +7045,8 @@ function migrateToV2(db) {
       status_json     TEXT NOT NULL,
       bead_id         TEXT,
       updated_at_ms   INTEGER NOT NULL,
-      last_output     TEXT
+      last_output     TEXT,
+      startup_payload_json TEXT
     );
     INSERT OR IGNORE INTO specialist_jobs_v2
       SELECT
@@ -7054,7 +7056,8 @@ function migrateToV2(db) {
         status_json,
         JSON_EXTRACT(status_json, '$.bead_id'),
         updated_at_ms,
-        last_output
+        last_output,
+        startup_payload_json
       FROM specialist_jobs;
     DROP TABLE IF EXISTS specialist_jobs;
     ALTER TABLE specialist_jobs_v2 RENAME TO specialist_jobs;
@@ -7081,7 +7084,8 @@ function migrateToV3(db) {
       status          TEXT NOT NULL,
       status_json     TEXT NOT NULL,
       updated_at_ms   INTEGER NOT NULL,
-      last_output     TEXT
+      last_output     TEXT,
+      startup_payload_json TEXT
     );
     INSERT OR IGNORE INTO specialist_jobs_v3
       SELECT
@@ -7093,7 +7097,8 @@ function migrateToV3(db) {
         COALESCE(JSON_EXTRACT(status_json, '$.status'), 'starting'),
         status_json,
         updated_at_ms,
-        last_output
+        last_output,
+        startup_payload_json
       FROM specialist_jobs;
     DROP TABLE IF EXISTS specialist_jobs;
     ALTER TABLE specialist_jobs_v3 RENAME TO specialist_jobs;
@@ -7108,6 +7113,15 @@ function migrateToV3(db) {
 function migrateToV11(db) {
   const hasV11 = db.query("SELECT 1 FROM schema_version WHERE version = 11 LIMIT 1").get();
   if (hasV11) {
+    const metricsColumns = new Set(db.query("PRAGMA table_info(specialist_job_metrics)").all().map((column) => column.name).filter((name) => typeof name === "string" && name.length > 0));
+    for (const column of [
+      { name: "active_runtime_ms", definition: "INTEGER" },
+      { name: "waiting_ms", definition: "INTEGER" }
+    ]) {
+      if (!metricsColumns.has(column.name)) {
+        db.run(`ALTER TABLE specialist_job_metrics ADD COLUMN ${column.name} ${column.definition}`);
+      }
+    }
     db.run("CREATE INDEX IF NOT EXISTS idx_job_metrics_spec_model_updated ON specialist_job_metrics(specialist, model, updated_at_ms DESC)");
     db.run("CREATE INDEX IF NOT EXISTS idx_job_metrics_updated ON specialist_job_metrics(updated_at_ms DESC)");
     return;
@@ -7126,6 +7140,8 @@ function migrateToV11(db) {
       started_at_ms INTEGER,
       completed_at_ms INTEGER,
       elapsed_ms INTEGER,
+      active_runtime_ms INTEGER,
+      waiting_ms INTEGER,
       total_turns INTEGER NOT NULL DEFAULT 0,
       total_tools INTEGER NOT NULL DEFAULT 0,
       tool_call_counts_json TEXT NOT NULL,
@@ -7294,7 +7310,8 @@ function initSchema(db) {
     { name: "chain_root_bead_id", definition: "TEXT" },
     { name: "epic_id", definition: "TEXT" },
     { name: "status", definition: "TEXT NOT NULL DEFAULT 'starting'" },
-    { name: "last_output", definition: "TEXT" }
+    { name: "last_output", definition: "TEXT" },
+    { name: "startup_payload_json", definition: "TEXT" }
   ].filter(({ name }) => !specialistJobsColumns.has(name));
   for (const missingColumn of missingSpecialistJobsColumns) {
     db.run(`ALTER TABLE specialist_jobs ADD COLUMN ${missingColumn.name} ${missingColumn.definition}`);
@@ -7316,7 +7333,8 @@ function initSchema(db) {
         status          TEXT NOT NULL,
         status_json     TEXT NOT NULL,
         updated_at_ms   INTEGER NOT NULL,
-        last_output     TEXT
+        last_output     TEXT,
+        startup_payload_json TEXT
       );
       INSERT OR IGNORE INTO specialist_jobs_new
         SELECT
@@ -7333,7 +7351,8 @@ function initSchema(db) {
           COALESCE(status, JSON_EXTRACT(status_json, '$.status'), 'starting'),
           status_json,
           updated_at_ms,
-          last_output
+          last_output,
+          startup_payload_json
         FROM specialist_jobs;
       DROP TABLE IF EXISTS specialist_jobs;
       ALTER TABLE specialist_jobs_new RENAME TO specialist_jobs;
@@ -7456,6 +7475,7 @@ function migrateToV8(db) {
   }
   db.run("CREATE INDEX IF NOT EXISTS idx_jobs_chain ON specialist_jobs(chain_id) WHERE chain_id IS NOT NULL");
   db.run("CREATE INDEX IF NOT EXISTS idx_jobs_epic ON specialist_jobs(epic_id) WHERE epic_id IS NOT NULL");
+  db.run("CREATE UNIQUE INDEX IF NOT EXISTS idx_jobs_active_bead_specialist ON specialist_jobs(bead_id, specialist) WHERE bead_id IS NOT NULL AND status IN ('starting', 'running')");
   db.run(`
     CREATE TABLE IF NOT EXISTS epic_runs (
       epic_id         TEXT PRIMARY KEY,
@@ -7552,6 +7572,37 @@ function migrateToV10(db) {
       VALUES (10, strftime('%s', 'now') * 1000);
   `);
 }
+var STALE_CLAIM_AGE_MS = 60000;
+function defaultIsPidAlive(pid) {
+  if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0)
+    return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function claimJobStartWithStore(store, status, event, options = {}) {
+  const isPidAlive = options.isPidAlive ?? defaultIsPidAlive;
+  const nowMs = options.nowMs ?? Date.now;
+  const staleAgeMs = options.staleClaimAgeMs ?? STALE_CLAIM_AGE_MS;
+  return withRetry(() => store.transaction(() => {
+    const existing = store.findActiveJob(status.bead_id ?? null, status.specialist);
+    if (existing?.job_id && existing.job_id !== status.id) {
+      const updatedAtMs = existing.updated_at_ms ?? 0;
+      const isStale = updatedAtMs > 0 && nowMs() - updatedAtMs > staleAgeMs && !isPidAlive(existing.pid);
+      if (isStale && store.cancelStaleClaim) {
+        store.cancelStaleClaim(existing.job_id);
+      } else {
+        return { ok: false, existingJobId: existing.job_id, existingStatus: existing.status ?? "starting" };
+      }
+    }
+    store.writeStatusRow(status);
+    store.writeEventRow(status.id, status.specialist, status.bead_id, event);
+    return { ok: true };
+  }), "claimJobStart");
+}
 
 class SqliteClient {
   db;
@@ -7566,8 +7617,8 @@ class SqliteClient {
   writeStatusRow(status, lastOutput) {
     const statusJson = JSON.stringify(status);
     this.db.run(`
-      INSERT INTO specialist_jobs (job_id, specialist, worktree_column, bead_id, node_id, chain_kind, chain_id, chain_root_job_id, chain_root_bead_id, epic_id, status, status_json, updated_at_ms, last_output)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      INSERT INTO specialist_jobs (job_id, specialist, worktree_column, bead_id, node_id, chain_kind, chain_id, chain_root_job_id, chain_root_bead_id, epic_id, status, status_json, updated_at_ms, last_output, startup_payload_json)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(job_id) DO UPDATE SET
         specialist = excluded.specialist,
         worktree_column = excluded.worktree_column,
@@ -7581,7 +7632,8 @@ class SqliteClient {
         status = excluded.status,
         status_json = excluded.status_json,
         updated_at_ms = excluded.updated_at_ms,
-        last_output = COALESCE(excluded.last_output, specialist_jobs.last_output);
+        last_output = COALESCE(excluded.last_output, specialist_jobs.last_output),
+        startup_payload_json = COALESCE(excluded.startup_payload_json, specialist_jobs.startup_payload_json);
     `, [
       status.id,
       status.specialist,
@@ -7596,7 +7648,8 @@ class SqliteClient {
       status.status,
       statusJson,
       Date.now(),
-      lastOutput ?? null
+      lastOutput ?? null,
+      status.startup_payload_json ?? null
     ]);
   }
   writeEpicRunRow(epic) {
@@ -7642,6 +7695,36 @@ class SqliteClient {
       VALUES (?, ?, ?, ?, ?, ?, ?)
     `, [jobId, seq, specialist, beadId ?? null, event.t, event.type, eventJson]);
   }
+  claimJobStart(status, event) {
+    return claimJobStartWithStore({
+      transaction: (callback) => this.db.transaction(callback)(),
+      findActiveJob: (beadId, specialist) => this.db.query(`
+          SELECT
+            job_id,
+            status,
+            updated_at_ms,
+            CAST(JSON_EXTRACT(status_json, '$.pid') AS INTEGER) AS pid
+          FROM specialist_jobs
+          WHERE bead_id = ?
+            AND specialist = ?
+            AND status IN ('starting', 'running')
+          ORDER BY updated_at_ms DESC
+          LIMIT 1
+        `).get(beadId, specialist),
+      writeStatusRow: (nextStatus) => this.writeStatusRow(nextStatus),
+      writeEventRow: (jobId, specialist, beadId, nextEvent) => this.writeEventRow(jobId, specialist, beadId, nextEvent),
+      cancelStaleClaim: (jobId) => {
+        const nowMs = Date.now();
+        this.db.run(`
+            UPDATE specialist_jobs
+            SET status = 'cancelled',
+                status_json = JSON_PATCH(status_json, JSON_OBJECT('status', 'cancelled', 'cancelled_reason', 'orphan-claim-stale')),
+                updated_at_ms = ?
+            WHERE job_id = ?
+          `, [nowMs, jobId]);
+      }
+    }, status, event);
+  }
   writeResultRow(jobId, output) {
     this.db.run(`
       INSERT INTO specialist_results (job_id, output, updated_at_ms)
@@ -8102,6 +8185,15 @@ class SqliteClient {
       return statuses;
     }, "listStatuses");
   }
+  removeJobs(jobIds) {
+    return withRetry(() => {
+      if (jobIds.length === 0)
+        return 0;
+      const placeholders = jobIds.map(() => "?").join(", ");
+      const result = this.db.query(`DELETE FROM specialist_jobs WHERE job_id IN (${placeholders})`).run(...jobIds);
+      return result.changes ?? 0;
+    }, "removeJobs");
+  }
   readEpicRun(epicId) {
     return withRetry(() => {
       const row = this.db.query("SELECT epic_id, status, status_json, updated_at_ms FROM epic_runs WHERE epic_id = ? LIMIT 1").get(epicId);
@@ -8131,7 +8223,6 @@ class SqliteClient {
         SELECT chain_id, epic_id, chain_root_bead_id, chain_root_job_id, updated_at_ms
         FROM epic_chain_membership
         WHERE epic_id = ?
-          AND (chain_root_job_id IS NULL OR chain_root_job_id != chain_id)
         ORDER BY updated_at_ms DESC
       `).all(epicId);
     }, "listEpicChains");
@@ -8149,6 +8240,16 @@ class SqliteClient {
       return removable;
     }, "deleteEpicChainMembership");
   }
+  listReferencedChainRootJobIds() {
+    return withRetry(() => {
+      const rows = this.db.query(`
+        SELECT DISTINCT chain_root_job_id
+        FROM epic_chain_membership
+        WHERE chain_root_job_id IS NOT NULL AND chain_root_job_id != ''
+      `).all();
+      return rows.map((row) => row.chain_root_job_id).filter((jobId) => typeof jobId === "string" && jobId.length > 0);
+    }, "listReferencedChainRootJobIds");
+  }
   listEpicChainsWithLatestJob(epicId) {
     return withRetry(() => {
       const rows = this.db.query(`
@@ -8226,6 +8327,18 @@ class SqliteClient {
       return rows.map((row) => row.job_id).filter((jobId) => typeof jobId === "string" && jobId.length > 0);
     }, "listChainJobIds");
   }
+  listLiveJobsForBead(beadId) {
+    return withRetry(() => {
+      const rows = this.db.query(`
+        SELECT job_id
+        FROM specialist_jobs
+        WHERE bead_id = ?
+          AND status IN ('starting', 'running', 'waiting')
+        ORDER BY updated_at_ms ASC
+      `).all(beadId);
+      return rows.map((row) => row.job_id).filter((jobId) => typeof jobId === "string" && jobId.length > 0);
+    }, "listLiveJobsForBead");
+  }
   resolveChainEpicLinkByJobId(jobId) {
     return withRetry(() => {
       const row = this.db.query(`
@@ -8305,7 +8418,7 @@ class SqliteClient {
   aggregateJobMetrics(jobId) {
     return withRetry(() => {
       const jobRow = this.db.query(`
-        SELECT job_id, specialist, status, chain_kind, chain_id, bead_id, node_id, epic_id, updated_at_ms
+        SELECT job_id, specialist, status, chain_kind, chain_id, bead_id, node_id, epic_id, updated_at_ms, startup_payload_json
         FROM specialist_jobs
         WHERE job_id = ?
       `).get(jobId);
@@ -8323,9 +8436,22 @@ class SqliteClient {
       let runCompleteJson = null;
       let model = null;
       let elapsedMs = null;
+      let activeRuntimeMs = 0;
+      let waitingMs = 0;
+      let phase = null;
+      let phaseStartedAtMs = null;
+      const closePhase = (endAtMs) => {
+        if (phase === null || phaseStartedAtMs === null || endAtMs < phaseStartedAtMs)
+          return;
+        const durationMs = endAtMs - phaseStartedAtMs;
+        if (phase === "running") {
+          activeRuntimeMs += durationMs;
+        } else {
+          waitingMs += durationMs;
+        }
+      };
       for (const event of events) {
         startedAtMs = startedAtMs === null ? event.t : Math.min(startedAtMs, event.t);
-        completedAtMs = completedAtMs === null ? event.t : Math.max(completedAtMs, event.t);
         if (event.type === "tool") {
           totalTools += 1;
           toolCallCounts[event.tool] = (toolCallCounts[event.tool] ?? 0) + 1;
@@ -8343,16 +8469,45 @@ class SqliteClient {
           tokenTrajectory.push({ t: event.t, source: event.source, token_usage: event.token_usage });
           continue;
         }
+        if (event.type === "run_start") {
+          phase = "running";
+          phaseStartedAtMs = event.t;
+          continue;
+        }
+        if (event.type === "status_change") {
+          if (event.status === "running" || event.status === "waiting") {
+            closePhase(event.t);
+            phase = event.status;
+            phaseStartedAtMs = event.t;
+            continue;
+          }
+          if (event.status === "done" || event.status === "error" || event.status === "cancelled") {
+            closePhase(event.t);
+            phase = null;
+            phaseStartedAtMs = null;
+          }
+          continue;
+        }
         if (event.type === "run_complete") {
+          closePhase(event.t);
+          completedAtMs = event.t;
           runCompleteJson = JSON.stringify(event);
           model = event.model ?? model;
           elapsedMs = Math.round(event.elapsed_s * 1000);
+          phase = null;
+          phaseStartedAtMs = null;
           continue;
         }
         if (event.type === "stale_warning" && event.reason === "tool_duration") {
           stallGaps.push({ t: event.t, tool: event.tool ?? null, silence_ms: event.silence_ms, threshold_ms: event.threshold_ms });
         }
       }
+      if (startedAtMs !== null && completedAtMs === null) {
+        completedAtMs = events.length > 0 ? events[events.length - 1].t : startedAtMs;
+      }
+      if (elapsedMs === null && startedAtMs !== null && completedAtMs !== null) {
+        elapsedMs = Math.max(0, completedAtMs - startedAtMs);
+      }
       const record = {
         job_id: jobRow.job_id,
         specialist: jobRow.specialist,
@@ -8366,6 +8521,8 @@ class SqliteClient {
         started_at_ms: startedAtMs,
         completed_at_ms: completedAtMs,
         elapsed_ms: elapsedMs,
+        active_runtime_ms: activeRuntimeMs,
+        waiting_ms: waitingMs,
         total_turns: totalTurns,
         total_tools: totalTools,
         tool_call_counts_json: stringifyJson(toolCallCounts),
@@ -8373,15 +8530,16 @@ class SqliteClient {
         context_trajectory_json: stringifyJson(contextTrajectory),
         stall_gaps_json: stringifyJson(stallGaps),
         run_complete_json: runCompleteJson,
+        startup_payload_json: jobRow.startup_payload_json ?? null,
         updated_at_ms: jobRow.updated_at_ms
       };
       this.db.run(`
         INSERT INTO specialist_job_metrics (
           job_id, specialist, model, status, chain_kind, chain_id, bead_id, node_id, epic_id,
-          started_at_ms, completed_at_ms, elapsed_ms, total_turns, total_tools,
+          started_at_ms, completed_at_ms, elapsed_ms, active_runtime_ms, waiting_ms, total_turns, total_tools,
           tool_call_counts_json, token_trajectory_json, context_trajectory_json, stall_gaps_json,
           run_complete_json, updated_at_ms
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
         ON CONFLICT(job_id) DO UPDATE SET
           specialist = excluded.specialist,
           model = excluded.model,
@@ -8394,6 +8552,8 @@ class SqliteClient {
           started_at_ms = excluded.started_at_ms,
           completed_at_ms = excluded.completed_at_ms,
           elapsed_ms = excluded.elapsed_ms,
+          active_runtime_ms = excluded.active_runtime_ms,
+          waiting_ms = excluded.waiting_ms,
           total_turns = excluded.total_turns,
           total_tools = excluded.total_tools,
           tool_call_counts_json = excluded.tool_call_counts_json,
@@ -8415,6 +8575,8 @@ class SqliteClient {
         record.started_at_ms,
         record.completed_at_ms,
         record.elapsed_ms,
+        record.active_runtime_ms,
+        record.waiting_ms,
         record.total_turns,
         record.total_tools,
         record.tool_call_counts_json,
@@ -8447,6 +8609,29 @@ class SqliteClient {
       return this.db.query(`SELECT * FROM specialist_job_metrics ${where} ORDER BY updated_at_ms DESC, job_id DESC`).all(...params);
     }, "listJobMetrics");
   }
+  listElapsedMsBySpecialist(sinceMs, limitPerSpecialist = 200) {
+    return withRetry(() => {
+      const rows = this.db.query(`
+        WITH ranked AS (
+          SELECT specialist, elapsed_ms,
+                 ROW_NUMBER() OVER (PARTITION BY specialist ORDER BY updated_at_ms DESC) AS rn
+          FROM specialist_job_metrics
+          WHERE status = 'completed' AND updated_at_ms >= ? AND elapsed_ms IS NOT NULL
+        )
+        SELECT specialist, elapsed_ms
+        FROM ranked
+        WHERE rn <= ?
+        ORDER BY specialist, rn
+      `).all(sinceMs, limitPerSpecialist);
+      const bySpecialist = {};
+      for (const row of rows) {
+        if (!row.specialist || typeof row.elapsed_ms !== "number" || !Number.isFinite(row.elapsed_ms))
+          continue;
+        (bySpecialist[row.specialist] ??= []).push(row.elapsed_ms);
+      }
+      return bySpecialist;
+    }, "listElapsedMsBySpecialist");
+  }
   readResult(jobId) {
     return withRetry(() => {
       const row = this.db.query("SELECT output FROM specialist_results WHERE job_id = ? LIMIT 1").get(jobId);
@@ -8847,27 +9032,72 @@ function createObservabilitySqliteClient(cwd = process.cwd()) {
 }
 
 // src/specialist/script-runner.ts
-function hasUnsubstitutedVariables(template) {
-  const match = template.match(/\$([a-zA-Z_][a-zA-Z0-9_]*)/);
-  return match?.[1] ?? null;
+class CompatGuardError extends Error {
+  field;
+  constructor(field, message) {
+    super(message);
+    this.field = field;
+    this.name = "CompatGuardError";
+  }
+}
+function hasUnsubstitutedVariables(template, variables) {
+  const matches = template.match(/\$([a-zA-Z_][a-zA-Z0-9_]*)/g) ?? [];
+  for (const match of matches) {
+    const key = match.slice(1);
+    if (variables[key] === undefined)
+      return key;
+  }
+  return null;
 }
-function compatGuard(spec) {
+function compatGuard(spec, trust) {
   const execution = spec.specialist.execution;
   if (execution.interactive)
-    throw new Error("interactive specialists are not allowed");
+    throw new CompatGuardError("execution.interactive", "interactive specialists are not allowed");
   if (execution.requires_worktree)
-    throw new Error("worktree specialists are not allowed");
+    throw new CompatGuardError("execution.requires_worktree", "worktree specialists are not allowed");
   if (execution.permission_required !== "READ_ONLY")
-    throw new Error("permission_required must be READ_ONLY");
-  if ((spec.specialist.skills?.scripts?.length ?? 0) > 0)
-    throw new Error("scripts not allowed");
+    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)");
+  }
+  const hasPaths = (spec.specialist.skills?.paths?.length ?? 0) > 0;
+  const hasSkillInherit = Boolean(spec.specialist.prompt.skill_inherit);
+  if (hasPaths && !trust?.allowSkills) {
+    throw new CompatGuardError("skills.paths", "skills not allowed (enable with --allow-skills)");
+  }
+  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) {
+    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`);
+      }
+    }
+  }
+}
+function computeSkillSources(spec) {
+  const paths = spec.specialist.skills?.paths ?? [];
+  const sources = [];
+  for (const path of paths) {
+    try {
+      const content = readFileSync2(path);
+      const sha256 = createHash("sha256").update(content).digest("hex");
+      sources.push({ path, sha256 });
+    } catch {
+      sources.push({ path, sha256: "unreadable" });
+    }
+  }
+  return sources;
 }
 function renderTaskTemplate(template, variables) {
-  const output = renderTemplate(template, variables);
-  const missing = hasUnsubstitutedVariables(output);
+  const missing = hasUnsubstitutedVariables(template, variables);
   if (missing)
     throw new Error(`Missing template variable: ${missing}`);
-  return output;
+  return renderTemplate(template, variables);
 }
 function mapErrorType(message) {
   if (message.includes("Specialist not found"))
@@ -8897,59 +9127,32 @@ function textFromMessage(message) {
     return "";
   return message.content.filter((part) => part.type === "text" && typeof part.text === "string").map((part) => part.text).join("");
 }
-function extractAssistantText(lines) {
-  for (let i = lines.length - 1;i >= 0; i--) {
-    const line = lines[i].trim();
-    if (!line)
-      continue;
-    let event;
-    try {
-      event = JSON.parse(line);
-    } catch {
-      continue;
-    }
-    if (event.type === "message_end") {
-      const text = textFromMessage(event.message);
+function extractAssistantTextFromEvent(event) {
+  if (event.type === "message_end") {
+    const text = textFromMessage(event.message);
+    if (text)
+      return text;
+  }
+  if (event.type === "agent_end" && Array.isArray(event.messages)) {
+    for (let j = event.messages.length - 1;j >= 0; j--) {
+      const text = textFromMessage(event.messages[j]);
       if (text)
         return text;
     }
-    if (event.type === "agent_end" && Array.isArray(event.messages)) {
-      for (let j = event.messages.length - 1;j >= 0; j--) {
-        const text = textFromMessage(event.messages[j]);
-        if (text)
-          return text;
-      }
-    }
-    if (event.type === "assistant" && typeof event.data?.text === "string")
-      return event.data.text;
-    const legacyContent = event.data?.content?.[0]?.text;
-    if (typeof legacyContent === "string")
-      return legacyContent;
   }
-  return "";
+  if (event.type === "assistant" && typeof event.data?.text === "string")
+    return event.data.text;
+  const legacyContent = event.data?.content?.[0]?.text;
+  if (typeof legacyContent === "string")
+    return legacyContent;
+  return;
 }
 function stripMarkdownFences(text) {
   const trimmed = text.trim();
   const fenced = trimmed.match(/^```(?:json|JSON)?\s*\n?([\s\S]*?)\n?```\s*$/);
   return fenced ? fenced[1].trim() : trimmed;
 }
-function extractPiErrorMessage(lines) {
-  for (let i = lines.length - 1;i >= 0; i--) {
-    const line = lines[i].trim();
-    if (!line)
-      continue;
-    try {
-      const event = JSON.parse(line);
-      const errMsg = event.message?.errorMessage;
-      if (typeof errMsg === "string" && errMsg.length > 0)
-        return errMsg;
-    } catch {
-      continue;
-    }
-  }
-  return null;
-}
-function writeTraceRow(client, specialist, model, traceId, output, durationMs) {
+function writeTraceRow(client, specialist, model, traceId, output, durationMs, skillSources, onAuditFailure) {
   if (!client)
     return;
   const status = {
@@ -8960,106 +9163,231 @@ function writeTraceRow(client, specialist, model, traceId, output, durationMs) {
     started_at_ms: Date.now() - durationMs,
     elapsed_s: durationMs / 1000,
     last_event_at_ms: Date.now(),
-    surface: "script_specialist"
+    surface: "script_specialist",
+    ...skillSources && skillSources.length > 0 ? { skill_sources: skillSources } : {}
   };
-  client.upsertStatus(status);
-  client.upsertResult(traceId, output);
+  try {
+    client.upsertStatus(status);
+    client.upsertResult(traceId, output);
+  } catch (error) {
+    onAuditFailure?.(error);
+  }
+}
+var DEFAULT_PENDING_LINE_LIMIT_BYTES = 16 * 1024 * 1024;
+var DEFAULT_ASSISTANT_TEXT_LIMIT_BYTES = 4 * 1024 * 1024;
+var DEFAULT_STDERR_LIMIT_BYTES = 1 * 1024 * 1024;
+function resolveAssistantTextLimitBytes(spec) {
+  return spec.specialist.execution.stdout_limit_bytes ?? resolveEnvAssistantTextLimitBytes() ?? DEFAULT_ASSISTANT_TEXT_LIMIT_BYTES;
+}
+function resolveEnvAssistantTextLimitBytes() {
+  const raw = process.env.SPECIALISTS_SCRIPT_STDOUT_LIMIT_BYTES;
+  if (raw === undefined)
+    return;
+  const envLimit = Number(raw);
+  if (!Number.isFinite(envLimit) || envLimit <= 0)
+    return;
+  process.stderr.write(`warning: SPECIALISTS_SCRIPT_STDOUT_LIMIT_BYTES is deprecated; applies to assistant text cap
+`);
+  return Math.floor(envLimit);
 }
 function openObservabilityClient(options) {
   const dbPath = options.observabilityDbPath ?? options.projectDir;
   return createObservabilitySqliteClient(dbPath);
 }
+function resolveScriptSpecialistName(name) {
+  if (name === "changelog-keeper")
+    return "changelog-drafter";
+  return name;
+}
 async function runScriptSpecialist(input, options) {
   const traceId = randomUUID();
   const startedAt = Date.now();
   try {
-    const spec = await options.loader.get(input.specialist);
-    compatGuard(spec);
+    const resolvedSpecialist = resolveScriptSpecialistName(input.specialist);
+    const spec = await options.loader.get(resolvedSpecialist);
+    compatGuard(spec, options.trust);
+    const skillSources = options.trust?.allowSkills ? computeSkillSources(spec) : undefined;
     const template = input.template ?? spec.specialist.prompt.task_template;
     const prompt = renderTaskTemplate(template, input.variables ?? {});
-    const model = input.model_override ?? spec.specialist.execution.model ?? options.fallbackModel ?? "unknown";
+    if (process.env.SPECIALISTS_SCRIPT_STUB_OUTPUT) {
+      return {
+        success: true,
+        output: prompt,
+        meta: {
+          specialist: resolvedSpecialist,
+          requested_specialist: input.requested_specialist ?? input.specialist,
+          resolved_specialist: resolvedSpecialist,
+          model: "stub",
+          duration_ms: Date.now() - startedAt,
+          trace_id: traceId
+        }
+      };
+    }
     const timeoutMs = input.timeout_ms ?? spec.specialist.execution.timeout_ms ?? 120000;
+    const modelCandidates = collectModelCandidates(input, spec, options);
+    const assistantTextLimitBytes = resolveAssistantTextLimitBytes(spec);
+    const attempts = [];
+    for (const model of modelCandidates) {
+      const attempt = await runSingleAttempt(prompt, model, input.thinking_level ?? spec.specialist.execution.thinking_level, timeoutMs, assistantTextLimitBytes, options);
+      attempts.push(attempt);
+      const parsed = classifyAttempt(attempt);
+      if (parsed.retryable)
+        continue;
+      const durationMs2 = Date.now() - startedAt;
+      const observability2 = openObservabilityClient(options);
+      if (input.trace !== false && observability2)
+        writeTraceRow(observability2, resolvedSpecialist, model, traceId, parsed.text, durationMs2, skillSources, options.onAuditFailure);
+      if (parsed.kind === "success") {
+        let parsed_json;
+        if (spec.specialist.execution.response_format === "json") {
+          try {
+            parsed_json = JSON.parse(stripMarkdownFences(parsed.text));
+            const required = Array.isArray(spec.specialist.prompt.output_schema?.required) ? spec.specialist.prompt.output_schema.required.filter((value) => typeof value === "string") : [];
+            for (const key of required) {
+              if (parsed_json === null || typeof parsed_json !== "object" || !(key in parsed_json))
+                throw new Error(`Missing required output field: ${key}`);
+            }
+          } catch (error) {
+            return { success: false, error: error instanceof Error ? error.message : String(error), error_type: "invalid_json", meta: { specialist: resolvedSpecialist, requested_specialist: input.requested_specialist ?? input.specialist, resolved_specialist: resolvedSpecialist, model, duration_ms: durationMs2, trace_id: traceId } };
+          }
+        }
+        return { success: true, output: parsed.text, parsed_json, meta: { specialist: resolvedSpecialist, requested_specialist: input.requested_specialist ?? input.specialist, resolved_specialist: resolvedSpecialist, model, duration_ms: durationMs2, trace_id: traceId } };
+      }
+      return { success: false, error: parsed.error, error_type: parsed.errorType, meta: { specialist: resolvedSpecialist, requested_specialist: input.requested_specialist ?? input.specialist, resolved_specialist: resolvedSpecialist, model, duration_ms: durationMs2, trace_id: traceId } };
+    }
+    const lastAttempt = attempts.at(-1);
+    const durationMs = Date.now() - startedAt;
+    const observability = openObservabilityClient(options);
+    if (input.trace !== false && observability)
+      writeTraceRow(observability, resolvedSpecialist, modelCandidates.at(-1) ?? "unknown", traceId, lastAttempt?.text ?? "", durationMs, skillSources, options.onAuditFailure);
+    return { success: false, error: lastAttempt?.stderr || "pi produced no assistant text", error_type: "internal", meta: { specialist: resolvedSpecialist, requested_specialist: input.requested_specialist ?? input.specialist, resolved_specialist: resolvedSpecialist, model: modelCandidates.at(-1) ?? "unknown", duration_ms: durationMs, trace_id: traceId } };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const resolvedSpecialist = resolveScriptSpecialistName(input.specialist);
+    return { success: false, error: message, error_type: mapErrorType(message), meta: { specialist: resolvedSpecialist, requested_specialist: input.requested_specialist ?? input.specialist, resolved_specialist: resolvedSpecialist, duration_ms: Date.now() - startedAt, trace_id: traceId } };
+  }
+}
+function collectModelCandidates(input, spec, options) {
+  const candidates = [input.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((resolve, reject) => {
     const args = ["--mode", "json", "--no-session", "--no-extensions", "--no-tools", "--model", model];
-    const thinkingLevel = input.thinking_level ?? spec.specialist.execution.thinking_level;
     if (thinkingLevel)
       args.push("--thinking", thinkingLevel);
     args.push(prompt);
     const pi = spawn("pi", args, { stdio: ["ignore", "pipe", "pipe"] });
     options.onChild?.(pi);
-    const chunks = [];
     let stderr = "";
     let timedOut = false;
     let outputTooLarge = false;
-    const stdoutLimit = 4 * 1024 * 1024;
-    let stdoutBytes = 0;
+    let outputTooLargeReason;
+    let pending = "";
+    let assistantText = "";
+    let pendingBytes = 0;
+    let stderrBytes = 0;
     const timer = setTimeout(() => {
       timedOut = true;
       pi.kill("SIGTERM");
       setTimeout(() => pi.kill("SIGKILL"), 2000);
     }, timeoutMs);
     pi.stdout.on("data", (chunk) => {
+      if (outputTooLarge)
+        return;
       const buffer = Buffer.from(chunk);
-      chunks.push(buffer);
-      stdoutBytes += buffer.length;
-      if (stdoutBytes > stdoutLimit && !outputTooLarge) {
+      pending += buffer.toString("utf-8");
+      pendingBytes += buffer.length;
+      if (pendingBytes > DEFAULT_PENDING_LINE_LIMIT_BYTES) {
         outputTooLarge = true;
+        outputTooLargeReason = "malformed_line_too_large";
         pi.kill("SIGTERM");
         setTimeout(() => pi.kill("SIGKILL"), 2000);
+        return;
       }
-    });
-    pi.stderr.on("data", (chunk) => {
-      stderr += String(chunk);
-    });
-    const exitCode = await new Promise((resolve, reject) => {
-      pi.on("error", reject);
-      pi.on("close", (code) => resolve(code ?? 0));
-    }).finally(() => clearTimeout(timer));
-    const stdout = Buffer.concat(chunks).toString("utf-8");
-    const text = extractAssistantText(stdout.split(/\r?\n/));
-    const durationMs = Date.now() - startedAt;
-    const observability = openObservabilityClient(options);
-    if (input.trace !== false && observability)
-      writeTraceRow(observability, input.specialist, model, traceId, text, durationMs);
-    if (outputTooLarge) {
-      return { success: false, error: "stdout exceeded 4MB cap", error_type: "output_too_large", meta: { specialist: input.specialist, model, duration_ms: durationMs, trace_id: traceId } };
-    }
-    if (timedOut) {
-      return { success: false, error: stderr || "timed out", error_type: "timeout", meta: { specialist: input.specialist, model, duration_ms: durationMs, trace_id: traceId } };
-    }
-    if (exitCode !== 0) {
-      return { success: false, error: stderr || `pi exit ${exitCode}`, error_type: mapErrorType(stderr), meta: { specialist: input.specialist, model, duration_ms: durationMs, trace_id: traceId } };
-    }
-    if (!text) {
-      const piError = extractPiErrorMessage(stdout.split(/\r?\n/));
-      if (piError) {
-        return { success: false, error: piError, error_type: mapErrorType(piError), meta: { specialist: input.specialist, model, duration_ms: durationMs, trace_id: traceId } };
-      }
-      return { success: false, error: "pi produced no assistant text", error_type: "internal", meta: { specialist: input.specialist, model, duration_ms: durationMs, trace_id: traceId } };
-    }
-    let parsed_json;
-    if (spec.specialist.execution.response_format === "json") {
-      try {
-        parsed_json = JSON.parse(stripMarkdownFences(text));
-        const required = Array.isArray(spec.specialist.prompt.output_schema?.required) ? spec.specialist.prompt.output_schema.required.filter((value) => typeof value === "string") : [];
-        for (const key of required) {
-          if (parsed_json === null || typeof parsed_json !== "object" || !(key in parsed_json)) {
-            throw new Error(`Missing required output field: ${key}`);
+      const lines = pending.split(/\r?\n/);
+      pending = lines.pop() ?? "";
+      pendingBytes = Buffer.byteLength(pending);
+      for (const rawLine of lines) {
+        const line = rawLine.trim();
+        if (!line)
+          continue;
+        try {
+          const event = JSON.parse(line);
+          const nextAssistantText = extractAssistantTextFromEvent(event);
+          if (nextAssistantText !== undefined) {
+            if (Buffer.byteLength(nextAssistantText, "utf8") > assistantTextLimitBytes) {
+              outputTooLarge = true;
+              outputTooLargeReason = "assistant_text_too_large";
+              pi.kill("SIGTERM");
+              setTimeout(() => pi.kill("SIGKILL"), 2000);
+              return;
+            }
+            assistantText = nextAssistantText;
           }
+        } catch {
+          continue;
         }
-      } catch (error) {
-        return { success: false, error: error instanceof Error ? error.message : String(error), error_type: "invalid_json", meta: { specialist: input.specialist, model, duration_ms: durationMs, trace_id: traceId } };
       }
-    }
-    return { success: true, output: text, parsed_json, meta: { specialist: input.specialist, model, duration_ms: durationMs, trace_id: traceId } };
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return { success: false, error: message, error_type: mapErrorType(message), meta: { specialist: input.specialist, duration_ms: Date.now() - startedAt, trace_id: traceId } };
-  }
+    });
+    pi.stderr.on("data", (chunk) => {
+      if (outputTooLarge)
+        return;
+      const text = String(chunk);
+      stderr += text;
+      stderrBytes += Buffer.byteLength(text, "utf8");
+      if (stderrBytes > DEFAULT_STDERR_LIMIT_BYTES) {
+        outputTooLarge = true;
+        outputTooLargeReason = "stderr_too_large";
+        stderr = stderr.slice(0, DEFAULT_STDERR_LIMIT_BYTES);
+        pi.kill("SIGTERM");
+        setTimeout(() => pi.kill("SIGKILL"), 2000);
+      }
+    });
+    pi.on("error", reject);
+    pi.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({
+        model,
+        text: assistantText,
+        stderr,
+        exitCode: code ?? 0,
+        timedOut,
+        outputTooLarge,
+        outputTooLargeReason
+      });
+    });
+  });
+}
+function classifyAttempt(attempt) {
+  if (attempt.outputTooLarge) {
+    if (attempt.outputTooLargeReason === "assistant_text_too_large")
+      return { retryable: false, kind: "failure", error: "assistant message too large", errorType: "output_too_large", text: attempt.text };
+    if (attempt.outputTooLargeReason === "stderr_too_large")
+      return { retryable: false, kind: "failure", error: "stderr too large", errorType: "output_too_large", text: attempt.text };
+    if (attempt.outputTooLargeReason === "malformed_line_too_large")
+      return { retryable: false, kind: "failure", error: "malformed line too large", errorType: "output_too_large", text: attempt.text };
+    return { retryable: false, kind: "failure", error: "output exceeded cap", errorType: "output_too_large", text: attempt.text };
+  }
+  if (attempt.timedOut)
+    return { retryable: false, kind: "failure", error: attempt.stderr || "timed out", errorType: "timeout", text: attempt.text };
+  const retryable = isRetryableModelFailure(attempt.stderr, attempt.text);
+  if (attempt.exitCode !== 0) {
+    const errorType = mapErrorType(attempt.stderr);
+    return { retryable, kind: "failure", error: attempt.stderr || `pi exit ${attempt.exitCode}`, errorType, text: attempt.text };
+  }
+  if (!attempt.text) {
+    return { retryable, kind: "failure", error: attempt.stderr || "pi produced no assistant text", errorType: mapErrorType(attempt.stderr), text: attempt.text };
+  }
+  return { retryable: false, kind: "success", error: "", errorType: "internal", text: attempt.text };
+}
+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();
 }
 // src/specialist/loader.ts
 import { readdir, readFile, stat } from "node:fs/promises";
 import { basename, join as join2 } from "node:path";
-import { existsSync as existsSync2 } from "node:fs";
+import { existsSync as existsSync3 } from "node:fs";
 
 // node_modules/yaml/dist/index.js
 var composer = require_composer();
@@ -12937,6 +13265,7 @@ var ExecutionSchema = objectType({
   stall_timeout_ms: numberType().optional(),
   max_retries: numberType().int().min(0).default(0),
   interactive: booleanType().default(false),
+  stdout_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"),
@@ -13087,6 +13416,20 @@ ${result.warnings.map((w) => `  ⚠ ${w}`).join(`
   return SpecialistSchema.parseAsync(raw);
 }
 
+// src/specialist/canonical-asset-resolver.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { fileURLToPath } from "node:url";
+function resolveCanonicalAssetDir(relativePath) {
+  const configPath = `config/${relativePath}`;
+  let resolved = fileURLToPath(new URL(`../${configPath}`, import.meta.url));
+  if (existsSync2(resolved))
+    return resolved;
+  resolved = fileURLToPath(new URL(`../../${configPath}`, import.meta.url));
+  if (existsSync2(resolved))
+    return resolved;
+  return null;
+}
+
 // src/specialist/loader.ts
 class SpecialistLoader {
   cache = new Map;
@@ -13101,11 +13444,12 @@ class SpecialistLoader {
       { path: join2(this.projectDir, ".specialists", "default"), scope: "default", source: "default-mirror" },
       { path: join2(this.projectDir, ".specialists", "default", "specialists"), scope: "default", source: "legacy" },
       { path: join2(this.projectDir, "config", "specialists"), scope: "package", source: "package-fallback" },
+      { path: resolveCanonicalAssetDir("specialists") ?? "", scope: "package", source: "package-live" },
       { path: join2(this.projectDir, "specialists"), scope: "default", source: "legacy" },
       { path: join2(this.projectDir, ".claude", "specialists"), scope: "default", source: "legacy" },
       { path: join2(this.projectDir, ".agent-forge", "specialists"), scope: "default", source: "legacy" }
     ];
-    return dirs.filter((d) => existsSync2(d.path));
+    return dirs.filter((d) => d.path && existsSync3(d.path));
   }
   toJson(content, isYaml) {
     if (!isYaml)
@@ -13114,11 +13458,11 @@ class SpecialistLoader {
   }
   resolveSpecialistPath(dirPath, specialistName) {
     const jsonPath = join2(dirPath, `${specialistName}.specialist.json`);
-    if (existsSync2(jsonPath)) {
+    if (existsSync3(jsonPath)) {
       return { filePath: jsonPath, deprecatedYaml: false };
     }
     const yamlPath = join2(dirPath, `${specialistName}.specialist.yaml`);
-    if (existsSync2(yamlPath)) {
+    if (existsSync3(yamlPath)) {
       return { filePath: yamlPath, deprecatedYaml: true };
     }
     return null;
@@ -13159,6 +13503,7 @@ class SpecialistLoader {
             thinking_level: spec.specialist.execution.thinking_level,
             skills: spec.specialist.skills?.paths ?? [],
             scripts: spec.specialist.skills?.scripts ?? [],
+            mandatoryRuleTemplateSets: spec.specialist.mandatory_rules?.template_sets ?? [],
             scope: dir.scope,
             source: dir.source,
             filePath: resolved.filePath,