elanous 0.2.21 → 0.2.23

package/src/graph-unify/wf-to-graph.ts

@@ -0,0 +1,79 @@
+import { topoSort } from '../workflow-runtime/schema.js';
+import type { DagNode, WorkflowDefinition } from '../workflow-runtime/types.js';
+import type { GraphEdgeSpec, GraphNodeSpec, GraphTemplateSpec } from '../self-implement/graph-yaml.js';
+import { WORKFLOW_CORE_KINDS } from '../graph-kinds/registry.js';
+
+/** In-memory graph projection. The compatibility executor dispatches these
+ * workflow recipes; graph-runner cannot execute all workflow node variants yet. */
+export interface WorkflowGraph {
+  readonly template: GraphTemplateSpec;
+  readonly recipes: Readonly<Record<string, DagNode>>;
+}
+
+export type WorkflowGraphResult =
+  | { readonly ok: true; readonly graph: WorkflowGraph }
+  | { readonly ok: false; readonly reason: string };
+
+/** Project a validated workflow without changing its YAML or executing any work.
+ * Reject constructs whose graph projection would silently change DAG semantics. */
+export function workflowToGraph(workflow: WorkflowDefinition): WorkflowGraphResult {
+  if ((workflow.concurrency ?? 1) !== 1) return { ok: false, reason: 'concurrency > 1' };
+  if (!workflow.nodes.length) return { ok: false, reason: 'empty workflow' };
+  if (workflow.nodes.some(node => node.on_error)) {
+    return { ok: false, reason: 'error routing' };
+  }
+  let order: string[];
+  try { order = topoSort(workflow.nodes); }
+  catch (error) { return { ok: false, reason: String(error) }; }
+  if (order.length !== workflow.nodes.length || new Set(order).size !== order.length) {
+    return { ok: false, reason: 'invalid topology' };
+  }
+  const byId = new Map(workflow.nodes.map(node => [node.id, node] as const));
+  const recipes: Record<string, DagNode> = Object.create(null);
+  const nodes: GraphNodeSpec[] = [];
+  for (const id of order) {
+    const node = byId.get(id)!;
+    const kind = typeof node.kind === 'string' ? node.kind
+      : WORKFLOW_CORE_KINDS.find(key => key !== 'subworkflow' && key in node);
+    if (!kind) {
+      return { ok: false, reason: `unknown node variant: ${id}` };
+    }
+    recipes[id] = node;
+    nodes.push({ nodeId: id, kind, recipe: `workflow:${id}`, maxVisits: 1 });
+  }
+  // A single cursor visits each node exactly once in the same stable topological
+  // order as the serial workflow executor. Preserve original dependencies and
+  // conditions in recipes; do not mistake a when expression for a graph outcome.
+  const edges: GraphEdgeSpec[] = order.slice(1).map((id, index) => ({ from: order[index]!, to: id }));
+  const template: GraphTemplateSpec = {
+    graphId: workflow.name, version: 1, entryNode: order[0]!, terminalNodes: [order.at(-1)!],
+    nodes, edges,
+  };
+  return { ok: true, graph: { template, recipes } };
+}
+
+/** The workflow compatibility cursor follows the projected graph edges, not
+ * the source DAG. The WF event adapter remains the owner of node dispatch. */
+export function walkWorkflowGraph(graph: WorkflowGraph): string[] {
+  const order: string[] = [];
+  const visited = new Set<string>();
+  let current: string | undefined = graph.template.entryNode;
+  while (current !== undefined) {
+    const spec = graph.template.nodes.find(node => node.nodeId === current);
+    if (visited.has(current) || !spec || spec.recipe !== `workflow:${current}` || spec.maxVisits !== 1
+      || !Object.hasOwn(graph.recipes, current)) throw new Error(`invalid workflow graph cursor: ${current}`);
+    const recipe = graph.recipes[current]!;
+    const kind = typeof recipe.kind === 'string' ? recipe.kind
+      : WORKFLOW_CORE_KINDS.find(key => key !== 'subworkflow' && key in recipe);
+    if (recipe.id !== current || kind !== spec.kind) throw new Error(`invalid workflow graph recipe: ${current}`);
+    visited.add(current);
+    order.push(current);
+    const outgoing: GraphEdgeSpec[] = graph.template.edges.filter(edge => edge.from === current);
+    if (outgoing.length > 1 || outgoing.some(edge => edge.to === undefined)) throw new Error(`invalid workflow graph edge: ${current}`);
+    current = outgoing[0]?.to;
+  }
+  if (order.length !== graph.template.nodes.length || !graph.template.terminalNodes.includes(order.at(-1)!)) {
+    throw new Error('incomplete workflow graph path');
+  }
+  return order;
+}

