specpi 0.26.0 → 0.28.0

package/extensions/jev-advisor/questions/compaction.mjs

@@ -0,0 +1,153 @@
+// System 1b: guide compaction, which is the one moment the prompt cache is discarded anyway.
+//
+// Pi's `findCutPoint` is documented as "walk backwards from newest, accumulating estimated message
+// sizes, stop when we've accumulated >= keepRecentTokens". It is a token ruler: it cannot tell the
+// load-bearing finding from six dead-end greps, and it discards whichever falls on the wrong side
+// of the line. Since the prefix is being rebuilt regardless, improving that choice costs nothing.
+//
+// This system never sets the cut itself. It supplies `customInstructions` — an existing documented
+// parameter on the compaction path — so the summariser is told what this session was actually
+// about. The token budget still bounds the result, so bad advice can shape a summary, never blow
+// the budget or drop an entry the preparation meant to keep.
+
+import { choice, noul } from "../client.mjs";
+import { choiceValue, nounTrue } from "../gate.mjs";
+import { compact } from "../sanitize.mjs";
+
+export const WORK_KINDS = Object.freeze({
+    debugging: "Tracking down why something fails",
+    building: "Adding or changing a feature",
+    refactoring: "Restructuring code without changing behaviour",
+    research: "Reading and answering questions about a codebase",
+    testing: "Writing or repairing tests",
+    ops: "Builds, releases, configuration or tooling",
+    review: "Reading a diff and judging it",
+});
+
+/**
+ * A digest of what compaction is about to discard: entry kinds and scale, never their text. The
+ * summariser still sees the real conversation; this only steers what it keeps.
+ */
+export function buildInput({ preparation, objective }) {
+    const messages = preparation?.messagesToSummarize ?? [];
+    const kinds = {};
+    for (const message of messages) {
+        const role = typeof message?.role === "string" ? message.role : "unknown";
+        kinds[role] = (kinds[role] ?? 0) + 1;
+    }
+
+    const files = preparation?.fileOps ?? {};
+
+    return {
+        objective: compact(objective ?? "", 180),
+        discarding: messages.length,
+        roles: kinds,
+        tokensBefore: preparation?.tokensBefore ?? 0,
+        splitTurn: preparation?.isSplitTurn === true,
+        filesRead: [...(files.read ?? [])].slice(0, 12).map((item) => compact(item, 60)),
+        filesWritten: [...(files.written ?? []), ...(files.edited ?? [])].slice(0, 12).map((item) => compact(item, 60)),
+        hadPreviousSummary: typeof preparation?.previousSummary === "string",
+    };
+}
+
+/**
+ * The same digest for a branch being left behind. `/tree` hands a different preparation shape --
+ * session entries rather than messages, and no token count, because nothing is being cut to fit a
+ * budget -- so it gets its own builder rather than a compaction input with three fields quietly
+ * reading undefined.
+ */
+export function buildBranchInput({ preparation, objective }) {
+    const entries = preparation?.entriesToSummarize ?? [];
+    const kinds = {};
+    for (const entry of entries) {
+        const kind = typeof entry?.type === "string" ? entry.type : "unknown";
+        kinds[kind] = (kinds[kind] ?? 0) + 1;
+    }
+
+    return {
+        objective: compact(objective ?? "", 180),
+        abandoning: entries.length,
+        kinds,
+        wantsSummary: preparation?.userWantsSummary === true,
+        // Navigating to an ancestor is backing out of a line of work; navigating elsewhere is
+        // moving between siblings. The distinction is most of what a label has to capture.
+        toAncestor: preparation?.targetId === preparation?.commonAncestorId,
+    };
+}
+
+/**
+ * Short, navigational, and a fixed enum so no model-written text reaches the session file. `/tree`
+ * can filter to labelled entries, so a branch that says what it was is the difference between a
+ * navigable tree and a list of timestamps.
+ */
+export const BRANCH_LABELS = Object.freeze({
+    "dead end": "The branch was abandoned because the approach did not work",
+    "alternative tried": "A different approach to the same goal, set aside for another",
+    "work completed": "The branch finished what it set out to do",
+    research: "The branch was reading and answering questions, not changing anything",
+    reverted: "The branch's changes were undone",
+    interrupted: "The branch stopped part-way for an unrelated reason",
+});
+
+export function questions({ branch = false } = {}) {
+    return {
+        ...(branch ? { branch_label: choice("What was this abandoned branch?", BRANCH_LABELS) } : {}),
+        work_kind: choice("What kind of work has this session mostly been doing?", WORK_KINDS),
+        unresolved_thread: noul("There is an unfinished investigation whose findings must survive compaction"),
+        discarded_span_was_dead_ends: noul(
+            "The work being discarded was mostly abandoned attempts that led nowhere useful",
+        ),
+    };
+}
+
+const FOCUS = Object.freeze({
+    debugging: "the symptom, what has been ruled out, and the current hypothesis",
+    building: "what has been implemented so far and what remains",
+    refactoring: "the invariants being preserved and which call sites have been updated",
+    research: "the questions answered so far, with the files each answer came from",
+    testing: "which tests exist, which fail, and why",
+    ops: "the commands run, their outcomes, and the current configuration state",
+    review: "the findings raised so far and their severity",
+});
+
+/**
+ * Build `customInstructions` from gated answers only. With nothing gated this returns undefined and
+ * Pi's own default prompt is used unchanged.
+ */
+/**
+ * The label for a branch summary entry, or undefined when the answer is ungated. Separate from
+ * `decide` because the compaction hook has no label to set and would carry a dead field.
+ */
+export function label(answers) {
+    const value = choiceValue(answers?.branch_label, "compaction");
+
+    return value && Object.hasOwn(BRANCH_LABELS, value) ? value : undefined;
+}
+
+export function decide(answers) {
+    const kind = choiceValue(answers?.work_kind, "compaction");
+    const unresolved = nounTrue(answers?.unresolved_thread, "compaction");
+    const deadEnds = nounTrue(answers?.discarded_span_was_dead_ends, "compaction");
+    const parts = [];
+    if (kind && FOCUS[kind]) {
+        parts.push(`This session has mainly been ${kind}. Prioritise ${FOCUS[kind]}.`);
+    }
+
+    if (unresolved) {
+        parts.push(
+            "An investigation is still open. Preserve its findings and the current hypothesis in full, even at the cost of earlier detail.",
+        );
+    }
+
+    if (deadEnds) {
+        parts.push(
+            "Most of the discarded work was abandoned attempts. Record what was ruled out in one line each rather than recounting them, so the same paths are not retried.",
+        );
+    }
+
+    if (parts.length === 0) {
+        return { customInstructions: undefined, deadEnds, unresolved };
+    }
+
+    return { customInstructions: parts.join(" "), deadEnds, unresolved };
+}

