@ianwremmel/dispatch 0.32.1-bootstrap.0

package/src/lib/graph/rows.mts

@@ -0,0 +1,99 @@
+import type {Row} from '../db/database.mts';
+import {isOutcome, isStatus, isTargetKind} from '../model/status.mts';
+import type {
+  Classification,
+  ClassifiedItem,
+  ClaimView,
+  OutcomeView,
+} from './types.mts';
+
+/** SQLite hands values back loosely typed; these narrow without trusting a cast. */
+export function text(value: unknown): string | null {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'bigint')
+    return String(value);
+  return null;
+}
+
+export function integer(value: unknown): number {
+  if (typeof value === 'number') return value;
+  if (typeof value === 'bigint') return Number(value);
+  return 0;
+}
+
+export function splitList(value: unknown): string[] {
+  const joined = text(value);
+  return joined === null || joined === '' ? [] : joined.split(',');
+}
+
+export function toClaim(row: Row): ClaimView | null {
+  const session = text(row.claim_session);
+  if (session === null) return null;
+  return {
+    session,
+    live: integer(row.claim_live) === 1,
+    actor: text(row.claim_actor),
+    worktree: text(row.claim_worktree),
+    branch: text(row.claim_branch),
+    claimedAt: text(row.claim_claimed_at) ?? '',
+  };
+}
+
+export function toOutcome(row: Row): OutcomeView | null {
+  const outcome = text(row.outcome);
+  if (outcome === null || !isOutcome(outcome)) return null;
+  return {
+    outcome,
+    retryable:
+      row.outcome_retryable === null || row.outcome_retryable === undefined
+        ? null
+        : integer(row.outcome_retryable) === 1,
+    detail: text(row.outcome_detail),
+  };
+}
+
+export function toClassified(row: Row): ClassifiedItem {
+  const status = text(row.status);
+  const targetKind = text(row.target_kind);
+  const rawLabels: unknown = JSON.parse(text(row.labels) ?? '[]');
+  const blockedBy = splitList(row.blocked_by);
+  const gatedBy = splitList(row.gated_by);
+
+  return {
+    item: {
+      id: text(row.id) ?? '',
+      kind: text(row.kind) === 'pr' ? 'pr' : 'ticket',
+      ticket: text(row.ticket),
+      project: text(row.project),
+      url: text(row.url),
+      title: text(row.title) ?? '',
+      // The CHECK constraints validated these on the way in; the guards keep
+      // the types honest without trusting a cast.
+      status: status !== null && isStatus(status) ? status : null,
+      repo: text(row.repo),
+      prNumber:
+        row.pr_number === null || row.pr_number === undefined
+          ? null
+          : integer(row.pr_number),
+      targetKind:
+        targetKind !== null && isTargetKind(targetKind) ? targetKind : null,
+      requiresHuman: integer(row.requires_human) === 1,
+      injected: integer(row.injected) === 1,
+      priority: typeof row.priority === 'number' ? row.priority : null,
+      branchHint: text(row.branch_hint),
+      labels: Array.isArray(rawLabels)
+        ? rawLabels.filter(
+            (label): label is string => typeof label === 'string'
+          )
+        : [],
+      milestones: splitList(row.milestones),
+    },
+    classification: (text(row.classification) ?? 'dormant') as Classification,
+    effectiveBlocked: blockedBy.length > 0 || gatedBy.length > 0,
+    blockedBy,
+    gatedBy,
+    claim: toClaim(row),
+    outcome: toOutcome(row),
+    fanout: integer(row.fanout),
+  };
+}

package/src/lib/graph/types.mts

