@ianwremmel/dispatch 0.32.1-bootstrap.0

package/src/commands/claim/check.mts

@@ -0,0 +1,88 @@
+import {AbstractCommand} from '../../lib/command/index.mts';
+import type {CommandContext, ParsedOptions} from '../../lib/command/index.mts';
+import {DB_OPTION, withDatabase} from '../../lib/db/index.mts';
+import {DataError, ensure} from '../../lib/errors/index.mts';
+import {correlateSession} from '../../lib/schedule/index.mts';
+import {CoordinationStore} from '../../lib/stores/index.mts';
+
+const options = {
+  node: {
+    type: 'string',
+    description:
+      'The ticket, PR item, or milestone this agent was launched for.',
+    positional: false,
+    required: true,
+  },
+  db: DB_OPTION,
+} as const;
+
+/**
+ * Prove that the scheduler actually dispatched this agent, and exit non-zero
+ * if it did not.
+ *
+ * A worker's authority to run comes from a claim: the scheduler takes one
+ * before it emits a work order, and the claim is also the admission that
+ * bounds how many agents run at once. An agent launched any other way holds
+ * no claim, so it spends no budget and nothing caps how many of them there are.
+ *
+ * That is not hypothetical. A session whose channel went unacknowledged
+ * received no work orders, decided on its own what to run, and launched
+ * twelve workers against a cap of three — every one of them unclaimed. The
+ * skill told it not to. Instructions are not a bound, so this is the bound:
+ * a worker asks first and exits when the answer is no, and an unbudgeted
+ * launch costs one command instead of an agent.
+ */
+export class Command extends AbstractCommand {
+  readonly name = 'check';
+  readonly summary =
+    'Verify this session holds a live claim on a node; exit non-zero if not.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      // Deliberately no --session. The whole point is to establish who the
+      // caller *is*, and an id it supplies is an assertion, not evidence:
+      // `dispatch claim status` prints the holders, so any worker could name
+      // one and pass. Correlation from the environment is the only identity
+      // the caller does not choose.
+      const caller = await correlateSession(db, ctx.env, undefined);
+      ensure(
+        caller !== null,
+        () =>
+          new DataError(
+            `no live server correlates to this session, so nothing can hold a claim on "${parsed.node}"`,
+            {
+              hint: 'you were not dispatched by a scheduler — or the one that dispatched you has died, and its claim is about to be swept. Stop, and report that work was launched without a work order.',
+            }
+          )
+      );
+
+      const held = (await new CoordinationStore(db).claims()).find(
+        (claim) => claim.node === parsed.node
+      );
+      ensure(
+        held !== undefined,
+        () =>
+          new DataError(`no claim is held on "${parsed.node}"`, {
+            hint: 'you were not dispatched for this node. Stop without doing any work; a worker runs only on a claim the scheduler took for it.',
+          })
+      );
+      ensure(
+        held.session === caller,
+        () =>
+          new DataError(
+            `the claim on "${parsed.node}" belongs to ${held.session}, not this session`,
+            {
+              hint: 'another session is working this node. Stop; two workers on one node undo each other.',
+            }
+          )
+      );
+
+      ctx.io.write(`claim ${parsed.node} ${caller}\n`);
+    });
+  }
+}

package/src/commands/claim/guard.mts

