dorfl 0.0.0 → 0.1.0

package/dist/status.d.ts

@@ -0,0 +1,199 @@
+import { type Harness } from './harness.js';
+import './pi-harness.js';
+import { type JobState } from './workspace.js';
+import { type ArbiterStatusReport } from './arbiter.js';
+import { type LockEntry } from './item-lock.js';
+import type { CwdSection } from './cwd-section.js';
+import { type DuplicateSlug } from './ledger-lint.js';
+/**
+ * `dorfl status` — the **operational dashboard of jobs** (ADR §4/§5/§12
+ * in `docs/adr/execution-substrate-decisions.md`). Split out of
+ * `agent-workspaces` so the substrate stays thin; this module owns the view.
+ *
+ * It lists the jobs under `<workspacesDir>/work/*` from their
+ * `.dorfl-job.json` records + worktree state, grouped by state:
+ *
+ *   - **active** — `running` AND the harness reports the job still alive.
+ *   - **failed / retained** — everything that wants a human's eye: a job the
+ *     `needs-attention` mechanism flagged (with its reason, ADR §12), a `done`
+ *     job whose worktree was never reaped (awaiting cleanup), or a `running`
+ *     job whose harness reports it DEAD (crashed — the runner died mid-flight).
+ *
+ * **Liveness comes from the harness seam (PID / session), NOT filesystem mtime**
+ * (ADR §5): a live agent can think for minutes without writing files, so mtime
+ * would mistake a thinking agent for a dead one. The harness answers liveness
+ * from the real signal.
+ *
+ * **Fetch-first (ADR §5/§6):** the per-mirror lock-ref + one-slug-one-folder
+ * lint surfaces are read AFTER refreshing each registered hub mirror's `main` —
+ * the old "scan is always offline" framing is RETIRED (it was the roots-local
+ * model). A failed mirror fetch is NOT fatal: it WARNS and falls back to that
+ * mirror's last-known `main`. The ledger read STRATEGY is unchanged
+ * (`claim-ledger-vs-protected-main.md`); `status` only ensures the ref is fresh.
+ *
+ * It is strictly **read-only**: it inspects records/worktrees; it never claims,
+ * runs, moves, or deletes (deletion is `gc`). It reuses the `gc` `discoverJobs`
+ * primitive to enumerate jobs (it does NOT re-implement the work-area layout).
+ *
+ * Distinct from `scan`: `scan` answers "what work is in the *backlog* and who
+ * can take it"; `status` answers "what is *running / stuck / awaiting cleanup*
+ * right now". The retained-worktree + stuck-lock items are the "look here" set.
+ */
+/** One job as the operational dashboard sees it (a record + its liveness). */
+export interface JobStatus {
+    /** The work slug being processed. */
+    slug: string;
+    /** The encoded repo key the job's hub mirror was cut from. */
+    repo: string;
+    /** The work branch checked out in the worktree (`work/<slug>`). */
+    branch: string;
+    /** ISO timestamp the job worktree was created. */
+    startedAt: string;
+    /** The persisted lifecycle state. */
+    state: JobState;
+    /** Liveness FROM THE HARNESS SEAM (PID/session), never mtime (ADR §5). */
+    alive: boolean;
+    /**
+     * Why the job is stuck (ADR §12), when known — surfaced for the
+     * failed/retained group. Present for `needs-attention` jobs that recorded a
+     * reason; absent otherwise.
+     */
+    reason?: string;
+    /**
+     * The review-request URL (e.g. a GitHub PR) opened for this job, when a
+     * `propose`-mode provider opened one (ADR §6). Surfaced so the human can jump
+     * straight to the PR. Absent otherwise.
+     */
+    prUrl?: string;
+    /** Absolute path to the job worktree (for the human to look). */
+    dir: string;
+}
+/**
+ * One repo's PER-ITEM LOCK refs, surfaced for the dashboard (prd
+ * `ledger-status-per-item-lock-refs` US #8; task
+ * `needs-attention-as-stuck-lock-state`). The in-flight view read from the lock
+ * refs — held (`active` = in-progress) and stuck (`needs-attention`) entries +
+ * their reasons — is the SOLE stuck-state surface (the
+ * `work/needs-attention/` folder is retired, task
+ * `cutover-needs-attention-becomes-lock-stuck-recovery-surface`).
+ */
+export interface RepoLockEntries {
+    /** The repo path whose lock refs were read (a hub-mirror path). */
+    repoPath: string;
+    /** The held lock entries (action × state + reason), sorted by entry. */
+    entries: LockEntry[];
+}
+/** One repo's one-slug-one-folder LINT result, surfaced for the dashboard. */
+export interface RepoLedgerDuplicates {
+    /** The repo path whose `work/` ledger was linted (a hub-mirror path). */
+    repoPath: string;
+    /** The slugs present in more than one status folder (non-empty here). */
+    duplicates: DuplicateSlug[];
+}
+/** The operational groups `status` reports. */
+export interface StatusReport {
+    /** Running jobs the harness reports still alive. */
+    active: JobStatus[];
+    /** Stuck (needs-attention), crashed (running-but-dead), or un-reaped (done) jobs. */
+    attention: JobStatus[];
+    /**
+     * The PER-ITEM LOCK in-flight view (prd `ledger-status-per-item-lock-refs` US
+     * #8; task `needs-attention-as-stuck-lock-state`): per registered hub mirror,
+     * the held lock entries read from the mirror's `refs/dorfl/lock/*` refs —
+     * `active` holds (in-progress) and `stuck` holds (needs-attention) + reasons.
+     * This is the SOLE stuck-state surface (the `work/needs-attention/` folder is
+     * retired, task
+     * `cutover-needs-attention-becomes-lock-stuck-recovery-surface`). Only repos
+     * WITH at least one held lock appear. Empty when no `mirrorPaths` were given or
+     * no locks are held. Optional so older literals stay valid; `status()` always
+     * populates it (possibly empty).
+     */
+    lockHeld?: RepoLockEntries[];
+    /**
+     * The one-slug-one-folder LINT (prd `ledger-integrity` story 3): per registered
+     * hub mirror, any slug present in MORE THAN ONE `work/` status folder (a corrupt
+     * ledger). Read from the mirror's bare `main` ref (the SAME `ls-tree` source the
+     * needs-attention surface uses). Only repos WITH a duplicate appear. `status`
+     * WARNS loudly about each (never a silent pass); a human resolves it. Empty when
+     * no `mirrorPaths` were given or every ledger is clean.
+     */
+    ledgerDuplicates?: RepoLedgerDuplicates[];
+    /**
+     * The current repo's arbiter state (folded in from the old `arbiter status`,
+     * ADR §1/§7): which remote, URL/path, exists/bare, main reachable, and the
+     * unsafe non-bare-with-main flag. Present only when the CLI resolved one (it is
+     * a current-checkout concern); absent for the pure job-area dashboard.
+     */
+    arbiter?: ArbiterStatusReport;
+    /**
+     * The CWD-LOCAL section (the `scan-status-read-cwd-repo` task): when `status`
+     * runs INSIDE a participating repo, this is that CURRENT repo read from its
+     * LOCAL WORKING TREE (fetch-its-arbiter-first), reported as a DISTINCT,
+     * separately-counted block alongside (never merged into) the registry view.
+     * Absent when the cwd does not participate or the caller did not resolve it.
+     */
+    cwd?: CwdSection;
+}
+export interface StatusOptions {
+    /** The execution working area to inspect (config `workspacesDir`). */
+    workspacesDir: string;
+    /**
+     * The harness used to answer liveness (PID/session — never mtime). When given,
+     * it answers liveness for EVERY job (tests inject a stub here). When omitted,
+     * each job's liveness is answered by the adapter that OWNS its record
+     * (`resolveHarness` keyed off the record's `adapter`) — so a `pi` job reports
+     * via the pi adapter (PID + session pointer) and a `null` job via the null
+     * adapter, never mtime.
+     */
+    harness?: Harness;
+    /**
+     * Hub-mirror PATHS whose lock refs + one-slug-one-folder lint to surface, read
+     * from each mirror's BARE `main` ref (mirrors have no working tree). The CLI
+     * wires these from the registry's {@link listMirrors}. `status` FETCHES each
+     * mirror's `main` first (ADR §5/§6 — the registry's remote is the source of
+     * truth); a failed fetch WARNS and falls back to last-known (never errors).
+     * Omitted ⇒ only the job worktrees are reported.
+     */
+    mirrorPaths?: string[];
+    /**
+     * Sink for the fetch-first fall-back warning (ADR §5/§6): when a mirror's `main`
+     * cannot be fetched, `status` warns through this and reads that mirror's
+     * last-known state. The CLI wires it to the standard `>>` stderr note.
+     */
+    warn?: (message: string) => void;
+    /**
+     * The current repo's arbiter state to fold into the dashboard (the old `arbiter
+     * status`, ADR §1). The CLI resolves it via `arbiterStatus` for the current
+     * checkout; omitted ⇒ no arbiter section.
+     */
+    arbiter?: ArbiterStatusReport;
+    /**
+     * The pre-resolved CWD-LOCAL section (the `scan-status-read-cwd-repo` task).
+     * The CLI resolves it via `resolveCwdSection` (cwd participation + fetch-first
+     * divergence + registry de-dup) and hands it here; `status` carries it onto the
+     * report and `formatStatus` renders it as a distinct local block. Omitted ⇒ no
+     * local section.
+     */
+    cwd?: CwdSection;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Build the operational status of every job under `<workspacesDir>/work/*`
+ * (ADR §4/§5/§12). READ-ONLY: enumerates job records via the `gc` `discoverJobs`
+ * primitive, asks the harness for liveness (NOT mtime), and groups each job as
+ * **active** (running + alive) or **failed/retained** (needs-attention, a
+ * crashed running-but-dead job, or a done-but-un-reaped one). Mutates nothing —
+ * no claim/run/move/delete.
+ */
+export declare function status(options: StatusOptions): Promise<StatusReport>;
+/**
+ * Render the operational status for the terminal: an **Active jobs** section and
+ * a **Failed / retained jobs** section, each line carrying slug, repo, branch,
+ * and started-at — plus, for stuck jobs, the recorded reason, and for a
+ * running-but-dead job a `(crashed — no longer alive)` marker.
+ *
+ * Deliberately framed in terms of **jobs** (running / stuck / awaiting cleanup),
+ * NOT the backlog *queue* — that is what keeps it visibly distinct from `scan`.
+ */
+export declare function formatStatus(report: StatusReport): string;
+//# sourceMappingURL=status.d.ts.map

package/dist/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,KAAK,OAAO,EAAC,MAAM,cAAc,CAAC;AAG1D,OAAO,iBAAiB,CAAC;AACzB,OAAO,EAAC,KAAK,QAAQ,EAAC,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAsB,KAAK,mBAAmB,EAAC,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAsB,KAAK,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAEnE,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAGN,KAAK,aAAa,EAClB,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,8EAA8E;AAC9E,MAAM,WAAW,SAAS;IACzB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,KAAK,EAAE,QAAQ,CAAC;IAChB,0EAA0E;IAC1E,KAAK,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC/B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,OAAO,EAAE,SAAS,EAAE,CAAC;CACrB;AAED,8EAA8E;AAC9E,MAAM,WAAW,oBAAoB;IACpC,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,UAAU,EAAE,aAAa,EAAE,CAAC;CAC5B;AAED,+CAA+C;AAC/C,MAAM,WAAW,YAAY;IAC5B,oDAAoD;IACpD,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,qFAAqF;IACrF,SAAS,EAAE,SAAS,EAAE,CAAC;IACvB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,oBAAoB,EAAE,CAAC;IAC1C;;;;;OAKG;IACH,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,UAAU,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC7B,sEAAsE;IACtE,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAkE1E;AAiCD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAgGzD"}

package/dist/status.js

@@ -0,0 +1,228 @@
+import { discoverJobs } from './gc.js';
+import { resolveHarness } from './harness.js';
+// Import for the registration side-effect: ensures the `pi` adapter is in the
+// harness registry so `resolveHarness` dispatches pi jobs' liveness to it.
+import './pi-harness.js';
+import { fetchMirrorMainOrWarn } from './repo-mirror.js';
+import { formatArbiterStatus } from './arbiter.js';
+import { listItemLockEntries } from './item-lock.js';
+import { formatCwdSection, formatLockEntryLines } from './format.js';
+import { lintRefLedger, formatDuplicateWarnings, } from './ledger-lint.js';
+/**
+ * Build the operational status of every job under `<workspacesDir>/work/*`
+ * (ADR §4/§5/§12). READ-ONLY: enumerates job records via the `gc` `discoverJobs`
+ * primitive, asks the harness for liveness (NOT mtime), and groups each job as
+ * **active** (running + alive) or **failed/retained** (needs-attention, a
+ * crashed running-but-dead job, or a done-but-un-reaped one). Mutates nothing —
+ * no claim/run/move/delete.
+ */
+export async function status(options) {
+    const active = [];
+    const attention = [];
+    for (const job of discoverJobs(options.workspacesDir)) {
+        const view = toJobStatus(job, options.harness);
+        // Active iff the runner believes the job is in flight (`running`) AND the
+        // harness confirms it is still alive. Everything else is "look here":
+        //   - needs-attention: the runner flagged it (gate red, conflict, …)
+        //   - done: landed but the worktree wasn't reaped (awaiting cleanup)
+        //   - running but NOT alive: the process died mid-flight (crashed)
+        if (view.state === 'running' && view.alive) {
+            active.push(view);
+        }
+        else {
+            attention.push(view);
+        }
+    }
+    active.sort(bySlug);
+    attention.sort(bySlug);
+    // The STUCK-STATE surface is now the PER-ITEM LOCK `state: stuck` (task
+    // `cutover-needs-attention-becomes-lock-stuck-recovery-surface`, decision i+:
+    // the `needs-attention/` folder is retired — NO code reads
+    // `work/needs-attention/`). `status` reads the lock refs per mirror to surface
+    // held (`active` = in-progress) AND stuck (`needs-attention`) entries + their
+    // reasons/questions.
+    const lockHeld = [];
+    const ledgerDuplicates = [];
+    for (const mirrorPath of options.mirrorPaths ?? []) {
+        // Fetch-first (ADR §5/§6): refresh this mirror's `main` so the duplicate lint
+        // reflects the remote truth. Never fatal — a failed fetch WARNS and falls back
+        // to the mirror's last-known `main`.
+        fetchMirrorMainOrWarn({ mirrorPath, warn: options.warn, env: options.env });
+        // The PER-ITEM LOCK in-flight view (prd US #8): read the mirror's lock refs to
+        // surface held (`active` = in-progress) and stuck (`needs-attention`) entries +
+        // reasons/questions. A bare hub mirror's arbiter is its `origin` (the SAME
+        // handle the `scan` held-slug subtraction reads). Best-effort: a fetch/read
+        // fault yields an EMPTY list (see {@link listItemLockEntries}), so this
+        // read-only view degrades to "no in-flight locks" rather than erroring.
+        const entries = await listItemLockEntries(mirrorPath, 'origin', options.env);
+        if (entries.length > 0) {
+            lockHeld.push({ repoPath: mirrorPath, entries });
+        }
+        // The one-slug-one-folder LINT (prd story 3): derive any slug residing in >1
+        // status folder from the SAME freshly-fetched `main` ref, surfaced LOUDLY.
+        const dups = lintRefLedger('main', mirrorPath, options.env);
+        if (dups.length > 0) {
+            ledgerDuplicates.push({ repoPath: mirrorPath, duplicates: dups });
+        }
+    }
+    lockHeld.sort((a, b) => a.repoPath.localeCompare(b.repoPath));
+    ledgerDuplicates.sort((a, b) => a.repoPath.localeCompare(b.repoPath));
+    return {
+        active,
+        attention,
+        lockHeld,
+        ledgerDuplicates,
+        ...(options.arbiter ? { arbiter: options.arbiter } : {}),
+        ...(options.cwd ? { cwd: options.cwd } : {}),
+    };
+}
+function bySlug(a, b) {
+    return a.slug.localeCompare(b.slug);
+}
+/**
+ * Project a discovered job + its harness liveness into a `JobStatus`. When no
+ * harness is forced (the normal case), each record's liveness is answered by the
+ * adapter that OWNS it (`resolveHarness`) — a pi job via the pi adapter (PID +
+ * session), never mtime.
+ */
+function toJobStatus(job, forced) {
+    const record = job.record;
+    const harness = forced ?? (record ? resolveHarness(record.harness) : undefined);
+    const alive = record !== undefined && harness !== undefined
+        ? harness.isAlive(record.harness)
+        : false;
+    return {
+        slug: job.slug,
+        repo: record?.repoKey ?? '(unknown)',
+        branch: job.branch,
+        startedAt: record?.startedAt ?? '(unknown)',
+        state: record?.state ?? 'running',
+        alive,
+        reason: record?.reason,
+        prUrl: record?.prUrl,
+        dir: job.dir,
+    };
+}
+/**
+ * Render the operational status for the terminal: an **Active jobs** section and
+ * a **Failed / retained jobs** section, each line carrying slug, repo, branch,
+ * and started-at — plus, for stuck jobs, the recorded reason, and for a
+ * running-but-dead job a `(crashed — no longer alive)` marker.
+ *
+ * Deliberately framed in terms of **jobs** (running / stuck / awaiting cleanup),
+ * NOT the backlog *queue* — that is what keeps it visibly distinct from `scan`.
+ */
+export function formatStatus(report) {
+    const lines = [];
+    // The cwd-local section (the `scan-status-read-cwd-repo` task): a DISTINCT,
+    // separately-counted block for the CURRENT repo's working tree, ABOVE the
+    // job/registry dashboard (never merged into the job counts).
+    const cwdLines = report.cwd !== undefined ? formatCwdSection(report.cwd) : [];
+    const lockHeld = report.lockHeld ?? [];
+    const lockCount = lockHeld.reduce((sum, r) => sum + r.entries.length, 0);
+    const ledgerDuplicates = report.ledgerDuplicates ?? [];
+    const dupCount = ledgerDuplicates.reduce((sum, r) => sum + r.duplicates.length, 0);
+    if (report.active.length === 0 &&
+        report.attention.length === 0 &&
+        lockCount === 0 &&
+        dupCount === 0 &&
+        report.arbiter === undefined &&
+        cwdLines.length === 0) {
+        return 'No jobs running or retained (the work area is empty).';
+    }
+    if (cwdLines.length > 0) {
+        lines.push(...cwdLines);
+        lines.push('');
+    }
+    lines.push('Active jobs (running):');
+    if (report.active.length === 0) {
+        lines.push('  (none)');
+    }
+    else {
+        for (const job of report.active) {
+            lines.push(formatJobLine(job));
+        }
+    }
+    lines.push('');
+    lines.push('Failed / retained jobs (look here):');
+    if (report.attention.length === 0) {
+        lines.push('  (none)');
+    }
+    else {
+        for (const job of report.attention) {
+            lines.push(formatJobLine(job));
+        }
+    }
+    // The PER-ITEM LOCK in-flight view (prd US #8; task
+    // `cutover-needs-attention-becomes-lock-stuck-recovery-surface`): the held lock
+    // refs read from each mirror — `active` holds (in-progress) and `stuck` holds
+    // (needs-attention) + their reasons/questions. This is the SOLE stuck-state
+    // surface now (the `needs-attention/` folder is retired).
+    if (lockCount > 0) {
+        lines.push('');
+        lines.push('In-flight locks (refs/dorfl/lock/* — held + stuck):');
+        for (const repo of lockHeld) {
+            lines.push(`  ${repo.repoPath}`);
+            for (const entry of repo.entries) {
+                // SHARED renderer (NOT a forked one) so the cwd section
+                // (`formatCwdSection`) presents a held/stuck item identically.
+                lines.push(...formatLockEntryLines(entry, '    '));
+            }
+        }
+    }
+    // The one-slug-one-folder LINT (prd `ledger-integrity` story 3): WARN LOUDLY
+    // about every slug residing in >1 status folder of a registered mirror's ledger
+    // (a corrupt ledger — never a silent pass). A human must resolve each.
+    if (dupCount > 0) {
+        lines.push('');
+        for (const repo of ledgerDuplicates) {
+            lines.push(`  ${repo.repoPath}`);
+            for (const w of formatDuplicateWarnings(repo.duplicates)) {
+                lines.push(`  ${w}`);
+            }
+        }
+    }
+    lines.push('');
+    lines.push(`Summary: ${report.active.length} active, ${report.attention.length} failed/retained job(s)` +
+        (lockCount > 0 ? `, ${lockCount} in-flight lock(s)` : '') +
+        (dupCount > 0 ? `, ${dupCount} one-slug-one-folder violation(s)` : '') +
+        '.');
+    // The folded-in arbiter state (ADR §1/§7, the old `arbiter status`).
+    if (report.arbiter !== undefined) {
+        lines.push('');
+        lines.push(formatArbiterStatus(report.arbiter));
+    }
+    return lines.join('\n');
+}
+/** One `slug  repo  branch  started-at  [marker]` job line, with reason below. */
+function formatJobLine(job) {
+    const marker = jobMarker(job);
+    const head = `  ${job.slug}   ${job.repo}   ${job.branch}   started ${job.startedAt}${marker}`;
+    const extra = [];
+    if (job.reason !== undefined && job.reason !== '') {
+        extra.push(`      reason: ${job.reason}`);
+    }
+    if (job.prUrl !== undefined && job.prUrl !== '') {
+        extra.push(`      PR: ${job.prUrl}`);
+    }
+    return extra.length > 0 ? [head, ...extra].join('\n') : head;
+}
+/**
+ * A trailing marker that explains WHY a non-active job is in the look-here group:
+ * a `running` job the harness reports dead is a **crashed** runner; a `done` job
+ * is **awaiting cleanup** (`gc` will reap it); a `needs-attention` job is
+ * **stuck** (its reason is rendered separately).
+ */
+function jobMarker(job) {
+    if (job.state === 'running' && !job.alive) {
+        return '   (crashed — no longer alive)';
+    }
+    if (job.state === 'done') {
+        return '   (done — awaiting cleanup)';
+    }
+    if (job.state === 'needs-attention') {
+        return '   (needs attention)';
+    }
+    return '';
+}
+//# sourceMappingURL=status.js.map

package/dist/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"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"}