package/src/graph-wizard/generate.ts

@@ -18,6 +18,8 @@ import { validateGraphYaml } from '../nexus/api/graph-kinds.js';
 import { defaultGraphsDir } from '../self-implement/graph-templates.js';
 import { WORKFLOW_SYNTH_SYSTEM_PROMPT } from '../workflow-synth/system-prompt.js';
 import { WIZARD_ARCHETYPES } from './archetypes.js';
+import { listInstalledPacks, queryInstalledPack } from '../knowledge/query.js';
+import { parsePackIdString } from '../knowledge/kgs/pack.js';
 import { WIZARD_MAX_RETRIES, WIZARD_STEPS, WIZARD_STEP_IDS, recipesYamlFor, type WizardNodeStep } from './steps.js';
 
 export interface GraphWizardTurn { role: 'user' | 'assistant'; text: string }
@@ -28,6 +30,8 @@ export interface GraphWizardRequest {
   /** 있으면 prompt 는 «이 그래프를 고치라»는 지시다 — 결과는 고친 «전체» YAML. */
   currentYaml?: string;
   history?: GraphWizardTurn[];
+  /** Installed pack selected for a knowledge (RAG) node. */
+  packId?: string;
 }
 
 export interface GraphWizardResult {
@@ -58,10 +62,18 @@ export interface GraphWizardDeps {
   /** 이미 쓰인 graph_id(핵심 ⊕ 내 그래프). 기본 = graphs/** ⊕ <state>/graphs. */
   existingIds?: () => ReadonlySet<string>;
   maxAttempts?: number;
+  /** Installed pack inventory and retrieval seams for isolated generation. */
+  packs?: typeof listInstalledPacks;
+  searchPack?: typeof queryInstalledPack;
 }
 
 export const GRAPH_WIZARD_MAX_ATTEMPTS = 3;
 
+/** Inventory used by the editor's pack picker and the wizard's validation. */
+export function wizardInstalledPacks(deps: GraphWizardDeps = {}): Array<{ id: string; title: string }> {
+  return (deps.packs ?? listInstalledPacks)();
+}
+
 /** 요청 자체가 틀렸다(400) — LLM 실패(502)와 가른다. */
 export class GraphWizardInputError extends Error { override name = 'GraphWizardInputError'; }
 const GRAPH_ID = /^[a-z0-9-]+$/;
@@ -422,8 +434,9 @@ async function defaultCallLLM(prompt: string): Promise<string> {
 function buildPrompt(input: {
   req: GraphWizardRequest; kind: GraphKind; id: string; base?: TemplateEntry; templates: readonly TemplateEntry[];
   previous?: { yaml: string; issues: string[] };
+  evidence?: string;
 }): string {
-  const { req, kind, id, base, templates, previous } = input;
+  const { req, kind, id, base, templates, previous, evidence } = input;
   const kinds = listNodeKinds(kind).map((k) => k.kind).join(', ');
   const editing = typeof req.currentYaml === 'string' && req.currentYaml.trim() !== '';
   const lines: string[] = [
@@ -451,6 +464,8 @@ function buildPrompt(input: {
   } else {
     lines.push('', `사용자의 말: ${req.prompt}`);
   }
+  if (evidence) lines.push('', '선택한 설치 팩의 검색 근거:', evidence,
+    `지식(RAG) 노드를 cmd 단계로 넣고 # 지식 검색 | knowledge-rag | ${req.packId} 주석을 붙인다. 다음 산출 단계는 이 노드의 근거를 사용한다. 실행 입력 input.query 가 있으면 질문으로 검색하고 없으면 설치 팩 전체 색인에서 가져온다. 근거에 없는 사실을 만들지 마라.`);
   if (previous) {
     lines.push('', '직전 시도가 검증에 실패했다. 아래 문제를 «전부» 고쳐 전체 YAML 을 다시 써라:', ...previous.issues.map((i) => `- ${i}`),
       '직전 YAML:', '```yaml', previous.yaml.trim(), '```');
@@ -467,6 +482,15 @@ export async function generateGraphFromPrompt(req: GraphWizardRequest, deps: Gra
   const kind: GraphKind = req.kind === 'workflow' ? 'workflow' : 'harness';
   const prompt = typeof req.prompt === 'string' ? req.prompt.trim() : '';
   if (!prompt) throw new GraphWizardInputError('prompt is required');
+  if (req.packId !== undefined && kind !== 'harness') throw new GraphWizardInputError('pack selection requires a harness graph');
+  let evidence: string | undefined;
+  if (req.packId !== undefined) {
+    if (!parsePackIdString(req.packId) || !wizardInstalledPacks(deps).some(pack => pack.id === req.packId))
+      throw new GraphWizardInputError(`pack not installed: ${req.packId}`);
+    const cards = (deps.searchPack ?? queryInstalledPack)(req.packId, prompt);
+    if (!cards.length) throw new GraphWizardInputError(`no knowledge found in ${req.packId} for: ${prompt}`);
+    evidence = cards.slice(0, 5).map(card => `[${card.ref}] ${card.title}: ${card.body.slice(0, 1200)}`).join('\n');
+  }
   const editing = typeof req.currentYaml === 'string' && req.currentYaml.trim() !== '';
   const graphsDir = deps.graphsDir ?? defaultGraphsDir();
   const templates = kind === 'harness' ? listWizardTemplates(graphsDir) : [];
@@ -497,7 +521,7 @@ export async function generateGraphFromPrompt(req: GraphWizardRequest, deps: Gra
   for (attempts = 1; attempts <= maxAttempts; attempts += 1) {
     let text: string;
     try {
-      text = await callLLM(buildPrompt({ req: { ...req, prompt }, kind, id, base: keywordBase, templates,
+      text = await callLLM(buildPrompt({ req: { ...req, prompt }, kind, id, base: keywordBase, templates, evidence,
         ...(attempts > 1 ? { previous: { yaml, issues } } : {}) }));
     } catch (error) {
       debug.log('graph.wizard', 'error', { id, kind, attempt: attempts, base, message: error instanceof Error ? error.message : String(error) });
@@ -514,6 +538,14 @@ export async function generateGraphFromPrompt(req: GraphWizardRequest, deps: Gra
     try { issues = validateWizardYaml(kind, yaml); }
     catch (error) { issues = [`검증 실패: ${error instanceof Error ? error.message : String(error)}`]; }
     steps = kind === 'harness' ? parseNodeAnnotations(yaml) : {};
+    if (req.packId && issues.length === 0) {
+      const raw = parseYaml(yaml) as { nodes?: Array<{ node_id: string; recipe: string }>; edges?: Array<{ from: string; map?: Record<string, string> }> };
+      const rag = (raw.nodes ?? []).find(node => node.recipe.startsWith('cmd:') && steps[node.node_id]?.step === 'knowledge-rag' && steps[node.node_id]?.arg === req.packId);
+      if (!rag || !(raw.edges ?? []).some(edge => edge.from === rag.node_id &&
+        typeof edge.map?.ok === 'string' && !['done', 'failed'].includes(edge.map.ok) &&
+        (raw.nodes ?? []).some(node => node.node_id === edge.map!.ok && node.recipe.startsWith('cmd:'))))
+        issues.push(`선택한 팩 ${req.packId} 의 knowledge-rag 노드를 산출 단계에 연결하라`);
+    }
     recipes = undefined;
     dryRun = undefined;
     if (kind === 'harness' && issues.length === 0) {

package/src/graph-wizard/steps.ts

@@ -9,6 +9,7 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { debug } from '../debug/log.js';
+import { queryInstalledPack } from '../knowledge/query.js';
 
 export interface WizardStepSpec {
   id: string;
@@ -28,6 +29,7 @@ export const WIZARD_STEPS: readonly WizardStepSpec[] = [
   { id: 'notify-me', use: '실패·포기 같은 사건을 나(대표)에게 알린다. arg = 알림 문구', outcomes: ['ok', 'fail'], timeoutMs: 60_000 },
   { id: 'gh-pr-review', use: 'GitHub PR 을 엘라누스 리뷰어로 리뷰한다. arg = PR 번호(없으면 실행 입력 input.pr). 결과 ok(must-fix 없음) · must-fix', outcomes: ['ok', 'must-fix', 'fail'], timeoutMs: 900_000 },
   { id: 'gh-pr-merge', use: 'GitHub PR 을 squash 머지한다. arg = PR 번호(없으면 input.pr)', outcomes: ['ok', 'fail'], timeoutMs: 300_000 },
+  { id: 'knowledge-rag', use: '설치된 지식 팩만 검색해 인용 가능한 근거를 낸다. arg = pack:<slug>@<version>; 실행 입력 input.query 또는 앞 단계 결과로 검색하며 둘 다 없으면 팩의 색인에서 가져온다', outcomes: ['ok', 'fail'], timeoutMs: 120_000 },
   { id: 'custom', use: '위 단계로 안 되는 외부 연동(노션·슬랙 업로드 등). 실행하면 «아직 구현되지 않음»으로 실패한다. arg = 무엇을 해야 하는지', outcomes: ['ok', 'fail'], timeoutMs: 60_000 },
 ];
 
@@ -140,6 +142,17 @@ export function runWizardStep(step: string, arg: string | undefined, ctx: GraphC
   const started = Date.now();
   let result: StepResult;
   switch (step) {
+    case 'knowledge-rag': {
+      const query = ctx.input && typeof ctx.input === 'object' && typeof (ctx.input as { query?: unknown }).query === 'string'
+        ? (ctx.input as { query: string }).query : prev.trim();
+      if (!arg) { result = { outcome: 'fail', error: 'knowledge-rag: pack id(arg) required' }; break; }
+      try {
+        const hits = queryInstalledPack(arg, query);
+        result = hits.length ? { outcome: 'ok', text: hits.slice(0, 5).map(hit => `[${hit.ref}] ${hit.title}: ${hit.body}`).join('\n') }
+          : { outcome: 'fail', error: `knowledge-rag: no matches in ${arg}` };
+      } catch (error) { result = { outcome: 'fail', error: error instanceof Error ? error.message : String(error) }; }
+      break;
+    }
     case 'web-search': {
       const query = arg?.trim() || (ctx.input && typeof ctx.input === 'object' && typeof (ctx.input as { query?: unknown }).query === 'string' ? (ctx.input as { query: string }).query : '');
       if (!query) { result = { outcome: 'fail', error: 'web-search: 검색어(arg)가 없다' }; break; }

package/src/harness/dispatch-backpressure.ts

@@ -0,0 +1,259 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync, readlinkSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { homedir } from 'node:os';
+import { logsDbPath, LogStore, type LogStoreRow, type LogQuery } from '../mss/logging/log-store.js';
+import { getUserConfig } from '../user-config.js';
+import { harnessQueuePath } from './harness-queue.js';
+import { leaseKubectl, measurePoolLease, recommendConcurrency } from '../task-orchestrator/surfaces/pod-lease.js';
+import { parsePodPool, resolvePodPoolSpec } from '../task-orchestrator/surfaces/pod-pool.js';
+import { listCodexAccountsInStore } from '../oauth/codex-account-store.js';
+import { defaultSshRunner, resolveParentHosts, type SshRunner } from '../task-agent/parent-host.js';
+
+export const BUILD_STOP = 4;
+export const BUILD_SLOW = 2;
+export const QUEUE_STOP = 8;
+export const QUEUE_SLOW = 4;
+export const UNKNOWN_CAP = 1;
+
+export type BackpressureSignal = number | 'unknown';
+export interface BackpressureSignals {
+  queueDepth: BackpressureSignal;
+  admitWaiting: BackpressureSignal;
+  admitStarvedOver30m: BackpressureSignal;
+  dockerBuilds: { local: BackpressureSignal; remote: BackpressureSignal };
+  podRecommended: BackpressureSignal;
+  staleParents: BackpressureSignal;
+  /**
+   * Parts that could not be measured while the signal's number is still a measured lower bound (e.g. the remote
+   * half of admitWaiting after an ssh failure, local half counted). Each part is an unknown (cap 1); the number
+   * still applies so measured saturation keeps winning.
+   */
+  unmeasured?: string[];
+}
+
+const constants = { BUILD_STOP, BUILD_SLOW, QUEUE_STOP, QUEUE_SLOW, UNKNOWN_CAP };
+const valid = (value: unknown): BackpressureSignal =>
+  typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 'unknown';
+
+/** Fixed, reviewable thresholds; observations are normalized before any arithmetic. */
+export function decideBackpressure(input: BackpressureSignals, { maxPerCycle = 6 }: { maxPerCycle?: number } = {}) {
+  const max = Number.isSafeInteger(maxPerCycle) && maxPerCycle >= 0 ? maxPerCycle : 6;
+  const signals: BackpressureSignals = {
+    queueDepth: valid(input.queueDepth), admitWaiting: valid(input.admitWaiting),
+    admitStarvedOver30m: valid(input.admitStarvedOver30m),
+    dockerBuilds: { local: valid(input.dockerBuilds?.local), remote: valid(input.dockerBuilds?.remote) },
+    podRecommended: valid(input.podRecommended), staleParents: valid(input.staleParents),
+  };
+  const unmeasured = Array.isArray(input.unmeasured) ? input.unmeasured.filter((part): part is string => typeof part === 'string' && part.length > 0) : [];
+  if (unmeasured.length) signals.unmeasured = unmeasured;
+  const reasons: string[] = [];
+  let budget = max;
+  const unknown = (name: string, value: BackpressureSignal) => {
+    if (value === 'unknown') { reasons.push(`unknown:${name}`); budget = Math.min(budget, UNKNOWN_CAP); }
+  };
+  for (const [name, value] of [
+    ['queueDepth', signals.queueDepth], ['admitWaiting', signals.admitWaiting],
+    ['admitStarvedOver30m', signals.admitStarvedOver30m],
+    ['dockerBuilds.local', signals.dockerBuilds.local], ['dockerBuilds.remote', signals.dockerBuilds.remote],
+    ['podRecommended', signals.podRecommended], ['staleParents', signals.staleParents],
+  ] as const) unknown(name, value);
+  for (const part of unmeasured) unknown(part, 'unknown');
+  // A measured part is a lower bound on the unmeasured whole (counts are ≥ 0), so measured saturation still wins
+  // over unknown: podRecommended alone bounds podRecommended−admitWaiting; one side's builds bound the total.
+  if (signals.podRecommended !== 'unknown') {
+    budget = Math.min(budget, Math.max(0, signals.podRecommended - (signals.admitWaiting === 'unknown' ? 0 : signals.admitWaiting)));
+    reasons.push('podRecommended−admitWaiting');
+  }
+  if (signals.admitStarvedOver30m !== 'unknown' && signals.admitStarvedOver30m >= 1) {
+    budget = 0; reasons.push('admit-starved');
+  }
+  if (signals.dockerBuilds.local !== 'unknown' || signals.dockerBuilds.remote !== 'unknown') {
+    // Each side is clamped at BUILD_STOP before adding: the sum stays a small safe integer and saturation is kept.
+    const side = (n: BackpressureSignal) => n === 'unknown' ? 0 : Math.min(n, BUILD_STOP);
+    const builds = side(signals.dockerBuilds.local) + side(signals.dockerBuilds.remote);
+    if (builds >= BUILD_SLOW) {
+      budget = Math.min(budget, builds >= BUILD_STOP ? 0 : Math.floor(max / 2));
+      reasons.push('docker-builds');
+    }
+  }
+  if (signals.queueDepth !== 'unknown' && signals.queueDepth >= QUEUE_SLOW) {
+    budget = Math.min(budget, signals.queueDepth >= QUEUE_STOP ? 0 : Math.floor(max / 2));
+    reasons.push('queue-depth');
+  }
+  if (signals.staleParents !== 'unknown' && signals.staleParents > 0) reasons.push(`stale-parents:${signals.staleParents}`);
+  return { launchBudget: Math.max(0, Math.min(max, Math.floor(budget))), reasons, signals, constants };
+}
+
+const LOG_LIMIT = 1000;
+const LOG_WINDOW_MS = 35 * 60_000;
+const WAIT_FRESH_MS = 5 * 60_000;
+const STARVED_MS = 30 * 60_000;
+const REMOTE_PS_MARKER = '__ELANOUS_BACKPRESSURE_PS__';
+
+type AdmissionRow = Pick<LogStoreRow, 'ts_ms' | 'data'>;
+export interface BackpressureReadDeps {
+  now?: () => number;
+  queue?: () => unknown;
+  podRecommended?: () => number | null;
+  logs?: (query: LogQuery) => readonly AdmissionRow[];
+  ps?: () => string;
+  currentVersion?: () => string;
+  parentHost?: () => { host: string; elanous?: string } | readonly { host: string; elanous?: string }[] | null;
+  ssh?: SshRunner;
+}
+
+function readQueue(): unknown {
+  return JSON.parse(readFileSync(harnessQueuePath(), 'utf8'));
+}
+
+/** Same pool, usage and recommendation inputs as pod lease status; DNS is deliberately skipped (no disposable Pod). */
+function readPodRecommendation(): number | null {
+  const config = getUserConfig();
+  const spec = resolvePodPoolSpec(undefined, process.env, () => config.harness?.podPool ?? config.pod?.pool);
+  const current = spec ? null : leaseKubectl(['config', 'current-context']);
+  const context = spec ?? (current?.status === 0 ? current.stdout.trim() : '');
+  if (!context) return null;
+  const members = parsePodPool(context);
+  const measure = measurePoolLease(members, { measureUsage: true, skipDnsProbe: true });
+  let accounts = -1;
+  try { accounts = listCodexAccountsInStore().length; } catch { /* Accounts are only observed, not a limit. */ }
+  return recommendConcurrency(measure, { capacity: members.reduce((sum, member) => sum + member.capacity, 0),
+    accounts, perAccount: config.pod?.lease?.perAccount ?? 4 }).recommended;
+}
+
+function readLocalAdmission(query: LogQuery): readonly AdmissionRow[] {
+  const store = LogStore.openReadOnly(logsDbPath());
+  try { return store.query(query); } finally { store.close(); }
+}
+
+function processOutput(): string {
+  const result = spawnSync('ps', ['-Ao', 'command'], { encoding: 'utf8', timeout: 5_000, maxBuffer: 16 * 1024 * 1024 });
+  if (result.error || result.status !== 0 || typeof result.stdout !== 'string') throw new Error('ps unavailable');
+  return result.stdout;
+}
+
+/**
+ * Counts docker *client* processes only (argv[0] is `docker`): a wrapping `sh -c "… docker build …"` line
+ * (remote build.sh runs over ssh that way) and the `docker-buildx` plugin child would otherwise double-count one build.
+ * Rail bakes labelled `elanous.builder=rail` are excluded — only launch bakes slow launches (OP 02:06 review note).
+ */
+function countBuilds(ps: string): number {
+  return ps.split('\n').filter((line) => /^(?:\S*\/)?docker\s+(?:buildx\s+build|build)(?:\s|$)/.test(line.trim())
+    && !/elanous\.builder=rail(?:\s|$|['"])/.test(line)).length;
+}
+
+function countStaleParents(ps: string, version: string): number {
+  return ps.split('\n').filter((line) => /\bharness\s+(?:say|ask)\b/.test(line)
+    && /\/\.local\/share\/elanous\/versions\/([^/\s]+)\//.test(line)
+    && /\/\.local\/share\/elanous\/versions\/([^/\s]+)\//.exec(line)![1] !== version).length;
+}
+
+function admissionCounts(rows: readonly AdmissionRow[], now: number): { waiting: BackpressureSignal; starved: BackpressureSignal } {
+  if (!Array.isArray(rows) || rows.length >= LOG_LIMIT) return { waiting: 'unknown', starved: 'unknown' };
+  const byRun = new Map<string, { firstZero: number | null; last: number; recommended: number }>();
+  for (const row of [...rows].sort((a, b) => a.ts_ms - b.ts_ms)) {
+    let data: unknown;
+    try { data = typeof row.data === 'string' ? JSON.parse(row.data) : row.data; } catch { return { waiting: 'unknown', starved: 'unknown' }; }
+    const value = data as { runId?: unknown; recommended?: unknown } | null;
+    if (!value || typeof value !== 'object' || !Number.isFinite(row.ts_ms)) return { waiting: 'unknown', starved: 'unknown' };
+    // Rows without a runId come from non-run callers (`pod lease status`, this command's own pool read) — not a waiting
+    // parent. A null recommendation is an unmeasured sample, not «recommended 0». Neither is a parent wait signal.
+    if (typeof value.runId !== 'string' || !value.runId || value.recommended === null) continue;
+    if (!Number.isSafeInteger(value.recommended) || (value.recommended as number) < 0) return { waiting: 'unknown', starved: 'unknown' };
+    if (row.ts_ms < now - LOG_WINDOW_MS || row.ts_ms > now) continue;
+    const recommended = value.recommended as number;
+    const previous = byRun.get(value.runId);
+    // Starvation is a continuous zero streak: a recovery (recommended > 0) resets it.
+    byRun.set(value.runId, { firstZero: recommended === 0 ? previous?.firstZero ?? row.ts_ms : null,
+      last: row.ts_ms, recommended });
+  }
+  let waiting = 0, starved = 0;
+  for (const run of byRun.values()) {
+    if (run.recommended !== 0 || now - run.last > WAIT_FRESH_MS) continue;
+    waiting++;
+    if (run.firstZero !== null && now - run.firstZero >= STARVED_MS) starved++;
+  }
+  return { waiting, starved };
+}
+
+function readRemote(host: { host: string; elanous?: string }, ssh: SshRunner): { rows: AdmissionRow[]; ps: string } {
+  const executable = host.elanous ?? '$HOME/.local/share/elanous/bin/elanous';
+  const escaped = executable === '$HOME/.local/share/elanous/bin/elanous' ? '"$HOME"/.local/share/elanous/bin/elanous'
+    : `'${executable.replaceAll("'", "'\\''")}'`;
+  const script = `${escaped} logs --event admit-by-usage --since 35m --json --limit ${LOG_LIMIT}; rc=$?; if [ "$rc" -ne 0 ]; then exit "$rc"; fi; printf '\\n${REMOTE_PS_MARKER}\\n'; ps -Ao command`;
+  const result = ssh(host.host, script, 15_000);
+  if (result.status !== 0) throw new Error(`remote observation unavailable: ${result.stderr}`);
+  if (typeof result.stdout !== 'string') throw new Error('remote observation missing stdout');
+  const index = result.stdout.indexOf(`\n${REMOTE_PS_MARKER}\n`);
+  if (index < 0) throw new Error('remote observation incomplete');
+  const logs = result.stdout.slice(0, index);
+  const ps = result.stdout.slice(index + REMOTE_PS_MARKER.length + 2);
+  if (!ps.trim()) throw new Error('remote ps unavailable');
+  const rows: AdmissionRow[] = [];
+  for (const line of logs.split('\n').filter(Boolean)) {
+    const row = JSON.parse(line) as Record<string, unknown>;
+    if (row._meta && typeof row._meta === 'object' && (row._meta as { limitReached?: boolean }).limitReached === true) throw new Error('remote logs truncated');
+    if (row._meta) continue;
+    if (row.event !== 'admit-by-usage' || row.category !== 'pod-lease') throw new Error('remote logs invalid row');
+    const ms = typeof row.ts_ms === 'number' ? row.ts_ms : Date.parse(String(row.ts ?? ''));
+    rows.push({ ts_ms: ms, data: typeof row.data === 'string' ? row.data : JSON.stringify(row.data ?? null) });
+  }
+  if (rows.length >= LOG_LIMIT) throw new Error('remote logs truncated');
+  return { rows, ps };
+}
+
+/** All probes are injectable; a failed individual observation is unknown, not a false zero. */
+export function readBackpressureSignals(deps: BackpressureReadDeps = {}): BackpressureSignals {
+  const now = (deps.now ?? Date.now)();
+  if (!Number.isFinite(now)) throw new Error('backpressure clock unavailable');
+  const query: LogQuery = { exactCategories: ['pod-lease'], events: ['admit-by-usage'], sinceMs: now - LOG_WINDOW_MS, limit: LOG_LIMIT };
+  const attempt = <T>(fn: () => T, fallback: T): T => { try { return fn(); } catch { return fallback; } };
+  const queue = attempt(() => (deps.queue ?? readQueue)(), null);
+  const queueDepth = Array.isArray(queue) && queue.every((row) => row && typeof row === 'object'
+    && ['queued', 'launching', 'launched', 'finished'].includes(row.status))
+    ? queue.filter((row) => row.status === 'queued' || row.status === 'launching').length : 'unknown';
+  const podRecommended = valid(attempt(() => (deps.podRecommended ?? readPodRecommendation)(), null));
+  const local = attempt(() => admissionCounts((deps.logs ?? readLocalAdmission)(query), now), { waiting: 'unknown', starved: 'unknown' } as ReturnType<typeof admissionCounts>);
+  const localPs = attempt(() => (deps.ps ?? processOutput)(), null);
+  const localBuilds = typeof localPs === 'string' ? countBuilds(localPs) : 'unknown';
+  const current = attempt(() => (deps.currentVersion ?? (() => basename(readlinkSync(join(homedir(), '.local/share/elanous/current')))))(), null);
+  const staleParents = typeof localPs !== 'string' || !current ? 'unknown' : countStaleParents(localPs, current);
+  // `null` = no parent host configured (remote share is 0, not unknown); a failed config/host read is unknown.
+  const configured = attempt<{ host: string; elanous?: string } | readonly { host: string; elanous?: string }[] | null | 'unknown'>(
+    () => (deps.parentHost ?? (() => resolveParentHosts(getUserConfig().taskAgent?.parentHost)))(), 'unknown');
+  const hosts = configured === 'unknown' || configured === null ? [] : Array.isArray(configured) ? configured : [configured as { host: string; elanous?: string }];
+  let waiting = 0, starved = 0, builds = 0;
+  let measuredHosts = 0;
+  let missingRemote = configured === 'unknown';
+  for (const host of hosts) {
+    try {
+      const observed = readRemote(host, deps.ssh ?? defaultSshRunner);
+      const counts = admissionCounts(observed.rows, now);
+      if (counts.waiting === 'unknown' || counts.starved === 'unknown') missingRemote = true;
+      else { waiting += counts.waiting; starved += counts.starved; measuredHosts++; }
+      builds += countBuilds(observed.ps);
+    } catch { missingRemote = true; }
+  }
+  const remote: ReturnType<typeof admissionCounts> = missingRemote && measuredHosts === 0
+    ? { waiting: 'unknown', starved: 'unknown' } : { waiting, starved };
+  const remoteBuilds: BackpressureSignal = missingRemote ? 'unknown' : builds;
+  // One measured half is a lower bound on the total: keep it (so a measured local starvation still stops launches)
+  // and name the missing half in `unmeasured` (so the unknown cap still applies).
+  const unmeasured: string[] = [];
+  const add = (name: string, a: BackpressureSignal, b: BackpressureSignal): BackpressureSignal => {
+    if (configured === null || (Array.isArray(configured) && configured.length === 0)) return a; // no remote half exists
+    if (a === 'unknown' && b === 'unknown') return 'unknown';
+    if (a === 'unknown') { unmeasured.push(`${name}.local`); return b; }
+    if (b === 'unknown') { unmeasured.push(`${name}.remote`); return a; }
+    return valid(a + b);
+  };
+  const admitWaiting = add('admitWaiting', local.waiting, remote.waiting);
+  const admitStarvedOver30m = add('admitStarvedOver30m', local.starved, remote.starved);
+  if (missingRemote && hosts.length) {
+    if (!unmeasured.includes('admitWaiting.remote')) unmeasured.push('admitWaiting.remote');
+    if (!unmeasured.includes('admitStarvedOver30m.remote')) unmeasured.push('admitStarvedOver30m.remote');
+  }
+  return { queueDepth, podRecommended, admitWaiting, admitStarvedOver30m,
+    dockerBuilds: { local: localBuilds, remote: remoteBuilds }, staleParents, ...(unmeasured.length ? { unmeasured } : {}) };
+}