@@ -0,0 +1,95 @@
+import {AbstractCommand} from '../../lib/command/index.mts';
+import type {CommandContext, ParsedOptions} from '../../lib/command/index.mts';
+import {DB_OPTION, nowIso, withDatabase} from '../../lib/db/index.mts';
+import {DataError, ensure} from '../../lib/errors/index.mts';
+import {DEFAULT_STALE_AFTER_SECONDS} from '../../lib/graph/index.mts';
+import {correlateSession} from '../../lib/schedule/index.mts';
+import {CoordinationStore} from '../../lib/stores/index.mts';
+
+const options = {
+  db: DB_OPTION,
+} as const;
+
+/**
+ * Judge a worker launch: read the would-be worker's prompt on stdin and pass
+ * only if it names a node this session holds a live claim on.
+ *
+ * This is the deterministic half of the PreToolUse hook. The hook itself
+ * decides nothing — it forwards the prompt here and relays the verdict — so
+ * the rule lives in the CLI where it is tested, versioned, and shared with
+ * `claim check`.
+ *
+ * Matching is by whole token against the session's own live claims, not by
+ * parsing the prompt: the claims are few and their ids unique, while prompt
+ * shapes change. A prompt that names none of them is a launch the scheduler
+ * never authorized, whoever composed it. A prompt that names a claimed node
+ * while instructing work on another passes here — the worker's own
+ * `claim check` on the node it actually works is the layer that catches
+ * that, and this hook exists to stop wholesale unbudgeted launches, not to
+ * parse intent.
+ *
+ * CLI-only: it reads the prompt from stdin, and the hook runs in a shell.
+ */
+export class Command extends AbstractCommand {
+  readonly name = 'guard';
+  readonly summary =
+    'Pass iff stdin names a node this session holds a live claim on.';
+  readonly env = [];
+  readonly options = options;
+  override readonly transports = {mcp: false};
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    const chunks: Buffer[] = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk as Buffer);
+    }
+    const prompt = Buffer.concat(chunks).toString('utf8');
+
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      const session = await correlateSession(db, ctx.env, undefined);
+      ensure(
+        session !== null,
+        () =>
+          new DataError('no live server correlates to this session', {
+            hint: 'a worker launch is authorized by a claim, and only a session with a live server can hold one.',
+          })
+      );
+      const held = (
+        await new CoordinationStore(db).liveClaims({
+          now: nowIso(),
+          staleAfterSeconds: DEFAULT_STALE_AFTER_SECONDS,
+        })
+      ).filter((claim) => claim.session === session);
+      // Whole-token match, not substring: a claim on CLC-7 must not
+      // authorize a launch for CLC-77. A node id is bounded by any character
+      // that cannot appear inside one.
+      const boundary = /[A-Za-z0-9/#_.-]/u;
+      const named = held.find((claim) => {
+        let from = 0;
+        for (;;) {
+          const at = prompt.indexOf(claim.node, from);
+          if (at === -1) return false;
+          const before = prompt.slice(Math.max(0, at - 1), at);
+          const afterIndex = at + claim.node.length;
+          const after = prompt.slice(afterIndex, afterIndex + 1);
+          if (!boundary.test(before) && !boundary.test(after)) return true;
+          from = at + 1;
+        }
+      });
+      ensure(
+        named !== undefined,
+        () =>
+          new DataError(
+            'the launch prompt names no node this session holds a claim on',
+            {
+              hint: 'workers are launched from work orders, which name a node the scheduler already claimed. Wait for a work order instead of composing a launch.',
+            }
+          )
+      );
+      ctx.io.write(`guard pass ${named.node}\n`);
+    });
+  }
+}

package/src/commands/claim/status.mts

