@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

package/dist/templates/monorepo/scripts/backlog/types.ts

@@ -62,6 +62,27 @@ export const EXECUTION_PATH = {
 
 export type ExecutionPath = (typeof EXECUTION_PATH)[keyof typeof EXECUTION_PATH];
 
+/**
+ * Whether a task may run under a dispatched worker with no person present (`headless`) or must be
+ * worked in a session with a person (`supervised`). Declared, never inferred — see
+ * `specs/backlog-task-lifecycle/spec.md` — "Task label taxonomy and required fields": a task with
+ * no `mode` label has an incomplete triage, it does not default to either value.
+ */
+export const MODE = {
+  HEADLESS: 'headless',
+  SUPERVISED: 'supervised',
+} as const;
+
+export type Mode = (typeof MODE)[keyof typeof MODE];
+
+/**
+ * The label that identifies the one board task mirroring the dependency graph view
+ * (`backlog-dependency-graph` capability, `graph.ts`). Found by this label, never by a fixed task
+ * id, because the same tooling ships to scaffolded applications whose boards number their tasks
+ * differently (design.md decision 2).
+ */
+export const GRAPH_HOLDER_LABEL = 'board:graph';
+
 /**
  * The two dispatch caps `lanes.json` declares: one concurrency cap per lane (`maxParallel`,
  * design.md — Component design, Slot pool) and the attempt ceiling (`attempts`, design.md decision
@@ -94,7 +115,16 @@ export interface Task {
   tier?: Tier;
   lane?: Lane;
   path?: ExecutionPath;
+  /** Missing has the same meaning as a missing `tier`/`lane`/`path`: an incomplete triage. */
+  mode?: Mode;
   bc?: string;
+  /**
+   * Whether this task carries the `board:graph` label — the graph-holder task
+   * (`backlog-dependency-graph` capability). Never listed by `graph.ts`'s renderer, whatever its
+   * own dependency state. Defaults to `false`: every fixture and every board read that predates
+   * this field is an ordinary task, not a holder.
+   */
+  isGraphHolder?: boolean;
   filesToTouch: string[];
   /**
    * The `Test command:` line as it read at LAUNCH time, or `null` when the task declared none.
@@ -103,19 +133,6 @@ export interface Task {
    * worker (or anyone else) left on the board while it ran.
    */
   testCommand: string | null;
-  /**
-   * The `Branch:` line as it read on THIS task's own description, or `undefined`/`null` when it
-   * declares none — a person writes this on a PARENT task right after creating its worktree branch
-   * (`superpowers:using-git-worktrees`, per the root `CLAUDE.md`'s Worktree Gate), since that branch
-   * is almost never `task/<id>` (see `catalyst-backlog/SKILL.md`'s `Branch:` convention). It is the
-   * FIRST link of `guards.ts`'s base-branch resolution chain: `taskBaseBranch`/`resolveTaskBase`
-   * read a SUBTASK's parent's `declaredBranch` — never a task's own, which is meaningless for
-   * anything but a parent — falling back to the `task/<parentId>` convention when it is absent.
-   * Optional (unlike `testCommand`) so a caller with no board lookup in hand (most existing test
-   * fixtures, and every leaf task that is not itself someone's parent) needs no change to keep
-   * reading as "no declaration", which resolves exactly as it always has.
-   */
-  declaredBranch?: string | null;
   /**
    * The acceptance-criteria and Definition-of-Done TEXTS as they read at LAUNCH, in board order and
    * without their checked state. The close re-reads the board for the checked state — the worker
@@ -157,12 +174,12 @@ export interface Board {
    * Whether `tasksById` is the WHOLE board — the same distinction `BoardLoad.complete` carries from
    * the read that produced it (`dispatch.ts`'s `loadBoard` drops a task whose `backlog task view`
    * threw and reports the read incomplete rather than silently proceeding as if it did not exist).
-   * Guard 4b (`guards.ts`'s `checkParentBranchOnRemote`) reads it: a subtask whose parent id is
-   * absent from an INCOMPLETE board waits for a pass with a working read, instead of being blocked
-   * on a base branch this pass could not actually determine.
+   * The parent-recomputation path (`dispatch.ts`'s `recomputeParent`, `maintenance.ts`'s step 5)
+   * reads it: deriving a parent from some but not all of its children produces a confident wrong
+   * answer, so that derivation is skipped entirely when the board it would read is incomplete.
    *
    * Optional, defaulting to "complete" (`true`) — every caller that predates this field (most
-   * existing test fixtures, and every real board load that succeeded outright) keeps every guard's
+   * existing test fixtures, and every real board load that succeeded outright) keeps every reader's
    * prior behaviour unchanged.
    */
   complete?: boolean;
@@ -179,6 +196,19 @@ export interface SlotInfo {
   pid: number | null;
   /** Hash of the `pnpm-lock.yaml` last installed in this slot, or `null` if never installed. */
   lockfileHash: string | null;
+  /**
+   * Hash of `packages/cli/pnpm-lock.yaml` last installed in this slot — `undefined` for a slot
+   * registered before this field existed. Deliberately a SEPARATE field from `lockfileHash`
+   * (T-50), never folded into it: the two are persisted at DIFFERENT points in the dispatch
+   * sequence — `lockfileHash` right after the root's own install, `cliLockfileHash` only after the
+   * CLI's install has actually succeeded, later in the same pass (after `prepareSlot`). A single
+   * combined field cannot honor two different success moments; an early return between them (a
+   * `branch-in-use` handback) would otherwise let one persisted write silently vouch for work the
+   * other artifact never did. `undefined` differs from any real hash, so a legacy slot's first
+   * acquisition re-triggers the CLI install once and self-corrects from there — the exact slots
+   * that genuinely have no `packages/cli/node_modules` of their own yet.
+   */
+  cliLockfileHash?: string | null;
   /**
    * Set when a close or a maintenance sweep could not PUSH the work this slot holds. The slot then
    * holds the only copy of that work, so it is neither released nor reassigned until the

package/dist/templates/monorepo/scripts/backlog/watch.test.ts

@@ -14,6 +14,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { describe, it } from 'node:test';
+import { renderStream } from './render.js';
 import { LANE, type DispatchLock, type SlotInfo } from './types.js';
 import {
   buildSlotsTable,
@@ -22,6 +23,8 @@ import {
   formatSlotsTable,
   latestAttemptDirName,
   readNewBytes,
+  splitCompleteLines,
+  tailAttemptStream,
   type PollScheduler,
 } from './watch.js';
 
@@ -240,6 +243,35 @@ describe('followTick', () => {
   });
 });
 
+// ── splitCompleteLines (T-30: line-buffering `stream.jsonl`'s live growth) ───────
+//
+// `stream.jsonl` grows by whole JSON lines, but a poll tick can land mid-write and hand
+// `followFile`'s chunk a partial trailing line. `splitCompleteLines` is the pure step that holds
+// that partial segment back as `remainder` until the next chunk completes it, so `createLiveRenderer`
+// (render.ts) is never fed a line `JSON.parse` cannot handle just because it was read too early.
+
+describe('splitCompleteLines', () => {
+  it('splits a chunk with a trailing newline into complete lines, remainder empty', () => {
+    const result = splitCompleteLines('', 'a\nb\n');
+    assert.deepEqual(result, { lines: ['a', 'b'], remainder: '' });
+  });
+
+  it('keeps a partial last line as remainder when the chunk has no trailing newline', () => {
+    const result = splitCompleteLines('', 'a\nb\npartial');
+    assert.deepEqual(result, { lines: ['a', 'b'], remainder: 'partial' });
+  });
+
+  it('prepends the carried-over remainder before splitting the new chunk', () => {
+    const result = splitCompleteLines('par', 'tial\nnext\n');
+    assert.deepEqual(result, { lines: ['partial', 'next'], remainder: '' });
+  });
+
+  it('returns no complete lines when the chunk carries no newline at all', () => {
+    const result = splitCompleteLines('so ', 'far no newline');
+    assert.deepEqual(result, { lines: [], remainder: 'so far no newline' });
+  });
+});
+
 // ── followFile (T-8 defects 9 and 10: the poll-scheduling glue itself) ────────
 
 /**
@@ -343,6 +375,27 @@ describe('followFile', () => {
     assert.equal(scheduler.stopCallCount, 0);
   });
 
+  it('uses options.initialSize as previousSize instead of its own stat, closing the catch-up race (T-30)', () => {
+    // Simulates a caller that already consumed 6 bytes ("first\n") via its own catch-up read, THEN
+    // — before followFile ever gets to run, exactly the race window a fresh internal stat cannot
+    // see around — a second process appends more. A followFile that stat'd the file itself at
+    // construction would read the CURRENT (post-append) size as its baseline and never surface the
+    // append at all; only trusting the caller's own count with `initialSize` catches it.
+    const filePath = tempLogPath('stream.jsonl');
+    fs.writeFileSync(filePath, 'first\n');
+    fs.appendFileSync(filePath, 'second\n');
+    const scheduler = manualScheduler();
+    const chunks: string[] = [];
+    followFile(filePath, (chunk) => chunks.push(chunk), {
+      initialSize: 6,
+      schedulePoll: scheduler.schedulePoll,
+    });
+
+    scheduler.tick();
+
+    assert.deepEqual(chunks, ['second\n']);
+  });
+
   it('keeps polling (never calls the stop function) while the lock is still there', () => {
     const filePath = tempLogPath('run.log');
     fs.writeFileSync(filePath, 'a');
@@ -358,3 +411,95 @@ describe('followFile', () => {
     assert.equal(scheduler.stopCallCount, 0);
   });
 });
+
+// ── `tailAttemptStream` — `main()`'s live-tail wiring, exercised end to end (T-30 AC4) ──────────
+//
+// tasks.md 3.20's old manual check copied a whole RECORDED fixture into `run.log` and watched it
+// stream — that proves a static file can be tailed, never that growth is visible WHILE it happens.
+// These tests drive `tailAttemptStream` directly — the SAME function `main()` calls, not a
+// hand-copied loop — so editing `main()`'s wiring cannot leave a copy behind for the test to keep
+// protecting instead.
+
+describe("main()'s live-tail wiring over a growing stream.jsonl", () => {
+  it('renders each event as its own line completes, matching a batch renderStream of the final content', () => {
+    const filePath = tempLogPath('stream.jsonl');
+    const scheduler = manualScheduler();
+    const rendered: string[] = [];
+
+    tailAttemptStream({
+      streamPath: filePath,
+      lockExists: () => true,
+      out: (line) => rendered.push(line),
+      schedulePoll: scheduler.schedulePoll,
+    });
+
+    const firstEvent = JSON.stringify({
+      type: 'assistant',
+      timestamp: '2026-09-11T10:00:00.000Z',
+      message: { content: [{ type: 'tool_use', name: 'Read', input: { file_path: 'a.ts' } }] },
+    });
+    fs.appendFileSync(filePath, `${firstEvent}\n`);
+    scheduler.tick();
+
+    // Visible LIVE, after only the first write — a copied-fixture check cannot show this: the
+    // whole file already existed before it was ever tailed.
+    assert.equal(rendered.length, 1);
+    assert.match(rendered[0], /Read/);
+
+    const secondEvent = JSON.stringify({ type: 'result', subtype: 'success', num_turns: 1 });
+    fs.appendFileSync(filePath, `${secondEvent}\n`);
+    scheduler.tick();
+
+    assert.equal(rendered.length, 2);
+    assert.match(rendered[1], /^result success/);
+
+    const finalLines = fs
+      .readFileSync(filePath, 'utf8')
+      .split('\n')
+      .filter((line) => line.trim() !== '');
+    assert.deepEqual(rendered, renderStream(finalLines));
+  });
+
+  // AC3: the common real-use path — a watcher attaches MINUTES into a live dispatch, when
+  // `stream.jsonl` already holds lines. `tailAttemptStream`'s catch-up read must render those
+  // pre-existing lines exactly once, and the `initialSize` it hands `followFile` must make the
+  // first live tick pick up ONLY what was appended afterwards — never re-reading the catch-up
+  // bytes (a duplicate) and never skipping the boundary between them (a gap).
+  it('catches up pre-existing lines once, then tails appended lines with none duplicated or skipped', () => {
+    const filePath = tempLogPath('stream.jsonl');
+    const firstEvent = JSON.stringify({
+      type: 'assistant',
+      timestamp: '2026-09-11T10:00:00.000Z',
+      message: { content: [{ type: 'tool_use', name: 'Read', input: { file_path: 'a.ts' } }] },
+    });
+    fs.writeFileSync(filePath, `${firstEvent}\n`);
+
+    const scheduler = manualScheduler();
+    const rendered: string[] = [];
+
+    tailAttemptStream({
+      streamPath: filePath,
+      lockExists: () => true,
+      out: (line) => rendered.push(line),
+      schedulePoll: scheduler.schedulePoll,
+    });
+
+    // The catch-up read runs synchronously, before any poll tick.
+    assert.equal(rendered.length, 1);
+    assert.match(rendered[0], /Read/);
+
+    const secondEvent = JSON.stringify({ type: 'result', subtype: 'success', num_turns: 1 });
+    fs.appendFileSync(filePath, `${secondEvent}\n`);
+    scheduler.tick();
+
+    // Exactly one more line — the appended one, never the pre-existing line again.
+    assert.equal(rendered.length, 2);
+    assert.match(rendered[1], /^result success/);
+
+    const finalLines = fs
+      .readFileSync(filePath, 'utf8')
+      .split('\n')
+      .filter((line) => line.trim() !== '');
+    assert.deepEqual(rendered, renderStream(finalLines));
+  });
+});

package/dist/templates/monorepo/scripts/backlog/watch.ts

@@ -1,47 +1,62 @@
 /**
- * watch.ts — `pnpm backlog:watch [id]`: tails a running task's human-rendered log, or (with no
- * id) lists busy dispatch slots.
+ * watch.ts — `pnpm backlog:watch [id]`: tails a running task's human-rendered log LIVE, or (with
+ * no id) lists busy dispatch slots.
  *
  * Implements `specs/backlog-task-dispatcher/spec.md` — "Observability of running and busy dispatch
- * state" (`pnpm backlog:watch T-12` streams that attempt's rendered log; `pnpm backlog:watch`
- * with no id lists busy slots from `slots.json`). Reads only — never writes board state, a lock,
- * or a slot; a pure spectator over `.backlog/.dispatch/`.
+ * state" (`pnpm backlog:watch T-12` streams that attempt's rendered log AS THE WORKER PRODUCES IT;
+ * `pnpm backlog:watch` with no id lists busy slots from `slots.json`). Reads only — never writes
+ * board state, a lock, or a slot; a pure spectator over `.backlog/.dispatch/`.
+ *
+ * T-30: the tailed file is `stream.jsonl`, the raw event log `attempt.ts`'s sink appends to as the
+ * worker runs, never `run.log` — `run.log` is the whole-session artifact `sink.finish()` writes
+ * ONCE, at the very end of the attempt, so a watcher tailing it saw nothing until the worker was
+ * already done. `main` renders each newly-completed line through `createLiveRenderer` (render.ts) —
+ * the SAME `renderEvent` `run.log` is built from, so a live tail and the final `run.log` read never
+ * disagree — at O(1) cost per line, never re-rendering the session collected so far. A poll tick can
+ * land mid-write and hand a partial trailing line; `splitCompleteLines` is the pure step that holds
+ * that partial segment back as `remainder` until the next chunk completes it, so the renderer only
+ * ever sees whole JSON lines.
  *
  * The pure helpers (`latestAttemptDirName`, `buildSlotsTable`, `formatSlotsTable`, `readNewBytes`,
- * `followTick`) are unit-tested in `watch.test.ts`. So is the poll-scheduling glue in `followFile`
- * itself — the stop-on-lock-disappearance loop, its `onExit` callback, and the default "no
- * `lockExists` option means never stop" behaviour — via an injectable `schedulePoll` (mirrors
- * `attempt.ts`'s `HeartbeatScheduler`) that lets a test drive one tick by hand instead of waiting on
- * a real interval. Only `main`'s argv parsing and console wiring are still verified manually per
- * tasks.md 3.20 — copy a recorded fixture into a temp `.backlog/.dispatch/<id>/intento-1/run.log`
- * and watch new lines stream as the file grows.
+ * `splitCompleteLines`, `followTick`) are unit-tested in `watch.test.ts`. So is the poll-scheduling
+ * glue in `followFile` itself — the stop-on-lock-disappearance loop, its `onExit` callback, and the
+ * default "no `lockExists` option means never stop" behaviour — via an injectable `schedulePoll`
+ * (mirrors `attempt.ts`'s `HeartbeatScheduler`) that lets a test drive one tick by hand instead of
+ * waiting on a real interval. Per T-30 AC4, `watch.test.ts`'s live-tail wiring test drives a REAL,
+ * growing file through several REAL `fs.appendFileSync` writes with polling ticks between them,
+ * proving an event renders after its OWN write, before any later one exists — the fixture-replay
+ * check tasks.md 3.20 used before `stream.jsonl` was tailed only ever copied a WHOLE recorded
+ * session into `run.log` at once, which proves nothing about whether growth is visible WHILE the
+ * worker still runs. `main`'s argv parsing and its `console`/`process.stdout` wiring to the real
+ * filesystem remain unverified by an automated test, same as before this change.
  *
  * T-8 point 1: `followFile` used to be a bare `setInterval` with no exit condition at all — two
  * watchers were measured six hours orphaned after their task's dispatch had already finished,
  * because nothing ever told the poller to stop. It now stops on its own once the task's lock file
  * (`locks/<TASK_ID>.json`) disappears — the close removes it as its very last step (`releaseLock`,
  * `entry.ts`), so "the lock is gone" means "there is nothing left to tail" — but it flushes
- * whatever `run.log` holds at THAT tick before stopping: a watcher that noticed the lock was gone
- * and exited without reading the file's final growth would lose exactly the tail of the log, which
- * is where a failure's explanation usually lives. `followTick` is the pure step that makes both
- * halves — "read what's new" and "stop after this read" — one atomic decision instead of two racy
- * ones.
+ * whatever `stream.jsonl` holds at THAT tick before stopping: a watcher that noticed the lock was
+ * gone and exited without reading the file's final growth would lose exactly the tail of the
+ * stream, which is where a failure's explanation usually lives. `followTick` is the pure step that
+ * makes both halves — "read what's new" and "stop after this read" — one atomic decision instead of
+ * two racy ones.
  *
- * T-8 defect 9 (2026-09-08 hardening): a missing `run.log` used to make a tick bail out via
+ * T-8 defect 9 (2026-09-08 hardening): a missing tailed file used to make a tick bail out via
  * `catch { return; }` BEFORE `followTick` — and therefore `lockExists` — was ever consulted.
- * `run.log` is written exactly once, by `sink.finish()` (`attempt.ts`), and two paths remove the
- * lock without ever calling it: `abortDispatch` (`entry.ts`) and the maintenance dead-worker sweep.
- * A watcher started on a task whose dispatch aborts before the worker ever streamed a line — a
- * failed `pnpm install`, say — therefore polled forever, the exact six-hour orphan AC1 exists to
- * kill. A missing file now reads as "no growth" instead of skipping the tick, so the lock is still
- * checked and the watcher still stops.
+ * `stream.jsonl` is created lazily, by the first `appendStreamLine` call (`attempt.ts`'s sink), so a
+ * task whose dispatch aborts before the worker ever streamed a line — a failed `pnpm install`, say —
+ * never creates it at all; two paths remove the lock without the worker ever emitting anything:
+ * `abortDispatch` (`entry.ts`) and the maintenance dead-worker sweep. Such a watcher therefore
+ * polled forever, the exact six-hour orphan AC1 exists to kill. A missing file now reads as "no
+ * growth" instead of skipping the tick, so the lock is still checked and the watcher still stops.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { findRepoRoot } from '../_catalog-runtime/repo-root.js';
 import { ATTEMPT_DIR_PATTERN } from './attempt.js';
+import { realGitCommonDir } from './dispatch.js';
 import { resolveContext } from './entry.js';
+import { createLiveRenderer } from './render.js';
 import { lockFilePath } from './slots.js';
 import type { DispatchLock, SlotInfo, SlotRegistry } from './types.js';
 
@@ -138,6 +153,28 @@ export function readNewBytes(input: ReadNewBytesInput): ReadNewBytesResult {
   return { content: input.readRange(input.previousSize), newSize: input.currentSize };
 }
 
+// ── splitCompleteLines — line-buffering a JSONL file's live growth ──────────────
+
+export interface SplitCompleteLinesResult {
+  /** Every newline-terminated line completed by this chunk, in order. */
+  lines: string[];
+  /** The trailing partial line (no newline yet), carried into the next call as its first argument. */
+  remainder: string;
+}
+
+/**
+ * Splits `remainder + chunk` into complete lines and a new remainder — the pure step behind
+ * tailing `stream.jsonl` live (T-30): a poll tick can land mid-write, handing `followFile`'s chunk a
+ * partial trailing JSON line `JSON.parse` cannot handle yet. Holding that partial segment back
+ * until the next chunk completes it is what lets `createLiveRenderer` (render.ts) only ever see
+ * whole lines, exactly as `renderStream`'s batch replay does.
+ */
+export function splitCompleteLines(remainder: string, chunk: string): SplitCompleteLinesResult {
+  const parts = (remainder + chunk).split('\n');
+  const newRemainder = parts.pop() ?? '';
+  return { lines: parts, remainder: newRemainder };
+}
+
 export interface FollowTickInput {
   previousSize: number;
   currentSize: number;
@@ -151,11 +188,11 @@ export interface FollowTickResult {
   newSize: number;
   /**
    * True once this tick has both read whatever growth there was AND found the lock gone — the
-   * caller stops polling AFTER this tick, never instead of it. `attempt.ts`'s `finish()` renders
-   * the whole `run.log` and `entry.ts`'s close removes the lock only at the very end, once the
-   * slot is released or held (`stopHeartbeat`) — so by the time the lock disappears, the file
-   * already holds everything there is to hold, and this same tick's `readNewBytes` step is what
-   * catches it.
+   * caller stops polling AFTER this tick, never instead of it. `stream.jsonl` gets its last line
+   * appended before `attempt.ts`'s `finish()` returns, and `entry.ts`'s close removes the lock only
+   * at the very end, once the slot is released or held (`stopHeartbeat`) — so by the time the lock
+   * disappears, the tailed file already holds everything there is to hold, and this same tick's
+   * `readNewBytes` step is what catches it.
    */
   done: boolean;
 }
@@ -197,6 +234,16 @@ export interface FollowFileOptions {
   onExit?: () => void;
   /** Injected so tests drive the poll tick by hand; defaults to a real `setInterval`. */
   schedulePoll?: PollScheduler;
+  /**
+   * The byte count a caller has ALREADY consumed (e.g. a catch-up read done before calling
+   * `followFile`), used as `previousSize` instead of `followFile`'s own initial `fs.statSync`.
+   * Without this, a caller who reads existing content first and only then calls `followFile` leaves
+   * a window between that read and `followFile`'s own stat — on a file another process keeps
+   * appending to (unlike a `run.log` written once, at the very end), bytes written inside that
+   * window are folded into the fresh stat's `previousSize` as if already consumed and are never
+   * read at all. Passing the caller's own consumed length closes the window instead of narrowing it.
+   */
+  initialSize?: number;
 }
 
 /**
@@ -212,10 +259,14 @@ export function followFile(
   const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
   const schedulePoll = options.schedulePoll ?? defaultSchedulePoll;
   let previousSize = 0;
-  try {
-    previousSize = fs.statSync(filePath).size;
-  } catch {
-    previousSize = 0;
+  if (options.initialSize !== undefined) {
+    previousSize = options.initialSize;
+  } else {
+    try {
+      previousSize = fs.statSync(filePath).size;
+    } catch {
+      previousSize = 0;
+    }
   }
 
   const stopPolling = schedulePoll(() => {
@@ -223,12 +274,13 @@ export function followFile(
     try {
       currentSize = fs.statSync(filePath).size;
     } catch {
-      // T-8 defect 9: the file may not exist YET (attempt just started), or may never exist AT
+      // T-8 defect 9: the file may not exist YET (attempt just started; `stream.jsonl` is created
+      // lazily by the FIRST `appendStreamLine` call in `attempt.ts`'s sink), or may never exist AT
       // ALL — `abortDispatch` (entry.ts) and the maintenance dead-worker sweep both remove the
-      // task's lock without ever calling `sink.finish()` (attempt.ts), the only thing that writes
-      // `run.log`. Treat a missing file as "no growth" rather than skipping the tick, so
-      // `lockExists` below is still consulted this tick — otherwise a watcher whose target file
-      // never appears polls forever even after the lock (and the task) is long gone.
+      // task's lock without the worker ever emitting a line. Treat a missing file as "no growth"
+      // rather than skipping the tick, so `lockExists` below is still consulted this tick —
+      // otherwise a watcher whose target file never appears polls forever even after the lock (and
+      // the task) is long gone.
       currentSize = previousSize;
     }
     const result = followTick({
@@ -260,6 +312,67 @@ export function followFile(
   return stopPolling;
 }
 
+// ── tailAttemptStream — main()'s live-tail wiring, extracted for direct test coverage ──────────
+
+export interface TailAttemptStreamInput {
+  streamPath: string;
+  /** Whether the task's dispatch lock file is STILL there — passed straight through to `followFile`. */
+  lockExists: () => boolean;
+  /** Called once per rendered line: `console.log` in production, a collector in a test. */
+  out: (line: string) => void;
+  /** Called once, after the final chunk (if any), right before the poll stops. */
+  onExit?: () => void;
+  /** Injected so a test drives the poll tick by hand; defaults to a real `setInterval`. */
+  schedulePoll?: PollScheduler;
+}
+
+/**
+ * `main()`'s live-tail wiring (T-30 AC4), extracted so a test can drive the REAL catch-up + live
+ * loop instead of a hand-copied one: catches up whatever the attempt already produced before this
+ * watcher attached, then follows `streamPath` for further growth, feeding every complete line
+ * through ONE `createLiveRenderer` so the catch-up half and the live half never disagree on state.
+ */
+export function tailAttemptStream(input: TailAttemptStreamInput): void {
+  const { streamPath, lockExists, out, onExit, schedulePoll } = input;
+
+  const renderer = createLiveRenderer();
+  let remainder = '';
+  const renderChunk = (chunk: string): void => {
+    const split = splitCompleteLines(remainder, chunk);
+    remainder = split.remainder;
+    for (const line of split.lines) {
+      if (line.trim().length === 0) {
+        continue;
+      }
+      const rendered = renderer.feed(line);
+      if (rendered !== null) {
+        out(rendered);
+      }
+    }
+  };
+
+  // Catches up whatever the attempt already produced before this watcher attached. Read as a
+  // BUFFER, not a decoded string, so `consumedSize` below is the exact byte count on disk — the
+  // same unit `fs.statSync().size` reports — and never a character count a multi-byte UTF-8
+  // sequence would throw off. That exact count is handed to `followFile` as `initialSize`: a fresh
+  // `fs.statSync` of its own, taken an instant later, would fold in whatever the worker appended
+  // during that instant and never read it (a real risk here — the worker writes `stream.jsonl`
+  // continuously, unlike `run.log`, written once at the very end).
+  let consumedSize = 0;
+  if (fs.existsSync(streamPath)) {
+    const buffer = fs.readFileSync(streamPath);
+    consumedSize = buffer.length;
+    renderChunk(buffer.toString('utf8'));
+  }
+
+  followFile(streamPath, renderChunk, {
+    initialSize: consumedSize,
+    lockExists,
+    onExit,
+    schedulePoll,
+  });
+}
+
 // ── main ────────────────────────────────────────────────────────────────────────
 
 function readSlotRegistry(dispatchDir: string): SlotRegistry {
@@ -282,10 +395,11 @@ function readAllLocks(dispatchDir: string): DispatchLock[] {
 }
 
 function main(): void {
+  const cwd = process.cwd();
   const { mainCheckoutPath } = resolveContext({
-    cwd: process.cwd(),
+    cwd,
     env: { BACKLOG_CWD: process.env.BACKLOG_CWD },
-    findRepoRoot,
+    gitCommonDir: () => realGitCommonDir(cwd),
   });
   const dispatchDir = path.join(mainCheckoutPath, DISPATCH_SUBDIR);
   const taskId = process.argv[2];
@@ -310,17 +424,19 @@ function main(): void {
     return;
   }
 
-  const runLog = path.join(taskDir, latest, 'run.log');
-  console.log(`Tailing ${runLog} ...`);
-  if (fs.existsSync(runLog)) {
-    process.stdout.write(fs.readFileSync(runLog, 'utf8'));
-  }
+  // T-30: tails `stream.jsonl` LIVE, one raw event at a time, through `createLiveRenderer` — the
+  // same `renderEvent` `run.log` is built from — instead of waiting for `run.log`, which
+  // `sink.finish()` (attempt.ts) only writes once, at the very end of the attempt.
+  const streamPath = path.join(taskDir, latest, 'stream.jsonl');
+  console.log(`Tailing ${streamPath} ...`);
 
   // T-8 point 1: stop on our own once the task's lock is gone, instead of polling forever — two
   // watchers were measured six hours orphaned after their task had already finished.
   const lockPath = lockFilePath(dispatchDir, taskId);
-  followFile(runLog, (chunk) => process.stdout.write(chunk), {
+  tailAttemptStream({
+    streamPath,
     lockExists: () => fs.existsSync(lockPath),
+    out: (line) => console.log(line),
     onExit: () => {
       console.log(`\nbacklog:watch: ${taskId}'s lock is gone; the attempt finished.`);
     },

package/dist/templates/monorepo/scripts/backlog/worker-edit.test.ts

@@ -154,7 +154,7 @@ describe('workerEditCommand', () => {
 // own task id as the parent (never a `--parent` the argv names itself).
 
 const FRONTIER_DESC = 'Split into IPC bridge work.\n\nTest command: pnpm --filter aurora-desktop test';
-const FRONTIER_LABELS = 'tier:medium,lane:frontier,path:direct,bc:desktop';
+const FRONTIER_LABELS = 'tier:medium,lane:frontier,path:direct,mode:headless,bc:desktop';
 
 const validSubtaskArgv = (): string[] => [
   'T-10',
@@ -231,12 +231,12 @@ describe('validateWorkerEditArgs — subtask refusals', () => {
     { name: 'missing --labels', argv: withoutFlag(validSubtaskArgv(), '--labels'), expected: /falta "--labels"/ },
     {
       name: 'a bad tier value',
-      argv: withLabels('tier:huge,lane:frontier,path:direct,bc:desktop'),
+      argv: withLabels('tier:huge,lane:frontier,path:direct,mode:headless,bc:desktop'),
       expected: /valor de "tier:" no permitido: "huge"/,
     },
     {
       name: 'tier:complex on lane:local',
-      argv: withLabels('tier:complex,lane:local,path:direct,bc:desktop'),
+      argv: withLabels('tier:complex,lane:local,path:direct,mode:headless,bc:desktop'),
       expected: /tier:complex exige lane:frontier/,
     },
     // T-6 measured this hole open: only tier:complex was refused on lane:local, so a tier:medium
@@ -244,9 +244,24 @@ describe('validateWorkerEditArgs — subtask refusals', () => {
     // after a slot was already taken (`dispatch-failed`).
     {
       name: 'tier:medium on lane:local',
-      argv: withLabels('tier:medium,lane:local,path:direct,bc:desktop'),
+      argv: withLabels('tier:medium,lane:local,path:direct,mode:headless,bc:desktop'),
       expected: /lane:local exige tier:minor, no "tier:medium"/,
     },
+    {
+      name: 'no mode: label at all',
+      argv: withLabels('tier:medium,lane:frontier,path:direct,bc:desktop'),
+      expected: /--labels debe declarar exactamente un "mode:" \(encontrados: 0\)/,
+    },
+    {
+      name: 'two mode: labels',
+      argv: withLabels('tier:medium,lane:frontier,path:direct,mode:headless,mode:supervised,bc:desktop'),
+      expected: /--labels debe declarar exactamente un "mode:" \(encontrados: 2\)/,
+    },
+    {
+      name: 'an illegal mode value',
+      argv: withLabels('tier:medium,lane:frontier,path:direct,mode:sometimes,bc:desktop'),
+      expected: /valor de "mode:" no permitido: "sometimes"/,
+    },
     {
       name: 'a description with no "Test command:" line',
       argv: withDesc('Split into IPC bridge work, no test line here.'),
@@ -261,7 +276,7 @@ describe('validateWorkerEditArgs — subtask refusals', () => {
       // FRONTIER_DESC declares a "Test command:" line but no "Files to touch:" one — exactly the
       // gap lane:local refuses to leave unfilled.
       name: 'lane:local with no "Files to touch:" line',
-      argv: withLabels('tier:minor,lane:local,path:direct,bc:desktop'),
+      argv: withLabels('tier:minor,lane:local,path:direct,mode:headless,bc:desktop'),
       expected: /lane:local exige la línea "Files to touch:"/,
     },
     { name: '--parent smuggled', argv: [...validSubtaskArgv(), '--parent', 'T-1'], expected: /no se acepta "--parent"/ },