@@ -0,0 +1,137 @@
+import type {OutcomeKind, Status, TargetKind} from '../model/status.mts';
+
+/**
+ * §2.6-derived buckets, highest precedence first: resolved → in-flight →
+ * dormant → blocked → human-blocked → available.
+ */
+export const CLASSIFICATIONS = [
+  'verified',
+  'canceled',
+  'in-flight',
+  'dormant',
+  'blocked',
+  'human-blocked',
+  'available',
+] as const;
+export type Classification = (typeof CLASSIFICATIONS)[number];
+
+/** A dispatch that continues earlier work rather than starting fresh. */
+export const PASSES = ['resume', 'verify', 'finalize', 'retry'] as const;
+export type Pass = (typeof PASSES)[number];
+
+export interface DeriveOptions {
+  /** RFC 3339 instant used for claim staleness; defaults to now. */
+  now?: string | undefined;
+  /** A session heartbeat older than this makes its claims stale. */
+  staleAfterSeconds?: number | undefined;
+  /** Restrict scheduling reads to one project (external id). */
+  project?: string | undefined;
+}
+
+export interface ClaimView {
+  session: string;
+  live: boolean;
+  actor: string | null;
+  worktree: string | null;
+  branch: string | null;
+  claimedAt: string;
+}
+
+export interface OutcomeView {
+  outcome: OutcomeKind;
+  retryable: boolean | null;
+  detail: string | null;
+}
+
+/** One dispatchable work item: a ticket, or a PR item (bare or ticket-backed). */
+export interface WorkItem {
+  id: string;
+  kind: 'ticket' | 'pr';
+  /** The ticket a PR item implements; null for tickets and bare PRs. */
+  ticket: string | null;
+  /** Null for a bare PR. */
+  project: string | null;
+  url: string | null;
+  title: string;
+  /** Null for a bare PR — its lifecycle is its outcome row. */
+  status: Status | null;
+  /** `owner/name`, on a PR item that names one; null on a ticket. */
+  repo: string | null;
+  /** The forge's number, once a PR exists; null while the item is unopened. */
+  prNumber: number | null;
+  targetKind: TargetKind | null;
+  requiresHuman: boolean;
+  injected: boolean;
+  priority: number | null;
+  branchHint: string | null;
+  labels: string[];
+  milestones: string[];
+}
+
+export interface ClassifiedItem {
+  item: WorkItem;
+  classification: Classification;
+  effectiveBlocked: boolean;
+  /** Unresolved blocking ancestors, by external id. */
+  blockedBy: string[];
+  /** Milestones whose unfinished review gates this item, by external id. */
+  gatedBy: string[];
+  claim: ClaimView | null;
+  outcome: OutcomeView | null;
+  /** Transitive descendant count — how much work this item gates. */
+  fanout: number;
+}
+
+export interface QueueEntry {
+  entry: ClassifiedItem;
+  /** Null for ordinary available work; otherwise the follow-up pass. */
+  pass: Pass | null;
+}
+
+export interface MilestoneState {
+  id: string;
+  project: string;
+  name: string;
+  members: string[];
+  memberCount: number;
+  openCount: number;
+  readyForReview: boolean;
+  reviewRecorded: boolean;
+  /** Ready, reviewed, and no member carries an unresolved dependency. */
+  open: boolean;
+  claim: ClaimView | null;
+}
+
+export interface Anomaly {
+  kind: 'cycle' | 'dangling-edge' | 'cross-project-reverse';
+  nodes: string[];
+  detail: string;
+}
+
+export interface ClassificationCounts {
+  available: number;
+  blocked: number;
+  humanBlocked: number;
+  inFlight: number;
+  dormant: number;
+  verified: number;
+  canceled: number;
+}
+
+export interface ProjectCounts extends ClassificationCounts {
+  project: string;
+  total: number;
+  terminal: boolean;
+}
+
+export interface DerivedGraph {
+  projects: {id: string; name: string; terminal: boolean}[];
+  items: ClassifiedItem[];
+  milestones: MilestoneState[];
+  counts: ProjectCounts[];
+  /** PR work items — prompt-injected or ticket-registered. */
+  prs: ClassifiedItem[];
+  anomalies: Anomaly[];
+  /** Every selected project terminal and no PR item open. */
+  terminal: boolean;
+}

package/src/lib/liveness/CLAUDE.md