@@ -0,0 +1,49 @@
+import {AbstractCommand} from '../../lib/command/index.mts';
+import type {CommandContext, ParsedOptions} from '../../lib/command/index.mts';
+import {DB_OPTION, nowIso, withDatabase} from '../../lib/db/index.mts';
+import {DEFAULT_STALE_AFTER_SECONDS} from '../../lib/graph/index.mts';
+import {CoordinationStore} from '../../lib/stores/index.mts';
+
+const options = {
+  db: DB_OPTION,
+} as const;
+
+/**
+ * How many claims are live right now, and on what.
+ *
+ * The count is what an outside supervisor needs to answer "is this session
+ * holding work" — a question it cannot get from `dispatch status`, whose
+ * `in-flight` counts items classified in-flight (a started ticket, a watched
+ * PR) rather than agents currently running.
+ */
+export class Command extends AbstractCommand {
+  readonly name = 'status';
+  readonly summary = 'Report the live claims and what holds them.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      const coordination = new CoordinationStore(db);
+      const now = nowIso();
+      const held = await coordination.inFlightCount({
+        now,
+        staleAfterSeconds: DEFAULT_STALE_AFTER_SECONDS,
+      });
+      ctx.io.write(`claims held=${String(held)}\n`);
+      // Only the claims the count includes. Listing every row while counting
+      // the live ones reports two different truths in one output — a stale
+      // claim would print as if held and contradict the header a consumer
+      // parses.
+      for (const claim of await coordination.liveClaims({
+        now,
+        staleAfterSeconds: DEFAULT_STALE_AFTER_SECONDS,
+      })) {
+        ctx.io.write(`claim ${claim.node} session=${claim.session}\n`);
+      }
+    });
+  }
+}

package/src/commands/edge/add.mts

@@ -0,0 +1,44 @@
+import {AbstractCommand} from '../../lib/command/index.mts';
+import type {CommandContext, ParsedOptions} from '../../lib/command/index.mts';
+import {DB_OPTION, withDatabase} from '../../lib/db/index.mts';
+import {RefreshService} from '../../lib/refresh/index.mts';
+import {EdgeStore} from '../../lib/stores/index.mts';
+
+const options = {
+  blocker: {
+    type: 'string',
+    description: 'The node that must resolve first.',
+    positional: false,
+    required: true,
+  },
+  blocked: {
+    type: 'string',
+    description: 'The node that waits on it.',
+    positional: false,
+    required: true,
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'add';
+  readonly summary = 'Record that one node blocks another.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      const added = await new EdgeStore(db).addEdge(
+        parsed.blocker,
+        parsed.blocked
+      );
+      await new RefreshService(db).reconcile();
+      ctx.io.write(
+        `edge ${parsed.blocker} -> ${parsed.blocked} added=${String(added)}\n`
+      );
+    });
+  }
+}

package/src/commands/edge/rm.mts

@@ -0,0 +1,44 @@
+import {AbstractCommand} from '../../lib/command/index.mts';
+import type {CommandContext, ParsedOptions} from '../../lib/command/index.mts';
+import {DB_OPTION, withDatabase} from '../../lib/db/index.mts';
+import {RefreshService} from '../../lib/refresh/index.mts';
+import {EdgeStore} from '../../lib/stores/index.mts';
+
+const options = {
+  blocker: {
+    type: 'string',
+    description: 'The node that must resolve first.',
+    positional: false,
+    required: true,
+  },
+  blocked: {
+    type: 'string',
+    description: 'The node that waits on it.',
+    positional: false,
+    required: true,
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'rm';
+  readonly summary = 'Remove a blocking edge between two nodes.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      const existed = await new EdgeStore(db).removeEdge(
+        parsed.blocker,
+        parsed.blocked
+      );
+      await new RefreshService(db).reconcile();
+      ctx.io.write(
+        `removed edge ${parsed.blocker} -> ${parsed.blocked} existed=${String(existed)}\n`
+      );
+    });
+  }
+}

package/src/commands/edge/set.mts

@@ -0,0 +1,56 @@
+import {AbstractCommand} from '../../lib/command/index.mts';
+import type {CommandContext, ParsedOptions} from '../../lib/command/index.mts';
+import {DB_OPTION, withDatabase} from '../../lib/db/index.mts';
+import {RefreshService} from '../../lib/refresh/index.mts';
+import {EdgeStore} from '../../lib/stores/index.mts';
+
+const options = {
+  node: {
+    type: 'string',
+    description: 'The node whose edges are being redeclared.',
+    positional: false,
+    required: true,
+  },
+  direction: {
+    type: 'string',
+    description: 'Which side to replace.',
+    positional: false,
+    required: true,
+    choices: ['blockers', 'blocks'],
+  },
+  others: {
+    type: 'string',
+    description:
+      'Comma-separated node ids; empty clears the direction. Only edges to ' +
+      'tickets are replaced — PR items and milestones are left alone.',
+    positional: false,
+    required: false,
+    default: '',
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'set';
+  readonly summary = 'Replace every edge on one side of a node.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    const others = parsed.others
+      .split(',')
+      .map((id) => id.trim())
+      .filter((id) => id !== '');
+
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      await new EdgeStore(db).setEdges(parsed.node, parsed.direction, others);
+      await new RefreshService(db).reconcile();
+      ctx.io.write(
+        `edges of ${parsed.node} (${parsed.direction}) = ${others.join(',')}\n`
+      );
+    });
+  }
+}

