tickmarkr 1.46.0 → 1.48.0

package/dist/route/profile.js

@@ -59,10 +59,11 @@ export function resolveHygieneWeight(row, discounts = []) {
 // yielded no quality obs (quota parks) has spent its budget — stop probing it, don't probe it forever.
 // ponytail: rank-decay ships in v1.8 (buildProfile below); remaining ceiling = doneMedianMs staleness
 // (perf term is undecayed) and per-cell EWMA as the finer upgrade path.
-export function explorationBonus(cell) {
+// ROUTE-15 PARAM-SHAPE: optional cap threads from routing.explore.cap; undefined ⇒ module default (byte-identical).
+export function explorationBonus(cell, cap = EXPLORE_CAP) {
     if (!cell)
         return 0;
-    return Math.max(0, 1 - cell.dispatches / EXPLORE_CAP); // ∈ [0,1]; exactly 0 once dispatches ≥ cap
+    return Math.max(0, 1 - cell.dispatches / cap); // ∈ [0,1]; exactly 0 once dispatches ≥ cap
 }
 const QUALITY_FAIL_PARKS = new Set(["ladder-exhausted", "attempt-cap", "gate-fail"]);
 // Quality observation per row: 1 clean, 0.5 degraded, 0 verified failure, null excluded/unobserved.
@@ -183,6 +184,7 @@ export function cellSummary(cell) {
 // Per-term decomposition of learnedScore — the single arithmetic source for profile --explain.
 export function learnedScoreTerms(profile, shape, chKey, channel, opts = {}) {
     const availWeight = opts.availWeight ?? AVAIL_WEIGHT;
+    const refMs = opts.slaMinutes !== undefined ? opts.slaMinutes * 60_000 : REF_MS;
     const cell = cellOf(profile, shape, chKey, channel);
     if (!cell)
         return { quality: NEUTRAL, perf: NEUTRAL, avail: NEUTRAL, overrun: NEUTRAL };
@@ -198,7 +200,7 @@ export function learnedScoreTerms(profile, shape, chKey, channel, opts = {}) {
     // 0 — a silent ROUTE-07 break. With it, every quotaHits=0 cell is byte-identical to pre-ROUTE-12.
     const perf = cell.n < MIN_SAMPLES || cell.doneMedianMs === undefined || cell.doneCount < MIN_SAMPLES
         ? 0
-        : PERF_WEIGHT * (REF_MS / (REF_MS + cell.doneMedianMs) - 0.5);
+        : PERF_WEIGHT * (refMs / (refMs + cell.doneMedianMs) - 0.5);
     // PENALTY-ONLY availability (ROUTE-12): a throttling channel is less available — deprioritize it without ever
     // treating quota as a quality signal, ejecting it, or predicting quota. quotaHits=0 ⇒ avail 0 (no-throttle
     // byte-identity). Gated on dispatches (≥ MIN_SAMPLES > 0 ⇒ positive denominator, no divide-by-zero) INDEPENDENTLY

package/dist/route/router.d.ts

@@ -1,5 +1,5 @@
 import { type Assignment, type BillingChannel } from "../adapters/types.js";
-import { type TickmarkrConfig } from "../config/config.js";
+import { type TickmarkrConfig, type Tier } from "../config/config.js";
 import type { Task } from "../graph/schema.js";
 import { type RoutingProfile } from "./profile.js";
 export type LadderStep = "retry" | "escalate" | "consult" | "human";
@@ -26,9 +26,16 @@ export interface RoutingPreferContext {
     doctorFresh: boolean;
     overlayPreferShapes: ReadonlySet<string>;
 }
+export interface ExploreContext {
+    noExplore?: boolean;
+    quality?: boolean;
+}
+export declare const NO_EXPLORE_ENV = "TICKMARKR_NO_EXPLORE";
+export declare const QUALITY_ENV = "TICKMARKR_QUALITY";
+export declare const raiseTier: (tier: Tier) => Tier;
 export declare class RoutingError extends Error {
     constructor(msg: string);
 }
 export declare function marginalCostRank(c: BillingChannel): number;
-export declare function route(task: Task, cfg: TickmarkrConfig, channels: BillingChannel[], profile?: RoutingProfile, preferCtx?: RoutingPreferContext, exclude?: ReadonlySet<string>): Route;
+export declare function route(task: Task, cfg: TickmarkrConfig, channels: BillingChannel[], profile?: RoutingProfile, preferCtx?: RoutingPreferContext, exclude?: ReadonlySet<string>, exploreCtx?: ExploreContext): Route;
 export declare function nextChannel(current: Assignment, task: Task, cfg: TickmarkrConfig, channels: BillingChannel[], tried: string[], profile?: RoutingProfile, exclude?: ReadonlySet<string>): Assignment | null;

package/dist/route/router.js

@@ -1,7 +1,27 @@
 import { channelKey, channelsFromConfig } from "../adapters/types.js";
 import { TIER_RANK } from "../config/config.js";
 import { disallowedBy } from "./preference.js";
-import { cellOf, EXPLORE_CAP, explorationBonus, learnedScore } from "./profile.js";
+import { cellOf, EXPLORE_CAP, explorationBonus, learnedScore, MIN_SAMPLES } from "./profile.js";
+export const NO_EXPLORE_ENV = "TICKMARKR_NO_EXPLORE";
+export const QUALITY_ENV = "TICKMARKR_QUALITY";
+const exploreCap = (cfg) => cfg.routing.explore?.cap ?? EXPLORE_CAP;
+const qualityOn = (exploreCtx) => !!exploreCtx?.quality || process.env[QUALITY_ENV] === "1";
+export const raiseTier = (tier) => tier === "cheap" ? "mid" : tier === "mid" ? "frontier" : "frontier";
+const exploreOff = (task, cfg, exploreCtx) => {
+    if (qualityOn(exploreCtx) || exploreCtx?.noExplore || process.env[NO_EXPLORE_ENV] === "1")
+        return true;
+    const e = cfg.routing.explore;
+    if (!e)
+        return false;
+    if (e.mode === "off")
+        return true;
+    if (e.excludeShapes?.includes(task.shape))
+        return true;
+    const thr = e.excludeComplexityAtOrAbove;
+    if (thr != null && task.complexity >= thr)
+        return true;
+    return false;
+};
 const autoPreferList = (doc, shape) => {
     const v = doc?.[shape];
     return Array.isArray(v) ? v : undefined;
@@ -50,10 +70,36 @@ function withoutExcluded(channels, exclude) {
     // OBS-57: in-run demotion after consecutive no-trailer windows — route around poisoned channels for the rest of the run.
     return channels.filter((c) => !exclude.has(channelKey(c)));
 }
-export function route(task, cfg, channels, profile, preferCtx, exclude) {
+const qualityBound = (quality, configFloor, taskFloor) => {
+    if (!quality)
+        return undefined;
+    if (configFloor)
+        return `floor ${configFloor}→${raiseTier(configFloor)} (--quality)`;
+    if (taskFloor)
+        return `floor ${taskFloor}→${raiseTier(taskFloor)} (--quality)`;
+    return undefined;
+};
+const maybeSlaLint = (lints, task, profile, slaMinutes, c) => {
+    if (slaMinutes === undefined || !profile)
+        return;
+    const cell = cellOf(profile, task.shape, channelKey(c), c.channel);
+    if (!cell?.doneMedianMs || cell.doneCount < MIN_SAMPLES)
+        return;
+    const slaMs = slaMinutes * 60_000;
+    if (cell.doneMedianMs <= slaMs)
+        return;
+    const medianMin = Math.round(cell.doneMedianMs / 60_000);
+    lints.push(`${task.id} (${task.shape}): median ${medianMin}m exceeds sla ${slaMinutes}m — learned perf term references sla ${slaMinutes}m ref`);
+};
+export function route(task, cfg, channels, profile, preferCtx, exclude, exploreCtx) {
     channels = withoutExcluded(channels, exclude);
     const lints = [];
-    const floor = cfg.routing.floors[task.shape];
+    const advisoryFloor = cfg.routing.floors[task.shape];
+    const quality = qualityOn(exploreCtx);
+    const floor = advisoryFloor;
+    const slaMinutes = cfg.routing.sla?.[task.shape];
+    // ponytail: sla is plan-time advisory only — never thread into learnedScore (would reroute warm rivals).
+    const scoreOpts = { availWeight: cfg.routing.learnedTuning?.availWeight };
     const entry = cfg.routing.map[task.shape];
     const prefer = effectivePrefer(task.shape, entry, preferCtx);
     const prefActive = !!(cfg.routing.allow || cfg.routing.deny);
@@ -83,11 +129,12 @@ export function route(task, cfg, channels, profile, preferCtx, exclude) {
         }
     };
     const lintFloor = (tier, what) => {
-        if (floor && TIER_RANK[tier] < TIER_RANK[floor]) {
-            lints.push(`${task.id} (${task.shape}): ${what} routes ${tier}, below advisory floor ${floor}`);
+        if (advisoryFloor && TIER_RANK[tier] < TIER_RANK[advisoryFloor]) {
+            lints.push(`${task.id} (${task.shape}): ${what} routes ${tier}, below advisory floor ${advisoryFloor}`);
         }
     };
-    const taskFloor = task.routingHints?.floor;
+    const taskFloorRaw = task.routingHints?.floor;
+    const taskFloor = taskFloorRaw && quality ? raiseTier(taskFloorRaw) : taskFloorRaw;
     const source = task.routingHints?.source;
     const src = source ? `, ${source}` : ""; // never interpolate a possibly-undefined source
     // task pin: planner-authored, try-first — degrades on miss or below-floor (D-05, research A3), never throws
@@ -98,6 +145,7 @@ export function route(task, cfg, channels, profile, preferCtx, exclude) {
         const c = channels.find((c) => c.adapter === taskPin.via && c.model === taskPin.model);
         if (c && (!taskFloor || TIER_RANK[c.tier] >= TIER_RANK[taskFloor])) {
             lintFloor(c.tier, "task pin");
+            maybeSlaLint(lints, task, profile, slaMinutes, c);
             return { assignment: toAssignment(c), ladder: ladderFor(task, entry), lints, provenance: `pin ${taskPin.via}:${taskPin.model} (task hint${src})` };
         }
         const why = c ? `below task floor ${taskFloor}` : "unavailable";
@@ -109,10 +157,16 @@ export function route(task, cfg, channels, profile, preferCtx, exclude) {
         disallowedPin(entry.pin.via, entry.pin.model, "map pin (config routing.map)");
         const c = resolvePin(entry.pin, channels);
         lintFloor(c.tier, "map pin");
+        maybeSlaLint(lints, task, profile, slaMinutes, c);
         return { assignment: toAssignment(c), ladder: ladderFor(task, entry), lints, provenance: `${degraded}pin ${entry.pin.via}:${entry.pin.model} (config routing.map)` };
     }
     const baseTier = entry?.tier ?? floor ?? "cheap";
-    const minTier = taskFloor && TIER_RANK[taskFloor] > TIER_RANK[baseTier] ? taskFloor : baseTier; // task floor is a hard >= constraint in all paths (D-04)
+    let minTier = taskFloor && TIER_RANK[taskFloor] > TIER_RANK[baseTier] ? taskFloor : baseTier; // task floor is a hard >= constraint in all paths (D-04)
+    if (quality && advisoryFloor) {
+        const raised = raiseTier(advisoryFloor);
+        if (TIER_RANK[raised] > TIER_RANK[minTier])
+            minTier = raised;
+    }
     if (entry?.tier)
         lintFloor(entry.tier, "map tier");
     if (prefActive)
@@ -145,13 +199,15 @@ export function route(task, cfg, channels, profile, preferCtx, exclude) {
         // is keyed by channelKey alone, which would collide only if a fleet exposed the same adapter:model on
         // both classes at once — impossible under today's scalar TierEntrySchema.channel.
         // ROUTE-15: availWeight threads from config as a pure param; undefined ⇒ module default (byte-identical).
-        const scores = new Map(eligibleRaw.map((c) => [channelKey(c), learnedScore(profile, task.shape, channelKey(c), c.channel, { availWeight: cfg.routing.learnedTuning?.availWeight })]));
+        const scores = new Map(eligibleRaw.map((c) => [channelKey(c), learnedScore(profile, task.shape, channelKey(c), c.channel, scoreOpts)]));
         const scoreOf = (c) => scores.get(channelKey(c));
         // v1.6 Phase 14: exploration bonus precomputed ONCE (Pitfall 5), a new key ABOVE the score. EXP-01 needs
         // it above the score (a warm-good incumbent can't permanently outrank an under-cap rival in a static tie);
         // magnitude-free as its own lexicographic key. EXP-02 holds structurally: pins returned at :67/:78 and the
         // floor filtered eligibleRaw at :89, all upstream of this block, so the bonus decides only within a static tie.
-        const bonuses = new Map(eligibleRaw.map((c) => [channelKey(c), explorationBonus(cellOf(profile, task.shape, channelKey(c), c.channel))]));
+        const cap = exploreCap(cfg);
+        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];
         // Phase 34 ROUTE-17: prefer becomes a BAND + group-rep keys so exploration fires ACROSS prefer
@@ -182,7 +238,7 @@ export function route(task, cfg, channels, profile, preferCtx, exclude) {
         const diffKey = ru ? firstDiff(w, ru) : -1;
         const probe = diffKey === 1 || diffKey === 6;
         if (probe) {
-            learnedChosen = `via exploration probe (dispatches=${cellOf(profile, task.shape, channelKey(w), w.channel)?.dispatches ?? 0} < ${EXPLORE_CAP})`;
+            learnedChosen = `via exploration probe (dispatches=${cellOf(profile, task.shape, channelKey(w), w.channel)?.dispatches ?? 0} < ${cap})`;
         }
         else if (diffKey === 2 || diffKey === 7) {
             const n = cellOf(profile, task.shape, channelKey(w), w.channel)?.n ?? 0;
@@ -195,10 +251,11 @@ export function route(task, cfg, channels, profile, preferCtx, exclude) {
     else {
         eligible = eligibleRaw.sort(staticCmp); // ROUTE-07/09: literally the v1.5 code path — dead code cannot deviate
     }
-    const bound = taskFloor && TIER_RANK[taskFloor] >= TIER_RANK[baseTier] ? `floor ${taskFloor} (task hint${src})` :
-        entry?.tier ? `tier ${entry.tier} (config routing.map)` :
-            floor ? `floor ${floor} (config floors)` :
-                "tier cheap (default)";
+    const bound = qualityBound(quality, advisoryFloor, taskFloorRaw) ??
+        (taskFloor && TIER_RANK[taskFloor] >= TIER_RANK[baseTier] ? `floor ${taskFloor} (task hint${src})` :
+            entry?.tier ? `tier ${entry.tier} (config routing.map)` :
+                floor ? `floor ${floor} (config floors)` :
+                    "tier cheap (default)");
     // name the key that actually broke the tie: prefer outranks the marginal-cost/tier keys, so if the
     // winner matched a prefer entry, prefer decided it — not "cheapest sufficient tier" (ROUTE-03, WR-01)
     const preferVia = preferFromAuto(task.shape, preferCtx)
@@ -206,6 +263,7 @@ export function route(task, cfg, channels, profile, preferCtx, exclude) {
         : "via prefer";
     const chosenBy = learnedChosen || (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 } : {}) };
 }
 export function nextChannel(current, task, cfg, channels, tried, profile, exclude) {

package/dist/run/daemon.js

@@ -427,7 +427,7 @@ export async function runDaemon(repoRoot, opts = {}) {
                 const promptFile = writePrompt(journal.dir, t, attempt, feedback, nonce);
                 // OBS-56: state the non-interactive, one-pass finish contract and the OBS-54 stall budget in every
                 // worker prompt, not only consult retry guidance. Prepended so prompt.ts's completion trailer stays last.
-                const workerContract = `## Harness contract\n- This harness is non-interactive: make one continuous pass; do not stop for questions or follow-up input.\n- You have a ${taskTimeoutMinutes} minute stall window. Budget the full suite once, then commit and emit the completion trailer before it expires.`;
+                const workerContract = `## Harness contract\n- This harness is non-interactive: make one continuous pass; do not stop for questions or follow-up input.\n- You have a ${taskTimeoutMinutes} minute stall window. Budget the full suite once, then commit and emit the completion trailer before it expires.\n- Each test: acceptance criterion must exist as a vitest test whose title matches the criterion string verbatim.`; // OBS-64
                 // OBS-47: state the worktree layout contract in the worker prompt (cheap-tier workers were
                 // committing/deleting node_modules and tripping the scope gate). The harness re-asserts the link
                 // itself before gates regardless of what the worker does with it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tickmarkr",
-  "version": "1.46.0",
+  "version": "1.48.0",
   "description": "Spec in, verified work out.",
   "type": "module",
   "license": "MIT",

package/skills/tickmarkr-auto/SKILL.md

@@ -14,7 +14,7 @@ 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) 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 `--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.
 
 Outside a multi-agent terminal environment, run the loop directly.
 
@@ -60,7 +60,7 @@ After sending, **confirm delivery** by reading the target pane and verifying the
 1. **Prepare** — confirm the target list. Run the [binary preflight](#binary-preflight-before-compile-or-run). Check `git status`, confirm no tickmarkr run is active, and work from a non-main branch.
 2. **Compile** — run `tickmarkr compile <spec-or-directory>`. Fix source-spec defects instead of editing the generated graph.
 3. **Plan** — run `tickmarkr plan`. Review routes, capability-floor warnings, and human gates before execution.
-4. **Run** — run `tickmarkr run`. Watch the run journal for its terminal event rather than polling agents. Resolve blocked interactions in the relevant agent session.
+4. **Run** — run `tickmarkr run`. Watch the run journal for its terminal event rather than polling agents — a self-terminating poll (`until grep -q '"event":"run-end"' <state-dir>/runs/<runId>/journal.jsonl; do sleep 20; done`), never `tail -F | grep -m1` (wedges on the journal's final line) and never a pane-level done wait (turn-end flaps). Resolve blocked interactions in the relevant agent session.
 5. **Verify and consolidate** — continue only after a green run. A run is green when the run-end event exists in the journal AND the tip verify is not "failed". Tickmarkr consolidates accepted work on `tickmarkr/<runId>` and never signs off to the main branch. A human controls any later release merge.
 6. **Record** — write `tickmarkr report <runId> --md` beside the source spec and commit the execution record when the repository tracks those records.
 7. **Continue** — move to the next requested target. If a target fails or is parked, stop with the journal evidence rather than silently skipping it.

package/skills/tickmarkr-loop/SKILL.md

@@ -53,13 +53,13 @@ After sending, **confirm delivery** by reading the target pane and verifying the
 ## Stand-down (mission end and retirement)
 
 - **Orchestrator, on terminal state** (green, failed, or parked), after the record commit and operator notification: stop every monitor and background task you started, print one final stand-down line, and leave NOTHING queued in your input box. A finished session with an armed watcher or pre-filled input is a loaded gun — a retired v1.40 orchestrator sat idle with "merge … tag, publish" unsent in its input; one stray Enter would have shipped a duplicate release.
-- **Supervisor, when a mission completes** (and always before spawning the next orchestrator): verify the orchestrator stood down, then close its tab. The journal, execution record, OBS ledger, and memory hold the story; pane scrollback is disposable. Never leave a retired agent idle with watchers armed.
+- **Supervisor, when a mission completes** (and always before spawning the next orchestrator): verify the orchestrator stood down, then close its tab. Seeming input-box text in a retired pane can be the TUI's dim ghost-text suggestion, not queued input — confirm with an ANSI read (dim escape around the text) or type-one-char-and-read-back before treating it as the loaded gun; close the tab either way. The journal, execution record, OBS ledger, and memory hold the story; pane scrollback is disposable. Never leave a retired agent idle with watchers armed.
 
 ## The loop
 
 1. **Prepare** — start from the requested spec. Run the [binary preflight](#binary-preflight-before-compile-or-run). Check `git status`, confirm no tickmarkr run is active, and work from a non-main branch.
 2. **Compile** — run `tickmarkr compile <spec>`. Correct compilation errors in the spec, never in the generated graph.
 3. **Plan** — run `tickmarkr plan`. Review the routing table, capability-floor warnings, and every human gate, including work that each gate blocks.
-4. **Run** — run `tickmarkr run`. Watch the run journal for its terminal event rather than repeatedly polling agents. Resolve blocked interactions in the agent session; do not turn them into proxy questions.
+4. **Run** — run `tickmarkr run`. Watch the run journal for its terminal event rather than repeatedly polling agents. Use a self-terminating poll — `until grep -q '"event":"run-end"' <state-dir>/runs/<runId>/journal.jsonl; do sleep 20; done` — never `tail -F | grep -m1` (run-end is the journal's last line, so tail never notices the broken pipe and the watcher hangs forever) and never a pane-level done wait (it fires on every agent turn end, not mission end). Resolve blocked interactions in the agent session; do not turn them into proxy questions.
 5. **Verify and consolidate** — accept only a green run. A run is green when the run-end event exists in the journal AND the tip verify is not "failed". Tickmarkr consolidates accepted task work on `tickmarkr/<runId>`; it never signs off to the main branch. A human may later merge that integration branch through the repository's normal release process.
 6. **Record** — write `tickmarkr report <runId> --md` beside the source spec and commit the execution record when the repository tracks those records. Then [stand down](#stand-down-mission-end-and-retirement).