@ianwremmel/dispatch 0.32.1-bootstrap.0

package/src/commands/mcp.mts

@@ -0,0 +1,155 @@
+import {randomUUID} from 'node:crypto';
+import {hostname} from 'node:os';
+
+import {AbstractCommand, discover} from '../lib/command/index.mts';
+import type {ParsedOptions, CommandContext} from '../lib/command/index.mts';
+import {nowIso, withDatabase} from '../lib/db/index.mts';
+import {DEFAULT_STALE_AFTER_SECONDS} from '../lib/graph/index.mts';
+import {processStartIso, retireNonLive} from '../lib/liveness/index.mts';
+import {runMcpServer} from '../lib/mcp/index.mts';
+import {
+  assertCapLimit,
+  DEFAULT_MAX_IN_FLIGHT_BUILDS,
+  DEFAULT_MAX_OPEN_PRS,
+  parseRepoLimits,
+} from '../lib/model/index.mts';
+import {createTickState, runServerTick} from '../lib/schedule/index.mts';
+import {PolicyStore, SessionStore} from '../lib/stores/index.mts';
+
+const options = {
+  'max-parallel': {
+    type: 'number',
+    description:
+      'Cap on agents running at once, across every session sharing this database.',
+    positional: false,
+    required: false,
+  },
+  'max-open-prs': {
+    type: 'number',
+    description:
+      'Cap on PRs open at once in one repo, for every repo without an override.',
+    positional: false,
+    required: false,
+    default: DEFAULT_MAX_OPEN_PRS,
+  },
+  'max-open-prs-by-repo': {
+    type: 'string',
+    description:
+      'Per-repo overrides of --max-open-prs, as owner/repo=<number>, comma separated.',
+    positional: false,
+    required: false,
+  },
+  'max-in-flight-builds': {
+    type: 'number',
+    description:
+      "Cap on one repo's PRs with CI running at once, for every repo without an override.",
+    positional: false,
+    required: false,
+    default: DEFAULT_MAX_IN_FLIGHT_BUILDS,
+  },
+  'max-in-flight-builds-by-repo': {
+    type: 'string',
+    description:
+      'Per-repo overrides of --max-in-flight-builds, as owner/repo=<number>, comma separated.',
+    positional: false,
+    required: false,
+  },
+  'tick-seconds': {
+    type: 'number',
+    description: 'Scheduler tick interval.',
+    positional: false,
+    required: false,
+    default: 15,
+  },
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'mcp';
+  readonly summary = 'Start the MCP server on stdio.';
+  readonly env = [];
+  readonly options = options;
+  override readonly transports = {mcp: false};
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    // Registration precedes everything else, command discovery included — it
+    // needs only the DB, and a skill invoked on the session's first turn
+    // would otherwise correlate to nothing. `started_at` records this
+    // process's own start: the identity a later liveness probe verifies the
+    // registered pid against.
+    const registryId = randomUUID();
+    const registeredAt = nowIso();
+    const claudeSessionId = ctx.env.CLAUDE_CODE_SESSION_ID ?? null;
+    // Parsed before anything is written: a malformed override list is a usage
+    // error, not a server that starts and then enforces half a policy.
+    const repoCaps = {
+      openPrs: assertCapLimit(parsed['max-open-prs'], 'max-open-prs'),
+      inFlightBuilds: assertCapLimit(
+        parsed['max-in-flight-builds'],
+        'max-in-flight-builds'
+      ),
+      openPrsByRepo: parseRepoLimits(
+        parsed['max-open-prs-by-repo'] ?? '',
+        'max-open-prs-by-repo'
+      ),
+      inFlightBuildsByRepo: parseRepoLimits(
+        parsed['max-in-flight-builds-by-repo'] ?? '',
+        'max-in-flight-builds-by-repo'
+      ),
+    };
+    await withDatabase(undefined, ctx.env, async (db) => {
+      // The caps bound the host's shared resources, so the policy lives in the
+      // database where every reader — this server's scheduler, and `dispatch
+      // status` in another process — sees the same one.
+      await new PolicyStore(db).setRepoCaps(repoCaps);
+      await new SessionStore(db).register({
+        id: registryId,
+        host: hostname(),
+        pid: process.pid,
+        claudeSessionId,
+        startedAt: processStartIso(),
+        heartbeatAt: registeredAt,
+      });
+      // Rows for this session whose server died without cleanup (a plugin
+      // reload) would otherwise hold their claims and slots until their
+      // heartbeat ages out; retire them now. Live rows stay — two live
+      // servers under one session id fail closed as ambiguous rather than
+      // being resolved by whichever registered last.
+      if (claudeSessionId !== null) {
+        await retireNonLive(db, {
+          claudeSessionId,
+          keep: registryId,
+          now: registeredAt,
+          staleAfterSeconds: DEFAULT_STALE_AFTER_SECONDS,
+        });
+      }
+    });
+
+    // Everything past registration runs under the finally: a startup
+    // failure — discovery included — must retire the row it just created,
+    // not strand it until the heartbeat sweep.
+    try {
+      const tree = await discover(new URL('./', import.meta.url));
+      const state = createTickState(registryId, parsed['max-parallel']);
+      await runMcpServer({
+        tree,
+        stdin: process.stdin,
+        stdout: process.stdout,
+        stderr: process.stderr,
+        env: ctx.env,
+        tick: {
+          intervalMs: parsed['tick-seconds'] * 1_000,
+          run: (channel) => runServerTick(channel, ctx.env, state),
+        },
+      });
+    } finally {
+      // The session dies with its server; claims cascade so another
+      // server can pick the work up through stale-free reclamation.
+      await withDatabase(undefined, ctx.env, async (db) =>
+        new SessionStore(db).close(registryId)
+      ).catch(() => undefined);
+    }
+  }
+}