package/dist/surface-gate.d.ts

@@ -0,0 +1,162 @@
+import { type Harness } from './harness.js';
+import type { NewQuestion } from './sidecar.js';
+/**
+ * The **SURFACE gate** (prd `advance-loop`, task `advance-rung-surface`,
+ * US #32/33) — the surface-question rung's fresh-context spawn, the DIRECT mirror
+ * of the PR/code review gate ({@link import('./review-gate.js')}). On
+ * `classify=surface`, the advance engine spawns a FRESH-CONTEXT agent with the
+ * `surface-questions` SKILL loaded (`skills/surface-questions/SKILL.md`); the
+ * skill GATHERS the item's open-judgement residue and EMITS questions and writes
+ * NOTHING (doc-shaped, like `review`). The ENGINE then ITSELF persists them to
+ * the sidecar CAS-atomically + sets `needsAnswers:true` (task
+ * `advance-rung-surface`'s persist half) — **the skill JUDGES, the engine
+ * PERSISTS.**
+ *
+ * This module is the SEAM (the {@link SurfaceGate} function type) + its
+ * production harness-backed implementation ({@link harnessSurfaceGate}), exactly
+ * as `review-gate.ts` is the seam + `harnessReviewGate`. The seam is injectable:
+ * tests stub a canned emitted-questions list (no real model); production launches
+ * the `surface-questions` agent through the EXISTING harness seam
+ * ({@link Harness}/`LaunchInput`), routing an optional `surfaceModel` override
+ * through `LaunchInput.model` — NOT a new model/launch mechanism (the §13
+ * model-routing intent). It mirrors `harnessReviewGate` byte-for-byte in shape;
+ * only the PROMPT ({@link buildSurfacePrompt}) and the parsed payload
+ * ({@link parseSurfaceEmit}, a `{questions}` list rather than a `{verdict}`)
+ * differ.
+ *
+ * ALWAYS-allowed: there is NO gate check before surfacing — surfacing a question
+ * is never gated, even with every autonomy flag off (the "question loop with zero
+ * autonomy" case, US #23). The expensive (agent/model) work is POST-lock,
+ * winner-only — but that sequencing is the ENGINE's job (`advance.ts`); this
+ * module is only the spawn→emit→parse.
+ */
+/**
+ * One question the `surface-questions` skill EMITS — the THREE authoring fields of
+ * the sidecar entry shape (`skills/surface-questions/SKILL.md` → "The emitted
+ * question shape"). It maps 1:1 onto {@link NewQuestion} (what the engine appends
+ * to the sidecar), so the engine persists with ZERO translation. The skill does
+ * NOT assign `id`/`answered`/`answer`/`allAnswered` — those are the sidecar's
+ * machine-owned fields the engine owns. A surfaced question is a PLAIN question:
+ * there is NO `disposition` token any more (task
+ * `agentic-apply-retire-disposition-vocabulary`) — what to DO with the answered
+ * signal is decided by the AGENTIC apply decision, not stamped on the question.
+ */
+export interface SurfaceQuestion {
+    /** The question, verbatim. */
+    question: string;
+    /** Inline context so the human need not open the item. */
+    context?: string;
+    /** Optional suggested default (the humility aid; NEVER a decision). */
+    default?: string;
+}
+/**
+ * What the `surface-questions` SKILL emits (and this gate parses): the item's
+ * identity (orientation only) + an ORDERED list of questions. An EMPTY list is a
+ * valid, honest result ("no open judgement") — the engine writes no sidecar.
+ */
+export interface SurfaceEmit {
+    /** The namespaced identity the skill surfaced for (orientation; advisory). */
+    item?: string;
+    /** The ordered emitted questions (possibly empty). */
+    questions: SurfaceQuestion[];
+}
+/** What the surface gate needs to launch a fresh-context surface of one item. */
+export interface SurfaceGateInput {
+    /** The namespaced identity the surface is for (`task:foo` / `prd:bar` / `observation:baz`). */
+    item: string;
+    /** The working clone/checkout the gate runs in. */
+    cwd: string;
+    /**
+     * The model the SURFACE agent runs on. `undefined` ⇒ no forced model (the
+     * harness's own default). Flows to the launch through `LaunchInput.model`.
+     */
+    surfaceModel?: string;
+    /** Environment for the surface-agent launch. */
+    env?: NodeJS.ProcessEnv;
+    /** `--watch`: tail the surface agent's pi session live (pure observer). */
+    watch?: boolean;
+    /** Where the tailed surface lines are written (defaults to stderr). */
+    watchSink?: (line: string) => void;
+    /** Emit ANSI colour in the tailed surface lines (the caller's TTY decision). */
+    color?: boolean;
+    /** The HOST-ONLY sessions root the surface session FILE is generated under. */
+    sessionsDir?: string;
+}
+/**
+ * The surface-gate SEAM: run a fresh-context surface of the item and return the
+ * parsed emitted questions. Injected by tests (a canned list, no real model);
+ * production uses {@link harnessSurfaceGate}. Mirrors `review-gate.ts`'s
+ * `ReviewGate` seam shape so the engine wiring is testable as pure logic.
+ */
+export type SurfaceGate = (input: SurfaceGateInput) => Promise<SurfaceEmit>;
+/** Raised when the surface agent ran but produced no parseable emit. */
+export declare class SurfaceParseError extends Error {
+}
+/**
+ * Parse the `surface-questions` SKILL's emitted questions out of the surface
+ * agent's textual output. The skill emits a `{item, questions:[…]}` JSON object
+ * (the agent may wrap it in prose / a fenced block), so we extract the first JSON
+ * object carrying a `questions` field and validate its shape. An EMPTY
+ * `questions` list is VALID (the honest "no open judgement" result). Throws
+ * {@link SurfaceParseError} when no valid emit is present (the caller treats an
+ * unparseable emit as an error — never a silent "surfaced nothing").
+ *
+ * The emit MAY also carry a free-prose `note` field (the surface counterpart of
+ * the verdict's `review`): a HOME inside the object for the agent's reasoning /
+ * findings so it never needs to write prose AROUND the JSON (the cause of the
+ * "no parseable {questions}" trailing-chatter failure — observation
+ * `surface-rung-agent-emits-no-parseable-questions`). The engine does not
+ * persist `note`, so it is simply IGNORED here (like every unrecognised field);
+ * the prompt's job is to give the prose a place to go, not the parser's to keep
+ * it.
+ */
+export declare function parseSurfaceEmit(output: string): SurfaceEmit;
+/**
+ * Convert the emitted questions to the {@link NewQuestion} shape the engine
+ * appends to the sidecar — a 1:1 field map (the emit shape IS the sidecar
+ * authoring shape, by design), so the engine persists with ZERO translation.
+ */
+export declare function toNewQuestions(emit: SurfaceEmit): NewQuestion[];
+/**
+ * Render the surface-agent PROMPT: instruct a fresh-context agent to apply the
+ * **surface-questions discipline** (`work/protocol/SURFACE-PROTOCOL.md`) to ONE
+ * `work/` item and to EMIT a single `{item, questions}` JSON object (so
+ * {@link parseSurfaceEmit} can read it). The discipline body (the two laws —
+ * GATHER-only / PERSIST-NEVER — the humility rule, the composed sources, the
+ * emitted-question shape) lives in `SURFACE-PROTOCOL.md` — NOT inlined here
+ * (task `surface-protocol-doc-and-prompt`). The shape's source of truth is
+ * {@link parseSurfaceEmit}; the doc DESCRIBES it (D2).
+ *
+ * This builder owns ONLY the PER-BUILDER framing: who you are (a fresh-context
+ * question-surfacer, the engine's surface-question rung), what you are
+ * surfacing (ONE namespaced item), and the required JSON output shape. It
+ * MIRRORS {@link buildReviewPrompt}: a fresh-context agent that EDITS nothing
+ * and EMITS a single structured object the ENGINE routes/persists.
+ */
+export declare function buildSurfacePrompt(item: string): string;
+/** What a harness-backed surface gate needs to launch the surface agent. */
+export interface HarnessSurfaceGateOptions {
+    /** The harness seam used to launch the fresh-context surface agent. */
+    harness?: Harness;
+    /** The agent command the null/shell adapter shells out to (`{model}`-aware). */
+    agentCmd?: string;
+    /**
+     * Read the surface agent's textual output for parsing. Production reads
+     * `launched.output` (the ANSWER channel, distinct from `detail`); tests inject
+     * `readOutput` to stub a canned emit string.
+     */
+    readOutput?: (output: string | undefined) => string;
+}
+/**
+ * The PRODUCTION surface gate: launch the `surface-questions` SKILL as a
+ * fresh-context agent through the EXISTING harness seam, routing the
+ * `surfaceModel` override via `LaunchInput.model` (the §13 model-routing intent —
+ * NOT a new mechanism), then parse the emitted `{item, questions}`. It is the
+ * DIRECT mirror of `harnessReviewGate`: a SEPARATE harness launch (fresh context
+ * = not the engine's session) in the same checkout `cwd`, fed
+ * {@link buildSurfacePrompt}; the model flows through `LaunchInput.model`, which
+ * each adapter injects natively. The surface uses a DISTINCT session id
+ * (`<item>-surface`) so its session never collides with a build/review session.
+ */
+export declare function harnessSurfaceGate(options?: HarnessSurfaceGateOptions): SurfaceGate;
+//# sourceMappingURL=surface-gate.d.ts.map

package/dist/surface-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-gate.d.ts","sourceRoot":"","sources":["../src/surface-gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,OAAO,EAAC,MAAM,cAAc,CAAC;AAKvD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,cAAc,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe;IAC/B,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,SAAS,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAChC,+FAA+F;IAC/F,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uEAAuE;IACvE,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,gFAAgF;IAChF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,gBAAgB,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;AAE5E,wEAAwE;AACxE,qBAAa,iBAAkB,SAAQ,KAAK;CAAG;AAE/C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAgB5D;AAsCD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,EAAE,CAW/D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAuDvD;AAED,4EAA4E;AAC5E,MAAM,WAAW,yBAAyB;IACzC,uEAAuE;IACvE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,MAAM,CAAC;CACpD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CACjC,OAAO,GAAE,yBAA8B,GACrC,WAAW,CA0Cb"}