@nledford/omp-coord 0.4.1 → 0.4.2

package/.omp-plugin/marketplace.json

@@ -7,7 +7,7 @@
       "name": "omp-coord",
       "source": "./",
       "description": "Shared subagent caps, build and test queues, claims, pause, a decision log and messages across omp sessions working in one project on one machine.",
-      "version": "0.4.1",
+      "version": "0.4.2",
       "author": { "name": "Nathaniel Ledford" },
       "homepage": "https://github.com/nledford/omp-coord",
       "repository": "https://github.com/nledford/omp-coord",

package/CHANGELOG.md

@@ -6,6 +6,13 @@ Add each user-visible change under Unreleased as it lands, in one of: Added, Cha
 
 ## [Unreleased]
 
+## [0.4.2] - 2026-11-02
+
+### Added
+
+- `omp-coord run --meta k=v` (repeatable, at most 8; the key matches `[a-z][a-z0-9_-]{0,31}`, the value is at most 200 characters on one line) tags a job. The tags go into the `job_queued` and `job_ended` events as `meta`, and `job_ended` now also carries the job's `key`. A script can detect support with `omp-coord --help 2>&1 | grep -q -- '--meta'`. The jobs table gains a nullable `meta` column (no schema version bump).
+- `omp-coord stats` and `/coord stats` add `; of the failures: N repeat an unchanged failure, M intended` to a queue's line when a failed job of that day had tags: a repeat is a failed job whose `fp` tag equals that of an earlier failed job in the same queue, with no successful job of that `fp` in between; intended is `intent=failfirst`.
+
 ## [0.4.1] - 2026-10-30
 
 ### Added
@@ -113,7 +120,8 @@ Add each user-visible change under Unreleased as it lands, in one of: Added, Cha
 - An SQLite event log per scope, with retention.
 - Packaging as an omp plugin, with a marketplace catalog; queued commands run on omp's own Bun.
 
-[Unreleased]: https://github.com/nledford/omp-coord/compare/v0.4.1...HEAD
+[Unreleased]: https://github.com/nledford/omp-coord/compare/v0.4.2...HEAD
+[0.4.2]: https://github.com/nledford/omp-coord/compare/v0.4.1...v0.4.2
 [0.4.1]: https://github.com/nledford/omp-coord/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/nledford/omp-coord/compare/v0.3.2...v0.4.0
 [0.3.2]: https://github.com/nledford/omp-coord/compare/v0.3.1...v0.3.2

package/docs/commands.md

@@ -26,7 +26,7 @@
 ## `omp-coord`
 
 ```sh
-omp-coord run <queue> [--lane L] [--priority N] [--key K] [--owner SESSION] [--timeout 90m] -- <command> [args…]
+omp-coord run <queue> [--lane L] [--priority N] [--key K] [--owner SESSION] [--timeout 90m] [--meta k=v]... -- <command> [args…]
 omp-coord status [--agents | --json] | stats [days] | interrupted [hours] | notes [count] | note <text…>
 omp-coord pause [reason…] | resume | doctor [--fix]
 ```

package/docs/event-log.md

@@ -25,7 +25,7 @@ These tables are rebuilt as sessions come and go; their layout is not part of th
 `events` is an append-only log: `at` (ms since epoch), `type`, `session_id` (null for jobs from outside omp), `label`, and `data` (JSON). Types:
 
 - Sessions and agents: `session_joined`, `session_left`, `spawn_approved`, `spawn_refused` (with `position`, `used`, `cap`, or `nested` and `reason`), `run_started` (with `revived`), `run_ended` (with `ranMs`), `start_expired`, `hold_granted`, `hold_used` and `hold_expired` (with `waitedMs` since the first refusal), `message_sent` (recipients and length, never the text).