package/src/commands/milestone/rm.mts

@@ -0,0 +1,35 @@
+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 {MilestoneStore} from '../../lib/stores/index.mts';
+
+const options = {
+  id: {
+    type: 'string',
+    description: 'Tracker identifier for the milestone.',
+    positional: false,
+    required: true,
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'rm';
+  readonly summary = 'Delete one milestone.';
+  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 MilestoneStore(db).removeMilestone(parsed.id);
+      await new RefreshService(db).reconcile();
+      ctx.io.write(
+        `removed milestone ${parsed.id} existed=${String(existed)}\n`
+      );
+    });
+  }
+}

package/src/commands/milestone/set.mts

@@ -0,0 +1,49 @@
+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 {MilestoneStore} from '../../lib/stores/index.mts';
+
+const options = {
+  id: {
+    type: 'string',
+    description: 'Tracker identifier for the milestone.',
+    positional: false,
+    required: true,
+  },
+  project: {
+    type: 'string',
+    description: 'Project the milestone belongs to.',
+    positional: false,
+    required: true,
+  },
+  name: {
+    type: 'string',
+    description: 'Human-readable milestone name.',
+    positional: false,
+    required: true,
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'set';
+  readonly summary = 'Create or update one milestone.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      await new MilestoneStore(db).upsertMilestone({
+        id: parsed.id,
+        project: parsed.project,
+        name: parsed.name,
+      });
+      await new RefreshService(db).reconcile();
+      ctx.io.write(`milestone ${parsed.id}\n`);
+    });
+  }
+}

package/src/commands/outcome/rm.mts

@@ -0,0 +1,36 @@
+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 {nowIso} from '../../lib/db/time.mts';
+import {DEFAULT_STALE_AFTER_SECONDS} from '../../lib/graph/index.mts';
+import {CoordinationStore} from '../../lib/stores/index.mts';
+
+const options = {
+  id: {
+    type: 'string',
+    description: 'The node whose recorded outcome should be dropped.',
+    positional: false,
+    required: true,
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'rm';
+  readonly summary = 'Drop a recorded outcome, requeueing surfaced work.';
+  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 CoordinationStore(db).removeOutcome(parsed.id, {
+        now: nowIso(),
+        staleAfterSeconds: DEFAULT_STALE_AFTER_SECONDS,
+      });
+      ctx.io.write(`removed outcome ${parsed.id} existed=${String(existed)}\n`);
+    });
+  }
+}

package/src/commands/outcome/set.mts

@@ -0,0 +1,86 @@
+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 {OUTCOMES} from '../../lib/model/status.mts';
+import {correlateSession} from '../../lib/schedule/index.mts';
+import {CoordinationStore} from '../../lib/stores/index.mts';
+
+const options = {
+  id: {
+    type: 'string',
+    description: 'The node (ticket or PR item) this outcome reports on.',
+    positional: false,
+    required: true,
+  },
+  outcome: {
+    type: 'string',
+    description: 'The final report.',
+    positional: false,
+    required: true,
+    choices: OUTCOMES,
+  },
+  retryable: {
+    type: 'boolean',
+    description: 'A failed run worth re-dispatching (failed only).',
+    positional: false,
+    required: false,
+  },
+  detail: {
+    type: 'string',
+    description: 'One line of context for whoever reads the report.',
+    positional: false,
+    required: false,
+  },
+  force: {
+    type: 'boolean',
+    description:
+      'Record even though no claim is held. For an operator resolving a node by hand; a dispatched worker always holds its claim and never needs this.',
+    positional: false,
+    required: false,
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'set';
+  readonly summary = 'Record a final report on a node, releasing its claim.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      // Identity comes from the environment, never from a flag. An id a
+      // caller supplies is an assertion, not evidence, and the holders are
+      // printed by `dispatch claim status` — so an unclaimed worker could
+      // name one and pass.
+      //
+      // Holding the claim is what authorizes a report: an outcome is a report
+      // from work that was dispatched. The check runs inside the write's own
+      // transaction, because a claim read out here can be swept, released, or
+      // taken by another session before the write lands.
+      //
+      // `correlateSession` returning null cannot tell an operator at a
+      // terminal from a worker whose server just died, so it is not treated
+      // as authority — that would leave the guard bypassable exactly when the
+      // system is unhealthy, which is when it matters. An operator resolving
+      // a node by hand passes --force and says so.
+      const session = await correlateSession(db, ctx.env, undefined);
+      await new CoordinationStore(db).recordOutcome(
+        {
+          node: parsed.id,
+          outcome: parsed.outcome,
+          // The parser defaults an absent boolean to false; only a failure
+          // carries a meaningful retryable, and the store enforces that.
+          retryable: parsed.outcome === 'failed' ? parsed.retryable : null,
+          detail: parsed.detail ?? null,
+          recordedAt: nowIso(),
+        },
+        {session: session ?? '', requireClaim: !parsed.force}
+      );
+      ctx.io.write(`outcome ${parsed.id} ${parsed.outcome}\n`);
+    });
+  }
+}