package/extensions/jev-advisor/questions/gap.mjs

@@ -0,0 +1,140 @@
+// System 2: triage a capability-gap report before it is written.
+//
+// This fixes two real defects in the improvement loop rather than saving tokens.
+//
+// Fragmentation: `aggregateEvents` groups by exact `canonicalKey` string, with manual alias
+// decisions as the only correction, and qualification needs `priority >= blocked || occurrences
+// >= 2`. A genuinely recurring problem that the model names differently each time fragments into
+// singletons and can stay permanently unqualified — it never reaches the human at
+// /harness-improvement. Lexical matching cannot fix that; semantic clustering can.
+//
+// Self-reported severity: `priority` sums IMPACT_WEIGHT[event.impact], and `impact` is reported by
+// the model about its own gap. The ranking that decides what a human sees rests on the least
+// reliable field in the record. An independent score is recorded *alongside* it, never over it, so
+// the human still sees what the model claimed.
+//
+// Authority is unchanged. Only an exact human selection through /harness-improvement authorizes a
+// wishlist-sourced change, and nothing here writes a decision.
+
+import { choice, noul, score } from "../client.mjs";
+import { choiceValue, nounTrue, scoreLevel } from "../gate.mjs";
+import { compact } from "../sanitize.mjs";
+
+export const IMPACT_LEVELS = Object.freeze([
+    "Minor: a small inconvenience with an easy workaround",
+    "Moderate: real friction that cost time or forced a detour",
+    "Blocked: the task could not be completed as asked",
+]);
+
+export const FIX_KINDS = Object.freeze({
+    tool: "A new or changed tool would solve it",
+    skill: "A skill or documented procedure would solve it",
+    prompt: "Different instructions would solve it",
+    config: "A configuration or setting change would solve it",
+    bug: "Something is broken and should be repaired",
+    unknown: "Not clear from what was observed",
+});
+
+export const NEW_CLUSTER = "__new__";
+
+/** The Choice ceiling is 255; above the cap, rank by similarity first and choose among the top N. */
+export const MAX_CLUSTER_OPTIONS = 200;
+
+function similarity(a, b) {
+    const left = new Set(
+        String(a)
+            .toLowerCase()
+            .split(/[^a-z0-9]+/u)
+            .filter(Boolean),
+    );
+    const right = new Set(
+        String(b)
+            .toLowerCase()
+            .split(/[^a-z0-9]+/u)
+            .filter(Boolean),
+    );
+    if (left.size === 0 || right.size === 0) {
+        return 0;
+    }
+
+    let shared = 0;
+    for (const token of left) {
+        if (right.has(token)) {
+            shared += 1;
+        }
+    }
+
+    return shared / Math.max(left.size, right.size);
+}
+
+/**
+ * TypeSafe's own two-stage pattern for high cardinality: score candidates cheaply, then make one
+ * explicit choice among the survivors. Below the cap every key is offered.
+ */
+export function clusterOptions(existing, gap) {
+    const keys = [...new Set(existing.map((item) => item.canonicalKey).filter(Boolean))];
+    const probe = `${gap?.capability ?? ""} ${gap?.scenario ?? ""}`;
+    const ranked =
+        keys.length <= MAX_CLUSTER_OPTIONS
+            ? keys
+            : keys
+                  .map((key) => ({ key, rank: similarity(key, probe) }))
+                  .sort((a, b) => b.rank - a.rank)
+                  .slice(0, MAX_CLUSTER_OPTIONS)
+                  .map((item) => item.key);
+
+    const criteria = { [NEW_CLUSTER]: "This is a distinct problem not already on the list" };
+    for (const key of ranked) {
+        const match = existing.find((item) => item.canonicalKey === key);
+        criteria[key] = compact(match?.title ?? key, 90);
+    }
+
+    return criteria;
+}
+
+export function buildInput({ gap, existing = [] }) {
+    return {
+        capability: compact(gap?.capability ?? "", 120),
+        scenario: compact(gap?.scenario ?? "", 200),
+        limitation: compact(gap?.limitation ?? "", 160),
+        workaround: compact(gap?.workaround ?? "", 160),
+        claimedImpact: compact(gap?.impact ?? "", 20),
+        knownProblems: existing.slice(0, 8).map((item) => compact(item.title ?? item.canonicalKey, 60)),
+    };
+}
+
+export function questions({ gap, existing = [] }) {
+    return {
+        cluster: choice(
+            "Which known problem is this the same underlying problem as, if any?",
+            clusterOptions(existing, gap),
+        ),
+        independent_impact: score("How badly did this actually obstruct the task?", IMPACT_LEVELS),
+        suggested_fix: choice("What kind of change would address this?", FIX_KINDS),
+        contains_secret_or_path: noul(
+            "This report contains a credential, an absolute filesystem path, or other machine-specific detail",
+        ),
+        is_transient_or_user_error: noul(
+            "This was a one-off failure or a mistake in how the task was asked, not a reusable gap in the harness",
+        ),
+    };
+}
+
+const IMPACT_NAMES = Object.freeze(["minor", "moderate", "blocked"]);
+
+/**
+ * Advice, in the shape the caller applies it. `blockForSanitization` is the only field that stops
+ * a write, and it stops it to ask the model to rewrite its own text — never to discard the report.
+ */
+export function decide(answers) {
+    const cluster = choiceValue(answers?.cluster, "gap");
+    const level = scoreLevel(answers?.independent_impact, "gap");
+
+    return {
+        canonicalKey: cluster && cluster !== NEW_CLUSTER ? cluster : undefined,
+        independentImpact: level === undefined ? undefined : IMPACT_NAMES[level],
+        suggestedFix: choiceValue(answers?.suggested_fix, "gap"),
+        blockForSanitization: nounTrue(answers?.contains_secret_or_path, "gap"),
+        transient: nounTrue(answers?.is_transient_or_user_error, "gap"),
+    };
+}

