tickmarkr 1.93.0 → 1.97.0

package/dist/adapters/model-lints.d.ts

@@ -57,7 +57,7 @@ export declare function catalogModelAdvisory(cfg: TickmarkrConfig, catalog: Cata
  */
 export declare function hasWindowsConfig(cfg: TickmarkrConfig): boolean;
 export declare function declaredModelWindow(cfg: TickmarkrConfig, adapter: string, model: string): number | undefined;
-/** A numeric estimate exists only when every payload path is measurable from the worker-visible tree. */
+/** A numeric estimate exists only when every context ref is measurable from the worker-visible tree. */
 export declare function estimateTaskPayloadTokens(task: Task, repoRoot: string, feedback?: string): number | undefined;
 export type RoutedAssignment = {
     taskId: string;

package/dist/adapters/model-lints.js

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { DEFAULT_CONFIG, TIER_RANK } from "../config/config.js";
+import { filesGlob } from "../graph/files-glob.js";
 import { buildTaskPrompt } from "./prompt.js";
 import { channelKey, MODEL_ID_RE } from "./types.js";
 import { resolveCatalogModel } from "./catalog-remote.js";
@@ -194,80 +195,136 @@ export function hasWindowsConfig(cfg) {
 export function declaredModelWindow(cfg, adapter, model) {
     return cfg.tiers[adapter]?.windows?.[model];
 }
+/** Named paths per lint line: an uncapped enumeration reached 4,924 columns on the P99 graph. */
+const MAX_NAMED_PATHS = 3;
 const GLOB_CHARS = /[*?{[]/;
 // T13's visibility oracle is the committed base tree: workers are created from HEAD, not from the
 // author's checkout or index. Keep --full-tree load-bearing for callers below the repository root.
+// `-l` prices every blob in the SAME call (a per-path `cat-file -s` spawn cannot price a pattern),
+// and `-z` is load-bearing correctness, not economy: without it git quotes any non-ASCII path, so
+// every Arabic/UTF-8 tracked file read as absent.
 function baseTreeAtHead(dir) {
     const git = (...args) => spawnSync("git", ["-C", dir, ...args], { encoding: "utf8", maxBuffer: 1 << 28 });
     const top = git("rev-parse", "--show-toplevel");
-    const tree = git("ls-tree", "--full-tree", "-r", "--name-only", "HEAD");
+    const tree = git("ls-tree", "--full-tree", "-r", "-l", "-z", "HEAD");
     if (top.status !== 0 || tree.status !== 0 || typeof top.stdout !== "string" || typeof tree.stdout !== "string")
         return undefined;
-    return { root: top.stdout.trim(), tracked: new Set(tree.stdout.split("\n").filter(Boolean)) };
+    const sizes = new Map();
+    for (const record of tree.stdout.split("\0")) {
+        const tab = record.indexOf("\t");
+        if (tab < 0)
+            continue;
+        // `<mode> <type> <object> <size>\t<path>`; a submodule entry carries `-` as its size and no bytes.
+        const bytes = Number.parseInt(record.slice(0, tab).split(/\s+/)[3] ?? "", 10);
+        sizes.set(record.slice(tab + 1), Number.isSafeInteger(bytes) && bytes >= 0 ? bytes : 0);
+    }
+    return { root: top.stdout.trim(), sizes };
 }
-function fileBytes(repoRoot, rel, tree = baseTreeAtHead(repoRoot)) {
-    if (GLOB_CHARS.test(rel))
-        return { status: "unreadable", reason: "glob" };
-    if (!tree)
-        return { status: "unreadable", reason: "base-tree-unavailable" };
+/**
+ * Bytes a worker can read at that path in the base tree, or undefined when the tree carries nothing
+ * there. A files[]-shaped pattern and a directory both price as everything they cover — matching
+ * through src/graph/files-glob.ts so the estimate reads patterns exactly as the scope gate does.
+ */
+function measureBytes(tree, rel) {
     const path = rel.replace(/\/+$/, "");
-    if (!tree.tracked.has(path)) {
-        if ([...tree.tracked].some((tracked) => tracked.startsWith(`${path}/`))) {
-            return { status: "unreadable", reason: "directory" };
-        }
-        return { status: "unreadable", reason: existsSync(join(tree.root, path)) ? "untracked" : "absent" };
+    const exact = tree.sizes.get(path);
+    if (exact !== undefined)
+        return exact;
+    const match = GLOB_CHARS.test(path) ? filesGlob(path) : undefined;
+    let total = 0;
+    let covered = false;
+    for (const [tracked, bytes] of tree.sizes) {
+        if (!(match ? match(tracked) : tracked.startsWith(`${path}/`)))
+            continue;
+        total += bytes;
+        covered = true;
     }
-    // Read the blob size from HEAD too: an unstaged/staged checkout edit is not what the worker receives.
-    const size = spawnSync("git", ["-C", tree.root, "cat-file", "-s", `HEAD:${path}`], { encoding: "utf8" });
-    const bytes = Number.parseInt(typeof size.stdout === "string" ? size.stdout.trim() : "", 10);
-    return size.status === 0 && Number.isSafeInteger(bytes) && bytes >= 0
-        ? { status: "measured", bytes }
-        : { status: "unreadable", reason: "base-tree-read-failed" };
+    return covered ? total : undefined;
 }
-function taskPayloadResolution(task, repoRoot, feedback) {
-    let bytes = buildTaskPrompt(task, feedback).length;
-    const unreadable = [];
-    const tree = baseTreeAtHead(repoRoot);
-    const add = (field, path) => {
-        const measured = fileBytes(repoRoot, path, tree);
-        if (measured.status === "measured")
-            bytes += measured.bytes;
-        else
-            unreadable.push({ field, path, reason: measured.reason });
+function absentContextReason(root, path) {
+    if (spawnSync("git", ["-C", root, "check-ignore", "-q", "--", path]).status === 0)
+        return "gitignored";
+    return existsSync(join(root, path)) ? "untracked" : "absent";
+}
+function upstreamProducer(tasks) {
+    const byId = new Map(tasks.map((t) => [t.id, t]));
+    const cache = new Map();
+    const upstream = (taskId) => {
+        let entry = cache.get(taskId);
+        if (!entry) {
+            const seen = new Set();
+            const walk = (from) => {
+                for (const dep of byId.get(from)?.deps ?? [])
+                    if (!seen.has(dep)) {
+                        seen.add(dep);
+                        walk(dep);
+                    }
+            };
+            walk(taskId);
+            entry = [...seen].map((id) => {
+                const files = byId.get(id)?.files ?? [];
+                return { id, covers: files.length ? filesGlob(files) : () => false };
+            });
+            cache.set(taskId, entry);
+        }
+        return entry;
     };
-    for (const path of task.context)
-        add("context", path);
+    return (taskId, path) => upstream(taskId).find((dep) => dep.covers(path))?.id;
+}
+function taskPayloadResolution(task, repoRoot, feedback, tree = baseTreeAtHead(repoRoot), producerOf = () => undefined) {
+    let bytes = buildTaskPrompt(task, feedback).length;
+    if (!tree) {
+        return { tokens: Math.ceil(bytes / CHARS_PER_TOKEN), unmeasurable: [{ path: ".", reason: "base-tree-unavailable" }] };
+    }
+    // files[] is WRITE SCOPE, not payload: a task's own output (`99-04-SUMMARY.md`) is absent from the
+    // base tree BY CONSTRUCTION and a scope entry is a set, not a document. Price what the worker can
+    // already read there and charge nothing for the rest. Billing an output path as a measurement
+    // failure is what made the window comparison unreachable on every real graph — 41 of 41 tasks on
+    // the P99 graph reported "payload unreadable" and none was ever compared to its model's window.
     for (const path of task.files)
-        add("files", path);
-    return { tokens: Math.ceil(bytes / CHARS_PER_TOKEN), unreadable };
+        bytes += measureBytes(tree, path) ?? 0;
+    const unmeasurable = [];
+    for (const path of task.context) {
+        const measured = measureBytes(tree, path);
+        if (measured !== undefined) {
+            bytes += measured;
+            continue;
+        }
+        const producer = producerOf(task.id, path);
+        unmeasurable.push(producer
+            ? { path, reason: "produced-upstream", producer }
+            : { path, reason: absentContextReason(tree.root, path) });
+    }
+    return { tokens: Math.ceil(bytes / CHARS_PER_TOKEN), unmeasurable };
 }
-/** A numeric estimate exists only when every payload path is measurable from the worker-visible tree. */
+/** A numeric estimate exists only when every context ref is measurable from the worker-visible tree. */
 export function estimateTaskPayloadTokens(task, repoRoot, feedback = "") {
     const estimate = taskPayloadResolution(task, repoRoot, feedback);
-    return estimate.unreadable.length === 0 ? estimate.tokens : undefined;
+    return estimate.unmeasurable.length === 0 ? estimate.tokens : undefined;
 }
-function unreadablePayloadLint(taskId, unreadable) {
-    const describe = ({ field, path, reason }) => {
-        const prefix = `${field} ${JSON.stringify(path)}`;
-        if (reason === "untracked")
-            return `${prefix} is present in the checkout but not in the base tree`;
-        if (reason === "absent")
-            return `${prefix} is absent from the base tree and checkout`;
-        if (reason === "glob")
-            return `${prefix} is a glob and cannot be measured`;
-        if (reason === "directory")
-            return `${prefix} is a directory and cannot be measured as one file`;
+function unreachableContextLint(taskId, dangling) {
+    const describe = ({ path, reason }) => {
         if (reason === "base-tree-unavailable")
-            return `${prefix} cannot be checked because the base tree is unavailable`;
-        return `${prefix} could not be read from the base tree`;
+            return "the base tree is unavailable, so no context ref can be checked";
+        const named = JSON.stringify(path);
+        if (reason === "gitignored")
+            return `${named} is gitignored — no commit can carry it into a worktree`;
+        if (reason === "untracked")
+            return `${named} is present in the checkout but not in the base tree`;
+        return `${named} is absent from the base tree and no task in this graph produces it`;
     };
-    return `${taskId}: payload unreadable — ${unreadable.map(describe).join(", ")}; context-window comparison skipped`;
+    const rest = dangling.length - MAX_NAMED_PATHS;
+    return `${taskId}: context unreachable — ${dangling.slice(0, MAX_NAMED_PATHS).map(describe).join(", ")}`
+        + `${rest > 0 ? `, +${rest} more` : ""}; the worker's "read these first" list dangles`
+        + " and the context-window comparison is skipped";
 }
 /** Advisory only — absent windows config or undeclared model window ⇒ no lint. */
 export function contextWindowLints(tasks, assignments, cfg, repoRoot) {
     if (!hasAnyWindows(cfg))
         return [];
     const byId = new Map(assignments.map((a) => [a.taskId, a]));
+    const tree = baseTreeAtHead(repoRoot);
+    const producerOf = upstreamProducer(tasks);
     const lints = [];
     for (const t of tasks) {
         const a = byId.get(t.id);
@@ -276,13 +333,20 @@ export function contextWindowLints(tasks, assignments, cfg, repoRoot) {
         const window = declaredModelWindow(cfg, a.adapter, a.model);
         if (window === undefined)
             continue;
-        const estimate = taskPayloadResolution(t, repoRoot, "");
-        if (estimate.unreadable.length > 0) {
-            lints.push(unreadablePayloadLint(t.id, estimate.unreadable));
+        const estimate = taskPayloadResolution(t, repoRoot, "", tree, producerOf);
+        const dangling = estimate.unmeasurable.filter((u) => u.reason !== "produced-upstream");
+        if (dangling.length > 0) {
+            lints.push(unreachableContextLint(t.id, dangling));
             continue;
         }
+        // An upstream-produced ref is unmeasurable but REACHABLE — the run writes it before this task
+        // branches — so it earns no lint of its own: silence on the benign class is what leaves a real
+        // dangling ref visible. The estimate is then a lower bound, and a lower bound over the window is
+        // still an overflow, so it is reported with what it excludes named.
         if (estimate.tokens > window) {
-            lints.push(`${t.id}: payload ~${estimate.tokens} tokens exceeds ${a.adapter}:${a.model} window ${window}`);
+            const pending = estimate.unmeasurable.length;
+            lints.push(`${t.id}: payload ~${estimate.tokens} tokens exceeds ${a.adapter}:${a.model} window ${window}`
+                + (pending > 0 ? ` (lower bound — ${pending} context ref(s) are produced upstream and not yet measurable)` : ""));
         }
     }
     return lints;

package/dist/brand.d.ts

@@ -26,6 +26,8 @@ export declare function paneDispatchCommand(scriptPath: string): string;
 export declare const BRAND_RAMP: readonly [84, 78, 41, 35];
 /** Brand green (ramp anchor 41) — the tickmark hue; also the ok/pass/authed verdict color. */
 export declare const brand: (s: string) => string;
+/** Compact product chip — black ink on the terminal theme's ANSI green. */
+export declare const brandChip: (s: string) => string;
 /** Ok verdicts (pass/authed/green) render in the brand green ramp — same hue as the tickmark. */
 export declare const ok: (s: string) => string;
 /** Fail verdicts (unauthed/red) — red, always paired with the ✗ shape. */
@@ -39,6 +41,7 @@ export declare const bold: (s: string) => string;
 /** Every semantic color token, for sweeps: each is TTY-gated and NO_COLOR-aware. */
 export declare const TOKENS: {
     readonly brand: (s: string) => string;
+    readonly brandChip: (s: string) => string;
     readonly ok: (s: string) => string;
     readonly fail: (s: string) => string;
     readonly warn: (s: string) => string;

package/dist/brand.js

@@ -108,6 +108,8 @@ const visual = () => process.stdout.isTTY === true && process.env.NO_COLOR === u
 const sgr = (code) => (s) => visual() ? `\x1b[${code}m${s}${R}` : s;
 /** Brand green (ramp anchor 41) — the tickmark hue; also the ok/pass/authed verdict color. */
 export const brand = sgr(`38;5;${BRAND_RAMP[2]}`);
+/** Compact product chip — black ink on the terminal theme's ANSI green. */
+export const brandChip = sgr("30;42");
 /** Ok verdicts (pass/authed/green) render in the brand green ramp — same hue as the tickmark. */
 export const ok = brand;
 /** Fail verdicts (unauthed/red) — red, always paired with the ✗ shape. */
@@ -119,7 +121,7 @@ export const dim = sgr("2");
 /** Emphasis (titles, selection, the product name) — bold. */
 export const bold = sgr("1");
 /** Every semantic color token, for sweeps: each is TTY-gated and NO_COLOR-aware. */
-export const TOKENS = { brand, ok, fail, warn, dim, bold };
+export const TOKENS = { brand, brandChip, ok, fail, warn, dim, bold };
 /**
  * The glyph vocabulary — plain characters only; color layers on via tokens so
  * shape survives NO_COLOR. Bracket toggles ([x]/[ ]) are forbidden on every surface.

package/dist/cli/commands/beat.d.ts

@@ -0,0 +1 @@
+export declare function beat(argv: string[], cwd?: string): Promise<string>;

package/dist/cli/commands/beat.js

@@ -0,0 +1,50 @@
+import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { tickmarkrDir } from "../../graph/graph.js";
+import { SUPERVISION_BEAT_MS, SUPERVISION_STALE_MS, SUPERVISION_TIERS, beatSupervision, supervisionStandDownPath, } from "../../run/supervision.js";
+// SUP-04: the writer side of supervision, as a VERB. `beatSupervision` and `SUPERVISION_BEAT_MS` shipped
+// with exactly one in-repo caller — the daemon, on one tier — so `status` printed
+// `orchestrator ARMED / overseer ABSENT / watch ABSENT` while a real overseer worked the run: two thirds
+// of a supervision claim were constants dressed as measurements. A seat that supervises from a shell
+// (the overseer skill's watcher loop) has no way into a node module; a command does.
+//
+// ONE-SHOT AND ERROR-PROPAGATING, deliberately not `armSupervision`. That helper is the right shape for
+// a long-lived node process and the wrong shape here twice over. Its recurring interval would outlive
+// the invocation — in a long-lived dispatcher a later `--stand-down` would disarm only its own timer
+// while an earlier one kept writing, flipping DISARMED back to ARMED ten seconds later: the exact
+// fail-open this instrument exists to catch. And it swallows write failures by design (an unwritten
+// beat ages out, which is the truth for a watcher that must not be crashed by its own instrument) —
+// but a CLI that swallows them PRINTS a state nothing recorded, so `beat` says ARMED while `status`
+// reads UNREADABLE. Here the writes are unguarded: a failure leaves the process with a non-zero exit
+// and a message instead of a claim. The LOOP belongs to the caller, which is what makes the beat
+// evidence: stop calling it and the tier ages into STALE on its own.
+export async function beat(argv, cwd = process.cwd()) {
+    const standDown = argv.includes("--stand-down");
+    const named = argv.find((a) => !a.startsWith("--"));
+    if (!isTier(named)) {
+        throw new Error(`usage: tickmarkr beat <${SUPERVISION_TIERS.join("|")}> [--stand-down] — got ${named ? `\`${named}\`` : "no tier"}`);
+    }
+    if (standDown)
+        return standDownTier(cwd, named);
+    // Clear a stand-down marker left by an earlier session BEFORE beating: a valid marker outranks every
+    // beat that does not strictly follow it, and two writes landing in the same millisecond do not. An
+    // uncleared marker would render DISARMED while this verb claimed ARMED, so the removal is unguarded
+    // too — `force` makes the ordinary "no marker" case a no-op, and anything else is a real failure.
+    rmSync(supervisionStandDownPath(cwd, named), { force: true, recursive: true });
+    beatSupervision(cwd, named);
+    return `${named} ARMED — beat again every ${SUPERVISION_BEAT_MS / 1_000}s; the tier reads STALE ${SUPERVISION_STALE_MS / 1_000}s after the last beat`;
+}
+// Stand-down is a RECORDED act, not a silence: the marker tells a reader this watcher left on purpose,
+// so the tier reads DISARMED rather than ageing out as a death. Published atomically — written aside,
+// renamed over — because a torn marker is rejected by the reader, and a rejected stand-down reports a
+// deliberate hand-off as a death.
+function standDownTier(repoRoot, tier) {
+    tickmarkrDir(repoRoot); // the write path DOES create — markers land inside the gitignored state dir
+    const p = supervisionStandDownPath(repoRoot, tier);
+    const tmp = `${p}.${process.pid}.tmp`;
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(tmp, JSON.stringify({ tier, pid: process.pid, disarmedAt: new Date().toISOString() }) + "\n");
+    renameSync(tmp, p);
+    return `${tier} DISARMED — hand-off recorded; status reads it stood down, not dead`;
+}
+const isTier = (v) => SUPERVISION_TIERS.includes(v ?? "");