tickmarkr 1.57.0 → 1.59.0

package/README.md

@@ -415,9 +415,15 @@ These are optional — the CLI works standalone. Skills are repo-scoped and ship
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, the green bar (build/test/lint), and 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, the green bar (build/test/lint), and
 design invariants. Pull requests welcome; non-trivial changes should include test coverage.
 
+**Boundaries:** this repo is a squashed export of private development — each release is a verified
+snapshot, not a live mirror of every commit. Before tickmarkr 2.0, minor versions may break with every
+break noted in [CHANGELOG.md](CHANGELOG.md). Support is best effort for the latest version only;
+accepted contributions are credited via `Co-authored-by:` on the release commit. Details in
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## Documentation
 
 - **[LICENSE](LICENSE)** — MIT license

package/dist/adapters/kimi.js

@@ -1,16 +1,33 @@
 import { spawnSync } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { probeVersion } from "./claude-code.js";
 import { parseWorkerResult } from "./prompt.js";
-import { channelsFromConfig, MODEL_ID_RE, shq } from "./types.js";
-// KIMI-03: collectUsage is DELIBERATELY ABSENT — documented won't-implement, consistent with the
-// metering-honesty invariant (adapters/types.ts). Sessions live under ~/.kimi-code/sessions/ with
-// kimi export (ZIP) + session_index.jsonl; no harness-readable per-attempt token counter was found
-// in the session store (research F-6, 2026-07-17). Consequence: kimi channels report honestly
-// `unmetered` — same class as grok (grok.ts:11-39). Revisit if kimi ships usage in the
-// `-p --output-format stream-json` envelope or a counter in the session store.
+import { channelsFromConfig, MODEL_ID_RE, shq, TokenUsageSchema } from "./types.js";
+// KIMI-03 → v1.58 T5: the "no harness-readable counter" block (research F-6, 2026-07-17) is
+// LIFTED for collectUsage — kimi 0.27.0 writes a wire journal per agent at
+// ~/.kimi-code/sessions/<wd>/session_<uuid>/agents/<agent>/wire.jsonl, and ~/.kimi-code/
+// workspaces.json maps each wd_* dir to its realpath'd workspace root. Field mapping pinned ONLY
+// after live verification of the real store (2026-07-18, 53 wire files / 178 usage rows, zero
+// tokens spent):
+//   - the canonical row is top-level `{"type":"usage.record","usage":{...},"usageScope":"turn",
+//     "time":<epoch ms>}` — 178/178 rows carried scope "turn" and the identical key set
+//     {inputOther, output, inputCacheRead, inputCacheCreation};
+//   - per-turn DELTA semantics verified arithmetically: each turn's inputCacheRead ≈ prior
+//     inputCacheRead + inputOther + output (the grown context re-read from cache — claude's
+//     per-message convention), and inputOther/output are non-monotonic per-turn counts, so
+//     SUMMING rows is the correct fold (never a cumulative 3A+2B+C trap);
+//   - the SAME usage object is echoed inside the step.end loop event
+//     (`type:"context.append_loop_event"`, event.usage) — folding anything but usage.record
+//     rows double-counts every turn, hence the exact type+scope pin below;
+//   - mapping: inputOther→input, output→output, inputCacheRead→cacheRead,
+//     inputCacheCreation→cacheWrite (creation observed live only as 0; mapped by name).
+// Absent or ambiguous usage resolves to UNMETERED, never an invented count: unknown usageScope,
+// non-numeric core fields, torn lines, or no post-cursor row all skip/return undefined — the
+// "?? 0" poisoning class stays banned. contextUsage remains absent (resumeUnknownContext below).
+const MAX_SESSION_FILES = 20;
+const MAX_SESSION_BYTES = 8_000_000;
 const CREDENTIALS_PATH = join(homedir(), ".kimi-code", "credentials", "kimi-code.json");
 // KIMI-01. Auth verdict from ~/.kimi-code/credentials/kimi-code.json ONLY — flat JSON, never a
 // network call. expires_at is epoch SECONDS (not ISO like grok). Non-empty refresh_token dominates
@@ -101,6 +118,102 @@ export const kimi = {
         return { command: this.headlessCommand(ctx.promptFile, a.model) };
     },
     parse: parseKimiResult,