package/extensions/jev-advisor/questions/guard.mjs

@@ -0,0 +1,168 @@
+// System 8: score a shell or file call that local rules could not settle, before it runs.
+//
+// This is the native command guard. It replaces the pinned `specpi-jev-guard` package, and the
+// reason it exists rather than that package being configured is that the package's shape kept
+// producing the same class of defect: its configuration was a global file with no session scope, so
+// there was no such thing as enabling it for one session; it read its key from the environment only,
+// so a credential `/login` had stored was invisible to it; and it was fail-closed, so an outage or a
+// missing key turned every shell call in the session into a refusal.
+//
+// Native, all three go away. The switch is `systems.guard` like every other system, so it is
+// session-scoped, budgeted, reported in `/jev status` and toggled by `/jev enable guard`. The key is
+// whatever `key-source.mjs` resolves, which includes Pi's own credential store. And the failure
+// posture is inverted, deliberately:
+//
+//   FAIL OPEN. Jev unreachable, unconfident, out of budget, or without a key means the call goes to
+//   @gotgenes/pi-permission-system exactly as it did before this layer existed.
+//
+// That is the rule the rest of this extension already follows -- "nothing here is ever the reason a
+// tool is blocked" -- and applying it here is not a weakening. The guard sits *in front of* the
+// permission system, which still decides every call it defers. Fail-closed meant an outage stopped
+// work; fail-open means an outage returns policy to the component that owned it anyway. The guard
+// adds blocking for confident, dangerous verdicts, and adds nothing else.
+//
+// What it sends is bounded by sanitize.mjs like every other system: a redacted digest, never the raw
+// environment, and never more than the shared 1 KB budget.
+
+import { score } from "../client.mjs";
+import { THRESHOLDS, scoreLevel } from "../gate.mjs";
+
+/** How a decision was reached, for the ledger and for `/jev status`. */
+export const SOURCES = Object.freeze(["local", "jev", "human", "deferred"]);
+
+/**
+ * One Score, not a Noul.
+ *
+ * A Noul returns a bare probability with no confidence field, and this is the one system whose
+ * action takes a tool call away from the person. Gating that on a number with no reported confidence
+ * is exactly what the calibration work found unreachable elsewhere: without a confidence the gate
+ * either fires on coin flips or never fires at all. A Score reports both, so "confident this is
+ * destructive" and "unsure" are distinguishable, and only the first can block.
+ */
+export function questions(input) {
+    return {
+        risk: score(
+            "Rate how likely this call is to destroy data, exfiltrate a credential, or hand control " +
+                "of the machine to someone else, given what the person asked for. Judge the call as " +
+                "written, not the worst command that shares its first word. Routine development work " +
+                "-- building, testing, installing declared dependencies, editing source, committing -- " +
+                "is not destructive merely because it writes.",
+            [
+                "harmless: reads, or writes only within the project in the ordinary course of the task",
+                "ordinary: changes state the person would expect this task to change",
+                "risky: destroys work, rewrites history, or reaches outside the project, but plausibly intended",
+                "destructive: irreversible loss, credential exposure, or remote code execution that the request does not call for",
+            ],
+        ),
+        intended: score("Rate how well this call matches what the person actually asked for.", [
+            "unrelated",
+            "tangential",
+            "plausible",
+            "clearly what was asked",
+        ]),
+        ...(input?.protected === true
+            ? {
+                  credential: score(
+                      "Rate how likely this write targets a real secret rather than a template, " +
+                          "example, fixture or documentation file that merely looks like one.",
+                      ["template or example", "unclear", "likely a real secret", "certainly a real secret"],
+                  ),
+              }
+            : {}),
+    };
+}
+
+/**
+ * Turn the answers into one of three outcomes.
+ *
+ * `block` needs a confident destructive reading *and* a confident reading that the request does not
+ * account for the call. Both, because the single most likely way to be wrong here is a genuinely
+ * destructive-looking command that the person asked for in as many words -- `rm -rf node_modules`, a
+ * force push to a branch they named. Requiring the intent answer to actively disagree is what keeps
+ * those working.
+ *
+ * "Both" means both, including when the intent answer does not survive its own confidence gate. An
+ * earlier version read a missing intent answer as agreement, which mattered far more than it sounds:
+ * `gate.mjs`'s own calibration records a score coverage near 0.2, so roughly four answers in five are
+ * ungated and a confident risk=3 would have blocked essentially unconditionally -- turning the one
+ * stated safeguard into a clause that almost never applied.
+ *
+ * `ask` is the middle band, and only when there is a human to ask. Without a UI it becomes `defer`,
+ * because a question nobody can answer is a block wearing a friendlier word.
+ *
+ * Everything else defers to the permission system.
+ */
+export function decide(answers, { hasUI = false } = {}) {
+    const risk = answers?.risk;
+    const intended = answers?.intended;
+    if (!risk) {
+        return { action: "defer", source: "deferred", reason: "no answer" };
+    }
+
+    const level = scoreLevel(risk, "guard");
+    const wanted = intended ? scoreLevel(intended, "guard") : undefined;
+
+    // A confident secret verdict blocks on its own: a write to a real credential file is not made
+    // acceptable by having been asked for, and the fixture case is what the question separates.
+    const credential = answers?.credential ? scoreLevel(answers.credential, "guard") : undefined;
+    if (credential === 3) {
+        return { action: "block", source: "jev", reason: "writes a real credential file" };
+    }
+
+    if (level === 3 && wanted !== undefined && wanted <= 1) {
+        return { action: "block", source: "jev", reason: "destructive and not what was asked for" };
+    }
+
+    if (level === 3 || level === 2) {
+        return hasUI
+            ? { action: "ask", source: "human", reason: level === 3 ? "destructive" : "risky" }
+            : { action: "defer", source: "deferred", reason: "no interface to ask" };
+    }
+
+    return { action: "defer", source: "deferred", reason: "below the bar" };
+}
+
+/** The two answers the guard's confirmation dialog offers, in the order it offers them. */
+export const CHOICES = Object.freeze({ run: "Run it", block: "Block it" });
+
+/**
+ * Whether a human's answer to that dialog is consent.
+ *
+ * Only the affirmative is. Escape, a dismissed picker, a host that resolves with nothing and a host
+ * that throws all produce something that is not `CHOICES.run`, and every one of them has to mean
+ * "not approved" -- reaching this point means the verdict already said the call needs a person's
+ * approval, and an unanswerable question resolved as yes is what a confirmation dialog exists to
+ * rule out. It lives here rather than in the handler so that it is a rule with a test, not a
+ * comparison inside a closure no test imports.
+ */
+export function approved(choice) {
+    return choice === CHOICES.run;
+}
+
+/** The gate's own numbers, named so `/jev status` and the tests read the same source. */
+export const GATE = Object.freeze({
+    scoreConfidence: THRESHOLDS.guard.scoreConfidence,
+    boundary: THRESHOLDS.guard.boundary,
+});
+
+/**
+ * The state the question is asked against, bounded like every other system's.
+ *
+ * What the model needs is the call, what the person asked for, and enough recent history to tell a
+ * cleanup step from a first move. What it must not receive is the environment, the file's contents,
+ * or anything the sanitiser has not seen: `buildState` applies the shared redaction and the 1 KB
+ * ceiling, so a long command arrives truncated rather than in full.
+ */
+export function buildInput({ tool, subject, protectedTarget, objective, recent, cwd }) {
+    return {
+        system: "command-guard",
+        tool: String(tool ?? ""),
+        call: String(subject ?? ""),
+        protectedTarget: protectedTarget === true,
+        // Why the call was made matters as much as what it does: the same command is routine in one
+        // task and destructive in another, and the intent question has nothing to weigh without it.
+        objective: String(objective ?? ""),
+        recent: Array.isArray(recent) ? recent.slice(-6).map((item) => `${item.tool}:${item.outcome}`) : [],
+        cwd: String(cwd ?? ""),
+    };
+}