-- Jobs: `job_queued` (with `queue`, `lane`, `priority`, `key`, and `agent` when recorded), `job_refused` (with `reason`), `job_started` (with `waitedMs`), `job_ended` (with `exitCode`, `ranMs`, and `timedOut` when the time limit stopped it), `job_withdrawn` (left the line before starting), `job_superseded`, `job_lost` (its runner died), `job_reprioritized`.
+- Jobs: `job_queued` (with `queue`, `lane`, `priority`, `key`, and `agent` and `meta` when recorded), `job_refused` (with `reason`), `job_started` (with `waitedMs`), `job_ended` (with `exitCode`, `ranMs`, `key` and `meta` when the job had them, and `timedOut` when the time limit stopped it), `job_withdrawn` (left the line before starting), `job_superseded`, `job_lost` (its runner died), `job_reprioritized`.
 - Control: `paused` (with `reason`), `resumed` (with `pausedMs`), `claimed`, `released`, `claim_refused` (with `holder`), `write_refused` (a file-tool write or a state-changing `git` command refused in a protected checkout: `agentId`, `tool` (`bash` for git), `paths` as the agent wrote them, empty for git), `note_added` (note number and length).
 
 `notes` is the decision log: `id`, `at`, `label`, `author`, `text`.

package/docs/queues.md

@@ -3,7 +3,7 @@
 `omp-coord run <queue> -- <command>` waits for one of the queue's slots, shared by everything on this machine in the same scope, then runs the command. `just` recipes, scripts and terminals call it; agents' matching bash commands are rewritten to go through it. Queues are set under `queues` in the [configuration](configuration.md).
 
 ```sh
-omp-coord run <queue> [--lane L] [--priority N] [--key K] [--owner SESSION] [--timeout 90m] -- <command> [args…]
+omp-coord run <queue> [--lane L] [--priority N] [--key K] [--owner SESSION] [--timeout 90m] [--meta k=v]... -- <command> [args…]
 ```
 
 ## Running a job
@@ -14,6 +14,7 @@ The command runs in its own process group and session, so a time limit stops eve
 
 - **Exit codes**: the command's own, `75` when the job was not run (a refused or superseded duplicate), `124` when its time limit stopped it, `2` for a usage or configuration error.
 - **Owner**: jobs belong to the omp session in `OMP_COORD_SESSION` (set by the extension, so commands an agent runs inherit it) or `--owner`; otherwise to no session ("outside omp").
+- **Tags**: `--meta k=v` (repeatable, at most 8; a repeated key: the last wins) records tags on the job's `job_queued` and `job_ended` events. A key matches `[a-z][a-z0-9_-]{0,31}`; a value is at most 200 characters on one line. Scripts can tag a job with a fingerprint of the code state (`fp`) and mark a deliberate failure (`intent=failfirst`); `omp-coord stats` then adds `; of the failures: N repeat an unchanged failure, M intended` to the queue's line. A repeat is a failed job whose `fp` equals that of an earlier failed job in the same queue inside the stats window, with no successful job of that `fp` in between. Detect support with `omp-coord --help 2>&1 | grep -q -- '--meta'`.
 - **Duplicates**: jobs with the same `--key` (for example `"<checkout> ci"`) are duplicates. One that duplicates a running job is refused; one that duplicates a waiting job is refused or, with `onDuplicate: "supersede"`, replaces it in its place in line.
 
 ## Order

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nledford/omp-coord",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "files": [
     "src",
     "docs",

package/src/adapters/cli/cli.ts

@@ -4,7 +4,7 @@
  * terminals, or agents' bash calls (which the extension rewrites to go through here when a rule queues them), and
  * reports on the scope.
  *
- *   omp-coord run <queue> [--lane L] [--priority N] [--key K] [--owner SESSION] [--timeout 90m] -- <command> [args…]
+ *   omp-coord run <queue> [--lane L] [--priority N] [--key K] [--owner SESSION] [--timeout 90m] [--meta k=v]... -- <command> [args…]
  *   omp-coord status [--agents | --json] | stats [days] | interrupted [hours] | notes [count] | note <text…>
  *   omp-coord pause [reason…] | resume | doctor [--fix]
  *
@@ -24,7 +24,7 @@ import { doctor } from "../../app/doctor.ts";
 import { EXIT_TIMED_OUT, runJob } from "../../app/job-runner.ts";
 import { type Config, ConfigError, findConfigFile, loadConfig } from "../../config.ts";
 import { statusView } from "../../domain/overview.ts";
-import { MAX_PRIORITY } from "../../domain/queues.ts";
+import { MAX_PRIORITY, parseMeta } from "../../domain/queues.ts";
 import { agentOfOmpSession } from "../../domain/sessions.ts";
 import { osLoad } from "../os/load.ts";
 import { groupRunning } from "../os/process-group.ts";