package/src/commands/pr/rm.mts

@@ -0,0 +1,33 @@
+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 {PrStore} from '../../lib/stores/index.mts';
+
+const options = {
+  id: {
+    type: 'string',
+    description: 'Identifier for the PR item.',
+    positional: false,
+    required: true,
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'rm';
+  readonly summary = 'Delete one PR work item.';
+  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 PrStore(db).removePr(parsed.id);
+      await new RefreshService(db).reconcile();
+      ctx.io.write(`removed pr ${parsed.id} existed=${String(existed)}\n`);
+    });
+  }
+}

package/src/commands/pr/set.mts

@@ -0,0 +1,110 @@
+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 {PR_ORIGINS} from '../../lib/model/status.mts';
+import {RefreshService} from '../../lib/refresh/index.mts';
+import {PrStore} from '../../lib/stores/index.mts';
+
+const options = {
+  id: {
+    type: 'string',
+    description: 'Identifier for the PR item, e.g. owner/repo#7.',
+    positional: false,
+    required: true,
+  },
+  ticket: {
+    type: 'string',
+    description: 'The originating ticket; omit for a bare PR or prompt item.',
+    positional: false,
+    required: false,
+  },
+  origin: {
+    type: 'string',
+    description: 'How the item entered the graph.',
+    positional: false,
+    required: false,
+    choices: PR_ORIGINS,
+  },
+  repo: {
+    type: 'string',
+    description: 'Repository as owner/repo.',
+    positional: false,
+    required: false,
+  },
+  'pr-number': {
+    type: 'number',
+    description: 'Pull request number, once one exists.',
+    positional: false,
+    required: false,
+  },
+  url: {
+    type: 'string',
+    description: 'Pull request URL.',
+    positional: false,
+    required: false,
+  },
+  branch: {
+    type: 'string',
+    description: 'Head branch.',
+    positional: false,
+    required: false,
+  },
+  title: {
+    type: 'string',
+    description: 'One-line description of the work.',
+    positional: false,
+    required: false,
+  },
+  injected: {
+    type: 'boolean',
+    description: 'Rank this item to the top of the frontier.',
+    positional: false,
+    required: false,
+  },
+  priority: {
+    type: 'number',
+    description: 'Lower is more urgent.',
+    positional: false,
+    required: false,
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'set';
+  readonly summary = 'Create or update one PR work item.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      // Only what the caller named. A worker keeping the URL and PR number
+      // current names nothing else, and must not thereby unlink the item from
+      // its ticket or blank its title. An explicit empty string still clears a
+      // field — omission is what preserves. `injected` is the exception the
+      // parser forces: an absent boolean is indistinguishable from `--no`, so
+      // it is carried only when set.
+      await new PrStore(db).patchPr({
+        id: parsed.id,
+        ...(parsed.ticket === undefined
+          ? {}
+          : {ticket: parsed.ticket === '' ? null : parsed.ticket}),
+        ...(parsed.origin === undefined ? {} : {origin: parsed.origin}),
+        ...(parsed.repo === undefined ? {} : {repo: parsed.repo}),
+        ...(parsed['pr-number'] === undefined
+          ? {}
+          : {prNumber: parsed['pr-number']}),
+        ...(parsed.url === undefined ? {} : {url: parsed.url}),
+        ...(parsed.branch === undefined ? {} : {branch: parsed.branch}),
+        ...(parsed.title === undefined ? {} : {title: parsed.title}),
+        ...(parsed.injected ? {injected: true} : {}),
+        ...(parsed.priority === undefined ? {} : {priority: parsed.priority}),
+      });
+      await new RefreshService(db).reconcile();
+      ctx.io.write(`pr ${parsed.id}\n`);
+    });
+  }
+}