package/extensions/jev-advisor/questions/progress.mjs

@@ -0,0 +1,195 @@
+// System 5: notice that a session has stopped making progress, while it can still be helped.
+//
+// This is the only system aimed at turns rather than at input tokens, and turns are where the money
+// is on the hard tiers. Splitting recorded cost three ways: at tier 3 output is 59% of spend, at
+// tier 4 66%, at tier 5 56%. Output is bought by turns, and every other system here targets
+// input. At tier 4 `specpi-jev` runs cheaper per turn than `specpi-default` -- $0.000538 against
+// $0.000613 -- and costs more per attempt anyway, because it takes 29.4 turns against 24.8.
+//
+// The evidence that turns are wasted rather than merely numerous is in the same runs.
+// `specpi-default` invoked `webqa` 199 times across 30 turns on `t4-browser-triage` and still
+// failed. Pi stock abandoned after two tries and burned the full 600-second timeout on two tier-4
+// tasks, scoring zero both times. A turn costs 4-7 seconds and $0.0005-$0.0011; a Jev call costs
+// about 300ms and $0.0000105. Preventing one timeout pays for roughly two thousand calls.
+//
+// LOCAL STATE FIRST, which is the standing rule and the reason this is affordable. Local state
+// cannot answer "is this session stuck" -- that needs a judgement about whether the work is going
+// anywhere -- but it answers "is that question worth asking", and it answers it cheaply. Nothing is
+// sent unless a repeated tool signature, a run of errors or a stretch of turns without a file
+// change has already made the session look suspicious.
+//
+// It is an append, so it passes the standing cache rule: the line goes on the end of the transcript
+// at a turn boundary and invalidates no prefix. It is written once and never retracted, because
+// retracting it would mean rewriting the thing it was appended to.
+//
+// The plan named `deliverAs: "nextTurn"` for that append. Pi documents that mode as "queued for
+// next user prompt, does not interrupt or trigger anything", and an unattended session has exactly
+// one user prompt -- so a nextTurn message would never arrive, in precisely the case the argument
+// for this system rests on. The caller uses "steer" instead: delivered after the current tool calls
+// finish and before the next model request, which is the same append at the same boundary and is
+// actually read. `triggerTurn` stays off, so this can never add a turn of its own.
+
+import { choice, noul } from "../client.mjs";
+import { choiceValue, nounTrue } from "../gate.mjs";
+import { compact } from "../sanitize.mjs";
+
+/**
+ * The same taxonomy `scripts/jev-triage.mjs` uses offline. It lives here, in the shipped extension,
+ * and the script imports it: the corpus that calibrates this system and the enum this system asks
+ * against have to be the same object, or the published failure-mode distribution is measuring
+ * something the session never asks.
+ */
+export const FAILURE_MODES = Object.freeze({
+    "gave-up-on-fault": "Met an injected command failure and stopped instead of retrying",
+    "turn-cap": "Ran out of turns or requests while still working",
+    timeout: "Exceeded the wall-clock limit",
+    "wrong-approach": "Worked steadily but solved the wrong problem",
+    "misread-requirement": "Produced output that misses a stated requirement",
+    "scope-violation": "Changed files it was told to leave alone",
+    "tool-error-loop": "Repeated the same failing tool call without progress",
+    "harness-error": "The harness itself crashed or could not start",
+    unknown: "Not determinable from what was recorded",
+});
+
+/** Modes a session can still act on. A timeout or a crashed harness is not advice, it is an epitaph. */
+export const ACTIONABLE_MODES = Object.freeze(
+    new Set(["wrong-approach", "misread-requirement", "tool-error-loop", "gave-up-on-fault", "scope-violation"]),
+);
+
+/** Tools whose success means the worktree changed. Used only to decide whether anything happened. */
+export const MUTATING_TOOLS = Object.freeze(
+    new Set(["write", "edit", "multi_edit", "apply_patch", "create_file", "str_replace"]),
+);
+
+/** Turns without a single successful mutation before that counts as a reason to look. */
+export const STALE_TURNS = 4;
+const REPEAT_SIGNATURES = 2;
+const CONSECUTIVE_ERRORS = 3;
+
+/**
+ * Turns to stay quiet after asking. Conditions persist for many turns at a time, so without this
+ * the same unchanged situation is re-asked every turn until the budget runs out.
+ */
+export const ASK_COOLDOWN_TURNS = 4;
+
+/**
+ * A tool call reduced to something comparable. The arguments matter -- reading two different files
+ * twice is work, reading one file twice is a loop -- but their contents do not, so this keeps a
+ * short normalized form rather than the payload.
+ */
+export function signature(toolName, input) {
+    return compact(`${toolName}:${JSON.stringify(input ?? {})}`, 120);
+}
+
+/**
+ * Whether local state alone already justifies the question. Returns the reasons rather than a bare
+ * boolean, because they go into the state as the grounds for asking and a caller logging "asked"
+ * without "why" cannot audit the budget afterwards.
+ *
+ * One reason is not enough, and that is a correction rather than a precaution. The first version
+ * asked whenever any single signal fired, and a live run of `t3-cascade-ledger` spent all twelve
+ * calls of its budget on a session that finished with a score of 0.978. A 120-step repair chain
+ * re-runs the same verification command constantly, so "a tool signature repeated" is its normal
+ * condition, not a symptom. The same is true of "no file written for four turns" during a long
+ * read: a research task looks identical to a stuck one from that signal alone.
+ *
+ * So a repeated call or a quiet stretch must coincide with something else before it is worth
+ * asking about. A run of consecutive errors stands alone, because nothing healthy produces three
+ * failures in a row.
+ */
+export function suspicious(history) {
+    const reasons = [];
+    const signatures = history?.signatures ?? [];
+    const counts = new Map();
+    for (const item of signatures) {
+        counts.set(item, (counts.get(item) ?? 0) + 1);
+    }
+
+    const repeated = [...counts.entries()].filter(([, count]) => count >= REPEAT_SIGNATURES);
+    if (repeated.length > 0) {
+        reasons.push("repeated-tool-call");
+    }
+
+    const errors = (history?.consecutiveErrors ?? 0) >= CONSECUTIVE_ERRORS;
+    if (errors) {
+        reasons.push("consecutive-errors");
+    }
+
+    if ((history?.turnsSinceChange ?? 0) >= STALE_TURNS) {
+        reasons.push("no-file-change");
+    }
+
+    // Conditions persist across turns, so a verdict of "not stuck" is still the right answer three
+    // turns later and asking again buys nothing. The cooldown is what stops one situation being
+    // charged for repeatedly.
+    const cooling = Number.isFinite(history?.askedAtTurn)
+        ? (history.turn ?? 0) - history.askedAtTurn < ASK_COOLDOWN_TURNS
+        : false;
+
+    return {
+        ask: !cooling && (errors || reasons.length >= 2),
+        reasons,
+        repeatedSignatures: repeated.length,
+        cooling,
+    };
+}
+
+/** Shape and counts. No tool output, no file contents, no arguments beyond a normalized signature. */
+export function buildInput({ history, objective, reasons }) {
+    return {
+        objective: compact(objective ?? "", 180),
+        turn: history?.turn ?? 0,
+        reasons,
+        turnsSinceFileChange: history?.turnsSinceChange ?? 0,
+        consecutiveErrors: history?.consecutiveErrors ?? 0,
+        distinctTools: [...new Set((history?.tools ?? []).slice(-12))].slice(0, 12),
+        repeatedCalls: suspicious(history).repeatedSignatures,
+        recentErrors: (history?.errors ?? []).slice(-4).map((item) => compact(item, 80)),
+        filesChanged: history?.filesChanged ?? 0,
+    };
+}
+
+export function questions() {
+    return {
+        // Deliberately two questions rather than one. "Is it stuck" is the decision; "which mode"
+        // is what makes a fixed remedy line possible without any model-written prose.
+        is_stuck: noul("This session has stopped making progress and will not finish without changing approach"),
+        failure_mode: choice("If this session is going to fail, why?", FAILURE_MODES),
+        needs_human: noul("A person would have to answer something before this session could continue"),
+    };
+}
+
+/** One fixed line per mode. Code-written, so nothing the model produced reaches the transcript. */
+const REMEDIES = Object.freeze({
+    "wrong-approach":
+        "Progress check: the last few turns have not moved the task forward. Re-read the objective and state, in one line, what the current approach is meant to achieve before continuing.",
+    "misread-requirement":
+        "Progress check: the work so far may not match what was asked. Re-read the requirements and list which ones are satisfied and which are not, before making further changes.",
+    "tool-error-loop":
+        "Progress check: the same tool call has failed repeatedly. Stop retrying it and either fix the cause or use a different approach.",
+    "gave-up-on-fault":
+        "Progress check: a command failed and was not retried. Transient failures are expected here; retry it before concluding the task cannot be done.",
+    "scope-violation":
+        "Progress check: files outside the permitted scope may have been changed. Check what has been modified against what the task allows.",
+});
+
+/**
+ * The nudge, or nothing. Requires a confident stuck verdict AND a gated mode with a remedy: a
+ * confident "stuck" with no idea why would produce a message that says only that something is
+ * wrong, which is the kind of unfalsifiable hint the standing rule against risk hints rejects.
+ *
+ * `needsHuman` decides who the nudge is for. If the session is blocked on something only a person
+ * can answer -- a missing credential, an ambiguous requirement -- then telling the model to try
+ * harder is the wrong recipient and costs a turn to say nothing. The caller reads it to suppress
+ * the message path while still surfacing the notification.
+ */
+export function decide(answers) {
+    const stuck = nounTrue(answers?.is_stuck, "progress");
+    const mode = choiceValue(answers?.failure_mode, "progress");
+    const needsHuman = nounTrue(answers?.needs_human, "progress");
+    if (!stuck || !mode || !ACTIONABLE_MODES.has(mode) || !REMEDIES[mode]) {
+        return { nudge: undefined, stuck, mode, needsHuman };
+    }
+
+    return { nudge: REMEDIES[mode], stuck, mode, needsHuman };
+}