elanous 0.2.38 → 0.2.40

package/src/intake-plane/intake-to-tasks.ts

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
 import { debug } from '../debug/log.js';
 import type { TaskPriority } from '../task-orchestrator/types.js';
@@ -71,15 +71,187 @@ export function interpretIntakeInput(response: string): IntakeInputInterpretatio
   return { tasks, questions };
 }
 
+export const CHANNEL_PUBLISH_APPROVAL_CATEGORIES = ['first-release', 'patent', 'external-contract'] as const;
+export const CHANNEL_PUBLISH_CROWN_OWNER = '\u{1F451}';
+export type ChannelPublishApprovalCategory = (typeof CHANNEL_PUBLISH_APPROVAL_CATEGORIES)[number];
+export type ChannelPublishStatus = 'queued' | 'approved' | 'published';
+type ChannelPublishApproval = { kind: 'automatic' } | { kind: 'human'; approvedBy: string };
+
+export interface ChannelPublishDraft {
+  channel: string;
+  cadence: string;
+  voice: string;
+  owner: string;
+  category: ChannelPublishApprovalCategory | (string & {});
+  title: string;
+  body: string;
+}
+
+export interface ChannelPublishPlan extends ChannelPublishDraft {
+  status: ChannelPublishStatus;
+  approvedBy?: string;
+}
+
+export interface ChannelPublishConnector {
+  publish(plan: ChannelPublishPlan): Promise<{ publishedId: string }>;
+}
+
+// MK·crown 소유자의 첫 공개·특허·외부 계약 초안은 사람 승인 전 자동 승인하지 않는다.
+export function isChannelPublishApprovable(draft: ChannelPublishDraft): boolean {
+  if (draft.owner !== 'MK' && draft.owner !== CHANNEL_PUBLISH_CROWN_OWNER) return true;
+  return !(CHANNEL_PUBLISH_APPROVAL_CATEGORIES as readonly string[]).includes(draft.category);
+}
+
+export function toChannelPublishDraft(row: Record<string, unknown>): ChannelPublishDraft | null {
+  const text = (key: string, max: number): string | null => {
+    const value = row[key];
+    if (typeof value !== 'string') return null;
+    const trimmed = value.trim();
+    return trimmed && trimmed.length <= max ? trimmed : null;
+  };
+  const channel = text('channel', 200);
+  const cadence = text('cadence', 200);
+  const voice = text('voice', 200);
+  const owner = text('owner', 200);
+  const category = text('category', 200);
+  const title = text('title', TASK_DEFAULTS.titleMaxLen);
+  const body = text('body', TASK_DEFAULTS.descriptionMaxLen);
+  if (!channel || !cadence || !voice || !owner || !category || !title || !body) return null;
+  return { channel, cadence, voice, owner, category, title, body };
+}
+
+function isChannelPublishPlan(value: unknown): value is ChannelPublishPlan {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const plan = value as Record<string, unknown>;
+  return toChannelPublishDraft(plan) !== null
+    && (plan.status === 'queued' || plan.status === 'approved' || plan.status === 'published')
+    && (plan.approvedBy === undefined || typeof plan.approvedBy === 'string');
+}
+
+export class ChannelPublishQueue {
+  readonly queueDir: string;
+  readonly publishedFile: string;
+
+  constructor(instanceRoot: string) {
+    this.queueDir = join(intakeLedgerDir(instanceRoot), 'channel-publish', 'queue');
+    this.publishedFile = join(intakeLedgerDir(instanceRoot), 'channel-publish', 'published.jsonl');
+    mkdirSync(this.queueDir, { recursive: true, mode: 0o700 });
+  }
+
+  entryPath(id: string): string {
+    return join(this.queueDir, `${createHash('sha256').update(`channel:${id}`).digest('hex')}.json`);
+  }
+
+  tryAcquirePublish(id: string): (() => void) | null {
+    const path = `${this.entryPath(id)}.publishing`;
+    const token = randomUUID();
+    // Do not auto-steal stale locks: a takeover race could duplicate an irreversible external post.
+    // If a process dies mid-publish, reconcile the approved queue entry and lock explicitly.
+    let fd: number;
+    try {
+      fd = openSync(path, 'wx', 0o600);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'EEXIST') return null;
+      throw error;
+    }
+    try { writeFileSync(fd, token); }
+    catch (error) { rmSync(path, { force: true }); throw error; }
+    finally { closeSync(fd); }
+    return () => {
+      // Never let a late releaser remove a lock created by another publisher.
+      try {
+        if (readFileSync(path, 'utf8') === token) rmSync(path);
+      } catch { /* The lock is already gone; leave a replacement untouched. */ }
+    };
+  }
+
+  plan(id: string): ChannelPublishPlan | null {
+    const path = this.entryPath(id);
+    if (!existsSync(path)) return null;
+    const value: unknown = JSON.parse(readFileSync(path, 'utf8'));
+    if (!isChannelPublishPlan(value)) throw new Error('invalid channel publish plan');
+    return value;
+  }
+
+  entries(): ChannelPublishPlan[] {
+    return readdirSync(this.queueDir).filter((name) => /^[a-f0-9]{64}\.json$/.test(name))
+      .map((name) => {
+        const value: unknown = JSON.parse(readFileSync(join(this.queueDir, name), 'utf8'));
+        if (!isChannelPublishPlan(value)) throw new Error('invalid channel publish plan');
+        return value;
+      });
+  }
+
+  count(): number { return this.entries().length; }
+
+  publishedIds(): Set<string> {
+    if (!existsSync(this.publishedFile)) return new Set();
+    const ids = new Set<string>();
+    for (const line of readFileSync(this.publishedFile, 'utf8').split('\n')) {
+      try {
+        const row: unknown = JSON.parse(line);
+        if (row && typeof row === 'object' && !Array.isArray(row) && typeof (row as Record<string, unknown>).id === 'string') {
+          ids.add((row as { id: string }).id);
+        }
+      } catch { /* ignore incomplete ledger lines */ }
+    }
+    return ids;
+  }
+
+  enqueue(id: string, draft: ChannelPublishDraft): ChannelPublishPlan {
+    if (this.publishedIds().has(id)) return { ...draft, status: 'published' };
+    const existing = this.plan(id);
+    if (existing) return existing;
+    const plan: ChannelPublishPlan = { ...draft, status: 'queued' };
+    this.savePlan(id, plan);
+    return plan;
+  }
+
+  approve(id: string, plan: ChannelPublishPlan, approval: ChannelPublishApproval): ChannelPublishPlan {
+    if (plan.status !== 'queued') return plan;
+    if (!isChannelPublishApprovable(plan) && approval.kind !== 'human') return plan;
+    if (approval.kind === 'human' && approval.approvedBy !== 'MK' && approval.approvedBy !== CHANNEL_PUBLISH_CROWN_OWNER) return plan;
+    const approvedBy = approval.kind === 'human' ? approval.approvedBy : 'automation';
+    const approved: ChannelPublishPlan = { ...plan, status: 'approved', approvedBy };
+    this.savePlan(id, approved);
+    return approved;
+  }
+
+  savePlan(id: string, plan: ChannelPublishPlan): void {
+    const path = this.entryPath(id);
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    writeFileSync(temporary, JSON.stringify(plan));
+    renameSync(temporary, path);
+  }
+
+  recordPublished(id: string, plan: ChannelPublishPlan, publishedId: string): void {
+    // Ledger first, then remove the plan: a crash between the connector call and this append may
+    // republish (at-least-once), matching the HookQueue queue-file/seen ordering across restarts.
+    appendFileSync(this.publishedFile, JSON.stringify({ id, channel: plan.channel, publishedId }) + '\n');
+    rmSync(this.entryPath(id), { force: true });
+  }
+}
+
+/** Explicit approval entry point for a human-controlled API, CLI, or UI action. */
+export function approveChannelPublish(instanceRoot: string, id: string, approvedBy: string): ChannelPublishPlan | null {
+  const queue = new ChannelPublishQueue(instanceRoot);
+  const plan = queue.plan(id);
+  if (!plan || plan.status !== 'queued' || isChannelPublishApprovable(plan)
+    || (approvedBy !== 'MK' && approvedBy !== CHANNEL_PUBLISH_CROWN_OWNER)) return null;
+  return queue.approve(id, plan, { kind: 'human', approvedBy });
+}
+
 export type IntakeTaskInput =
   | { kind: 'goal-line'; id: string; fact: string; current: string; url?: string }