package/src/commands/greet.mts

@@ -0,0 +1,34 @@
+import {AbstractCommand} from '../lib/command/index.mts';
+import type {ParsedOptions, CommandContext} from '../lib/command/index.mts';
+
+const options = {
+  who: {
+    type: 'string',
+    description: 'Who to greet.',
+    positional: true,
+    required: false,
+    default: 'world',
+  },
+  loud: {
+    type: 'boolean',
+    description: 'Shout the greeting.',
+    positional: false,
+    required: false,
+  },
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'greet';
+  readonly summary = 'Print a friendly greeting.';
+  readonly env = [];
+  readonly options = options;
+
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    const message = `hello ${parsed.who}`;
+    ctx.io.write(`${parsed.loud ? message.toUpperCase() : message}\n`);
+  }
+}

package/src/commands/mcp/ack.mts

@@ -0,0 +1,43 @@
+import {AbstractCommand} from '../../lib/command/index.mts';
+import type {CommandContext, ParsedOptions} from '../../lib/command/index.mts';
+import {DB_OPTION, nowIso, withDatabase} from '../../lib/db/index.mts';
+import {DataError, ensure} from '../../lib/errors/index.mts';
+import {SessionStore} from '../../lib/stores/index.mts';
+
+const options = {
+  server: {
+    type: 'string',
+    description: 'Registry id from the probe event being acknowledged.',
+    positional: false,
+    required: true,
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'ack';
+  readonly summary = 'Acknowledge a channel probe, unlocking work orders.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      const acked = await new SessionStore(db).ack(
+        parsed.server,
+        ctx.env.CLAUDE_CODE_SESSION_ID ?? null,
+        nowIso()
+      );
+      ensure(
+        acked,
+        () =>
+          new DataError(`no server registered as "${parsed.server}"`, {
+            hint: 'pass the registry id exactly as the probe event carried it.',
+          })
+      );
+      ctx.io.write(`acked ${parsed.server}\n`);
+    });
+  }
+}

package/src/commands/mcp/ping.mts

@@ -0,0 +1,61 @@
+import {randomUUID} from 'node:crypto';
+
+import {AbstractCommand} from '../../lib/command/index.mts';
+import type {CommandContext, ParsedOptions} from '../../lib/command/index.mts';
+
+const options = {
+  nonce: {
+    type: 'string',
+    description:
+      'Token to echo back; one is generated when omitted. Match it against the pong to be sure they are the same round trip.',
+    positional: false,
+    required: false,
+  },
+} as const;
+
+/**
+ * Ask the server to push a `pong` into the session, and report the nonce it
+ * used. Whether that pong arrives is the whole answer to "does this channel
+ * work".
+ *
+ * Everything else the server pushes is indirect evidence. A probe goes
+ * unanswered for two indistinguishable reasons — the runner never delivered
+ * it, or the session received it and did nothing — and an unacknowledged
+ * session row cannot tell them apart. This can: the tool result proves the
+ * call reached the server, so a missing pong isolates the failure to
+ * delivery.
+ *
+ * Over the CLI there is no session to push to, and the command says so rather
+ * than pretending to test anything.
+ */
+export class Command extends AbstractCommand {
+  readonly name = 'ping';
+  readonly summary =
+    'Push a pong through the channel to prove it reaches the session.';
+  readonly env = [];
+  readonly options = options;
+
+  // eslint-disable-next-line @typescript-eslint/require-await -- the contract is async; this command only writes
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    const nonce = parsed.nonce ?? randomUUID();
+
+    if (ctx.channel === undefined) {
+      ctx.io.write(
+        `ping ${nonce} no-channel\nThis ran outside an MCP server, so there is no session to push to. Call the \`mcp_ping\` tool instead.\n`
+      );
+      return;
+    }
+
+    ctx.channel.push(
+      'pong',
+      {nonce},
+      `pong ${nonce} — this text was pushed over the channel, not returned by the tool call. Seeing it proves the channel reaches this session.`
+    );
+    ctx.io.write(
+      `ping ${nonce} pushed\nA pong carrying nonce ${nonce} went out over the channel. If it does not appear, the runner is not delivering channel events and every push the server makes is being dropped.\n`
+    );
+  }
+}