@@ -45,7 +45,7 @@ const KILL_GRACE_MS = 10_000;
 const DAY = 86_400_000;
 
 const USAGE = `usage:
-  omp-coord run <queue> [--lane L] [--priority N] [--key K] [--owner SESSION] [--timeout 90m] -- <command…>
+  omp-coord run <queue> [--lane L] [--priority N] [--key K] [--owner SESSION] [--timeout 90m] [--meta k=v]... -- <command…>
   omp-coord status [--agents | --json] | stats [days] | interrupted [hours] | notes [count] | note <text…>
   omp-coord pause [reason…] | resume | doctor [--fix]`;
 
@@ -206,6 +206,12 @@ async function run(args: string[]): Promise<number> {
   if (!Number.isSafeInteger(priority) || Math.abs(priority) > MAX_PRIORITY) {
     throw new UsageError(`omp-coord run: --priority must be a whole number from -${MAX_PRIORITY} to ${MAX_PRIORITY}`);
   }
+  let meta: ReturnType<typeof parseMeta>;
+  try {
+    meta = parseMeta(values.meta ?? []);
+  } catch (error) {
+    throw new UsageError(`omp-coord run: ${error instanceof Error ? error.message : String(error)}`);
+  }
   const timeoutMs = values.timeout === undefined ? undefined : parseDuration(values.timeout);
   const command = args.slice(split + 1);
 
@@ -258,6 +264,7 @@ async function run(args: string[]): Promise<number> {
         ...(values.lane === undefined ? {} : { lane: values.lane }),
         priority,
         ...(values.key === undefined ? {} : { key: values.key }),
+        ...(meta === undefined ? {} : { meta }),
         command: command.join(" "),
         pid: process.pid,
         ...(timeoutMs === undefined ? {} : { timeoutMs }),
@@ -293,6 +300,7 @@ function parseRunFlags(args: string[]) {
       key: { type: "string" },
       owner: { type: "string" },
       timeout: { type: "string" },
+      meta: { type: "string", multiple: true },
     },
   });
 }

package/src/adapters/sqlite/store.ts