-  | { kind: 'idea-note'; id: string; content: string; url?: string };
+  | { kind: 'idea-note'; id: string; content: string; url?: string }
+  | { kind: 'channel-post'; id: string; draft: ChannelPublishDraft | null };
 
 export interface IntakeToTasksDeps {
   llm: (input: IntakeTaskInput) => Promise<string>;
   post: (request: IntakeTaskRequest) => Promise<{ taskId: string; deduplicated?: boolean }>;
   list?: typeof listIntakeItems;
   readNote?: (path: string) => string;
+  connector?: ChannelPublishConnector;
 }
 
 export interface IntakeToTasksResult {
@@ -87,7 +259,19 @@ export interface IntakeToTasksResult {
   created: number;
   skipped: number;
   failed: number;
-  items: Array<{ id: string; status: 'created' | 'deduplicated' | 'dry-run' | 'skipped' | 'failed'; taskId?: string; types?: IntakeTaskType[]; reason?: string }>;
+  items: Array<{
+    id: string;
+    status: 'created' | 'deduplicated' | 'dry-run' | 'skipped' | 'failed' | 'queued' | 'approved' | 'published';
+    taskId?: string;
+    types?: IntakeTaskType[];
+    reason?: string;
+    channel?: string;
+    cadence?: string;
+    voice?: string;
+    owner?: string;
+    category?: string;
+    publishedId?: string;
+  }>;
 }
 
 export function interpretIntakeItem(response: string): IntakeTaskInterpretation | null {
@@ -180,6 +364,10 @@ function goalLines(root: string): IntakeTaskInput[] {
         const value: unknown = JSON.parse(line);
         if (!value || typeof value !== 'object' || Array.isArray(value)) return;
         const row = value as Record<string, unknown>;
+        if (row.kind === 'channel-post') {
+          rows.push({ kind: 'channel-post', id: goalLineId(file, index), draft: toChannelPublishDraft(row) });
+          return;
+        }
         if (typeof row.fact !== 'string' || !row.fact.trim()) return;
         rows.push({ kind: 'goal-line', id: goalLineId(file, index), fact: row.fact, current: typeof row.current === 'string' ? row.current : '',
           ...(typeof row.url === 'string' ? { url: row.url } : {}) });
@@ -240,6 +428,61 @@ export async function runIntakeToTasks(
     .filter(({ input }) => !consumed.has(input.id)).slice(0, limit);
   const result: IntakeToTasksResult = { processed: selected.length, created: 0, skipped: 0, failed: 0, items: [] };
   for (const { input, path } of selected) {
+    if (input.kind === 'channel-post') {
+      if (opts.dryRun) {
+        result.items.push({ id: input.id, status: 'dry-run' });
+        continue;
+      }
+      if (!input.draft) {
+        result.skipped++;
+        result.items.push({ id: input.id, status: 'skipped', reason: 'invalid-channel-post-draft' });
+        continue;
+      }
+      const queue = new ChannelPublishQueue(instanceRoot);
+      try {
+        const queued = queue.enqueue(input.id, input.draft);
+        const plan = isChannelPublishApprovable(queued) ? queue.approve(input.id, queued, { kind: 'automatic' }) : queued;
+        if (plan.status === 'published') {
+          // Crash between the publish ledger and the consumed ledger: the post is already out.
+          appendFileSync(consumedFile(instanceRoot), JSON.stringify({ id: input.id }) + '\n');
+          result.items.push({ id: input.id, status: 'published', channel: plan.channel, cadence: plan.cadence, voice: plan.voice });
+          continue;
+        }
+        if (plan.status === 'approved' && deps.connector) {
+          const release = queue.tryAcquirePublish(input.id);
+          if (release) {
+            try {
+              // Recheck under the per-item lock; another process may have completed before it was acquired.
+              const current = queue.plan(input.id);
+              if (current?.status === 'approved' && !queue.publishedIds().has(input.id)) {
+                const { publishedId } = await deps.connector.publish(current);
+                queue.recordPublished(input.id, current, publishedId);
+                appendFileSync(consumedFile(instanceRoot), JSON.stringify({ id: input.id, publishedId }) + '\n');
+                result.items.push({
+                  id: input.id, status: 'published', channel: current.channel, cadence: current.cadence,
+                  voice: current.voice, owner: current.owner, category: current.category, publishedId,
+                });
+                continue;
+              }
+              if (queue.publishedIds().has(input.id)) {
+                appendFileSync(consumedFile(instanceRoot), JSON.stringify({ id: input.id }) + '\n');
+                result.items.push({ id: input.id, status: 'published', channel: plan.channel, cadence: plan.cadence, voice: plan.voice });
+                continue;
+              }
+            } finally { release(); }
+          }
+          // Another process owns the publish attempt. Leave this item approved for its next pass.
+          result.items.push({ id: input.id, status: 'approved', channel: plan.channel, cadence: plan.cadence, voice: plan.voice });
+          continue;
+        }
+        result.items.push({ id: input.id, status: plan.status, channel: plan.channel, cadence: plan.cadence, voice: plan.voice });
+      } catch {
+        result.failed++;
+        result.items.push({ id: input.id, status: 'failed', reason: 'channel publish failed' });
+        debug.log('intake.to-tasks', 'channel-publish-failed', { id: input.id });
+      }
+      continue;
+    }
     try {
       let plan = loadTaskPlan(instanceRoot, input.id);
       if (!plan) {

package/src/lessons/friction-ledger.ts

@@ -0,0 +1,154 @@
+import { Database } from 'bun:sqlite';
+import { chmodSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { debug } from '../debug/log.js';
+import type { LessonLedgerOptions } from './lesson-ledger.js';
+
+export type FrictionActor = 'OP' | 'TC' | 'MK' | 'UX' | 'ceo' | 'person';
+export type FrictionKind = 'hand-step' | 'ceo-correction' | 'repeat-question';
+
+export const FRICTION_ACTORS: readonly FrictionActor[] = ['OP', 'TC', 'MK', 'UX', 'ceo', 'person'];
+export const FRICTION_KINDS: readonly FrictionKind[] = ['hand-step', 'ceo-correction', 'repeat-question'];
+export const FRICTION_CANDIDATE_MIN = 3;
+
+export interface FrictionRecordInput {
+  actor: FrictionActor;
+  kind: FrictionKind;
+  signature: string;
+  note?: string;
+  ref: string;
+}
+
+export interface FrictionRow {
+  id: number;
+  actor: FrictionActor;
+  kind: FrictionKind;
+  signature: string;
+  note: string;
+  ref: string;
+  recorded_at: string;
+}
+
+export interface FrictionCandidate {
+  kind: FrictionKind;
+  signature: string;
+  count: number;
+  firstAt: string;
+  lastAt: string;
+  refs: string[];
+}
+
+export class FrictionInputError extends Error {
+  override name = 'FrictionInputError';
+}
+
+/** Secret-shaped note bodies are never persisted: a token or key would be copied into the ledger. */
+const SECRET_PATTERNS: readonly RegExp[] = [
+  /sk-[A-Za-z0-9_-]{8,}/u,
+  /(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{8,}/u,
+  /AKIA[0-9A-Z]{12,}/u,
+  /xox[bapr]-[A-Za-z0-9-]{8,}/u,
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----/u,
+  /\b[0-9a-f]{32,}\b/u,
+  /\b[A-Za-z0-9+/=_-]{40,}\b/u,
+  /(?:api[_-]?key|access[_-]?key|token|secret|password)\s*[:=]\s*\S{8,}/iu,
+];
+
+function required(value: unknown, field: string): string {
+  if (typeof value !== 'string' || !value.trim()) throw new FrictionInputError(`${field} is required`);
+  return value.trim();
+}
+
+function checkActor(value: FrictionActor): FrictionActor {
+  if (!FRICTION_ACTORS.includes(value)) throw new FrictionInputError(`actor must be one of ${FRICTION_ACTORS.join(', ')}`);
+  return value;
+}
+
+function checkKind(value: FrictionKind): FrictionKind {
+  if (!FRICTION_KINDS.includes(value)) throw new FrictionInputError(`kind must be one of ${FRICTION_KINDS.join(', ')}`);
+  return value;
+}
+
+/** Same hand step spelled differently is the same hand step: lower case, whitespace runs folded to one space. */
+function normalizeSignature(value: unknown): string {
+  const signature = required(value, 'signature').replace(/\s+/gu, ' ').toLowerCase();
+  if (!signature) throw new FrictionInputError('signature is required');
+  return signature;
+}
+
+export function frictionActor(name: string): FrictionActor {
+  const key = name.trim().toLowerCase();
+  return FRICTION_ACTORS.find(actor => actor.toLowerCase() === key) ?? 'person';
+}
+
+function secretFreeNote(note: unknown): string {
+  const text = note === undefined || note === null ? '' : String(note);
+  if (SECRET_PATTERNS.some(pattern => pattern.test(text))) throw new FrictionInputError('note looks like a secret (token or key)');
+  return text;
+}
+
+export class FrictionLedger {
+  readonly path: string;
+  private readonly now: () => Date;
+
+  constructor(options: LessonLedgerOptions = {}) {
+    this.path = join(options.stateDir ?? elanousStateRoot(), 'lessons', 'friction.sqlite');
+    this.now = options.now ?? (() => new Date());
+  }
+
+  private open(): Database {
+    mkdirSync(dirname(this.path), { recursive: true });
+    const db = new Database(this.path, { create: true, strict: true });
+    try {
+      chmodSync(this.path, 0o600);
+      db.exec('PRAGMA busy_timeout = 10000');
+      db.exec('PRAGMA journal_mode = WAL');
+      db.exec(`CREATE TABLE IF NOT EXISTS friction (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        actor TEXT NOT NULL CHECK(actor IN ('OP','TC','MK','UX','ceo','person')),
+        kind TEXT NOT NULL CHECK(kind IN ('hand-step','ceo-correction','repeat-question')),
+        signature TEXT NOT NULL, note TEXT NOT NULL DEFAULT '', ref TEXT NOT NULL, recorded_at TEXT NOT NULL);
+        CREATE INDEX IF NOT EXISTS friction_group ON friction (kind, signature);`);
+      return db;
+    } catch (error) { db.close(); throw error; }
+  }
+
+  private using<T>(work: (db: Database) => T): T {
+    const db = this.open();
+    try { return work(db); } finally { db.close(); }
+  }
+
+  record(input: FrictionRecordInput): FrictionRow {
+    const actor = checkActor(input.actor);
+    const kind = checkKind(input.kind);
+    const signature = normalizeSignature(input.signature);
+    const note = secretFreeNote(input.note);
+    const ref = required(input.ref, 'ref');
+    return this.using(db => {
+      const at = this.now().toISOString();
+      const inserted = db.query('INSERT INTO friction (actor, kind, signature, note, ref, recorded_at) VALUES (?, ?, ?, ?, ?, ?)')
+        .run(actor, kind, signature, note, ref, at);
+      const row = db.query('SELECT id, actor, kind, signature, note, ref, recorded_at FROM friction WHERE id = ?')
+        .get(Number(inserted.lastInsertRowid)) as FrictionRow | null;
+      if (!row) throw new FrictionInputError('friction row was not stored');
+      debug.log('lessons.friction', 'record', { id: row.id, kind: row.kind, actor: row.actor });
+      return row;
+    });
+  }
+
+  /** Same hand step three times is a proposal candidate (§4⑤ SELF-PROPOSE-BASE), not one-off noise. */
+  candidates(min: number = FRICTION_CANDIDATE_MIN): FrictionCandidate[] {
+    if (!Number.isInteger(min) || min < 1) throw new FrictionInputError('min must be a positive integer');
+    return this.using(db => {
+      const groups = db.query(`SELECT kind, signature, count(*) AS count, min(recorded_at) AS firstAt, max(recorded_at) AS lastAt
+        FROM friction GROUP BY kind, signature HAVING count(*) >= ?
+        ORDER BY count DESC, lastAt DESC, kind, signature`).all(min) as Omit<FrictionCandidate, 'refs'>[];
+      return groups.map(group => ({
+        ...group,
+        refs: (db.query('SELECT ref FROM friction WHERE kind = ? AND signature = ? ORDER BY id')
+          .all(group.kind, group.signature) as { ref: string }[]).map(row => row.ref),
+      }));
+    });
+  }
+}

package/src/live-supply/collector.ts

@@ -0,0 +1,149 @@
+import { appendFileSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getElanousConfigDir } from '../elanous-config-dir.js';
+import { SUPPLY_AXES, type LiveSupplySnapshot, type SupplyAxis, type SupplyEvent, type SupplyProbes, type SupplySourceState, type SupplyValues } from './snapshot.js';
+
+export interface SupplyCollectorOptions {
+  directory?: string;
+  now?: () => number;
+  intervalMs?: number;
+  probeTimeoutMs?: number;
+  setInterval?: typeof globalThis.setInterval;
+  clearInterval?: typeof globalThis.clearInterval;
+}
+
+function readLatest(path: string): LiveSupplySnapshot | null {
+  try {
+    const row = JSON.parse(readFileSync(path, 'utf8')) as LiveSupplySnapshot;
+    return row.version === 1 && Number.isSafeInteger(row.sequence) ? row : null;
+  } catch { return null; }
+}
+
+/** A failed source retains its last value only with a stale label. Each tick commits before it publishes events. */
+export class LiveSupplyCollector {
+  readonly directory: string;
+  private readonly now: () => number;
+  private readonly intervalMs: number;
+  private readonly probeTimeoutMs: number;
+  private readonly setInterval: typeof globalThis.setInterval;
+  private readonly clearInterval: typeof globalThis.clearInterval;
+  private latest: LiveSupplySnapshot | null;
+  private hasFreshTick = false;
+  private pending: Promise<LiveSupplySnapshot> | null = null;
+  private timer: ReturnType<typeof globalThis.setInterval> | null = null;
+
+  constructor(private readonly probes: SupplyProbes, options: SupplyCollectorOptions = {}) {
+    this.directory = options.directory ?? join(getElanousConfigDir(), 'live-supply');
+    this.now = options.now ?? Date.now;
+    this.intervalMs = options.intervalMs ?? 60_000;
+    this.probeTimeoutMs = options.probeTimeoutMs ?? 10_000;
+    this.setInterval = options.setInterval ?? globalThis.setInterval;
+    this.clearInterval = options.clearInterval ?? globalThis.clearInterval;
+    this.latest = readLatest(join(this.directory, 'latest.json'));
+  }
+
+  /** Disk cache is diagnostic until a fresh tick; a restart never silently blesses old measurements. */
+  read(): LiveSupplySnapshot | null {
+    if (!this.latest) return null;
+    if (this.hasFreshTick && Date.parse(this.latest.expiresAt) > this.now()) return this.latest;
+    return {
+      ...this.latest,
+      sources: Object.fromEntries(SUPPLY_AXES.map(axis => [axis, {
+        ...this.latest!.sources[axis],
+        status: this.latest!.sources[axis].status === 'measured' ? 'stale' : this.latest!.sources[axis].status,
+      }])) as LiveSupplySnapshot['sources'],
+    };
+  }
+
+  async start(): Promise<LiveSupplySnapshot> {
+    const first = await this.tick();
+    if (this.timer === null) this.timer = this.setInterval(() => { void this.tick().catch(() => {}); }, this.intervalMs);
+    return first;
+  }
+
+  stop(): void {
+    if (this.timer !== null) this.clearInterval(this.timer);
+    this.timer = null;
+  }
+
+  tick(): Promise<LiveSupplySnapshot> {
+    if (this.pending) return this.pending;
+    const work = this.collect();
+    this.pending = work;
+    void work.finally(() => { if (this.pending === work) this.pending = null; }).catch(() => {});
+    return work;
+  }
+
+  private async collect(): Promise<LiveSupplySnapshot> {
+    const previous = this.latest;
+    const at = new Date(this.now()).toISOString();
+    const sources = {} as LiveSupplySnapshot['sources'];
+    const values: Partial<SupplyValues> = {};
+    const results = await Promise.all(SUPPLY_AXES.map(async axis => {
+      try { return { axis, value: await this.withTimeout(this.probes[axis]()), error: null }; }
+      catch (error) { return { axis, value: null, error: error instanceof Error ? error.message : 'probe-failed' }; }
+    }));
+    for (const result of results) {
+      const axis = result.axis;
+      if (result.error === null && result.value !== null) {
+        (values as Record<SupplyAxis, unknown>)[axis] = result.value;
+        sources[axis] = { status: 'measured', observedAt: at, reason: null };
+      } else {
+        const oldValue = previous?.values[axis];
+        if (oldValue !== undefined) (values as Record<SupplyAxis, unknown>)[axis] = oldValue;
+        const oldAt = previous?.sources[axis]?.observedAt ?? null;
+        sources[axis] = { status: oldValue === undefined ? 'unknown' : 'stale', observedAt: oldAt, reason: this.safeReason(result.error) };
+      }
+    }
+    const snapshot: LiveSupplySnapshot = {
+      version: 1, sequence: (previous?.sequence ?? 0) + 1, observedAt: at,
+      expiresAt: new Date(this.now() + this.intervalMs).toISOString(), sources, values,
+    };
+    const events = this.events(previous, snapshot);
+    mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+    const latestPath = join(this.directory, 'latest.json');
+    const tempPath = join(this.directory, `.latest.${process.pid}.${snapshot.sequence}.tmp`);
+    try {
+      appendFileSync(join(this.directory, 'snapshots.jsonl'), `${JSON.stringify(snapshot)}\n`, { mode: 0o600 });
+      writeFileSync(tempPath, JSON.stringify(snapshot), { mode: 0o600 });
+      renameSync(tempPath, latestPath);
+      this.latest = snapshot;
+      this.hasFreshTick = true;
+    } catch (error) {
+      // The pointer must never claim freshness after an unsuccessful commit.
+      this.latest = previous;
+      throw error;
+    }
+    if (events.length) appendFileSync(join(this.directory, 'events.jsonl'), events.map(event => JSON.stringify(event)).join('\n') + '\n', { mode: 0o600 });
+    return snapshot;
+  }
+
+  private withTimeout<T>(value: Promise<T> | T): Promise<T> {
+    return new Promise((resolve, reject) => {
+      const timer = globalThis.setTimeout(() => reject(new Error('probe-timeout')), this.probeTimeoutMs);
+      Promise.resolve(value).then(
+        result => { globalThis.clearTimeout(timer); resolve(result); },
+        error => { globalThis.clearTimeout(timer); reject(error); },
+      );
+    });
+  }
+
+  private safeReason(reason: string | null): string {
+    if (reason === 'probe-timeout') return reason;
+    return reason === null ? 'probe-unmeasured' : 'probe-failed';
+  }
+
+  private events(previous: LiveSupplySnapshot | null, next: LiveSupplySnapshot): SupplyEvent[] {
+    const rows: SupplyEvent[] = [];
+    for (const axis of SUPPLY_AXES) {
+      const before = previous?.sources[axis] as SupplySourceState | undefined;
+      const after = next.sources[axis];
+      if (after.status !== 'measured' && (before?.status !== after.status || before?.reason !== after.reason)) {
+        rows.push({ kind: 'supply.unmeasured', sequence: next.sequence, axis, from: before?.status ?? 'unknown', to: after.status, reason: after.reason, observedAt: next.observedAt });
+      } else if (before && (before.status !== after.status || JSON.stringify(previous?.values[axis]) !== JSON.stringify(next.values[axis]))) {
+        rows.push({ kind: 'supply.changed', sequence: next.sequence, axis, from: before.status, to: after.status, reason: null, observedAt: next.observedAt });
+      }
+    }
+    return rows;
+  }
+}

package/src/live-supply/probes.ts

@@ -0,0 +1,52 @@
+import { inspectCodexRotation, readCachedGrokQuota } from '../oauth/codex-account-store.js';
+import { readParentHostCapacity, type ParentHostConfig } from '../task-agent/parent-host.js';
+import { measureMemberOccupancy, parsePodPool } from '../task-orchestrator/surfaces/pod-pool.js';
+import type { SupplyProbes, SupplyValues } from './snapshot.js';
+
+/** Host credential and cost transports are caller-owned: this module never transfers secret material. */
+export interface SupplyProbeDependencies {
+  podPoolSpec: () => string | null;
+  parentHosts: () => readonly ParentHostConfig[];
+  readCost: () => Promise<SupplyValues['cost']> | SupplyValues['cost'];
+  readHostCredentials: () => Promise<SupplyValues['hostCredentials']> | SupplyValues['hostCredentials'];
+  inspectCodex?: typeof inspectCodexRotation;
+  grokQuota?: typeof readCachedGrokQuota;
+  occupancy?: typeof measureMemberOccupancy;
+  parentCapacity?: typeof readParentHostCapacity;
+}
+
+/** Existing provider and pool readers are projected to the no-secret supply contract. */
+export function createSupplyProbes(deps: SupplyProbeDependencies): SupplyProbes {
+  return {
+    codex: () => {
+      const state = (deps.inspectCodex ?? inspectCodexRotation)();
+      return { accounts: state.candidates.map(candidate => ({
+        name: candidate.name,
+        usedPercent: candidate.usedPercent ?? null,
+        signalAt: state.observedAtByHome[candidate.home] === undefined ? null : new Date(state.observedAtByHome[candidate.home]).toISOString(),
+        available: state.freshByHome[candidate.home] !== true ? null : candidate.reached === true ? false : null,
+      })) };
+    },
+    grok: () => ({ quota: (deps.grokQuota ?? readCachedGrokQuota)(), observedAt: null }),
+    cost: deps.readCost,
+    pool: () => {
+      const spec = deps.podPoolSpec();
+      if (!spec) throw new Error('pool-unconfigured');
+      const members = parsePodPool(spec);
+      const measured = (deps.occupancy ?? measureMemberOccupancy)(members);
+      return { members: members.map(member => ({
+        context: member.context, occupied: measured[member.context]?.occupied ?? null, capacity: member.capacity,
+      })) };
+    },
+    hostCredentials: deps.readHostCredentials,
+    parentHosts: () => ({ hosts: deps.parentHosts().map(host => {
+      const measurement = (deps.parentCapacity ?? readParentHostCapacity)(host);
+      return {
+        host: host.host,
+        approvalCapacity: host.approvalCapacity ?? 1,
+        active: measurement?.active ?? null,
+        headroom: measurement?.approvalHeadroom ?? null,
+      };
+    }) }),
+  };
+}