+    collectUsage(cwd, sinceMs) {
+        try {
+            const real = realpathSync(cwd);
+            const home = join(homedir(), ".kimi-code");
+            const ws = JSON.parse(readFileSync(join(home, "workspaces.json"), "utf8"));
+            // a recreated workspace gets a new wd_* hash for the same root — fold every match
+            const wdDirs = Object.entries(ws.workspaces ?? {})
+                .filter(([, v]) => v && typeof v === "object" && v.root === real)
+                .map(([k]) => k);
+            // newest-first by mtime, bounded — mtime picks WHICH files to scan, never a record's cursor
+            const files = [];
+            for (const wd of wdDirs) {
+                const wdPath = join(home, "sessions", wd);
+                let sessions;
+                try {
+                    sessions = readdirSync(wdPath);
+                }
+                catch {
+                    continue;
+                }
+                for (const s of sessions) {
+                    if (!s.startsWith("session_"))
+                        continue;
+                    const agentsPath = join(wdPath, s, "agents");
+                    let agents;
+                    try {
+                        agents = readdirSync(agentsPath);
+                    }
+                    catch {
+                        continue;
+                    }
+                    for (const a of agents) {
+                        const p = join(agentsPath, a, "wire.jsonl");
+                        try {
+                            files.push({ path: p, m: statSync(p).mtimeMs });
+                        }
+                        catch {
+                            continue;
+                        }
+                    }
+                }
+            }
+            files.sort((a, b) => b.m - a.m);
+            let input = 0, output = 0, kept = false;
+            let cacheRead, cacheWrite;
+            for (const { path: fp } of files.slice(0, MAX_SESSION_FILES)) {
+                let text;
+                try {
+                    text = readFileSync(fp, "utf8").slice(0, MAX_SESSION_BYTES);
+                }
+                catch {
+                    continue;
+                }
+                for (const line of text.split("\n")) {
+                    if (!line.trim())
+                        continue;
+                    let recRaw;
+                    try {
+                        recRaw = JSON.parse(line);
+                    }
+                    catch {
+                        continue;
+                    }
+                    const rec = recRaw;
+                    // exact type+scope pin: the step.end loop event ECHOES the same usage (double-count),
+                    // and any scope other than the live-verified "turn" has unknown fold semantics — skip
+                    if (rec.type !== "usage.record" || rec.usageScope !== "turn")
+                        continue;
+                    if (typeof rec.time !== "number" || !Number.isFinite(rec.time) || rec.time < sinceMs)
+                        continue;
+                    const u = rec.usage;
+                    if (!u || typeof u !== "object")
+                        continue;
+                    const uu = u;
+                    // ambiguous row (core fields missing/non-numeric) resolves to unmetered, never 0
+                    if (typeof uu.inputOther !== "number" || typeof uu.output !== "number")
+                        continue;
+                    input += uu.inputOther;
+                    output += uu.output;
+                    if (typeof uu.inputCacheRead === "number")
+                        cacheRead = (cacheRead ?? 0) + uu.inputCacheRead;
+                    if (typeof uu.inputCacheCreation === "number")
+                        cacheWrite = (cacheWrite ?? 0) + uu.inputCacheCreation;
+                    kept = true;
+                }
+            }
+            if (!kept)
+                return undefined; // nothing matched ⇒ unmetered, never {input:0,…}
+            const out = { input, output, ...(cacheRead !== undefined ? { cacheRead } : {}), ...(cacheWrite !== undefined ? { cacheWrite } : {}) };
+            const p = TokenUsageSchema.safeParse(out);
+            return p.success ? p.data : undefined;
+        }
+        catch {
+            return undefined; // missing home/workspaces.json / any throw ⇒ fail open
+        }
+    },
     listModels: async () => {
         const r = spawnSync("kimi", ["provider", "list", "--json"], { encoding: "utf8", timeout: 15000 });
         return r.error || r.status !== 0 ? [] : parseKimiModels(r.stdout || "");

package/dist/cli/commands/init.js

@@ -1,5 +1,6 @@
-import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { createInterface } from "node:readline/promises";
 import { parseArgs } from "node:util";
 import { allAdapters, formatDoctorAgeForInit, formatDoctorReport, initDoctorReuse } from "../../adapters/registry.js";
@@ -61,7 +62,7 @@ function nextSteps(cwd, scaffoldedSpec) {
     return `next: edit ${scaffoldedSpec}, then tickmarkr compile ${scaffoldedSpec} && tickmarkr plan && tickmarkr run`;
 }
 const visual = () => process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
-const AGENT_SKILLS = ["tickmarkr-loop", "tickmarkr-auto"];
+const AGENT_SKILLS = ["tickmarkr-loop", "tickmarkr-auto", "tickmarkr-overseer"];
 const DOCS_BEGIN = "<!-- tickmarkr:agent-docs begin -->";
 const DOCS_END = "<!-- tickmarkr:agent-docs end -->";
 const AGENT_DOCS = `${DOCS_BEGIN}
@@ -110,9 +111,16 @@ A run is green only when the run-end event exists in the journal AND tip verify
 When relaying missions between agents, never use bare send-text (\`herdr agent send\` / pane send-text) — it omits Enter. Use \`herdr pane run <pane> "<message>"\` or \`herdr notification show "<message>"\`. Confirm delivery by reading the target pane afterward; never report "relayed" without read-back.
 ${DOCS_END}
 `;
-const skillsRoot = (cwd) => existsSync(join(cwd, ".claude", "skills")) ? join(cwd, ".claude", "skills") : join(cwd, ".agents", "skills");
-const skillPath = (cwd, skill) => join(skillsRoot(cwd), skill, "SKILL.md");
-const skillsInstalled = (cwd) => AGENT_SKILLS.every((s) => existsSync(skillPath(cwd, s)));
+// Every applicable host location gets the skills, each paired with its own repository guidance
+// file: codex discovers .agents/skills + AGENTS.md (always applicable); claude discovers
+// .claude/skills + CLAUDE.md (applicable when the repo already shows claude usage).
+const hostTargets = (cwd) => {
+    const targets = [{ skillsDir: join(cwd, ".agents", "skills"), docPath: join(cwd, "AGENTS.md") }];
+    if (existsSync(join(cwd, ".claude")) || existsSync(join(cwd, "CLAUDE.md")))
+        targets.push({ skillsDir: join(cwd, ".claude", "skills"), docPath: join(cwd, "CLAUDE.md") });
+    return targets;
+};
+const skillsInstalled = (cwd) => hostTargets(cwd).every((t) => AGENT_SKILLS.every((s) => existsSync(join(t.skillsDir, s, "SKILL.md"))));
 const wizardDriverDefault = () => process.env.HERDR_ENV === "1" ? "herdr" : "auto";
 async function installAgentFiles(cwd, force, docs, notes) {
     const interactive = process.stdin.isTTY === true && process.stdout.isTTY === true;
@@ -124,31 +132,30 @@ async function installAgentFiles(cwd, force, docs, notes) {
         return /^(?:y|yes)$/i.test((await prompt.question(`${question} [y/N] `)).trim());
     };
     try {
-        for (const skill of AGENT_SKILLS) {
-            const dest = skillPath(cwd, skill);
-            const exists = existsSync(dest);
-            if (exists && !force && !(await confirm(`Overwrite ${dest}?`))) {
-                notes.push(`skipped existing ${dest}; pass --force to overwrite it`);
-                continue;
+        for (const { skillsDir, docPath } of hostTargets(cwd)) {
+            for (const skill of AGENT_SKILLS) {
+                const dest = join(skillsDir, skill, "SKILL.md");
+                const exists = existsSync(dest);
+                if (exists && !force && !(await confirm(`Overwrite ${dest}?`))) {
+                    notes.push(`skipped existing ${dest}; pass --force to overwrite it`);
+                    continue;
+                }
+                // whole skill dir, not just SKILL.md — the overseer ships its pane-watcher script
+                cpSync(fileURLToPath(new URL(`../../../skills/${skill}`, import.meta.url)), join(skillsDir, skill), { recursive: true });
+                notes.push(`${exists ? "overwrote" : "wrote"} ${dest}`);
+            }
+            const current = existsSync(docPath) ? readFileSync(docPath, "utf8") : "";
+            if (current.includes(DOCS_BEGIN) || current.includes(`<!-- ${LEGACY_PREFIX}:agent-docs begin -->`)
+                || current.includes(DOCS_END) || current.includes(`<!-- ${LEGACY_PREFIX}:agent-docs end -->`)) {
+                notes.push(`kept existing tickmarkr agent docs in ${docPath}`);
+            }
+            else if (docs || await confirm(`Append tickmarkr agent docs to ${docPath}?`)) {
+                appendFileSync(docPath, `${current ? current.endsWith("\n") ? "\n" : "\n\n" : ""}${AGENT_DOCS}`);
+                notes.push(`appended tickmarkr agent docs to ${docPath}`);
+            }
+            else {
+                notes.push(`skipped agent docs for ${docPath}; pass --docs to append them`);
             }
-            mkdirSync(join(skillsRoot(cwd), skill), { recursive: true });
-            writeFileSync(dest, readFileSync(new URL(`../../../skills/${skill}/SKILL.md`, import.meta.url)), exists ? undefined : { flag: "wx" });
-            notes.push(`${exists ? "overwrote" : "wrote"} ${dest}`);
-        }
-        const claude = join(cwd, "CLAUDE.md");
-        const agents = join(cwd, "AGENTS.md");
-        const docPath = existsSync(claude) || !existsSync(agents) ? claude : agents;
-        const current = existsSync(docPath) ? readFileSync(docPath, "utf8") : "";
-        if (current.includes(DOCS_BEGIN) || current.includes(`<!-- ${LEGACY_PREFIX}:agent-docs begin -->`)
-            || current.includes(DOCS_END) || current.includes(`<!-- ${LEGACY_PREFIX}:agent-docs end -->`)) {
-            notes.push(`kept existing tickmarkr agent docs in ${docPath}`);
-        }
-        else if (docs || await confirm(`Append tickmarkr agent docs to ${docPath}?`)) {
-            appendFileSync(docPath, `${current ? current.endsWith("\n") ? "\n" : "\n\n" : ""}${AGENT_DOCS}`);
-            notes.push(`appended tickmarkr agent docs to ${docPath}`);
-        }
-        else {
-            notes.push(`skipped agent docs for ${docPath}; pass --docs to append them`);
         }
     }
     finally {
@@ -183,7 +190,7 @@ async function runInitWizard(cwd) {
         let installSkills = false;
         if (!skillsInstalled(cwd)) {
             const skillsDef = existsSync(join(cwd, ".claude", "skills")) && !skillsInstalled(cwd);
-            installSkills = await askYesNo(rl, "Install agent skills (tickmarkr-loop/tickmarkr-auto)?", skillsDef);
+            installSkills = await askYesNo(rl, "Install agent skills (tickmarkr-loop/tickmarkr-auto/tickmarkr-overseer)?", skillsDef);
         }
         return { overlay: { driver, concurrency, visibility: { llm } }, installSkills };
     }

package/dist/route/router.js

@@ -67,6 +67,43 @@ function ladderFor(task, entry) {
     const escalate = task.routingHints?.escalate ?? entry?.escalate ?? true;
     return escalate ? ["retry", "escalate", "consult", "human"] : ["retry", "consult", "human"];
 }
+// v1.58 frontier spread (operator ruling .planning/rulings/2026-07-18-frontier-spread-credits.md):
+// every sub channel marginal-cost-ranks 0, so tier-equal frontier ties fell through all sort keys
+// to discovery order — the first sub channel (claude-code:fable) served every frontier auto pick,
+// and same-day quota exhaustion on that one channel interrupted two live pipeline agents. A
+// deterministic task-keyed rotation now spreads each residual frontier tie across its whole tie
+// group, so sol/k3-class channels serve frontier work as first-class candidates. Strictly the LAST
+// tiebreak: it permutes only maximal runs already tied on every key above it (prefer band,
+// marginal cost, tier — plus exploration bonus and learned score on the learned path), and only
+// runs of zero-marginal-cost frontier SUB channels outside any prefer entry. Pins return upstream,
+// denies filter upstream, prefer order is operator-explicit — none are touched.
+// ponytail: frontier runs only — the ruled scope (ruling §1); spreading mid/cheap ties too = drop
+// the tier guard. Rotation, not utilization: profile-driven spread would be inert exactly where
+// the concentration bites (cold profiles, plan-time static routing, learned:off).
+const spreadOffset = (task) => {
+    let h = 0;
+    for (const ch of `${task.id}\n${task.goal}`)
+        h = (h * 31 + ch.charCodeAt(0)) >>> 0;
+    return h;
+};
+function spreadFrontierTies(sorted, task, prefer, tied) {
+    const out = [...sorted];
+    const preferLen = prefer?.length ?? 0;
+    let i = 0;
+    while (i < out.length) {
+        let j = i + 1;
+        while (j < out.length && tied(out[i], out[j]))
+            j++;
+        const len = j - i;
+        if (len > 1 && out[i].tier === "frontier" && marginalCostRank(out[i]) === 0 && preferIndex(out[i], prefer) === preferLen) {
+            const run = out.slice(i, j);
+            const k = spreadOffset(task) % len;
+            out.splice(i, len, ...run.slice(k), ...run.slice(0, k));
+        }
+        i = j;
+    }
+    return out;
+}
 function withoutExcluded(channels, exclude) {
     if (!exclude?.size)
         return channels;
@@ -174,8 +211,9 @@ export function route(task, cfg, channels, profile, preferCtx, exclude, exploreC
         for (const p of prefer ?? [])
             preflightPrefer(p);
     // key order is a contract: prefer > marginal cost > tier (cheapest sufficient) > learned score (v1.6 ROUTE-06)
-    // > discovery order (same-tier fairness, D2). The learned score is the LAST key — it decides only the
-    // discovery-order tail, never a pin/floor/prefer/cost/tier boundary (they all sort above it, ROUTE-08).
+    // > frontier spread (v1.58) > discovery order (same-tier fairness, D2). The learned score decides only the
+    // discovery-order tail, never a pin/floor/prefer/cost/tier boundary (they all sort above it, ROUTE-08);
+    // the spread rotates only what would otherwise fall to discovery order.
     const staticCmp = (a, b) => preferIndex(a, prefer) - preferIndex(b, prefer) || marginalCostRank(a) - marginalCostRank(b) || TIER_RANK[a.tier] - TIER_RANK[b.tier];
     const eligibleRaw = channels.filter((c) => TIER_RANK[c.tier] >= TIER_RANK[minTier]);
     if (!eligibleRaw.length) {
@@ -192,6 +230,11 @@ export function route(task, cfg, channels, profile, preferCtx, exclude, exploreC
     let eligible;
     let deviation;
     let learnedChosen = "";
+    let spreadDecided = false;
+    // v1.58: the spread is applied identically on both sort paths (and to the deviation baseline), so
+    // an empty/cold profile stays byte-identical to the 3-arg call (ROUTE-07) and a deviation always
+    // means learned evidence moved the pick — never the spread mislabeled as learning.
+    const spreadStatic = (sorted) => spreadFrontierTies(sorted, task, prefer, (a, b) => staticCmp(a, b) === 0);
     if (profile) {
         // scores precomputed ONCE over the eligible set — never inside the comparator (Pitfall 1).
         // ponytail: no epsilon — two finite scores subtract to a finite number (Phase 12 totality); an
@@ -210,7 +253,7 @@ export function route(task, cfg, channels, profile, preferCtx, exclude, exploreC
         const off = exploreOff(task, cfg, exploreCtx);
         const bonuses = new Map(eligibleRaw.map((c) => [channelKey(c), off ? 0 : explorationBonus(cellOf(profile, task.shape, channelKey(c), c.channel), cap)]));
         const bonusOf = (c) => bonuses.get(channelKey(c));
-        const staticWinner = [...eligibleRaw].sort(staticCmp)[0];
+        const staticWinner = spreadStatic([...eligibleRaw].sort(staticCmp))[0];
         // Phase 34 ROUTE-17: prefer becomes a BAND + group-rep keys so exploration fires ACROSS prefer
         // entries, while intra-entry order (cost > tier > bonus > score) and every cold path stay byte-identical.
         // Cold reduces to preferIndex || cost || tier ≡ staticCmp (proof P1); rep keys use the group HEAD so
@@ -232,7 +275,11 @@ export function route(task, cfg, channels, profile, preferCtx, exclude, exploreC
         }));
         const kOf = (c) => keyOf.get(channelKey(c));
         const firstDiff = (a, b) => kOf(a).findIndex((v, i) => v !== kOf(b)[i]);
-        eligible = [...eligibleRaw].sort((a, b) => { const i = firstDiff(a, b); return i === -1 ? 0 : kOf(a)[i] - kOf(b)[i]; });
+        const sortedByKey = [...eligibleRaw].sort((a, b) => { const i = firstDiff(a, b); return i === -1 ? 0 : kOf(a)[i] - kOf(b)[i]; });
+        // spread runs tied on the FULL learned key (bonus/score included) — a warm score or live probe
+        // bonus still decides its tie exactly as before; the spread rotates only the residual all-equal runs.
+        eligible = spreadFrontierTies(sortedByKey, task, prefer, (a, b) => firstDiff(a, b) === -1);
+        spreadDecided = channelKey(eligible[0]) !== channelKey(sortedByKey[0]);
         const w = eligible[0];
         const ru = channelKey(staticWinner) !== channelKey(w) ? staticWinner : eligible[1];
         // Phase 34 ROUTE-17: first-differing-key markers — probe when a rep or intra bonus key decided.
@@ -250,7 +297,9 @@ export function route(task, cfg, channels, profile, preferCtx, exclude, exploreC
         }
     }
     else {
-        eligible = eligibleRaw.sort(staticCmp); // ROUTE-07/09: literally the v1.5 code path — dead code cannot deviate
+        const sortedStatic = eligibleRaw.sort(staticCmp); // ROUTE-07/09: the v1.5 key order, spread applied as the last key
+        eligible = spreadStatic(sortedStatic);
+        spreadDecided = channelKey(eligible[0]) !== channelKey(sortedStatic[0]);
     }
     const bound = qualityBound(quality, advisoryFloor, taskFloorRaw) ??
         (taskFloor && TIER_RANK[taskFloor] >= TIER_RANK[baseTier] ? `floor ${taskFloor} (task hint${src})` :
@@ -261,8 +310,10 @@ export function route(task, cfg, channels, profile, preferCtx, exclude, exploreC
     const preferVia = preferFromAuto(task.shape, preferCtx)
         ? `via prefer (auto-modernized ${preferCtx.autoPrefer.derivedAt.slice(0, 10)})`
         : "via prefer";
-    const chosenBy = learnedChosen || (prefer && preferIndex(eligible[0], prefer) < prefer.length
-        ? preferVia : "cheapest sufficient tier");
+    // a spread-decided winner is never inside a prefer band (the spread skips those runs), so the
+    // three arms below are mutually exclusive by construction
+    const chosenBy = learnedChosen || (spreadDecided ? "via frontier spread"
+        : prefer && preferIndex(eligible[0], prefer) < prefer.length ? preferVia : "cheapest sufficient tier");
     maybeSlaLint(lints, task, profile, slaMinutes, eligible[0]);
     return { assignment: toAssignment(eligible[0]), ladder: ladderFor(task, entry), lints, provenance: `${degraded}${bound}, marginal-cost auto (${chosenBy})`, ...(deviation ? { deviation } : {}) };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tickmarkr",
-  "version": "1.57.0",
+  "version": "1.59.0",
   "description": "Spec in, verified work out.",
   "type": "module",
   "license": "MIT",
@@ -31,6 +31,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "lint": "oxlint src tests scripts",
+    "pretest": "npm run build",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "schema": "tsx scripts/emit-schema.ts",

package/skills/tickmarkr-auto/SKILL.md

@@ -14,7 +14,9 @@ When working in a multi-agent terminal environment, decide your role before star
 
 - **Orchestrator:** your session was started to execute the mission. Rename your own tab/pane `ORCH · <version>` (short labels: ≤20 chars, `ROLE · token`) and run the loop below.
 - **Supervisor with a live orchestrator:** do not start a second run. Relay the mission to the existing orchestrator with a [verified handoff](#verified-handoffs-agent-to-agent-messaging), then supervise it as OVERSEER.
-- **Primary session without an orchestrator:** rename your own tab `OVERSEER · <version>` and your agent `overseer`, spawn one child orchestration session with `--permission-mode bypassPermissions`, label its tab `ORCH · <version>` and name its agent, give it the mission and these rules verbatim, then supervise it. Do not drive a duplicate single-tier run yourself. Before spawning, confirm any PREVIOUS orchestrator has stood down (monitors stopped, input box empty — dim ghost-text suggestions are UI, not queued input; ANSI-verify before alarming) and close its tab — the journal, records, and ledger hold the story; scrollback is disposable.
+- **Primary session without an orchestrator:** rename your own tab `OVERSEER · <version>` and your agent `overseer`, spawn one child orchestration session with your host's launch form, label its tab `ORCH · <version>` and name its agent, give it the mission and these rules verbatim, then supervise it. Do not drive a duplicate single-tier run yourself. Before spawning, confirm any PREVIOUS orchestrator has stood down (monitors stopped, input box empty — dim ghost-text suggestions are UI, not queued input; ANSI-verify before alarming) and close its tab — the journal, records, and ledger hold the story; scrollback is disposable.
+  - **Claude Code:** `herdr agent start orchestrator --cwd <repo> --no-focus -- claude --permission-mode bypassPermissions`
+  - **Codex:** `herdr agent start orchestrator --cwd <repo> --no-focus -- codex --ask-for-approval never --sandbox workspace-write`
 
 Outside a multi-agent terminal environment, run the loop directly.
 

package/skills/tickmarkr-loop/SKILL.md

@@ -13,7 +13,9 @@ When working in a multi-agent terminal environment, decide your role before star
 
 - **Orchestrator:** your session was started to execute the mission. Rename your own tab/pane `ORCH · <version>` (short labels: ≤20 chars, `ROLE · token`) and run the loop below.
 - **Supervisor with a live orchestrator:** do not start a second run. Relay the mission to the existing orchestrator with a [verified handoff](#verified-handoffs-agent-to-agent-messaging), then supervise it as OVERSEER.
-- **Primary session without an orchestrator:** rename your own tab `OVERSEER · <version>` and your agent `overseer`, spawn one child orchestration session with `--permission-mode bypassPermissions`, label its tab `ORCH · <version>` and name its agent, give it the mission and these rules verbatim, then supervise it. Do not drive a duplicate single-tier run yourself. Before spawning, confirm any PREVIOUS orchestrator has [stood down](#stand-down-mission-end-and-retirement) and close its tab.
+- **Primary session without an orchestrator:** rename your own tab `OVERSEER · <version>` and your agent `overseer`, spawn one child orchestration session with your host's launch form, label its tab `ORCH · <version>` and name its agent, give it the mission and these rules verbatim, then supervise it. Do not drive a duplicate single-tier run yourself. Before spawning, confirm any PREVIOUS orchestrator has [stood down](#stand-down-mission-end-and-retirement) and close its tab.
+  - **Claude Code:** `herdr agent start orchestrator --cwd <repo> --no-focus -- claude --permission-mode bypassPermissions`
+  - **Codex:** `herdr agent start orchestrator --cwd <repo> --no-focus -- codex --ask-for-approval never --sandbox workspace-write`
 
 Outside a multi-agent terminal environment, run the loop directly.
 

package/skills/tickmarkr-overseer/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: tickmarkr-overseer
+description: "Use when the user asks to oversee/supervise/babysit an autonomous tickmarkr run in a Herdr workspace (e.g. '/tickmarkr-overseer run the milestone', 'supervise this tickmarkr run', 'babysit this pipeline'). Requires HERDR_ENV=1. The skill argument is the mission (what to run end-to-end)."
+---
+
+# Overseer (tickmarkr)
+
+Become the OVERSEER for this workspace. Do no heavy work directly — build and supervise a two-tier
+hierarchy of VISIBLE agents (you → orchestrator → tickmarkr's own worker fleet), and route human decisions
+to the user with evidence.
+
+The mission is the skill argument. If empty, ask the user what to run end-to-end before doing anything else.
+Requires `HERDR_ENV=1`; if unset, say so and stop.
+
+## Setup
+
+0. **Adopt before you build.** If this workspace already has a supervision hierarchy — an
+   OVERSEER/ORCHESTRATOR tab, a live agent named `*orch*`, or a `<repo>/<state-dir>/overseer/` dir
+   (state dir = `.tickmarkr/`; legacy standalone `<repo>/.overseer/` counts
+   too) — do NOT spawn a duplicate (two orchestrators risk two concurrent tickmarkr runs in one repo,
+   which tickmarkr forbids). Read that dir's `DECISIONS.md` + `ORCH-BRIEF.md`, check the existing agents'
+   status, and either ADOPT the
+   existing orchestrator (updated brief, re-armed watchers) or, if the old hierarchy is dead, archive the
+   stale brief and build fresh.
+1. Load the `herdr` skill. `herdr pane list` to map the workspace — the focused pane is yours. Rename your
+   tab OVERSEER; create ONE tab ORCHESTRATOR.
+   **Live tab labels (standing operator rule, 2026-07-12):** on every decision or state change (role
+   handoff, task done/merged, run end) rename the affected tabs — and keep labels SHORT: the role as the
+   main name plus at most ONE hot-state token. Vocabulary: ORCH carries the milestone and progress
+   fraction (`ORCH · v1.19 4/5`, updated on every task-done); WORKERS carries the task token (tickmarkr
+   updates it). Never long context strings or ✓-chains.
+2. **Orchestrator**: Launch the orchestrator with your agent host. For Claude Code, use `herdr agent start orchestrator --cwd <repo> --no-focus -- claude --permission-mode bypassPermissions` (pin a strong model with `--model <m>` if the operator has a policy). For Codex, use `herdr agent start orchestrator --cwd <repo> --no-focus -- codex --ask-for-approval never --sandbox workspace-write` (add `--model <m>` to specify the model). Workers you never spawn — tickmarkr spawns its own visible worker panes.
+3. **Standing instructions travel as a brief FILE, never as pane text** — PTY input truncates at ~1024B and a
+   truncated brief silently drops policy. Write the full brief to `<repo>/.tickmarkr/overseer/ORCH-BRIEF.md`
+   (inside the tickmarkr state dir — already self-gitignored, no exclude step needed), then send one line:
+   `herdr pane run <orch> "Read .tickmarkr/overseer/ORCH-BRIEF.md and follow it exactly."` The brief MUST contain: the
+   mission, the pane mechanics below, rules 1–2, and require a verbatim one-sentence acknowledgment of the
+   human-checkpoint rule before anything is dispatched. Delete the dir at mission end.
+4. Arm the watcher (Supervision). Report the hierarchy map (pane ids + names) to the user.
+
+## Supervising tickmarkr as the executor
+
+When the mission runs `/tickmarkr-auto` (tickmarkr dispatches the workers), supervision changes shape:
+
+- **Give the run a live surface.** `tickmarkr run` is stdout-silent until run-end by design — split a pane in the
+  ORCHESTRATOR tab running `tickmarkr status --watch`. Narration also arrives as herdr notifications.
+- **Watch the journal, not the panes.** The append-only journal
+  (`.tickmarkr/runs/<runId>/journal.jsonl`) is the
+  source of truth. Arm a background watcher on `run-end` / `task-human` / `task-failed` / `consult-verdict`
+  events; never sleep-poll inside an agent turn.
+- **Daemon liveness ≠ journal activity.** A dead daemon emits no events, so journal watchers sleep through
+  its death. `tickmarkr status` prints last-event age + daemon pid liveness; check it before diagnosing a stall.
+  Recovery is `tickmarkr resume <runId>` — crash-safe by design (journal replay restores attempt counts and
+  consult channel bans).
+- **Gate quiet ≠ idle.** Between `worker-result` and the batched `gate-result`s tickmarkr runs shell gates plus a
+  headless LLM judge/review with little visible signal — check the journal timestamps before intervening.
+- **Classify gate failures before reacting.** The same fingerprint failing across DIFFERENT workers, or a
+  scope/test catch-22 (attempt N edits a file → scope gate fails; attempt N+1 leaves it → test gate fails),
+  is a PLAN defect: widen `files_modified` in the phase PLAN, recompile the phase dir after the run ends or
+  the task parks, release (`human → pending`), resume. A cross-vendor review rejection with concrete findings
+  is a REAL defect — let the escalation ladder work.
+- **Dialog watchers go stale per attempt.** Every retry/escalation may spawn a new pane; re-arm dialog
+  watchers on each `task-dispatch` journal event.
+
+## Pane mechanics that bite
+
+- **Verified send protocol**: `herdr agent send` writes WITHOUT Enter, and `pane run`'s Enter can be swallowed
+  by bracketed-paste on long payloads. Robust sequence: read the pane (bare prompt required) → send-text →
+  sleep 2–3s → send-keys Enter → read back (input empty / agent `working`). Never report "briefed" without
+  the read-back. Long content goes in a brief file, never pane text.
+- **Guard-before-Enter** (race-safe prompt answering): chain with `&&` — pane get shows `blocked` && pane
+  read shows the expected option under the cursor && only then send-keys. If no longer `blocked`, someone
+  already answered; do nothing.
+- `herdr wait agent-status` exits 1 on timeout, 0 on match — but ALSO 0 (with an error JSON) when the pane is
+  GONE. Never chain `wait && act` without confirming the pane exists.
+- Stale typed input is unclearable via CLI — supersede it:
+  `pane run "<-- disregard everything before this arrow (stale draft). ACTUAL: <message>"`.
+
+## Supervision watcher
+
+Arm the bundled watcher as its OWN Bash call with `run_in_background` — chaining it after other commands
+with `&` orphans it from the wake chain. It prints one wake reason and exits; re-arm after every wake.
+
+```bash
+.claude/skills/tickmarkr-overseer/scripts/watch-panes.sh WORKER_PANE ORCH_PANE [--fast-blocked]
+```
+
+Default mode wakes only when both panes are quiet (dropped handoff) or the orchestrator blocks; the
+orchestrator gets a 90s grace window to handle worker blocks first. For long parked stretches a targeted
+`herdr wait agent-status <pane> --status <s> --timeout <ms>` beats the watcher. When parking a human
+checkpoint, also fire `herdr notification show "HUMAN CHECKPOINT: <gate>" --sound request`.
+
+## Specialist pipeline rules
+
+- **Dedicated consultant tab**: Consultants (agents spawned to gather synthesis input for decisions like SCOPER analysis or architectural reviews) must run in a DEDICATED tab separate from the ORCHESTRATOR tab. When the orchestrator stands down, the consultant panes should persist so their assessments remain available for review and reference.
+- **Scoper worktree rule**: The SCOPER (or any worktree-based specialist synthesizing into the spec pipeline) must do ALL git operations in a dedicated worktree (e.g., `git worktree add /private/tmp/tkr-scoper-v155 -b spec/...`), never switching the main checkout's branch. This prevents race conditions between the specialist's branch operations and the orchestrator's shipping logic.
+
+## Non-negotiable rules
+
+1. **Takeover rule**: only act on a worker if it needs input AND the orchestrator is not `working`.
+2. **Human checkpoints (absolute)**: any gate marked `autonomous: false` or asking for product/visual
+   sign-off is NEVER auto-answered — regardless of how obviously correct the highlighted option looks. Leave
+   it blocked and bring the user the decision WITH evidence. If the mission explicitly delegates authority,
+   routine-class gates may be overseer-decided after polling the operator first — but spend and ship gates
+   NEVER self-decide.
+3. **Trust disk over transcripts**: verify artifacts on disk before building on them; a subagent killed
+   mid-flight still renders "Done" without writing its artifact.
+4. **Report concisely on every state change**: what happened, who handled it, what's next. Lead with the
+   outcome. Surface product decisions; never make them.
+5. **Log every abnormality** to `.planning/OBSERVATIONS.md` (or the project's ledger), even mid-run.

package/skills/tickmarkr-overseer/scripts/watch-panes.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# watch-panes.sh — Herdr overseer watcher.
+# Polls worker + orchestrator agent_status via `herdr pane get`, prints ONE wake
+# reason to stdout, then exits. Run it via the Bash tool with run_in_background
+# so the overseer is re-invoked when it fires. Re-run (re-arm) after every wake.
+#
+# Usage:
+#   watch-panes.sh WORKER_PANE ORCH_PANE [--fast-blocked] [--cap-seconds N] [--settle-seconds N]
+#
+# Options:
+#   --fast-blocked     Wake fast (20s debounce) whenever the WORKER blocks, even
+#                      if the orchestrator is working. Use during stretches with
+#                      human checkpoints. Without it, a blocked worker gets a 90s
+#                      grace window for the orchestrator to handle it first
+#                      (takeover rule), and only wakes if BOTH panes are quiet.
+#   --cap-seconds N    Max watch duration (default 14400 = 4h).
+#   --settle-seconds N Initial sleep before polling (default 60) so a
+#                      just-dispatched turn can start without an instant refire.
+#
+# Wake reasons printed:
+#   WORKER_PANE_GONE / ORCH_PANE_GONE   — a pane disappeared
+#   ORCH:blocked WORKER:<s>             — orchestrator itself needs input
+#   WORKER:blocked ORCH:<s>             — worker blocked (fast-blocked mode)
+#   WORKER:<s> ORCH:<s>                 — both quiet: dropped handoff / done
+#   WATCH_CAP_REACHED ...               — cap hit, everything still working
+set -u
+WORKER="${1:?worker pane id required}"
+ORCH="${2:?orchestrator pane id required}"
+shift 2
+FAST_BLOCKED=false
+CAP=14400
+SETTLE=60
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --fast-blocked) FAST_BLOCKED=true ;;
+    --cap-seconds) CAP="$2"; shift ;;
+    --settle-seconds) SETTLE="$2"; shift ;;
+  esac
+  shift
+done
+
+get_status() {
+  herdr pane get "$1" 2>/dev/null | python3 -c '
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    p = d.get("result", {}).get("pane", d.get("result", {}))
+    print(p.get("agent_status", "unknown"))
+except Exception:
+    print("gone")
+' 2>/dev/null || echo gone
+}
+
+# Transient CLI/server failures also read as "gone" — recheck before declaring.
+confirmed_gone() {
+  sleep 5
+  [ "$(get_status "$1")" = "gone" ]
+}
+
+END=$((SECONDS + CAP))
+sleep "$SETTLE"
+while [ $SECONDS -lt $END ]; do
+  WS=$(get_status "$WORKER")
+  OS=$(get_status "$ORCH")
+  if [ "$WS" = "gone" ]; then
+    confirmed_gone "$WORKER" && { echo "WORKER_PANE_GONE ORCH:$(get_status "$ORCH")"; exit 0; }
+    continue
+  fi
+  if [ "$OS" = "gone" ]; then
+    confirmed_gone "$ORCH" && { echo "ORCH_PANE_GONE WORKER:$(get_status "$WORKER")"; exit 0; }
+    continue
+  fi
+  # orchestrator itself stuck on a prompt (debounced)
+  if [ "$OS" = "blocked" ]; then
+    sleep 15
+    [ "$(get_status "$ORCH")" = "blocked" ] && { echo "ORCH:blocked WORKER:$WS"; exit 0; }
+  fi
+  # human-checkpoint mode: wake fast on any persisting worker block
+  if $FAST_BLOCKED && [ "$WS" = "blocked" ]; then
+    sleep 20
+    [ "$(get_status "$WORKER")" = "blocked" ] && { echo "WORKER:blocked ORCH:$(get_status "$ORCH")"; exit 0; }
+  fi
+  # standard mode: worker needs attention AND orchestrator is not driving
+  if [ "$WS" != "working" ]; then
+    sleep 90
+    WS2=$(get_status "$WORKER"); OS2=$(get_status "$ORCH")
+    if [ "$WS2" != "working" ] && [ "$OS2" != "working" ]; then
+      echo "WORKER:$WS2 ORCH:$OS2"; exit 0
+    fi
+  fi
+  sleep 20
+done
+echo "WATCH_CAP_REACHED WORKER:$(get_status "$WORKER") ORCH:$(get_status "$ORCH")"