@@ -81,6 +81,7 @@ CREATE TABLE jobs (
   key        TEXT,
   command    TEXT NOT NULL,
   agent      TEXT,
+  meta       TEXT,
   socket     TEXT NOT NULL,
   pid        INTEGER NOT NULL,
   state      TEXT NOT NULL CHECK (state IN ('waiting', 'running', 'superseded')),
@@ -258,6 +259,7 @@ export class BoardStore implements BoardRepository {
         .all()
         .some(c => c.name === column);
     if (!has("jobs", "agent")) this.#db.exec("ALTER TABLE jobs ADD COLUMN agent TEXT");
+    if (!has("jobs", "meta")) this.#db.exec("ALTER TABLE jobs ADD COLUMN meta TEXT");
     if (!has("slots", "unqueued"))
       this.#db.exec("ALTER TABLE slots ADD COLUMN unqueued TEXT CHECK (unqueued IN ('revived', 'eval'))");
     if (!has("sessions", "omp_session")) this.#db.exec("ALTER TABLE sessions ADD COLUMN omp_session TEXT");
@@ -369,6 +371,7 @@ export class BoardStore implements BoardRepository {
             key: string | null;
             command: string;
             agent: string | null;
+            meta: string | null;
             socket: string;
             pid: number;
             state: "waiting" | "running" | "superseded";
@@ -387,6 +390,7 @@ export class BoardStore implements BoardRepository {
           key: r.key ?? undefined,
           command: r.command,
           agent: r.agent ?? undefined,
+          meta: r.meta === null ? undefined : (JSON.parse(r.meta) as Record<string, string>),
           socket: r.socket,
           pid: r.pid,
           state: r.state,
@@ -499,7 +503,7 @@ export class BoardStore implements BoardRepository {
     const sent = db.query("INSERT INTO sent (session_id, at) VALUES (?, ?)");
     for (const x of board.sent) sent.run(x.sessionId, x.at);
     const job = db.query(
-      "INSERT INTO jobs (id, queue, owner, lane, priority, key, command, agent, socket, pid, state, since, started_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+      "INSERT INTO jobs (id, queue, owner, lane, priority, key, command, agent, meta, socket, pid, state, since, started_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
     );
     for (const j of board.jobs) {
       job.run(
@@ -511,6 +515,7 @@ export class BoardStore implements BoardRepository {
         j.key ?? null,
         j.command,
         j.agent ?? null,
+        j.meta === undefined ? null : JSON.stringify(j.meta),
         j.socket,
         j.pid,
         j.state,

package/src/adapters/text/report.ts

@@ -212,7 +212,7 @@ export function formatStats(days: DayStats[]): string {
     );
     for (const [q, s] of Object.entries(d.queues)) {
       lines.push(
-        `  ${q}: ${s.started} started, wait avg ${minutes(s.avgWaitMs)} / max ${minutes(s.maxWaitMs)}; ${s.ended} ended, ${s.failed} failed${s.timedOut ? ` (${s.timedOut} timed out)` : ""}`,
+        `  ${q}: ${s.started} started, wait avg ${minutes(s.avgWaitMs)} / max ${minutes(s.maxWaitMs)}; ${s.ended} ended, ${s.failed} failed${s.timedOut ? ` (${s.timedOut} timed out)` : ""}${s.ofFailures ? `; of the failures: ${s.ofFailures.repeats} repeat an unchanged failure, ${s.ofFailures.intended} intended` : ""}`,
       );
     }
   }

package/src/app/coordinator.ts

@@ -161,7 +161,7 @@ export class Coordinator {
   }
 
   stats(sinceMs: number): DayStats[] {
-    return stats(this.repo.events(this.clock.now() - sinceMs), 0).days;
+    return stats(this.repo.events(), this.clock.now() - sinceMs).days;
   }
 
   requestSpawn(req: Omit<SpawnRequest, "now">): SpawnDecision {

package/src/app/job-runner.ts

@@ -22,6 +22,8 @@ export interface JobSpec {
   lane?: string;
   priority: number;
   key?: string;
+  /** Tags for the event log. */
+  meta?: Record<string, string>;
   /** For display. */
   command: string;
   pid: number;

package/src/domain/history.ts

@@ -67,6 +67,8 @@ export interface QueueDay {
   /** Ended with a nonzero exit code, a signal, or a timeout. */
   failed: number;
   timedOut: number;
+  /** Present when any failed job of the day carried `--meta` tags. */
+  ofFailures?: { repeats: number; intended: number };
 }
 
 export interface DayStats {
@@ -80,7 +82,16 @@ export interface DayStats {
   queues: Record<string, QueueDay>;
 }
 
+/**
+ * Per queue and day: failures that repeat an unchanged failure (a failed job with `meta.fp` equal to that of an
+ * earlier failed job of the same queue in the window, with no successful job of that `fp` in between) and failures
+ * marked `meta.intent == "failfirst"`.
+ */
 export function stats(events: BoardEvent[], since: number): { days: DayStats[] } {
+  // Per queue: fingerprints whose latest outcome was a failure.
+  const failing = new Map<string, Set<string>>();
+  // Tags seen at queue time, for a job_ended that lost them (an older omp-coord still running rewrote the job without them).
+  const queuedMeta = new Map<string, unknown>();
   const days = new Map<string, DayStats & { waits: Record<string, number[]> }>();
   const dayOf = (at: number) => {
     const d = new Date(at);
@@ -96,6 +107,11 @@ export function stats(events: BoardEvent[], since: number): { days: DayStats[] }
     (s.queues[q] ??= { started: 0, avgWaitMs: 0, maxWaitMs: 0, ended: 0, failed: 0, timedOut: 0 });
 
   for (const e of events) {
+    // Tags are indexed from the whole log, so a job queued before the window still explains its end inside it.
+    if (e.type === "job_queued") {
+      if (e.data.meta === undefined) queuedMeta.delete(String(e.data.job));
+      else queuedMeta.set(String(e.data.job), e.data.meta);
+    }
     if (e.at < since) continue;
     const s = dayOf(e.at);
     const n = (k: string) => (typeof e.data[k] === "number" ? (e.data[k] as number) : 0);
@@ -117,8 +133,30 @@ export function stats(events: BoardEvent[], since: number): { days: DayStats[] }
     if (e.type === "job_ended") {
       const q = queueOf(s, String(e.data.queue));
       q.ended++;
-      if (e.data.exitCode !== 0 || e.data.timedOut === true) q.failed++;
+      const failed = e.data.exitCode !== 0 || e.data.timedOut === true;
+      if (failed) q.failed++;
       if (e.data.timedOut === true) q.timedOut++;
+      const jobId = String(e.data.job);
+      const meta = e.data.meta ?? queuedMeta.get(jobId);
+      queuedMeta.delete(jobId);
+      if (typeof meta === "object" && meta !== null) {
+        const tags = meta as Record<string, unknown>;
+        const fp = typeof tags.fp === "string" ? tags.fp : undefined;
+        const queueName = String(e.data.queue);
+        const set = failing.get(queueName) ?? new Set<string>();
+        failing.set(queueName, set);
+        if (failed) {
+          const counts = q.ofFailures ?? { repeats: 0, intended: 0 };
+          q.ofFailures = counts;
+          if (fp !== undefined) {
+            if (set.has(fp)) counts.repeats++;
+            set.add(fp);
+          }
+          if (tags.intent === "failfirst") counts.intended++;
+        } else if (fp !== undefined) {
+          set.delete(fp);
+        }
+      }
     }
   }
   return {

package/src/domain/model.ts

@@ -181,6 +181,8 @@ export interface Job {
   priority: number;
   /** Jobs with the same key are duplicates (e.g. "<checkout> ci"). */
   key: string | undefined;
+  /** Tags the caller gave (`--meta k=v`), kept in the event log; undefined when none. */
+  meta?: Record<string, string> | undefined;
   /** What runs, for display. */
   command: string;
   /** The runner's liveness socket and process id. */

package/src/domain/queues.ts

@@ -47,12 +47,38 @@ export interface JobRequest {
   lane?: string;
   priority: number;
   key?: string;
+  meta?: Record<string, string>;
   command: string;
   socket: string;
   pid: number;
   now: number;
 }
 
+export const MAX_META = 8;
+const META_KEY = /^[a-z][a-z0-9_-]{0,31}$/;
+const MAX_META_VALUE = 200;
+
+/**
+ * Parses repeated `--meta k=v` values into tags (a repeated key: the last wins). Throws an Error naming the problem:
+ * more than `MAX_META` pairs, no `=`, a key outside `[a-z][a-z0-9_-]{0,31}`, a value over 200 characters or with a
+ * newline. Returns undefined for no pairs.
+ */
+export function parseMeta(pairs: string[]): Record<string, string> | undefined {
+  if (pairs.length > MAX_META) throw new Error(`--meta may be given at most ${MAX_META} times`);
+  const meta: Record<string, string> = {};
+  for (const pair of pairs) {
+    const eq = pair.indexOf("=");
+    if (eq < 0) throw new Error(`--meta takes k=v, not "${pair}"`);
+    const k = pair.slice(0, eq);
+    const v = pair.slice(eq + 1);
+    if (!META_KEY.test(k)) throw new Error(`--meta key "${k}" must match [a-z][a-z0-9_-]{0,31}`);
+    if (v.length > MAX_META_VALUE) throw new Error(`--meta ${k}: the value is over ${MAX_META_VALUE} characters`);
+    if (/[\r\n]/.test(v)) throw new Error(`--meta ${k}: the value must not contain a newline`);
+    meta[k] = v;
+  }
+  return Object.keys(meta).length ? meta : undefined;
+}
+
 export type EnqueueResult = { ok: true } | { ok: false; reason: string };
 
 /** Puts a job in line (or starts it at once when a slot is free). */
@@ -86,6 +112,7 @@ export function enqueueJob(board: Board, queues: Queues, req: JobRequest): Enque
     lane,
     priority: req.priority,
     key: req.key,
+    meta: req.meta,
     command: req.command,
     socket: req.socket,
     pid: req.pid,
@@ -100,6 +127,7 @@ export function enqueueJob(board: Board, queues: Queues, req: JobRequest): Enque
     priority: req.priority,
     ...(req.key === undefined ? {} : { key: req.key }),
     ...(req.agent === undefined ? {} : { agent: req.agent }),
+    ...(req.meta === undefined ? {} : { meta: req.meta }),
   });
   schedule(board, queues, req.now);
   return { ok: true };
@@ -128,6 +156,8 @@ export function jobEnded(
       queue: job.queue,
       exitCode: j.exitCode,
       ranMs: j.now - (job.startedAt ?? j.now),
+      ...(job.key === undefined ? {} : { key: job.key }),
+      ...(job.meta === undefined ? {} : { meta: job.meta }),
       ...(j.timedOut ? { timedOut: true } : {}),
     });
   } else if (job.state === "waiting") {