@agentskit/harness 0.10.0 → 0.11.0

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { createHash, randomUUID, createPrivateKey, createPublicKey, sign, verify } from 'crypto';
-import { readFileSync, mkdirSync, existsSync, unlinkSync, openSync, writeFileSync, closeSync, readdirSync, writeSync, appendFileSync, mkdtempSync, renameSync, rmSync, statSync } from 'fs';
-import { Command } from 'commander';
+import { readFileSync, mkdirSync, existsSync, unlinkSync, openSync, writeFileSync, closeSync, readdirSync, statSync, writeSync, appendFileSync, mkdtempSync, renameSync, rmSync } from 'fs';
 import { resolve, dirname, relative, basename, join, extname, isAbsolute, delimiter, sep } from 'path';
+import { Command } from 'commander';
 import { execFile, spawn, execFileSync } from 'child_process';
 import { promisify } from 'util';
 import { tmpdir, totalmem, release, freemem, cpus, loadavg } from 'os';
@@ -921,11 +921,34 @@ var cleanTaskArtifacts = (configPath) => cleanConfiguredArtifacts(loadConfig(con
 var index = (root, indexPath) => JSON.parse(readFileSync(resolve(root, indexPath), "utf8"));
 var text = (entry) => [entry.id, entry.type, entry.title, entry.path, entry.description, entry.body, ...Array.isArray(entry.tags) ? entry.tags : []].filter((value) => typeof value === "string").join(" ").toLowerCase();
 var sourceHash = (document) => typeof document.contentHash === "string" && document.contentHash.length > 0 ? document.contentHash : hashJson(document);
+var tokenSeparator = /[^\p{L}\p{N}@/_-]+/gu;
+var tokenize = (value) => value.toLowerCase().split(tokenSeparator).filter((token) => token.length >= 2);
+var containsToken = (value, token) => {
+  if (/[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]/u.test(token)) return value.includes(token);
+  const escaped = token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(?:^|[^\\p{L}\\p{N}])${escaped}(?:s|es)?(?:[^\\p{L}\\p{N}]|$)`, "u").test(value);
+};
+var score = (value, query) => tokenize(query).reduce((total, token) => total + (containsToken(value, token) ? token.length : 0), 0);
 var matches = (entry, query) => {
-  const needle = query.query.trim().toLowerCase();
-  const scopes = query.scope?.map((scope) => scope.toLowerCase()) ?? [];
+  const needle = query.query.trim();
+  if (!needle) return 0;
   const value = text(entry);
-  return Boolean(needle && value.includes(needle) && (scopes.length === 0 || scopes.some((scope) => value.includes(scope))));
+  if (query.scope?.length && !query.scope.some((scope) => containsToken(value, scope.toLowerCase()))) return 0;
+  return score(value, needle);
+};
+var ownershipEntries = (document) => {
+  if (typeof document.lookup !== "object" || document.lookup === null || Array.isArray(document.lookup)) return [];
+  const ownership = document.lookup.ownership;
+  if (typeof ownership !== "object" || ownership === null || Array.isArray(ownership)) return [];
+  return Object.entries(ownership).flatMap(([id2, value]) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) return [];
+    const owner = value;
+    const path = typeof owner["agentDoc"] === "string" ? owner["agentDoc"] : owner["path"];
+    if (!path) return [];
+    const description = typeof owner["purpose"] === "string" ? owner["purpose"] : void 0;
+    const body2 = [owner["purpose"], owner["group"], owner["layer"], owner["agentDoc"], owner["humanDoc"]].filter((item) => typeof item === "string").join(" ");
+    return [{ id: typeof owner["id"] === "string" ? owner["id"] : id2, type: "ownership", path, ...description ? { description } : {}, ...body2 ? { body: body2 } : {} }];
+  });
 };
 var inspectDocBridgeIndex = (root, indexPath = ".doc-bridge/index.json", now4 = Date.now()) => {
   const path = resolve(root, indexPath);
@@ -940,15 +963,30 @@ var inspectDocBridgeIndex = (root, indexPath = ".doc-bridge/index.json", now4 =
     return { present: true, path, contentHash: null, mtimeMs: null, ageHours: null, error: error instanceof Error ? error.message : String(error) };
   }
 };
-var createDocBridgeContextProvider = ({ root, indexPath = ".doc-bridge/index.json" }) => ({
+var createDocBridgeContextProvider = ({ root, indexPath = ".doc-bridge/index.json", maxAgeHours, now: now4 = Date.now }) => ({
   id: "doc-bridge",
-  version: "1.0.0",
+  version: "1.1.0",
   resolve: async (query) => {
     const started = Date.now();
+    const ageBudget = maxAgeHours ?? 0;
+    const inspection = ageBudget > 0 ? inspectDocBridgeIndex(root, indexPath, now4()) : null;
+    if (inspection?.error) throw new Error(`Doc Bridge index is unreadable: ${inspection.error}`);
+    if (inspection?.ageHours !== null && inspection?.ageHours !== void 0 && inspection.ageHours > ageBudget) {
+      throw new Error(`Doc Bridge index is ${inspection.ageHours.toFixed(1)}h old; refresh it before resolving context.`);
+    }
     const document = index(root, indexPath);
     const contentHash = sourceHash(document);
-    const entries = Array.isArray(document.knowledge) ? document.knowledge.filter((value) => typeof value === "object" && value !== null && !Array.isArray(value)).filter((entry) => matches(entry, query)).sort((left, right) => String(left.id ?? "").localeCompare(String(right.id ?? ""))).slice(0, 8) : [];
-    const references = entries.flatMap((entry) => typeof entry.id === "string" && typeof entry.path === "string" ? [{ id: entry.id, uri: `doc-bridge://${entry.path}`, ...typeof entry.title === "string" ? { title: entry.title } : {}, contentHash: typeof entry.contentHash === "string" ? entry.contentHash : contentHash, relevance: 1 }] : []);
+    const knowledge = Array.isArray(document.knowledge) ? document.knowledge.filter((value) => typeof value === "object" && value !== null && !Array.isArray(value)) : [];
+    const ranked = [...knowledge, ...ownershipEntries(document)].map((entry) => ({ entry, score: matches(entry, query) })).filter(({ score: entryScore }) => entryScore > 0);
+    const byPath = /* @__PURE__ */ new Map();
+    for (const candidate of ranked) {
+      const path = typeof candidate.entry.path === "string" ? candidate.entry.path : String(candidate.entry.id ?? "");
+      const current = byPath.get(path);
+      if (!current || candidate.score > current.score || candidate.score === current.score && candidate.entry.type === "ownership" && current.entry.type !== "ownership") byPath.set(path, candidate);
+    }
+    const entries = [...byPath.values()].sort((left, right) => right.score - left.score || String(left.entry.id ?? "").localeCompare(String(right.entry.id ?? ""))).slice(0, 8);
+    const maxScore = entries[0]?.score ?? 1;
+    const references = entries.flatMap(({ entry, score: entryScore }) => typeof entry.id === "string" && typeof entry.path === "string" ? [{ id: entry.id, uri: `doc-bridge://${entry.path}`, ...typeof entry.title === "string" ? { title: entry.title } : {}, contentHash: typeof entry.contentHash === "string" ? entry.contentHash : contentHash, relevance: entryScore / maxScore }] : []);
     const telemetry = { status: "measured", durationMs: Date.now() - started, contextReferences: references.length, contextCostTokens: Math.max(1, Math.ceil(JSON.stringify(references).length / 4)) };
     return { providerId: "doc-bridge", query, references, sourceHash: contentHash, snapshotHash: hashContextSnapshot({ providerId: "doc-bridge", query, references, sourceHash: contentHash }), resolvedAt: (/* @__PURE__ */ new Date()).toISOString(), assurance: "contract-tested", telemetry };
   }
@@ -1543,6 +1581,14 @@ var createKvMemoryAdapter = (store, options2 = {}) => {
     const scopeMatch = record3.scope === "global" || (record3.scope === "issue" ? Boolean(issueId && record3.source.includes(issueId)) : Boolean(project && record3.source.includes(project)));
     return scopeMatch && (!query || `${record3.summary} ${record3.source}`.toLowerCase().includes(query));
   };
+  let allRecordsCache = null;
+  const allRecords = async () => {
+    if (allRecordsCache) return allRecordsCache;
+    const ids = await store.get(indexKey);
+    const records = Array.isArray(ids) ? await Promise.all(ids.filter((id2) => typeof id2 === "string").map((id2) => store.get(`agentskit-harness:memory:${id2}`))) : [];
+    allRecordsCache = records.filter((record3) => Boolean(record3 && typeof record3 === "object" && record3.approved === true));
+    return allRecordsCache;
+  };
   return {
     id: options2.id ?? "agentskit-kv",
     version: options2.version ?? "1",
@@ -1554,13 +1600,13 @@ var createKvMemoryAdapter = (store, options2 = {}) => {
       const index2 = Array.isArray(ids) ? ids.filter((id2) => typeof id2 === "string") : [];
       if (!index2.includes(valid.id)) await store.set(indexKey, [...index2, valid.id].sort());
       await store.set(`agentskit-harness:memory:${valid.id}`, valid);
+      allRecordsCache = null;
       writes += 1;
     },
     async recall({ query, issueId, project, sourceRevision }) {
       reads += 1;
-      const ids = await store.get(indexKey);
-      const records = Array.isArray(ids) ? await Promise.all(ids.filter((id2) => typeof id2 === "string").map((id2) => store.get(`agentskit-harness:memory:${id2}`))) : [];
-      const hits = records.filter((record3) => Boolean(record3 && typeof record3 === "object" && record3.approved === true)).filter((record3) => matches2(record3, query.trim().toLowerCase(), issueId, project)).map((record3) => ({ record: record3, relevant: true, stale: sourceRevision !== void 0 && record3.sourceRevision !== sourceRevision }));
+      const records = await allRecords();
+      const hits = records.filter((record3) => matches2(record3, query.trim().toLowerCase(), issueId, project)).map((record3) => ({ record: record3, relevant: true, stale: sourceRevision !== void 0 && record3.sourceRevision !== sourceRevision }));
       relevantHits += hits.length;
       staleHits += hits.filter((hit) => hit.stale).length;
       return hits;
@@ -2514,10 +2560,16 @@ var orcaTerminalCreate = async (runner, input, options2 = {}) => {
 };
 var parseOrcaSendReceipt = (result) => {
   const record3 = isRecord7(result) ? result : {};
-  const receipt = isRecord7(record3["receipt"]) ? record3["receipt"] : record3;
-  const stages = Array.isArray(receipt["stages"]) ? receipt["stages"].map((stage) => isRecord7(stage) ? str(stage["stage"], str(stage["name"])) : str(stage)).filter(Boolean) : [];
-  const accepted = receipt["accepted"] === false ? false : receipt["accepted"] === true || stages.includes("input_accepted") || (result === null || result === void 0 || Object.keys(record3).length === 0);
-  return { accepted, requestId: str(receipt["requestId"], str(record3["requestId"])) || null, stages, warnings: Array.isArray(record3["warnings"]) ? record3["warnings"].map((warning) => isRecord7(warning) ? str(warning["message"], JSON.stringify(warning)) : str(warning)) : [] };
+  const send = isRecord7(record3["send"]) ? record3["send"] : null;
+  const prompt = send && isRecord7(send["prompt"]) ? send["prompt"] : null;
+  const receipt = isRecord7(record3["receipt"]) ? record3["receipt"] : send ?? record3;
+  const rawStages = Array.isArray(receipt["stages"]) ? receipt["stages"] : prompt && Array.isArray(prompt["stages"]) ? prompt["stages"] : [];
+  const stages = rawStages.map((stage) => isRecord7(stage) ? str(stage["stage"], str(stage["name"])) : str(stage)).filter(Boolean);
+  const inputAccepted = stages.some((stage) => ["input_accepted", "input_queued", "prompt_accepted", "queued"].includes(stage.toLowerCase()));
+  const acceptedValue = receipt["accepted"] ?? send?.["accepted"];
+  const accepted = inputAccepted || acceptedValue === true || acceptedValue !== false && (result === null || result === void 0 || Object.keys(record3).length === 0);
+  const warnings = Array.isArray(record3["warnings"]) ? record3["warnings"] : send && Array.isArray(send["warnings"]) ? send["warnings"] : [];
+  return { accepted, requestId: str(receipt["requestId"], str(prompt?.["requestId"], str(record3["requestId"]))) || null, stages, warnings: warnings.map((warning) => isRecord7(warning) ? str(warning["message"], JSON.stringify(warning)) : str(warning)) };
 };
 var orcaTerminalSend = async (runner, input, options2 = {}) => parseOrcaSendReceipt(await orcaJson(runner, ["terminal", "send", "--terminal", input.terminal, "--text", input.text, ...input.enter === false ? [] : ["--enter"], ...input.waitSubmitSeconds ? ["--wait-submit", String(input.waitSubmitSeconds)] : []], { ...options2, timeoutMs: options2.timeoutMs ?? (input.waitSubmitSeconds ?? 0) * 1e3 + 3e4 }));
 var orcaTerminalWait = async (runner, input, options2 = {}) => {
@@ -2770,6 +2822,8 @@ var LoopConfigSchema = z.object({
     }).prefault({}),
     catalog: z.object({
       sources: z.array(z.enum(["cli", "artificial-analysis", "builtin"])).default(["cli", "builtin"]),
+      /** How long a provider's CLI-discovered model list (e.g. `grok models`) is trusted before spawning the CLI again — it rarely changes between releases. */
+      cliCacheHours: z.number().positive().default(6),
       artificialAnalysis: z.object({
         enabled: z.boolean().default(false),
         apiKeyEnv: nonEmpty2.default("ARTIFICIAL_ANALYSIS_API_KEY"),
@@ -3292,7 +3346,12 @@ var selectModel = (config, role, availability, extraCandidates = []) => {
 var routeAllRoles = (config, availability, extrasByRole = {}) => Object.fromEntries(MODEL_ROLES.map((role) => [role, selectModel(config, role, availability, extrasByRole[role] ?? [])]));
 var rankModels = (config, role, availability, extraCandidates = []) => {
   const byId = new Map(availability.map((item) => [item.id, item]));
-  const { ranked } = availableFromTiers(config, role, availability);
+  const { ranked, skipped } = availableFromTiers(config, role, availability);
+  if (config.models.routing.pin[role]) {
+    const pinned = applyPin(config, role, availability, skipped);
+    if (pinned) return [pinned, ...ranked.filter((item) => !(item.provider === pinned.provider && item.model === pinned.model))];
+    if (config.models.routing.pinStrict) return [];
+  }
   const extras = [];
   let extraIndex = 1e4;
   for (const ref of extraCandidates) {
@@ -3413,6 +3472,32 @@ ${outcome.stderr}`);
   }
   return [];
 };
+var cliModelsCachePath = (stateDir, provider) => join(stateDir, "catalog", `cli-${provider}.json`);
+var readCliModelsCache = (stateDir, provider) => {
+  const path = cliModelsCachePath(stateDir, provider);
+  if (!existsSync(path)) return null;
+  try {
+    const raw = readJson2(path);
+    return typeof raw.fetchedAt === "string" && Array.isArray(raw.ids) ? { fetchedAt: raw.fetchedAt, ids: raw.ids } : null;
+  } catch {
+    return null;
+  }
+};
+var writeCliModelsCache = (stateDir, provider, ids, now4 = /* @__PURE__ */ new Date()) => {
+  const path = cliModelsCachePath(stateDir, provider);
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify({ fetchedAt: now4.toISOString(), ids }, null, 2)}
+`, "utf8");
+  renameSync(tmp, path);
+};
+var listCliModelsCached = async (provider, bin, runner, stateDir, cacheHours, now4 = () => /* @__PURE__ */ new Date()) => {
+  const cached = readCliModelsCache(stateDir, provider);
+  if (cached && now4().getTime() - Date.parse(cached.fetchedAt) <= cacheHours * 36e5) return cached.ids;
+  const ids = await listCliModels(provider, bin, runner);
+  if (ids.length) writeCliModelsCache(stateDir, provider, ids, now4());
+  return ids.length ? ids : cached?.ids ?? [];
+};
 var parseArtificialAnalysisPayload = (payload) => {
   const root = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
   const data = Array.isArray(root["data"]) ? root["data"] : Array.isArray(payload) ? payload : [];
@@ -3497,7 +3582,7 @@ var resolveCatalogCandidates = async (input) => {
       const settings = config.models.providers[provider];
       if (settings) {
         try {
-          const ids = await listCliModels(provider, settings.bin, input.runner);
+          const ids = input.stateDir ? await listCliModelsCached(provider, settings.bin, input.runner, input.stateDir, config.models.catalog.cliCacheHours, input.now) : await listCliModels(provider, settings.bin, input.runner);
           for (const id2 of ids) {
             const resolved = resolveAlias(provider, id2, aliases);
             const existing = builtin[provider]?.models.find((model) => model.id === resolved);
@@ -3529,9 +3614,9 @@ var resolveCatalogCandidates = async (input) => {
         const matches2 = models.models.filter((model) => model.creatorSlug === creator || model.creatorSlug.includes(creator));
         for (const model of matches2) {
           const id2 = resolveAlias(provider, model.slug, aliases);
-          const score = model.codingIndex ?? model.intelligenceIndex ?? 50;
-          const quality = score >= 80 ? "frontier" : score >= 60 ? "balanced" : "fast";
-          push(provider, { id: id2, quality, codingScore: score, source: "artificial-analysis", creator });
+          const score2 = model.codingIndex ?? model.intelligenceIndex ?? 50;
+          const quality = score2 >= 80 ? "frontier" : score2 >= 60 ? "balanced" : "fast";
+          push(provider, { id: id2, quality, codingScore: score2, source: "artificial-analysis", creator });
         }
       }
     }
@@ -3583,6 +3668,16 @@ var markProviderExhausted = (stateDir, provider, options2) => {
   return entry;
 };
 var rotationStatePath = (stateDir) => join(stateDir, "queue-owner.json");
+var countRotationBlockingLeases = (loaded, leases) => leases.filter((lease) => {
+  const path = join(loaded.stateDir, "issues", lease.issue, "delivery.json");
+  if (!existsSync(path)) return true;
+  try {
+    const delivery2 = JSON.parse(readFileSync(path, "utf8"));
+    return delivery2.prNumber == null && !delivery2.heldFor && !delivery2.finalOutcome;
+  } catch {
+    return true;
+  }
+}).length;
 var queueOwner = (loaded) => {
   const { rotation } = loaded.config.linear;
   if (!rotation.enabled || !rotation.owners.length) return loaded.config.linear.person;
@@ -4077,10 +4172,10 @@ var planMemoryContext = async (input) => {
     hits = [];
   }
   const selected = selectMemoryForPrompt(hits, memory);
-  const beforeChars = input.references.reduce((sum, ref) => sum + JSON.stringify(ref).length, 0) + issueBudgetDefault;
+  const beforeChars = input.references.reduce((sum2, ref) => sum2 + JSON.stringify(ref).length, 0) + issueBudgetDefault;
   const preferred = memory.preferOverDocBridge ? preferMemoryOverDocBridge(input.references, selected.hits, memory.minDocBridgeWhenMemory) : { references: input.references};
   const issueCharBudget = selected.hits.length && memory.shrinkIssueCharsWhenMemory ? Math.min(issueBudgetDefault, memory.issueCharsWithMemory) : issueBudgetDefault;
-  const afterChars = preferred.references.reduce((sum, ref) => sum + JSON.stringify(ref).length, 0) + issueCharBudget + selected.approxChars;
+  const afterChars = preferred.references.reduce((sum2, ref) => sum2 + JSON.stringify(ref).length, 0) + issueCharBudget + selected.approxChars;
   return {
     hits: selected.hits,
     references: preferred.references,
@@ -4535,7 +4630,6 @@ var resumeIssue = (stateDir, issue) => {
   writeIssueFailures(stateDir, next);
   return next;
 };
-var isIssuePaused = (stateDir, issue) => readIssueFailures(stateDir, issue).pausedAt !== null;
 var listPausedIssues = (stateDir) => {
   const dir = join(stateDir, "issues");
   if (!existsSync(dir)) return [];
@@ -4637,9 +4731,14 @@ var writeDispatchRecord = (stateDir, record3) => {
   writeJson2(path, record3);
   return path;
 };
-var appendLoopEvent = (stateDir, event2, bus) => {
+var EVENTS_ROTATE_AT_BYTES = 10 * 1024 * 1024;
+var appendLoopEvent = (stateDir, event2, bus, now4 = () => /* @__PURE__ */ new Date()) => {
   const path = join(stateDir, "events.ndjson");
   mkdirSync(dirname(path), { recursive: true });
+  try {
+    if (statSync(path).size > EVENTS_ROTATE_AT_BYTES) renameSync(path, join(stateDir, `events-archive-${now4().getTime()}.ndjson`));
+  } catch {
+  }
   appendFileSync(path, `${JSON.stringify(event2)}
 `, "utf8");
   if (bus && typeof event2["type"] === "string") bus.emit(event2);
@@ -4671,7 +4770,7 @@ var gatherLoopState = async (input) => {
   const leases = input.ledger.active();
   const busy = busyIssues(queue, leases, worktrees, person);
   const candidates = queue.filter((issue) => !busy.has(issue.identifier) && (!input.onlyIssue || issue.identifier === input.onlyIssue));
-  return { person, providers, routing, worktrees, slots, queue, leases, busy, candidates };
+  return { person, providers, routing, worktrees, slots, queue, leases, busy, candidates, extrasByRole };
 };
 var precheckTick = async (input) => {
   const loaded = input.loaded ?? loadLoopConfig(input.configPath);
@@ -4712,16 +4811,7 @@ var runTick = async (input) => {
   }
   const state = await gatherLoopState({ loaded, runner: input.runner, ledger, env: input.env, platform: input.platform, now: now4, onlyIssue: input.onlyIssue, machine: input.machine });
   const orchestrator = state.routing["orchestrator"] ?? { role: "orchestrator", selected: null, skipped: [] };
-  const orchestratorExtras = config.models.routing.mode === "catalog" ? await resolveCatalogCandidates({
-    config,
-    role: "orchestrator",
-    availableProviderIds: state.providers.filter((provider) => provider.available).map((provider) => provider.id),
-    runner: input.runner,
-    stateDir: loaded.stateDir,
-    env: input.env,
-    now: now4
-  }) : [];
-  const orchestratorCandidates = rankModels(config, "orchestrator", state.providers, orchestratorExtras);
+  const orchestratorCandidates = rankModels(config, "orchestrator", state.providers, state.extrasByRole["orchestrator"] ?? []);
   const onProviderFailure = (failure) => {
     if (dryRun) return;
     const resetsAt = extractResetsAt(failure.detail, now4());
@@ -4741,7 +4831,7 @@ var runTick = async (input) => {
     return { ...base, status: "idle", results, notes };
   }
   if (!state.candidates.length) {
-    const rotation = dryRun ? { owner: state.person, advanced: false } : advanceQueueOwner(loaded, { queueEmpty: state.queue.length === 0, activeLeases: state.leases.length, now: now4() });
+    const rotation = dryRun ? { owner: state.person, advanced: false } : advanceQueueOwner(loaded, { queueEmpty: state.queue.length === 0, activeLeases: countRotationBlockingLeases(loaded, state.leases), now: now4() });
     if (rotation.advanced) notes.push(`queue drained for ${state.person}; switched to ${rotation.owner}`);
     else notes.push("queue has no dispatchable candidate");
     return { ...base, status: "idle", results, notes };
@@ -4774,17 +4864,32 @@ The loop will not retry this issue until you remove the \`${config.resilience.pa
     appendLoopEvent(loaded.stateDir, { at: now4().toISOString(), type: "issue.paused", issue, kind, consecutive: failureState.consecutive, reason }, bus);
     await bus.runHook("onPause", { issue, kind, consecutive: failureState.consecutive, reason });
   };
+  let pinnedSkillsOnce;
+  const getPinnedSkills = () => {
+    if (pinnedSkillsOnce === void 0) {
+      try {
+        pinnedSkillsOnce = loadPinnedSkills(loaded.root, config.brief.skills, config.brief.maxSkillChars);
+      } catch (error) {
+        pinnedSkillsOnce = { error };
+        throw error;
+      }
+    }
+    if ("error" in pinnedSkillsOnce) throw pinnedSkillsOnce.error;
+    return pinnedSkillsOnce;
+  };
   let dispatched = 0;
   for (const candidate of state.candidates) {
     if (dispatched >= budget) break;
     const setupBudgetMs = config.project.setup.command ? Number.isFinite(timeBudgetMs) ? Math.min(config.project.setup.timeoutSec * 1e3, Math.max(0, timeBudgetMs - config.contract.timeoutMs - 125e3)) : config.project.setup.timeoutSec * 1e3 : 0;
-    if (remainingMs() < config.contract.timeoutMs + setupBudgetMs + 12e4 && !readStoredContract(loaded.stateDir, candidate.identifier)) {
+    const cachedContract = readStoredContract(loaded.stateDir, candidate.identifier);
+    if (remainingMs() < config.contract.timeoutMs + setupBudgetMs + 12e4 && !cachedContract) {
       notes.push(`time budget: ${candidate.identifier} left for the next tick (${Math.round(remainingMs() / 1e3)}s remaining)`);
       continue;
     }
-    if (isIssuePaused(loaded.stateDir, candidate.identifier)) {
+    const failureState = readIssueFailures(loaded.stateDir, candidate.identifier);
+    if (failureState.pausedAt !== null) {
       if (candidate.labels.includes(config.resilience.pausedLabel)) {
-        results.push({ issue: candidate.identifier, outcome: "skipped", reason: `paused after ${readIssueFailures(loaded.stateDir, candidate.identifier).consecutive} consecutive failures; remove the "${config.resilience.pausedLabel}" label or run "ak-harness loop resume ${candidate.identifier}" to retry` });
+        results.push({ issue: candidate.identifier, outcome: "skipped", reason: `paused after ${failureState.consecutive} consecutive failures; remove the "${config.resilience.pausedLabel}" label or run "ak-harness loop resume ${candidate.identifier}" to retry` });
         continue;
       }
       if (!dryRun) clearIssueFailures(loaded.stateDir, candidate.identifier);
@@ -4797,8 +4902,8 @@ The loop will not retry this issue until you remove the \`${config.resilience.pa
       results.push({ issue: candidate.identifier, outcome: "failed", reason: `issue fetch failed: ${message2(error)}` });
       continue;
     }
-    let stored = readStoredContract(loaded.stateDir, detail.identifier);
-    const memoryProbe = memory ? await planMemoryContext({
+    let stored = cachedContract;
+    const memoryPlan = memory ? await planMemoryContext({
       adapter: memory,
       config,
       issueId: detail.identifier,
@@ -4806,7 +4911,7 @@ The loop will not retry this issue until you remove the \`${config.resilience.pa
       project: config.project.name,
       references: []
     }) : null;
-    if (stored && !contractIsFresh(stored, detail, config.contract.reuseHours, now4(), memoryProbe?.memoryDigest)) stored = null;
+    if (stored && !contractIsFresh(stored, detail, config.contract.reuseHours, now4(), memoryPlan?.memoryDigest)) stored = null;
     if (!stored) {
       if (input.skipContractGeneration) {
         results.push({ issue: detail.identifier, outcome: "skipped", reason: "no cached contract; generation skipped" });
@@ -4906,16 +5011,9 @@ The loop will not retry this issue until you remove the \`${config.resilience.pa
         }
         if (setupFailed) notes.push(`${detail.identifier}: setup command failed but project.setup.required is false \u2014 continuing`);
       }
-      const briefMemory = memory ? await planMemoryContext({
-        adapter: memory,
-        config,
-        issueId: detail.identifier,
-        issueTitle: detail.title,
-        project: config.project.name,
-        references: []
-      }) : { memoryBlock: "", issueCharBudget: config.contract.maxIssueChars, hits: [] };
+      const briefMemory = memoryPlan ?? { memoryBlock: "", issueCharBudget: config.contract.maxIssueChars, hits: [] };
       const guidanceRefs = config.contract.maxBriefReferences > 0 && config.contract.briefScopes.length ? await resolveDocContext(loaded.root, `${detail.identifier} ${detail.title}`, config.contract.maxBriefReferences, config.contract.briefScopes) : [];
-      const pinnedSkills = loadPinnedSkills(loaded.root, config.brief.skills, config.brief.maxSkillChars);
+      const pinnedSkills = getPinnedSkills();
       const brief = renderWorkerBrief({
         issue: detail,
         contract: stored,
@@ -5245,7 +5343,7 @@ var providerUnavailable = (ctx, providerId) => {
   return !match || !match.available;
 };
 var pickHandoffBuilder = (ctx, record3) => {
-  const ranked = rankModels(ctx.config, "builder", ctx.providers);
+  const ranked = rankModels(ctx.config, "builder", ctx.providers, ctx.builderExtras);
   const different = ranked.find((candidate) => candidate.provider !== record3.provider || candidate.model !== record3.model);
   return different ?? null;
 };
@@ -5686,7 +5784,8 @@ var runDeliver = async (input) => {
   const availableIds = providers.filter((provider) => provider.available).map((provider) => provider.id);
   const catalogExtras = async (role) => config.models.routing.mode === "catalog" ? resolveCatalogCandidates({ config, role, availableProviderIds: availableIds, runner: input.runner, stateDir: loaded.stateDir, env: input.env, now: now4 }) : Promise.resolve([]);
   const reviewer = rankModels(config, "reviewer", providers, await catalogExtras("reviewer"))[0] ?? null;
-  const builder = rankModels(config, "builder", providers, await catalogExtras("builder"))[0] ?? null;
+  const builderExtras = await catalogExtras("builder");
+  const builder = rankModels(config, "builder", providers, builderExtras)[0] ?? null;
   let env = input.env ?? process.env;
   if (!env["GITHUB_TOKEN"] && !env["GH_TOKEN"]) {
     try {
@@ -5702,13 +5801,14 @@ var runDeliver = async (input) => {
     const { errors } = await loadLoopPlugins(loaded.root, config.plugins.modules, bus);
     for (const failure of errors) notes.push(`plugin ${failure.path} failed to load: ${failure.error}`);
   }
-  const ctx = { loaded, config, runner: input.runner, now: now4, dryRun, reviewer, builder, providers, env, ...input.assumeIdle === void 0 ? {} : { assumeIdle: input.assumeIdle }, notes, reviewDeadlineMs, bus };
+  const ctx = { loaded, config, runner: input.runner, now: now4, dryRun, reviewer, builder, providers, env, ...input.assumeIdle === void 0 ? {} : { assumeIdle: input.assumeIdle }, notes, reviewDeadlineMs, bus, builderExtras };
   const ledger = createDispatchLedger(loaded.stateDir);
   const leases = new Map(ledger.active().map((lease) => [lease.issue, lease]));
   const results = [];
   for (const record3 of listDispatched(loaded.stateDir)) {
     if (input.onlyIssue && record3.issue !== input.onlyIssue) continue;
     let state = readDeliveryState(loaded.stateDir, record3.issue);
+    if (state.finishedAt && state.finalOutcome === "merged") continue;
     const lease = leases.get(record3.issue);
     if (!state.finishedAt) {
       const ageMinutes = minutesBetween(now4(), record3.dispatchedAt);
@@ -5747,7 +5847,6 @@ var runDeliver = async (input) => {
         results.push(await handlePullRequest(ctx, record3, lease, state, pr));
         continue;
       }
-      if (state.finishedAt && state.finalOutcome === "merged") continue;
       const recordedMerge = readMergedEvent(loaded.stateDir, record3.issue);
       if (recordedMerge) {
         try {
@@ -6308,10 +6407,19 @@ ${step && total ? `${step}/${total} ` : ""}${title}`),
     ] }))
   };
 };
+var newestIssueMtimeMs = (stateDir, issue) => {
+  const mtimes = [dispatchRecordPath(stateDir, issue), deliveryStatePath(stateDir, issue), contractPath(stateDir, issue)].map((path) => {
+    try {
+      return statSync(path).mtimeMs;
+    } catch {
+      return null;
+    }
+  }).filter((value) => value !== null);
+  return mtimes.length ? Math.max(...mtimes) : null;
+};
 var HARNESS_REPO_URL = "https://github.com/AgentsKit-io/harness";
 var isRecord13 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-var readLoopEvents = (stateDir) => {
-  const path = join(stateDir, "events.ndjson");
+var parseEventsFile = (path) => {
   if (!existsSync(path)) return [];
   return readFileSync(path, "utf8").split(/\r?\n/).filter(Boolean).flatMap((line2) => {
     try {
@@ -6322,6 +6430,11 @@ var readLoopEvents = (stateDir) => {
     }
   });
 };
+var eventsArchivePattern = /^events-archive-(\d+)\.ndjson$/;
+var readLoopEvents = (stateDir, sinceMs) => {
+  const archives = existsSync(stateDir) ? readdirSync(stateDir).map((name2) => name2.match(eventsArchivePattern)).filter((match) => match !== null).map((match) => ({ path: join(stateDir, match[0]), rotatedAtMs: Number(match[1]) })).filter((archive) => sinceMs === void 0 || archive.rotatedAtMs >= sinceMs).sort((a, b) => a.rotatedAtMs - b.rotatedAtMs) : [];
+  return [...archives.flatMap((archive) => parseEventsFile(archive.path)), ...parseEventsFile(join(stateDir, "events.ndjson"))];
+};
 var parseSince = (value, now4) => {
   if (!value) return new Date(now4.getTime() - 7 * 864e5);
   const match = value.match(/^(\d+)([dhm])$/);
@@ -6368,10 +6481,11 @@ var buildSuggestions = (input) => {
 var buildRetroReport = async (input) => {
   const loaded = input.loaded ?? loadLoopConfig(input.configPath);
   const { config } = loaded;
+  const person = queueOwner(loaded);
   const now4 = (input.now ?? (() => /* @__PURE__ */ new Date()))();
   const since = parseSince(input.since, now4);
   const inWindow = (at) => typeof at === "string" && Date.parse(at) >= since.getTime() && Date.parse(at) <= now4.getTime();
-  const events2 = readLoopEvents(loaded.stateDir).filter((event2) => inWindow(event2.at));
+  const events2 = readLoopEvents(loaded.stateDir, since.getTime()).filter((event2) => inWindow(event2.at));
   const counts = {};
   for (const event2 of events2) counts[event2.type] = (counts[event2.type] ?? 0) + 1;
   const escalations = events2.filter((event2) => event2.type === "contract.escalated");
@@ -6393,6 +6507,8 @@ var buildRetroReport = async (input) => {
   if (existsSync(issuesDir)) for (const entry of readdirSync(issuesDir, { withFileTypes: true })) {
     if (!entry.isDirectory()) continue;
     const issue = entry.name;
+    const newestMtime = newestIssueMtimeMs(loaded.stateDir, issue);
+    if (newestMtime !== null && newestMtime < since.getTime()) continue;
     const dispatch = readDispatchRecord(loaded.stateDir, issue);
     const delivery2 = readDeliveryState(loaded.stateDir, issue);
     const contract = readStoredContract(loaded.stateDir, issue);
@@ -6450,7 +6566,7 @@ var buildRetroReport = async (input) => {
           else if (status2 === "ok") work += 1;
         }
       }
-      orca = { runs, idle, work, timedOut, avgDurationSec: durations.length ? Math.round(durations.reduce((sum, value) => sum + value, 0) / durations.length) : null, maxDurationSec: durations.length ? Math.round(Math.max(...durations)) : null };
+      orca = { runs, idle, work, timedOut, avgDurationSec: durations.length ? Math.round(durations.reduce((sum2, value) => sum2 + value, 0) / durations.length) : null, maxDurationSec: durations.length ? Math.round(Math.max(...durations)) : null };
     } catch {
       orca = null;
     }
@@ -6459,9 +6575,9 @@ var buildRetroReport = async (input) => {
     generatedAt: now4.toISOString(),
     window: { since: since.toISOString(), until: now4.toISOString(), days: Number(((now4.getTime() - since.getTime()) / 864e5).toFixed(2)) },
     project: config.project.repo,
-    person: config.linear.person,
+    person,
     counts,
-    escalations: { total: escalations.length, issues: [...new Set(escalations.map((event2) => String(event2.issue ?? "?")))], reasons: [...reasonCounts.entries()].map(([reason2, count2]) => ({ reason: reason2, count: count2 })).sort((left, right) => right.count - left.count) },
+    escalations: { total: escalations.length, issues: [...new Set(escalations.map((event2) => String(event2.issue ?? "?")))], reasons: [...reasonCounts.entries()].map(([reason2, count3]) => ({ reason: reason2, count: count3 })).sort((left, right) => right.count - left.count) },
     dispatches: { total: dispatchEvents.length, failed: counts["worker.dispatch-failed"] ?? 0, byProvider },
     delivery: { merged: tally("merged"), blocked: tally("blocked"), stuck: tally("stuck"), abandoned: tally("abandoned"), inFlight: tally("in-flight"), fixRounds, reviewsClean, reviewsFindings, reviewsIncomplete, medianLeadTimeMin: median2(rows.map((row) => row.leadTimeMin).filter((value) => value !== null)) },
     providers: { cooldowns, cooldownEvents: counts["provider.cooldown"] ?? 0 },
@@ -6488,7 +6604,7 @@ var renderRetroMarkdown = (report) => {
   if (report.orca) lines.push(`| Orca runs (idle / work / timed out) | ${report.orca.runs} (${report.orca.idle} / ${report.orca.work} / ${report.orca.timedOut}) \xB7 avg ${report.orca.avgDurationSec ?? "\u2014"} s \xB7 max ${report.orca.maxDurationSec ?? "\u2014"} s |`);
   lines.push("");
   if (Object.keys(report.dispatches.byProvider).length) {
-    lines.push("## Providers", "", ...Object.entries(report.dispatches.byProvider).map(([key, count2]) => `- ${key}: ${count2} dispatch(es)`), ...report.providers.cooldowns.map((row) => `- cooldown ${row.provider} until ${row.until.slice(0, 16)}Z \u2014 ${row.reason}`), "");
+    lines.push("## Providers", "", ...Object.entries(report.dispatches.byProvider).map(([key, count3]) => `- ${key}: ${count3} dispatch(es)`), ...report.providers.cooldowns.map((row) => `- cooldown ${row.provider} until ${row.until.slice(0, 16)}Z \u2014 ${row.reason}`), "");
   }
   if (report.escalations.reasons.length) {
     lines.push("## Problems", "", ...report.escalations.reasons.map((row) => `- ${row.count}\xD7 ${row.reason}`), ...report.issues.filter((row) => ["blocked", "stuck", "abandoned"].includes(row.outcome)).map((row) => `- ${row.issue} ${row.outcome}${row.pr ? ` (PR #${row.pr})` : ""} after ${row.fixRounds} fix round(s), ${row.nudges} nudge(s)`), "");
@@ -6669,7 +6785,7 @@ var buildDebriefReport = (input) => {
   }
   const inFlight = rows.filter((row) => !row.finalOutcome && row.phase !== "escalated");
   const held = rows.filter((row) => row.phase === "held" || row.phase === "held-incomplete-review" || row.heldFor);
-  const events2 = readLoopEvents(stateDir).filter((event2) => Date.parse(event2.at) >= since.getTime());
+  const events2 = readLoopEvents(stateDir, since.getTime()).filter((event2) => Date.parse(event2.at) >= since.getTime());
   const recentEscalations = events2.filter((event2) => event2.type === "contract.escalated").slice(-10).map((event2) => ({
     issue: typeof event2.issue === "string" ? event2.issue : "?",
     at: event2.at,
@@ -6751,6 +6867,138 @@ var renderDebriefMarkdown = (report) => {
   lines.push("_Read-only. Run `ak-harness loop deliver` / `tick` to act; `loop retro` for the weekly digest._");
   return lines.join("\n");
 };
+var connectedStatuses = /* @__PURE__ */ new Set(["connected", "running", "active", "idle"]);
+var stalledPhases = /* @__PURE__ */ new Set(["waiting-for-pr", "awaiting-review", "review-incomplete", "fix-round"]);
+var heldRow = (row) => Boolean(row.heldFor) || row.phase === "held" || row.phase === "held-incomplete-review";
+var count2 = (events2, type) => events2.filter((event2) => event2.type === type).length;
+var sum = (events2, key) => events2.reduce((total, event2) => total + (typeof event2[key] === "number" && Number.isFinite(event2[key]) ? Number(event2[key]) : 0), 0);
+var uniqueIssues = (events2, types) => new Set(events2.filter((event2) => types.includes(event2.type) && typeof event2.issue === "string").map((event2) => event2.issue)).size;
+var assessObservability = (input) => {
+  const anomalies = [];
+  for (const issue of input.missingDeliveryIssues) anomalies.push({ id: "claim-without-delivery", severity: "action_required", issue, message: `${issue} has an active claim but no delivery.json`, evidence: { issue } });
+  for (const terminal2 of input.terminals) {
+    if (terminal2.worktreeId && connectedStatuses.has(terminal2.status.toLowerCase()) && terminal2.lastOutputAt === null && !terminal2.preview.trim()) anomalies.push({ id: "connected-without-output", severity: "warning", issue: null, message: `terminal ${terminal2.handle} is connected but has not emitted output`, evidence: { handle: terminal2.handle, worktreeId: terminal2.worktreeId, status: terminal2.status } });
+  }
+  for (const worktree of input.finalizedDirtyWorktrees) anomalies.push({ id: "finalized-dirty-worktree", severity: "action_required", issue: worktree.issue, message: `finalized worktree ${worktree.worktreeId} still has ${worktree.files} uncommitted file(s)`, evidence: { ...worktree } });
+  const latestDispatch = input.events.filter((event2) => event2.type === "worker.dispatched").map((event2) => Date.parse(event2.at)).filter(Number.isFinite).sort((a, b) => b - a)[0];
+  const quietForMin = latestDispatch === void 0 ? Number.POSITIVE_INFINITY : Math.max(0, Math.round((Date.parse(input.generatedAt) - latestDispatch) / 6e4));
+  if (input.queueReady > 0 && input.freeSlots > 0 && quietForMin >= 15) anomalies.push({ id: "queue-ready-no-dispatch", severity: "action_required", issue: null, message: `${input.queueReady} ready issue(s) and ${input.freeSlots} free slot(s), but no dispatch in ${Number.isFinite(quietForMin) ? `${quietForMin} min` : "the observation window"}`, evidence: { queueReady: input.queueReady, freeSlots: input.freeSlots, quietForMin } });
+  for (const row of input.issues) {
+    if (row.heldFor || !stalledPhases.has(row.phase) || row.ageMin === null || row.ageMin < input.workerIdleTimeoutMin) continue;
+    anomalies.push({ id: "stalled-delivery", severity: "action_required", issue: row.issue, message: `${row.issue} is in ${row.phase} for ${row.ageMin} min (threshold ${input.workerIdleTimeoutMin} min)`, evidence: { issue: row.issue, phase: row.phase, ageMin: row.ageMin, thresholdMin: input.workerIdleTimeoutMin } });
+  }
+  const events2 = {};
+  for (const event2 of input.events) events2[event2.type] = (events2[event2.type] ?? 0) + 1;
+  const report = {
+    status: anomalies.some((item) => item.severity === "action_required") ? "action_required" : "healthy",
+    generatedAt: input.generatedAt,
+    project: input.project,
+    person: input.person,
+    windowHours: input.windowHours,
+    anomalies,
+    metrics: {
+      queueReady: input.queueReady,
+      freeSlots: input.freeSlots,
+      runningWorkers: input.runningWorkers,
+      maxAgents: input.maxAgents,
+      activeClaims: input.activeClaims,
+      inFlight: input.issues.filter((row) => !heldRow(row)).length,
+      held: input.issues.filter(heldRow).length,
+      merged: input.merged,
+      blocked: input.blocked,
+      fixRounds: input.fixRounds,
+      reviewFindings: input.reviewFindings,
+      reviewIncomplete: input.reviewIncomplete,
+      medianLeadTimeMin: input.medianLeadTimeMin,
+      providerRemainingPercent: input.providerRemainingPercent,
+      machine: input.machine,
+      memory: input.memory,
+      cache: input.cache,
+      tokens: input.tokens,
+      events: events2
+    }
+  };
+  return report;
+};
+var compactTerminal = (terminal2) => ({ handle: terminal2.handle, status: terminal2.status, worktreeId: terminal2.worktreeId, lastOutputAt: terminal2.lastOutputAt, preview: terminal2.preview });
+var dirtyFinalizedWorktrees = async (runner, worktrees) => {
+  const out = [];
+  for (const worktree of worktrees) {
+    if (worktree.workspaceStatus.trim().toLowerCase() !== "completed" || !worktree.path) continue;
+    try {
+      const result = await runner.run(["git", "-C", worktree.path, "status", "--porcelain"], { timeoutMs: 1e4 });
+      if (result.code === 0 && result.stdout.trim()) out.push({ worktreeId: worktree.id, issue: worktree.linkedLinearIssue, files: result.stdout.trim().split(/\r?\n/).length });
+    } catch {
+    }
+  }
+  return out;
+};
+var runObservability = async (input) => {
+  const loaded = input.loaded ?? loadLoopConfig(input.configPath ?? "loop.config.yaml");
+  const now4 = input.now ?? (() => /* @__PURE__ */ new Date());
+  const at = now4();
+  const since = parseSince(input.since ?? "24h", at);
+  const [doctor, debrief, worktrees, terminals] = await Promise.all([
+    runLoopDoctor({ loaded, runner: input.runner, env: input.env, platform: input.platform, now: () => at, probe: false }),
+    Promise.resolve(buildDebriefReport({ loaded, since: input.since ?? "24h", now: () => at })),
+    orcaWorktrees(input.runner, { bin: loaded.config.orca.bin, timeoutMs: loaded.config.orca.timeoutMs }).catch(() => []),
+    orcaTerminalList(input.runner, {}, { bin: loaded.config.orca.bin, timeoutMs: loaded.config.orca.timeoutMs }).catch(() => [])
+  ]);
+  const events2 = readLoopEvents(loaded.stateDir).filter((event2) => Date.parse(event2.at) >= since.getTime() && Date.parse(event2.at) <= at.getTime());
+  const ledger = createDispatchLedger(loaded.stateDir);
+  const active = ledger.active();
+  const missingDeliveryIssues = active.filter((lease) => !existsSync(deliveryStatePath(loaded.stateDir, lease.issue))).map((lease) => lease.issue);
+  const records = listDispatched(loaded.stateDir);
+  const completed = records.map((record3) => ({ record: record3, state: readDeliveryState(loaded.stateDir, record3.issue) })).filter(({ state }) => state.finishedAt && Date.parse(state.finishedAt) >= since.getTime());
+  const leadTimes = completed.map(({ record: record3, state }) => state.finishedAt ? (Date.parse(state.finishedAt) - Date.parse(record3.dispatchedAt)) / 6e4 : null).filter((value) => value !== null && Number.isFinite(value)).sort((a, b) => a - b);
+  const medianLeadTimeMin = leadTimes.length ? leadTimes.length % 2 ? leadTimes[Math.floor(leadTimes.length / 2)] : (leadTimes[leadTimes.length / 2 - 1] + leadTimes[leadTimes.length / 2]) / 2 : null;
+  const providerRemainingPercent = Object.fromEntries(doctor.providers.map((provider) => [provider.id, remainingUsagePercent(provider.usage, loaded.config.models.routing.usageMetric)]));
+  const cachedContracts = records.filter((record3) => existsSync(contractPath(loaded.stateDir, record3.issue))).length;
+  const memoryEvents = events2.filter((event2) => event2.type === "memory.recalled");
+  const tokens = { input: sum(events2, "inputTokens"), output: sum(events2, "outputTokens"), total: sum(events2, "totalTokens"), cacheRead: sum(events2, "cacheReadTokens"), cacheWrite: sum(events2, "cacheWriteTokens") };
+  const machine = { cpuCount: doctor.machine.sample.cpus, load1PerCpuPercent: doctor.machine.sample.load1PerCpuPercent, memoryUsedPercent: doctor.machine.sample.memoryUsedPercent, freeRamGb: doctor.machine.freeRamGb };
+  const snapshot = {
+    generatedAt: at.toISOString(),
+    project: doctor.config.project,
+    person: doctor.config.person,
+    windowHours: Math.max(1, Math.round((at.getTime() - since.getTime()) / 36e5)),
+    workerIdleTimeoutMin: loaded.config.delivery.workerIdleTimeoutMin,
+    queueReady: doctor.queue.count,
+    freeSlots: doctor.machine.free,
+    runningWorkers: doctor.workers.running,
+    maxAgents: doctor.machine.maxAgents,
+    activeClaims: active.length,
+    missingDeliveryIssues,
+    terminals: terminals.map(compactTerminal),
+    finalizedDirtyWorktrees: await dirtyFinalizedWorktrees(input.runner, worktrees),
+    issues: debrief.inFlight.map(({ issue, phase, ageMin, heldFor }) => ({ issue, phase, ageMin, heldFor })),
+    events: events2,
+    merged: uniqueIssues(events2, ["pr.merged", "worker.merged"]),
+    blocked: Math.max(records.filter((record3) => readDeliveryState(loaded.stateDir, record3.issue).finalOutcome === "blocked").length, uniqueIssues(events2, ["worker.blocked"])),
+    fixRounds: records.reduce((total, record3) => total + readDeliveryState(loaded.stateDir, record3.issue).fixRounds, 0),
+    reviewFindings: count2(events2, "pr.reviewed") - count2(events2.filter((event2) => event2["status"] !== "findings"), "pr.reviewed"),
+    reviewIncomplete: events2.filter((event2) => event2.type === "pr.reviewed" && event2["status"] === "incomplete").length,
+    medianLeadTimeMin,
+    providerRemainingPercent,
+    machine,
+    memory: { recalls: memoryEvents.length, hits: sum(memoryEvents, "hits"), approxCharsSaved: sum(memoryEvents, "approxCharsSaved") },
+    cache: { cachedContracts },
+    tokens
+  };
+  return assessObservability(snapshot);
+};
+var renderObservabilityMarkdown = (report) => {
+  const m = report.metrics;
+  const headroom = Object.entries(m.providerRemainingPercent).map(([provider, remaining]) => `${provider} ${remaining === null ? "?" : `${remaining}%`}`).join(", ");
+  const lines = [`# Loop observability \u2014 ${report.project} \xB7 ${report.person}`, "", `_${report.status}_ \xB7 generated ${report.generatedAt.slice(0, 19)}Z \xB7 last ${report.windowHours}h`, "", "## Metrics", "", `- Queue: ${m.queueReady} ready \xB7 ${m.freeSlots} free slot(s) \xB7 ${m.runningWorkers}/${m.maxAgents} workers`, `- Delivery: ${m.inFlight} in flight \xB7 ${m.held} held \xB7 ${m.merged} merged \xB7 ${m.blocked} blocked \xB7 ${m.fixRounds} fix round(s)`, `- Reviews: ${m.reviewFindings} findings \xB7 ${m.reviewIncomplete} incomplete`, `- Machine: ${m.machine.cpuCount} CPU \xB7 ${m.machine.load1PerCpuPercent}% load \xB7 ${m.machine.memoryUsedPercent}% memory \xB7 ${m.machine.freeRamGb} GB free`, `- Providers: ${headroom || "n/a"}`, `- Memory/cache: ${m.memory.recalls} recall(s), ${m.memory.hits} hit(s), ${m.memory.approxCharsSaved} chars saved \xB7 ${m.cache.cachedContracts} cached contract(s)`, `- Tokens observed: ${m.tokens.total || m.tokens.input + m.tokens.output || "n/a"}`, ""];
+  if (report.anomalies.length) {
+    lines.push("## Anomalies", "");
+    for (const anomaly of report.anomalies) lines.push(`- **${anomaly.severity}**${anomaly.issue ? ` \xB7 ${anomaly.issue}` : ""}: ${anomaly.message}`);
+    lines.push("");
+  } else lines.push("## Anomalies", "", "_None detected._", "");
+  lines.push("_Read-only. Run `ak-harness loop tick` or `deliver` to act on the queue._");
+  return lines.join("\n");
+};
 
 // src/loop/watch.ts
 var defaultSleep = (ms) => new Promise((resolve9) => setTimeout(resolve9, ms));
@@ -6887,6 +7135,32 @@ var print = (value) => {
   if (options().json) console.log(JSON.stringify(value));
   else console.log(typeof value === "string" ? value : JSON.stringify(value, null, 2));
 };
+var acquireStageLock = (stateDir, stage) => {
+  const path = join(stateDir, `.stage-${stage}.lock`);
+  mkdirSync(stateDir, { recursive: true });
+  try {
+    const fd = openSync(path, "wx");
+    writeFileSync(fd, `${JSON.stringify({ pid: process.pid, stage, at: (/* @__PURE__ */ new Date()).toISOString() })}
+`, "utf8");
+    closeSync(fd);
+    return () => {
+      try {
+        unlinkSync(path);
+      } catch {
+      }
+    };
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    try {
+      if (Date.now() - statSync(path).mtimeMs > 30 * 6e4) {
+        unlinkSync(path);
+        return acquireStageLock(stateDir, stage);
+      }
+    } catch {
+    }
+    return null;
+  }
+};
 var readBenchmarkEvidence = (path) => {
   try {
     const content = readFileSync(path, "utf8");
@@ -6991,6 +7265,12 @@ loop.command("stage <stage>").description("Run one stage (tick | deliver | retro
     process.exitCode = 1;
     return;
   }
+  const stageLock = acquireStageLock(loaded.stateDir, stage);
+  if (!stageLock) {
+    console.log(JSON.stringify({ status: "locked", stage, reason: "another stage run is still active" }, null, 2));
+    process.exitCode = 1;
+    return;
+  }
   const budgetMs = Math.max(6e4, loaded.config.schedule.stageTimeoutSec * 1e3 - 6e4);
   const threshold = loaded.config.resilience.stagePauseAfterRuns;
   try {
@@ -7001,6 +7281,8 @@ loop.command("stage <stage>").description("Run one stage (tick | deliver | retro
     const reason = error instanceof Error ? error.message : String(error);
     const entry = stage !== "retro" ? recordStageRunResult(loaded.stateDir, trackedStage, { succeeded: false, reason }, threshold) : null;
     console.log(JSON.stringify({ status: "error", stage, error: reason, ...entry ? { consecutiveFailures: entry.consecutiveFailures, paused: entry.pausedAt !== null } : {} }, null, 2));
+  } finally {
+    stageLock();
   }
   process.exitCode = 1;
 });
@@ -7080,6 +7362,13 @@ loop.command("debrief").description("Human-facing explanation of what the loop i
   if (options().json) return print(report);
   console.log(renderDebriefMarkdown(report));
 });
+loop.command("observe").description("Read-only anomaly scan and operating metrics for the loop (queue, workers, delivery, machine, memory, cache, tokens).").option("--since <window>", "window such as 24h, 7d or an ISO date", "24h").option("--precheck", "exit 0 when an action is required, 1 when healthy (for schedulers)").action(async function(command) {
+  const report = await runObservability({ configPath: loopFile(this), runner: createProcessRunner(), since: command.since });
+  if (options().json) print(report);
+  else console.log(renderObservabilityMarkdown(report));
+  if (command.precheck) process.exitCode = report.status === "action_required" ? 0 : 1;
+  else if (report.status === "action_required") process.exitCode = 2;
+});
 loop.command("watch").description("Watch delivery.json (+ optional live PR) for in-flight issues; prints DONE / FAILED / ACTION_REQUIRED / PROGRESS. Read-only.").option("--issue <identifier>", "restrict to one issue").option("--interval <seconds>", "poll interval", (value) => Number(value), 30).option("--once", "single snapshot then exit").option("--timeout <seconds>", "stop after N seconds (0 = until terminal)", (value) => Number(value), 0).option("--no-live-pr", "do not call gh; filesystem state only").action(async function(command) {
   const report = await watchDeliveries({
     configPath: loopFile(this),