@@ -0,0 +1,14 @@
+# liveness
+
+Process-level liveness for session registry rows — the half heartbeat
+freshness cannot see. Servers record their own process start as
+`started_at`; the probe (`ps -o etime=`) reads the running process's start
+back and `sameProcess` compares the two, so a reused pid never resolves.
+
+The two consumers lean opposite ways. `withLiveProcesses` (matching) needs
+proof of life: anything unverifiable — another host, no pid, a failed probe
+— is dropped, because a false `active` strands a session while a false
+`inactive` only costs polling. `retireNonLive` (the server's startup sweep)
+needs proof of death: it deletes a row only for a stale heartbeat, a
+vanished pid, or a reused pid, and leaves what it merely cannot verify to
+the heartbeat sweep.

package/src/lib/liveness/index.mts

@@ -0,0 +1,10 @@
+export {
+  parseEtime,
+  probeProcessStart,
+  processStartIso,
+  provenReused,
+  sameProcess,
+  withLiveProcesses,
+} from './liveness.mts';
+export type {ProbeResult} from './liveness.mts';
+export {retireNonLive} from './retire.mts';

package/src/lib/liveness/liveness.mts

@@ -0,0 +1,147 @@
+import {execFile} from 'node:child_process';
+import {hostname} from 'node:os';
+import {promisify} from 'node:util';
+
+import type {Session} from '../model/types.mts';
+
+const exec = promisify(execFile);
+
+/**
+ * Slack when comparing a probed process start against the row's registered
+ * one: `ps -o etime=` has second granularity and the two readings happen at
+ * different moments. Kept small deliberately — a wider window would tolerate
+ * larger clock steps, but it would also accept a pid reused by a process
+ * that started near the registered instant, and a false "live" strands a
+ * session where a false "dead" only costs polling.
+ */
+const START_SLACK_MS = 2_000;
+
+/**
+ * What a probe learned about the process at `pid`: its start instant (epoch
+ * ms), `absent` when no such process exists, or `unknown` when the probe
+ * itself failed — `ps` missing or broken, or output it could not parse. The
+ * three-way split matters because matching and retiring lean opposite ways:
+ * a match needs proof of life, retirement needs proof of death, and
+ * `unknown` provides neither.
+ */
+export type ProbeResult = number | 'absent' | 'unknown';
+
+/** Parse `ps -o etime=` output — `[[dd-]hh:]mm:ss` — into seconds. */
+export function parseEtime(raw: string): number | null {
+  const match = /^(?:(?:(\d+)-)?(\d+):)?(\d+):(\d+)$/u.exec(raw.trim());
+  if (match === null) return null;
+  const [, days, hours, minutes, seconds] = match;
+  return (
+    Number(days ?? 0) * 86_400 +
+    Number(hours ?? 0) * 3_600 +
+    Number(minutes) * 60 +
+    Number(seconds)
+  );
+}
+
+/**
+ * The start instant this very process would register: what its pid must
+ * verify against when a later caller probes it.
+ */
+export function processStartIso(): string {
+  return new Date(Date.now() - process.uptime() * 1_000).toISOString();
+}
+
+/**
+ * POSIX `etime` rather than procps's `etimes`: macOS `ps` has no `etimes`
+ * keyword and would exit nonzero on every probe. `ps` rather than
+ * `process.kill(pid, 0)` because it also sees processes owned by other
+ * users, where the signal probe reports EPERM.
+ */
+export async function probeProcessStart(pid: number): Promise<ProbeResult> {
+  try {
+    const {stdout} = await exec('ps', ['-o', 'etime=', '-p', String(pid)]);
+    const elapsed = parseEtime(stdout);
+    return elapsed === null ? 'unknown' : Date.now() - elapsed * 1_000;
+  } catch (error) {
+    // A string code (ENOENT, a spawn failure) is a failed probe. A numeric
+    // exit is how `ps` reports a missing pid — but an operationally broken
+    // `ps` exits nonzero too, so only trust "absent" once `ps` demonstrably
+    // works on this very process.
+    if (typeof (error as {code?: unknown}).code !== 'number') return 'unknown';
+    try {
+      const {stdout} = await exec('ps', [
+        '-o',
+        'etime=',
+        '-p',
+        String(process.pid),
+      ]);
+      return parseEtime(stdout) === null ? 'unknown' : 'absent';
+    } catch {
+      return 'unknown';
+    }
+  }
+}
+
+/**
+ * Whether a probed start instant identifies the process registered on the
+ * row — servers record their own process start as `started_at`. False on an
+ * unparseable registered instant: identity that cannot be read cannot be
+ * confirmed.
+ */
+export function sameProcess(probedStartMs: number, startedAt: string): boolean {
+  const registered = Date.parse(startedAt);
+  return (
+    Number.isFinite(registered) &&
+    Math.abs(probedStartMs - registered) <= START_SLACK_MS
+  );
+}
+
+/**
+ * Whether a probed start proves the registered process is gone: a reused
+ * pid can only start after the registered server died, so only a probed
+ * start decisively past the registered instant is proof. An earlier probed
+ * start merely means registration lagged the process start — rows written
+ * by older plugin versions recorded the registration instant here — and
+ * proves nothing about death.
+ *
+ * `slackMs` should be generous — the staleness window, not the matching
+ * slack: retiring a live row (say, after a forward clock step) is
+ * unrecoverable, while a reuse this slack fails to prove only leaves a row
+ * the heartbeat sweep bounds anyway.
+ */
+export function provenReused(
+  probedStartMs: number,
+  startedAt: string,
+  slackMs: number
+): boolean {
+  const registered = Date.parse(startedAt);
+  return Number.isFinite(registered) && probedStartMs > registered + slackMs;
+}
+
+/**
+ * Keep only rows whose server process this one can vouch for: same host, a
+ * recorded pid, and a running process whose start matches the registered
+ * one (which rules out a reused pid). This is the other half of liveness
+ * beside heartbeat freshness — a server killed without cleanup (a plugin
+ * reload) stops heartbeating, but its row would otherwise stay "live" for
+ * the whole staleness window, holding its session ambiguous. Rows that
+ * cannot pass the check — another host, no pid recorded, a failed probe —
+ * are dropped too: reporting a server the caller cannot verify risks a
+ * false `active`, which strands a session yielding for events that never
+ * arrive, where a false `inactive` only costs polling.
+ */
+export async function withLiveProcesses(
+  sessions: Session[],
+  opts?: {
+    probe?: ((pid: number) => Promise<ProbeResult>) | undefined;
+    host?: string | undefined;
+  }
+): Promise<Session[]> {
+  const probe = opts?.probe ?? probeProcessStart;
+  const host = opts?.host ?? hostname();
+  const live: Session[] = [];
+  for (const session of sessions) {
+    if (session.host !== host || session.pid === null) continue;
+    const probed = await probe(session.pid);
+    if (typeof probed !== 'number') continue;
+    if (!sameProcess(probed, session.startedAt)) continue;
+    live.push(session);
+  }
+  return live;
+}

package/src/lib/liveness/retire.mts

@@ -0,0 +1,63 @@
+import {hostname} from 'node:os';
+
+import type {Database} from '../db/database.mts';
+import type {Session} from '../model/types.mts';
+import {SessionStore} from '../stores/session.mts';
+import {probeProcessStart, provenReused} from './liveness.mts';
+import type {ProbeResult} from './liveness.mts';
+
+/**
+ * Startup retirement: delete rows carrying this session id whose server is
+ * provably dead — heartbeat gone stale, pid gone, or pid reused by a
+ * different process — so a server killed without cleanup (a plugin reload)
+ * does not hold its claims and slots for the rest of the staleness window.
+ * Deletion demands proof of death, the opposite bias from matching: a row
+ * that merely cannot be verified (another host, no pid, a failed probe) is
+ * left for the heartbeat sweep, and a genuinely live rival always stays —
+ * two live servers under one session id are the `ambiguous-session` case,
+ * which fails closed rather than being resolved by whichever registered
+ * last. Returns the number of rows retired.
+ */
+export async function retireNonLive(
+  db: Database,
+  opts: {
+    claudeSessionId: string;
+    /** The caller's own registry row, never retired. */
+    keep: string;
+    now: string;
+    staleAfterSeconds: number;
+    probe?: ((pid: number) => Promise<ProbeResult>) | undefined;
+    host?: string | undefined;
+  }
+): Promise<number> {
+  const sessions = new SessionStore(db);
+  const probe = opts.probe ?? probeProcessStart;
+  const host = opts.host ?? hostname();
+  let retired = 0;
+  for (const row of await sessions.forCaller(opts.claudeSessionId)) {
+    if (row.id === opts.keep) continue;
+    if (!(await provenDead(row, {...opts, probe, host}))) continue;
+    if (await sessions.close(row.id)) retired += 1;
+  }
+  return retired;
+}
+
+async function provenDead(
+  row: Session,
+  opts: {
+    now: string;
+    staleAfterSeconds: number;
+    probe: (pid: number) => Promise<ProbeResult>;
+    host: string;
+  }
+): Promise<boolean> {
+  const quietMs = Date.parse(opts.now) - Date.parse(row.heartbeatAt);
+  if (Number.isFinite(quietMs) && quietMs > opts.staleAfterSeconds * 1_000) {
+    return true;
+  }
+  if (row.host !== opts.host || row.pid === null) return false;
+  const probed = await opts.probe(row.pid);
+  if (probed === 'absent') return true;
+  if (probed === 'unknown') return false;
+  return provenReused(probed, row.startedAt, opts.staleAfterSeconds * 1_000);
+}

package/src/lib/logger/CLAUDE.md

@@ -0,0 +1,12 @@
+# Logger
+
+`createLogger(sink = console)` in `logger.mts` — a metadata-accumulating logger
+with a `child(meta)` binder. The docblock there is the contract: merge precedence
+and empty-meta handling.
+
+`streamSink(stream)` in `stream-sink.mts` is the sink every entry point binds to
+stderr, because `dispatch mcp` owns stdout as its JSON-RPC channel and `console`
+would put `log`/`info`/`debug` there.
+
+Tests pass a recording sink and assert what each call produced — level,
+message, metadata, and argument count.

package/src/lib/logger/index.mts

@@ -0,0 +1,2 @@
+export * from './logger.mts';
+export * from './stream-sink.mts';

package/src/lib/logger/logger.mts

@@ -0,0 +1,58 @@
+export type LogMethod = (
+  message: string,
+  meta?: Record<string, unknown>
+) => void;
+
+export const LEVELS = [
+  'error',
+  'warn',
+  'info',
+  'debug',
+  'trace',
+  'log',
+] as const;
+
+export type CoreLogger = Record<(typeof LEVELS)[number], LogMethod>;
+
+export interface Logger extends CoreLogger {
+  child(meta: Record<string, unknown>): Logger;
+}
+
+/**
+ * Wrap a console-shaped sink so every call carries accumulated metadata and the
+ * logger gains a `child()` binder. The default sink is `console`; the MCP server
+ * passes a stderr-bound sink so it never writes to the JSON-RPC channel.
+ *
+ * Bound metadata wins over a colliding key at the call site, and a deeper
+ * `child()` wins over a shallower one. When the merged metadata is empty the
+ * sink is called without a metadata argument, so plain calls stay plain.
+ */
+export function createLogger(sink: CoreLogger = console): Logger {
+  const bind = (bound: Record<string, unknown>): Logger =>
+    new Proxy(sink, {
+      get(target, prop, receiver) {
+        if (prop === 'child') {
+          return (meta: Record<string, unknown>): Logger =>
+            bind({...bound, ...meta});
+        }
+        if (
+          typeof prop === 'string' &&
+          (LEVELS as readonly string[]).includes(prop)
+        ) {
+          const method = Reflect.get(target, prop, receiver) as LogMethod;
+          return (message: string, meta?: Record<string, unknown>): void => {
+            const merged = {...meta, ...bound};
+            if (Object.keys(merged).length === 0) {
+              method.call(target, message);
+            } else {
+              method.call(target, message, merged);
+            }
+          };
+        }
+        const passthrough: unknown = Reflect.get(target, prop, receiver);
+        return passthrough;
+      },
+    }) as Logger;
+
+  return bind({});
+}

package/src/lib/logger/stream-sink.mts

@@ -0,0 +1,23 @@
+import type {Writable} from 'node:stream';
+
+import {LEVELS} from './logger.mts';
+import type {CoreLogger} from './logger.mts';
+
+/**
+ * A logger sink that writes one line per call to a stream — bind it to stderr.
+ * The default `console` sink sends `log`, `info`, and `debug` to stdout, which
+ * `dispatch mcp` owns as its JSON-RPC channel: one diagnostic line there is a
+ * protocol error for the client parsing it.
+ */
+export function streamSink(stream: Writable): CoreLogger {
+  const write = (message: string, meta?: Record<string, unknown>): void => {
+    stream.write(
+      meta === undefined
+        ? `${message}\n`
+        : `${message} ${JSON.stringify(meta)}\n`
+    );
+  };
+  const sink = {} as CoreLogger;
+  for (const level of LEVELS) sink[level] = write;
+  return sink;
+}

package/src/lib/mcp/CLAUDE.md

@@ -0,0 +1,21 @@
+# MCP
+
+`runMcpServer({tree, stdin, stdout, stderr, env})` in `mcp.mts` serves the
+command tree over newline-delimited JSON-RPC 2.0 on stdio — the sibling of
+`lib/cli` for the MCP transport. stdout is the protocol channel; diagnostics go
+to stderr. `index.mts` is the barrel.
+
+- `tools.mts` — `buildTools(tree)` walks the tree into MCP tool defs (name =
+  `_`-joined path, `inputSchema` from `options`) plus a name -> command map,
+  skipping commands whose `mcp` transport is off.
+- `dispatch.mts` — `callTool` runs one command with a capturing `io` (its output
+  is the result text); a `DispatchError` becomes an `isError` result.
+- `channel.mts` — `ChannelWriter` frames `notifications/claude/channel` events:
+  monotonic `seq`, meta keys filtered to `^[a-zA-Z_][a-zA-Z0-9_]*$`, never a
+  `source` key (the runner sets that one).
+- `drain.mts` — `drainInstructions` turns undelivered `fetch_request` rows and
+  owed completions into events, and records delivery in the database.
+
+The loop throws `JsonRpcError` (in `lib/errors`) for protocol failures (unknown
+method, malformed request, unknown tool) and renders it into a JSON-RPC `error`.
+Tool failures are `isError` results, not protocol errors.

package/src/lib/mcp/channel.mts

@@ -0,0 +1,41 @@
+/** The runner drops any meta key outside this shape. */
+const META_KEY = /^[a-zA-Z_][a-zA-Z0-9_]*$/u;
+
+/**
+ * Pushes channel events into the session that spawned the server. `source` is
+ * the runner's own attribute — a second one on the tag would not override it,
+ * so this never sets one.
+ */
+export class ChannelWriter {
+  readonly #emit: (payload: unknown) => void;
+  #seq = 0;
+
+  constructor(emit: (payload: unknown) => void) {
+    this.#emit = emit;
+  }
+
+  push(
+    kind: string,
+    meta: Readonly<Record<string, string | null>>,
+    content: string
+  ): void {
+    this.#seq += 1;
+    const params: Record<string, string> = {kind, seq: String(this.#seq)};
+    for (const [key, value] of Object.entries(meta)) {
+      if (value === null) continue;
+      if (key === 'source' || key === 'kind' || key === 'seq') continue;
+      if (!META_KEY.test(key)) continue;
+      // `meta` is typed `string | null`, but a caller's payload passed through
+      // JSON.parse behind an unchecked cast (`ScanPayload`/`TicketPayload`), so
+      // a numeric or boolean field can reach here as its native type despite
+      // what the type checker believes at this point.
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-conversion
+      params[key] = String(value);
+    }
+    this.#emit({
+      jsonrpc: '2.0',
+      method: 'notifications/claude/channel',
+      params: {content, meta: params},
+    });
+  }
+}