package/src/commands/mcp/status.mts

@@ -0,0 +1,89 @@
+import {AbstractCommand} from '../../lib/command/index.mts';
+import type {CommandContext, ParsedOptions} from '../../lib/command/index.mts';
+import {DB_OPTION, nowIso, withDatabase} from '../../lib/db/index.mts';
+import {DEFAULT_STALE_AFTER_SECONDS} from '../../lib/graph/index.mts';
+import {withLiveProcesses} from '../../lib/liveness/index.mts';
+import {SessionStore} from '../../lib/stores/index.mts';
+
+const options = {
+  server: {
+    type: 'string',
+    description:
+      'Answer for one registry id instead of correlating by session.',
+    positional: false,
+    required: false,
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'status';
+  readonly summary =
+    'Report whether this session has an acknowledged channel server.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      const sessions = new SessionStore(db);
+      const now = nowIso();
+      const caller = ctx.env.CLAUDE_CODE_SESSION_ID ?? null;
+
+      // Fail closed: a wrong `active` strands a session yielding for events
+      // that never arrive; a wrong `inactive` costs only polling.
+      if (parsed.server !== undefined) {
+        const named = await sessions.getSession(parsed.server);
+        if (
+          named === null ||
+          (caller !== null && named.claudeSessionId !== caller)
+        ) {
+          ctx.io.write('inactive no-server-for-session\n');
+          return;
+        }
+        // `--server` takes precedence over the match, not over liveness: a
+        // named row whose heartbeat went quiet or whose process is gone is
+        // no server at all.
+        const fresh =
+          Date.parse(now) - Date.parse(named.heartbeatAt) <=
+          DEFAULT_STALE_AFTER_SECONDS * 1_000;
+        if (!fresh || (await withLiveProcesses([named])).length === 0) {
+          ctx.io.write('inactive no-server-for-session\n');
+          return;
+        }
+        ctx.io.write(
+          named.ackedAt === null
+            ? 'inactive awaiting-ack\n'
+            : `active ${named.id}\n`
+        );
+        return;
+      }
+
+      if (caller === null) {
+        ctx.io.write('inactive no-session-id\n');
+        return;
+      }
+      // Heartbeat freshness alone would keep a killed server's row "live"
+      // for the whole staleness window; the process check rules it out now.
+      const live = await withLiveProcesses(
+        await sessions.liveForCaller(caller, now, DEFAULT_STALE_AFTER_SECONDS)
+      );
+      if (live.length === 0) {
+        ctx.io.write('inactive no-server-for-session\n');
+        return;
+      }
+      if (live.length > 1) {
+        ctx.io.write('inactive ambiguous-session\n');
+        return;
+      }
+      const only = live[0];
+      ctx.io.write(
+        only?.ackedAt == null
+          ? 'inactive awaiting-ack\n'
+          : `active ${only.id}\n`
+      );
+    });
+  }
+}