tickmarkr 2.5.5 → 2.5.7

package/dist/gates/test-manifest.d.ts

@@ -9,9 +9,17 @@ export declare function isVitestTestCommand(cmd: string, cwd: string): boolean;
 export declare function toManifestPath(file: string, cwd: string): string;
 export interface TestReportCompletion {
     at: number;
-    status: "passed" | "failed";
+    /** R41: `skipped` = the module ran its lifecycle but executed NO test body (every test skipped);
+     * it is present in the manifest accounting and never counted as executed success. */
+    status: "passed" | "failed" | "skipped";
     /** Failure fingerprints for this file; absent/empty on a passed file. */
     failures?: string[];
+    /** Per-module test-body counts the reporter observed (absent on reports from older reporters). */
+    tests?: {
+        passed: number;
+        failed: number;
+        skipped: number;
+    };
 }
 /** The runner's own machine report — requested/started/completed are the runner's claims about ITSELF. */
 export interface TestReport {
@@ -28,6 +36,9 @@ export interface TestReport {
     certificate?: {
         at: number;
         exitCode: number;
+        /** Unhandled and module collection errors observed by the reporter; absent on older reports. */
+        errors?: number;
+        diagnostics?: string[];
     };
 }
 /** Reads and structurally validates the report; a missing or malformed file is `undefined` — never a partial parse. */
@@ -89,6 +100,27 @@ export interface ManifestGateOutcome {
     exitCode: number;
     reportPath: string;
 }
+export interface DiscoveredManifest {
+    files: string[];
+    listing: string;
+    separator: string;
+    listingExit: number | undefined;
+    listingStdout: string;
+}
+/** OBS-1044: THE discovery seam — the files the runner would collect under this exact invocation,
+ * from its own listing and never from a stdout summary. The gate and the baseline capture share it,
+ * so the count a capture records is the count the gate later asks the report to certify. Throws
+ * when the runner cannot list: a count that is not the runner's own is not a count. */
+export declare function discoverTestManifest(cmd: string, cwd: string, opts: {
+    dir: string;
+    nonce: string;
+    env: NodeJS.ProcessEnv;
+    overallCeilingMs?: number;
+}): Promise<DiscoveredManifest>;
+/** The baseline capture's reading of the same seam: the manifest's file count, or null when the
+ * runner cannot list (a null compares nothing — it never manufactures a deficit). The suite is not
+ * run here; the capture already ran it once. */
+export declare function manifestFileCount(cmd: string, cwd: string): Promise<number | null>;
 /** One configured runner execution, and its own collection under the same arguments and environment.
  * The installed runner is trusted (R28 add.1 option B); the nonce catches stale artifacts, not forgery. */
 export declare function evaluateManifestedTest(cmd: string, cwd: string, opts: {

package/dist/gates/test-manifest.js

@@ -1,10 +1,10 @@
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { existsSync, mkdtempSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { isAbsolute, join, relative, sep } from "node:path";
 import { TEST_REPORTER_SOURCE } from "./test-reporter.js";
 import { shq } from "../adapters/types.js";
-import { FORK_CAP_ENV, ROUTING_ENV_SEAMS, SUITE_PARENT_ENV, shell, resolvedCapacity } from "../run/git.js";
+import { FORK_CAP_ENV, ROUTING_ENV_SEAMS, SUITE_PARENT_ENV, shell, resolvedCapacity, verificationProtocol } from "../run/git.js";
 /**
  * VL-1 (OBS-985 lineage): a test gate's completion must be the runner's OWN report, never a stdout
  * count. `fileCountDeficit` (baseline.ts) reads a summary LINE — a selected screen's smaller count
@@ -30,7 +30,12 @@ function scriptInvocation(cmd, cwd) {
         manager++;
     if (!["npm", "pnpm", "yarn"].includes(argv[manager]))
         return undefined;
-    const offset = manager + (["run", "run-script"].includes(argv[manager + 1]) ? 2 : 1);
+    let offset = manager + (["run", "run-script"].includes(argv[manager + 1]) ? 2 : 1);
+    // OBS-1044: `npm run -s test` — the very spelling detectGateCommands synthesizes — carries the
+    // manager's own flags before the script name; a seam blind to them routed every default-configured
+    // npm repository past the manifest. Skip flags, never a `--` (which ends the manager's arguments).
+    while (offset > manager + 1 && /^-(?!-$)/.test(argv[offset] ?? ""))
+        offset++;
     const name = ["t", "tst"].includes(argv[offset]) ? "test" : argv[offset];
     try {
         const body = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8")).scripts?.[name];
@@ -72,8 +77,13 @@ function runnerInvocation(cmd, cwd) {
     if (forwarded[0] === "run")
         forwarded.shift();
     const collection = forwarded.filter((a) => a !== "--run" && a !== "--watch" && a !== "--");
+    // R41: `--filesOnly` lists FILE SPECIFICATIONS — the unit the reporter certifies (module start/end) —
+    // instead of collected test cases, from which the ordinary listing omits every skipped test and so
+    // drops a module whose whole body is skipped (describe.skipIf): the runner then reported two files
+    // the manifest never expected (T4 236 vs 238, T8 288 vs 290 on run 91). Filters and the environment
+    // are forwarded exactly as before; only the unit enumerated changes.
     return {
-        listing: [...env, ...prefix.map(shq), shq(binary), "list", ...collection, "--json"].join(" "),
+        listing: [...env, ...prefix.map(shq), shq(binary), "list", ...collection, "--filesOnly", "--json"].join(" "),
         separator: script?.npm && !/(?:^|\s)--(?:\s|$)/.test(cmd) ? " --" : "",
     };
 }
@@ -107,8 +117,15 @@ function isTestReportShape(v) {
         if (typeof c !== "object" || c === null)
             return false;
         const cc = c;
-        if (typeof cc.at !== "number" || (cc.status !== "passed" && cc.status !== "failed"))
+        if (typeof cc.at !== "number" || (cc.status !== "passed" && cc.status !== "failed" && cc.status !== "skipped"))
             return false;
+        if (cc.tests !== undefined) {
+            if (typeof cc.tests !== "object" || cc.tests === null)
+                return false;
+            const t = cc.tests;
+            if (!["passed", "failed", "skipped"].every((k) => typeof t[k] === "number"))
+                return false;
+        }
     }
     if (r.duplicateCompletions !== undefined) {
         if (!Array.isArray(r.duplicateCompletions) || !r.duplicateCompletions.every((f) => typeof f === "string"))
@@ -208,12 +225,13 @@ export function verifyManifestReport(opts) {
             meta: { classification: "infra", infra: true, missingCertificate: true, ...(pending !== undefined ? { file: pending } : {}) },
         };
     }
-    const failures = Object.values(report.completed).filter((c) => c.status === "failed")
-        .flatMap((c) => c.failures?.length ? c.failures : ["<unnamed failure>"]);
+    const failedCompletions = Object.entries(report.completed).filter(([, c]) => c.status === "failed");
+    const failingFiles = failedCompletions.map(([file]) => file).sort();
+    const failures = failedCompletions.flatMap(([, c]) => c.failures?.length ? c.failures : ["<unnamed failure>"]);
     if (failures.length)
         return { kind: "work", pass: false,
             details: `test report names failing fingerprint(s):\n${failures.join("\n")}`,
-            meta: { classification: "regression", failingTests: failures, processExit: exitCode } };
+            meta: { classification: "regression", failingTests: failures, failingFiles, processExit: exitCode } };
     if (exitCode === undefined) {
         return {
             kind: "fail-closed",
@@ -264,11 +282,25 @@ export function verifyManifestReport(opts) {
             meta: { classification: "infra", infra: true, file: missing, missingFromReport: true },
         };
     }
+    // R41: a skipped whole module is PRESENT (the lifecycle certified it) but is not executed test-body
+    // success. The verdict says how many modules executed and names every one that did not; a report
+    // in which nothing executed proves nothing about the tree and is never a passing verdict.
+    const skippedModules = manifest.filter((f) => report.completed[f]?.status === "skipped").sort();
+    const executedModules = manifest.length - skippedModules.length;
+    if (executedModules === 0) {
+        return {
+            kind: "fail-closed",
+            pass: false,
+            details: `every manifest module was skipped whole (${skippedModules.join(", ")}) — no test body executed, so this report certifies nothing about the tree; failing closed`,
+            meta: { classification: "infra", infra: true, noExecutedModules: true, manifestFiles: manifest.length, executedModules, skippedModules },
+        };
+    }
     return {
         kind: "pass",
         pass: true,
-        details: `invocation-bound test report succeeded — ${manifest.length} manifest file(s) present exactly once`,
-        meta: { manifestFiles: manifest.length },
+        details: `invocation-bound test report succeeded — ${manifest.length} manifest file(s) present exactly once; ${executedModules} executed`
+            + (skippedModules.length ? `, ${skippedModules.length} skipped whole (${skippedModules.join(", ")})` : ""),
+        meta: { manifestFiles: manifest.length, executedModules, skippedModules },
     };
 }
 /** How much longer than its baseline measurement one file may legitimately run before it is a hang. */
@@ -328,42 +360,83 @@ export function runManifestedTest(cmd, cwd, opts) {
         report: readTestReport(opts.reportPath), killedFile, hangBudgetMs, pid,
     })).finally(() => { clearInterval(poll); });
 }
-/** One configured runner execution, and its own collection under the same arguments and environment.
- * The installed runner is trusted (R28 add.1 option B); the nonce catches stale artifacts, not forgery. */
-export async function evaluateManifestedTest(cmd, cwd, opts) {
-    const dir = opts.artifactDir ?? mkdtempSync(join(tmpdir(), "tickmarkr-test-report-"));
-    const nonce = randomBytes(16).toString("hex");
-    const reportPath = join(dir, `test-manifest-report-${nonce}.json`);
-    const reporterPath = join(dir, `test-reporter-${nonce}.mjs`);
-    let spawnedCommand = cmd;
+/** The child environment every manifest invocation (listing and run) receives, and the lifecycle
+ * protocol it records. R41: the policy is whatever THIS process was launched with (npm reads
+ * `npm_config_ignore_scripts` from the environment over every npmrc); the verdict records it so a
+ * verdict measured with `pretest` hooks is never compared to one without. */
+function manifestEnvironment(cwd) {
     const env = { ...process.env, PATH: `${join(cwd, "node_modules/.bin")}:${process.env.PATH ?? ""}`,
         [FORK_CAP_ENV]: String(resolvedCapacity().forkCap), [SUITE_PARENT_ENV]: String(process.pid) };
+    const verification = verificationProtocol(env, cwd);
     for (const key of ROUTING_ENV_SEAMS)
         delete env[key];
     // A gate can itself be tested under Vitest. Do not give the child the outer worker identity.
     for (const key of Object.keys(env))
         if (["VITEST", "TEST", "VITEST_WORKER_ID", "VITEST_POOL_ID"].includes(key))
             delete env[key];
+    return { env, verification };
+}
+/** OBS-1044: THE discovery seam — the files the runner would collect under this exact invocation,
+ * from its own listing and never from a stdout summary. The gate and the baseline capture share it,
+ * so the count a capture records is the count the gate later asks the report to certify. Throws
+ * when the runner cannot list: a count that is not the runner's own is not a count. */
+export async function discoverTestManifest(cmd, cwd, opts) {
+    const invocation = runnerInvocation(cmd, cwd);
+    const listed = await runManifestedTest(invocation.listing, cwd, {
+        manifest: [], nonce: opts.nonce, reportPath: join(opts.dir, `listing-${opts.nonce}.json`), env: opts.env,
+        overallCeilingMs: opts.overallCeilingMs ?? DEFAULT_FILE_HANG_BUDGET_MS,
+    });
+    if (listed.exitCode !== 0)
+        throw new Error(`vitest cannot list files (exit ${listed.exitCode ?? "signal"}): ${listed.stderr || listed.stdout}`);
+    let files;
     try {
-        const invocation = runnerInvocation(cmd, cwd);
-        const listed = await runManifestedTest(invocation.listing, cwd, {
-            manifest: [], nonce, reportPath: join(dir, `listing-${nonce}.json`), env,
-            overallCeilingMs: opts.overallCeilingMs ?? DEFAULT_FILE_HANG_BUDGET_MS,
-        });
-        if (listed.exitCode !== 0)
-            throw new Error(`vitest cannot list files (exit ${listed.exitCode ?? "signal"}): ${listed.stderr || listed.stdout}`);
-        let files;
-        try {
-            const rows = JSON.parse(listed.stdout.slice(listed.stdout.indexOf("[")));
-            if (!Array.isArray(rows) || !rows.every((r) => typeof r?.file === "string"))
-                throw new Error("invalid listing");
-            files = [...new Set(rows.map((r) => toManifestPath(r.file, cwd)))].sort();
-        }
-        catch {
-            throw new Error(`vitest cannot list files: invalid JSON listing: ${listed.stdout}`);
-        }
-        if (!files.length)
-            throw new Error("vitest cannot list files: empty manifest");
+        const rows = JSON.parse(listed.stdout.slice(listed.stdout.indexOf("[")));
+        if (!Array.isArray(rows) || !rows.every((r) => typeof r?.file === "string"))
+            throw new Error("invalid listing");
+        files = [...new Set(rows.map((r) => toManifestPath(r.file, cwd)))].sort();
+    }
+    catch {
+        throw new Error(`vitest cannot list files: invalid JSON listing: ${listed.stdout}`);
+    }
+    if (!files.length)
+        throw new Error("vitest cannot list files: empty manifest");
+    return { files, listing: invocation.listing, separator: invocation.separator, listingExit: listed.exitCode, listingStdout: listed.stdout };
+}
+/** The baseline capture's reading of the same seam: the manifest's file count, or null when the
+ * runner cannot list (a null compares nothing — it never manufactures a deficit). The suite is not
+ * run here; the capture already ran it once. */
+export async function manifestFileCount(cmd, cwd) {
+    const dir = mkdtempSync(join(tmpdir(), "tickmarkr-test-manifest-"));
+    try {
+        const { files } = await discoverTestManifest(cmd, cwd, { dir, nonce: randomBytes(16).toString("hex"), env: manifestEnvironment(cwd).env });
+        return files.length;
+    }
+    catch {
+        return null;
+    }
+}
+/** One configured runner execution, and its own collection under the same arguments and environment.
+ * The installed runner is trusted (R28 add.1 option B); the nonce catches stale artifacts, not forgery. */
+export async function evaluateManifestedTest(cmd, cwd, opts) {
+    const dir = opts.artifactDir ?? mkdtempSync(join(tmpdir(), "tickmarkr-test-report-"));
+    const nonce = randomBytes(16).toString("hex");
+    const reportPath = join(dir, `test-manifest-report-${nonce}.json`);
+    const reporterPath = join(dir, `test-reporter-${nonce}.mjs`);
+    let spawnedCommand = cmd;
+    let manifestPath;
+    const { env, verification } = manifestEnvironment(cwd);
+    try {
+        const invocation = await discoverTestManifest(cmd, cwd, { dir, nonce, env, overallCeilingMs: opts.overallCeilingMs });
+        const files = invocation.files;
+        // R41: the EXPECTED manifest is evidence in its own right — persisted beside the report with the
+        // exact discovery invocation, so a later reader can tell what this invocation was asked to prove
+        // without reconstructing it from the runner's own claims.
+        manifestPath = join(dir, `test-manifest-expected-${nonce}.json`);
+        writeFileSync(manifestPath, JSON.stringify({
+            nonce, verification, listingCommand: invocation.listing, listingExit: invocation.listingExit,
+            listingStdoutSha256: createHash("sha256").update(invocation.listingStdout).digest("hex"),
+            discoveredAt: Date.now(), files,
+        }, null, 2) + "\n");
         writeFileSync(reporterPath, TEST_REPORTER_SOURCE);
         spawnedCommand = `${cmd}${invocation.separator} --reporter=${shq(reporterPath)} --outputFile=${shq(reportPath)}`;
         const invoked = await runManifestedTest(spawnedCommand, cwd, {
@@ -375,15 +448,34 @@ export async function evaluateManifestedTest(cmd, cwd, opts) {
         });
         const verdict = verifyManifestReport({ manifest: files, nonce, exitCode: invoked.exitCode,
             report: invoked.report, killedFile: invoked.killedFile, hangBudgetMs: invoked.hangBudgetMs });
+        // Preserve the validator's verdict and classification; runner evidence only explains it.
+        const stdoutPath = join(dir, `test-runner-stdout-${nonce}.log`);
+        const stderrPath = join(dir, `test-runner-stderr-${nonce}.log`);
+        const stdoutTail = Buffer.from(invoked.stdout).subarray(-16 * 1024);
+        const stderrTail = Buffer.from(invoked.stderr).subarray(-16 * 1024);
+        writeFileSync(stdoutPath, stdoutTail);
+        writeFileSync(stderrPath, stderrTail);
+        const report = invoked.report?.nonce === nonce ? invoked.report : undefined;
+        const neverStarted = report ? files.filter(file => !(file in report.started)).length : "unknown";
+        const errors = report?.certificate?.errors;
+        const reporterErrors = typeof errors === "number" && Number.isInteger(errors) && errors >= 0 ? errors : "unknown";
+        const reportedDiagnostics = report?.certificate?.diagnostics;
+        const runnerErrors = Array.isArray(reportedDiagnostics) ? reportedDiagnostics.filter(error => typeof error === "string") : [];
+        const diagnostics = !verdict.pass
+            ? `\nclassification: ${verdict.meta.classification ?? "unknown"}; runner-level diagnostic: never-started ${neverStarted}; reporter errors ${reporterErrors}`
+                + [...runnerErrors,
+                    stdoutTail.toString(), stderrTail.toString()].filter(Boolean).map(text => `\n${text}`).join("")
+            : "";
         return { pass: verdict.pass, kind: verdict.kind,
-            details: verdict.details + (!invoked.report && invoked.stderr ? `\nvitest reporter: ${invoked.stderr}` : ""),
+            details: verdict.details + diagnostics,
             classification: verdict.meta.classification,
-            meta: { ...verdict.meta, nonce, manifest: files, spawnedCommand, processExit: invoked.exitCode, pid: invoked.pid },
+            meta: { ...verdict.meta, nonce, manifest: files, manifestPath, listingCommand: invocation.listing, verification,
+                spawnedCommand, processExit: invoked.exitCode, pid: invoked.pid, stdoutPath, stderrPath },
             exitCode: invoked.exitCode ?? -1, reportPath };
     }
     catch (error) {
         return { pass: false, kind: "infra", classification: "infra", exitCode: -1, reportPath,
             details: error instanceof Error ? error.message : String(error),
-            meta: { classification: "infra", infra: true, manifestDiscoveryFailed: true, spawnedCommand } };
+            meta: { classification: "infra", infra: true, manifestDiscoveryFailed: true, spawnedCommand, verification, ...(manifestPath ? { manifestPath } : {}) } };
     }
 }

package/dist/gates/test-reporter.js

@@ -27,22 +27,35 @@ export default class TickmarkrReporter {
     const file = this.file(module);
     const failed = module.state() === 'failed';
     const failures = [];
-    if (failed) {
-      for (const test of module.children.allTests()) {
-        if (test.result().state === 'failed') {
+    // R41: count test bodies by their own state so a module whose every test was skipped (a
+    // describe.skipIf gate) is recorded as SKIPPED — present in the lifecycle, but never as
+    // executed test-body success. 'passed'/'failed' executed; anything else did not run.
+    const tests = { passed: 0, failed: 0, skipped: 0 };
+    for (const test of module.children.allTests()) {
+      const state = test.result().state;
+      if (state === 'failed') {
+        tests.failed++;
+        if (failed) {
           const errors = test.result().errors || [];
           failures.push(...(errors.length ? errors.map(e => 'FAIL ' + file + ' > ' + test.fullName + ': ' + e.message) : ['FAIL ' + file + ' > ' + test.fullName]));
         }
-      }
-      if (!failures.length) failures.push('FAIL ' + file);
+      } else if (state === 'passed') tests.passed++;
+      else tests.skipped++;
     }
+    if (failed && !failures.length) failures.push('FAIL ' + file);
+    const status = failed ? 'failed' : tests.passed + tests.failed === 0 ? 'skipped' : 'passed';
     if (file in this.report.completed) this.report.duplicateCompletions.push(file);
-    this.report.completed[file] = { at: Date.now(), status: failed ? 'failed' : 'passed', failures };
+    this.report.completed[file] = { at: Date.now(), status, failures, tests };
     this.save();
   }
   onTestRunEnd(modules, errors, reason) {
     const failed = reason === 'failed' || errors.length > 0 || Object.values(this.report.completed).some(c => c.status === 'failed');
-    this.report.certificate = { at: Date.now(), exitCode: failed ? 1 : 0 };
+    // Collection failures can reach run end without a module start/end event. Keep their
+    // identity as diagnostics, without inventing lifecycle records or changing the verdict.
+    const loadErrors = modules.flatMap(module => module.errors().map(e => this.file(module) + ': ' + e.message));
+    this.report.certificate = { at: Date.now(), exitCode: failed ? 1 : 0,
+      errors: errors.length + loadErrors.length,
+      diagnostics: [...loadErrors, ...errors.map(e => [e.testPath, e.name, e.message].filter(Boolean).join(': '))] };
     this.save();
   }
 }

package/dist/graph/graph.d.ts

@@ -21,6 +21,8 @@ export interface OnDiskSpecHash {
  * evidence for failed recompiles, while moved/deleted source files need not strand a compiled graph.
  */
 export declare function onDiskSpecHash(_repoRoot: string, graph: RunGraph): OnDiskSpecHash | undefined;
+/** A task's definition minus its files[] (and run state): what a scope amendment must NOT move (OBS-1073). */
+export declare function taskDefinitionFingerprint(task: Task): string;
 export declare function graphDefinitionHash(g: RunGraph): string;
 export declare function taskContentDigest(task: Pick<Task, "goal" | "files" | "acceptance">): string;
 export declare function tickmarkrDir(repoRoot: string): string;
@@ -33,7 +35,9 @@ export declare function addEvidence(g: RunGraph, id: string, patch: {
     artifacts?: string[];
     gateResults?: unknown[];
 }): RunGraph;
+export declare function chainDepth(g: RunGraph): Map<string, number>;
 export declare function readyTasks(g: RunGraph): Task[];
+export declare function dispatchWaves(g: RunGraph, concurrency: number): Map<string, number>;
 export declare function isComplete(g: RunGraph): boolean;
 export declare function isStalled(g: RunGraph): boolean;
 export declare function closureReaches(g: RunGraph, taskId: string, pred: (t: Task) => boolean): boolean;

package/dist/graph/graph.js

@@ -80,6 +80,11 @@ export function onDiskSpecHash(_repoRoot, graph) {
 // single comparator in journal.ts (engagementComparable) so the journal↔graph join is decided once.
 // ponytail: sha256 truncated to 16 hex — stable, grep-friendly; promote to full digest only if a
 // collision ever bites (engagement ids are not a trust boundary, collisions just force a re-run).
+/** A task's definition minus its files[] (and run state): what a scope amendment must NOT move (OBS-1073). */
+export function taskDefinitionFingerprint(task) {
+    const { status: _status, evidence: _evidence, files: _files, ...def } = task;
+    return createHash("sha256").update(JSON.stringify(def)).digest("hex").slice(0, 16);
+}
 export function graphDefinitionHash(g) {
     const definitions = g.tasks.map(({ status: _status, evidence: _evidence, ...def }) => def);
     return createHash("sha256").update(JSON.stringify({ version: g.version, spec: g.spec, tasks: definitions })).digest("hex").slice(0, 16);
@@ -156,9 +161,53 @@ export function addEvidence(g, id, patch) {
             : t),
     };
 }
+// OBS-1018: chain depth = number of downstream edges on the longest dependency path from a task to
+// a leaf below it (a task nothing depends on is 0). Counted over the whole graph, status-blind: a
+// root's critical path does not shrink because part of it already ran.
+export function chainDepth(g) {
+    const dependents = new Map(g.tasks.map((t) => [t.id, []]));
+    for (const t of g.tasks)
+        for (const d of t.deps)
+            dependents.get(d)?.push(t.id);
+    const depth = new Map();
+    const visit = (id) => {
+        const known = depth.get(id);
+        if (known !== undefined)
+            return known;
+        const below = dependents.get(id) ?? [];
+        const value = below.length ? 1 + Math.max(...below.map(visit)) : 0; // acyclic: validateGraph rejects cycles
+        depth.set(id, value);
+        return value;
+    };
+    for (const t of g.tasks)
+        visit(t.id);
+    return depth;
+}
+// OBS-1018: admission is critical-path order — deepest chain root first, ties in declaration order.
+// The daemon's dispatch loop slices this list unchanged. Stated limit: resume-restore of previously
+// in-flight attempts keeps its own precedence (src/run/daemon.ts); only fresh admission is ordered here.
 export function readyTasks(g) {
     const done = new Set(g.tasks.filter((t) => t.status === "done").map((t) => t.id));
-    return g.tasks.filter((t) => t.status === "pending" && t.deps.every((d) => done.has(d)));
+    const depth = chainDepth(g);
+    return g.tasks
+        .filter((t) => t.status === "pending" && t.deps.every((d) => done.has(d)))
+        .sort((a, b) => depth.get(b.id) - depth.get(a.id)); // Array#sort is stable: equal depths keep declaration order
+}
+// OBS-1018: the dispatch wave each pending task would enter at `concurrency` slots if every wave
+// took one tick — computed by draining readyTasks, so plan and daemon can never disagree on order.
+// Tasks already past pending carry no wave.
+export function dispatchWaves(g, concurrency) {
+    const waves = new Map();
+    let sim = g;
+    for (let wave = 1;; wave++) {
+        const batch = readyTasks(sim).slice(0, Math.max(1, concurrency));
+        if (!batch.length)
+            return waves;
+        for (const t of batch) {
+            waves.set(t.id, wave);
+            sim = setStatus(sim, t.id, "done");
+        }
+    }
 }
 export function isComplete(g) {
     return g.tasks.every((t) => t.status === "done");

package/dist/run/activity.d.ts

@@ -1,4 +1,5 @@
 import { type JournalEvent } from "./journal.js";
+import { type CommandReceipt, type TrackedJournalRow } from "./protocol.js";
 export interface ActivityTask {
     id: string;
     gates: readonly string[];
@@ -13,3 +14,30 @@ export interface ActivitySnapshot {
     cells: Map<string, string>;
 }
 export declare function foldActivity(events: JournalEvent[], tasks: readonly ActivityTask[]): ActivitySnapshot;
+/** Recorded evidence, not a probe of whether a subprocess is still alive. */
+export type BuildActivity = {
+    state: "start-unrecorded" | "awaiting-command";
+} | {
+    state: CommandReceipt["outcome"] | "unresolved";
+    receipt: CommandReceipt;
+};
+export interface TaskActivityProjection {
+    taskId: string;
+    /** Journal attempt label (zero based), absent until an attempt is recorded. */
+    attempt?: number;
+    state: "unconfirmed" | "preparing" | "implementing" | "returned-for-verification" | "validating" | "reviewing" | "merging" | "terminal";
+    /** Concurrent gates retain separate entries; state alone is only a summary. */
+    phases: {
+        gate: string;
+        state: "validating" | "reviewing";
+    }[];
+    build: BuildActivity;
+}
+/**
+ * Pure, evidence-only successor to foldActivity. Feed Journal.readTracked() and the owning run ID;
+ * sourceIndex supplies journal order, never wall time. Unattributed legacy rows belong to their
+ * tracked run and current attempt/round. They cannot prove identities absent from the journal.
+ * A new gates phase opens a round; completed gates cannot reopen within that round. No declared
+ * gate order, graph status, or successful verdict predicts a later phase.
+ */
+export declare function projectActivity(runId: string, rows: readonly TrackedJournalRow[], tasks: readonly ActivityTask[]): Map<string, TaskActivityProjection>;