package/src/commands/pr/yield.mts

@@ -0,0 +1,114 @@
+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 {correlateSession} from '../../lib/schedule/index.mts';
+import {CoordinationStore, PrStore} from '../../lib/stores/index.mts';
+import {armWatch, githubSnapshot} from '../../lib/watch/index.mts';
+
+const options = {
+  id: {
+    type: 'string',
+    description: 'The PR item this worker is handing back.',
+    positional: false,
+    required: true,
+  },
+  session: {
+    type: 'string',
+    description:
+      'Registry id whose claim the handoff releases; defaults to the session correlated from the environment.',
+    positional: false,
+    required: false,
+  },
+  db: DB_OPTION,
+} as const;
+
+/**
+ * Yield an item back to the server: the worker is no longer working on it.
+ *
+ * Deliberately says nothing about what the worker is waiting for. A worker
+ * may be waiting on several things at once, and whatever it declared would go
+ * stale the moment the PR moved; the server reads the PR's own state and
+ * derives both what changed and how often to look.
+ *
+ * What the server cannot infer is this call itself. A worker that finished
+ * its turn and one that was killed leave the same row — a claim that goes
+ * stale — so without an explicit yield the server cannot tell a graceful
+ * handoff from a crash, and would have to choose between never resuming a
+ * crashed run and re-dispatching a healthy one forever.
+ *
+ * Releasing the claim gives back the compute grant, so the wait costs nothing
+ * while it lasts.
+ */
+export class Command extends AbstractCommand {
+  readonly name = 'yield';
+  readonly summary = 'Hand a PR item back to the server, releasing the claim.';
+  readonly env = [];
+  readonly options = options;
+
+  async run(
+    parsed: ParsedOptions<typeof options>,
+    ctx: CommandContext
+  ): Promise<void> {
+    await withDatabase(parsed.db, ctx.env, async (db) => {
+      const pr = await new PrStore(db).getPr(parsed.id);
+      ensure(
+        pr !== null,
+        () =>
+          new DataError(`no PR item "${parsed.id}" to watch`, {
+            hint: 'register the item with `dispatch pr set` first.',
+          })
+      );
+      ensure(
+        pr.repo !== null && pr.prNumber !== null,
+        () =>
+          new DataError(`PR item "${parsed.id}" has no PR to poll`, {
+            hint: 'record it with `dispatch pr set --repo <owner>/<name> --pr-number <n>` once the PR exists, then watch.',
+          })
+      );
+
+      const coordination = new CoordinationStore(db);
+      ensure(
+        (await coordination.getOutcome(parsed.id)) === null,
+        () =>
+          new DataError(`PR item "${parsed.id}" already has an outcome`, {
+            hint: 'a concluded item is not waiting; remove the outcome first if it must re-run.',
+          })
+      );
+
+      const caller = await correlateSession(db, ctx.env, parsed.session);
+
+      // Release before arming, and refuse the handoff if the claim does not
+      // actually go. A watching item is never queued, so a watch armed over
+      // a claim still held would consume capacity that nothing can ever
+      // reclaim — the item reads as waiting and as in flight at once.
+      const released =
+        caller === null
+          ? 'absent'
+          : await coordination.release(parsed.id, caller);
+      ensure(
+        released === 'released' || released === 'absent',
+        () =>
+          new DataError(
+            `the claim on "${parsed.id}" belongs to another session`,
+            {
+              hint: 'this worker was superseded; return without arming a watch, and let the session that holds the claim finish.',
+            }
+          )
+      );
+
+      await armWatch(db, {
+        node: parsed.id,
+        repo: pr.repo,
+        prNumber: pr.prNumber,
+        at: nowIso(),
+        snapshot: githubSnapshot,
+        session: caller,
+        releaseClaimFor: caller,
+        log: ctx.log,
+      });
+
+      ctx.io.write(`yield ${parsed.id}\n`);
+    });
+  }
+}

package/src/commands/project/rm.mts

@@ -0,0 +1,33 @@
+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 {ProjectStore} from '../../lib/stores/index.mts';
+
+const options = {
+  id: {
+    type: 'string',
+    description: 'Tracker identifier for the project.',
+    positional: false,
+    required: true,
+  },
+  db: DB_OPTION,
+} as const;
+
+export class Command extends AbstractCommand {
+  readonly name = 'rm';
+  readonly summary = 'Delete one project.';
+  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 ProjectStore(db).removeProject(parsed.id);
+      await new RefreshService(db).reconcile();
+      ctx.io.write(`removed project ${parsed.id} existed=${String(existed)}\n`);
+    });
+  }
+}