@intentic/sandbox-contract 1.170.0 → 1.172.0

package/src/chores/verdict.test.ts

@@ -0,0 +1,394 @@
+import type { ChoreLedgerEntry, ChorePackage, ChoresReport, ChoreShape, ChoreSignals, ProbeResult } from "../schemas.js";
+import { describe, expect, test } from "vitest";
+import { choreById, CHORES } from "./chores.js";
+import { assessReport, ledgerKey, unseenVerdicts } from "./verdict.js";
+
+/* The state machine, tested at the distinctions it exists to draw. Every case below is one that a simpler design
+ * gets wrong in a way that costs the surface its credibility: reporting a repository clean that was never
+ * measured, badging the same finding every hour while its fix sits in review, letting a snooze become a
+ * permanent silence, or letting an agent's "these were false positives" be forgotten by the next poll. */
+
+const DAY = 86_400_000;
+const NOW = Date.UTC(2026, 6, 31);
+
+const pkg = (over: Partial<ChorePackage> = {}): ChorePackage => ({
+    dir: `_libs/thing`,
+    name: `@x/thing`,
+    dependencies: [],
+    devDependencies: [],
+    documented: true,
+    ...over,
+});
+
+// A repository that is a Node workspace with documents, a pipeline and an image — so every chore APPLIES by
+// default and each applicability test can turn off exactly the one fact it is about.
+const shape = (over: Partial<ChoreShape> = {}): ChoreShape => ({
+    docs: [`docs/architecture/repo.md`],
+    dockerfiles: [`Dockerfile`],
+    ci: [`.github/workflows/ci.yml`],
+    lockfile: true,
+    packageManifest: true,
+    ...over,
+});
+
+const signals = (over: Partial<ChoreSignals> = {}): ChoreSignals => ({
+    packages: [pkg()],
+    shape: shape(),
+    hotspots: [],
+    keyModules: [],
+    totals: { files: 100, symbols: 1000, complexity: 900, hotspots: 0 },
+    indexed: true,
+    ...over,
+});
+
+const probe = (over: Partial<ProbeResult> & Pick<ProbeResult, "id">): ProbeResult => ({ state: `ok`, ranAt: NOW - DAY, tookMs: 1000, ...over });
+
+const auditProbe = (names: readonly string[]): ProbeResult =>
+    probe({
+        id: `audit`,
+        facts: { id: `audit`, advisories: names.map((name) => ({ name, severity: `high` as const, title: `${name} is bad`, patched: `>=2`, dev: false })) },
+    });
+
+const report = (over: Partial<ChoresReport> = {}): ChoresReport => ({ repos: [{ repo: `app`, probes: [], signals: signals() }], ledger: [], node: `v24.18.0`, ...over });
+
+const verdictFor = (input: ChoresReport, chore: string, repo = `app`) => {
+    const found = assessReport(input, NOW).find((verdict) => verdict.chore.id === chore && verdict.repo === repo);
+    if (found === undefined) {
+        throw new Error(`no verdict for ${chore} in ${repo}`);
+    }
+    return found;
+};
+
+describe(`what "we have not measured this" means`, () => {
+    test(`a chore whose probe never ran is unavailable, not clear`, () => {
+        const verdict = verdictFor(report(), `security-advisories`);
+        expect(verdict.state).toBe(`unavailable`);
+        expect(verdict.detail).toEqual([`Security advisories · not measured yet`]);
+    });
+
+    // The distinction that stops the panel reporting a green repository it has never looked at. A tool the repo
+    // does not have is not evidence of anything, and it carries the tool's own reason rather than an invented one.
+    test(`a probe the repository cannot run says so, and never badges`, () => {
+        const input = report({
+            repos: [{ repo: `app`, probes: [probe({ id: `knip`, state: `unavailable`, reason: `knip is not a devDependency` })], signals: signals() }],
+        });
+        const verdict = verdictFor(input, `dead-code`);
+        expect(verdict.state).toBe(`unavailable`);
+        expect(verdict.detail[0]).toContain(`knip is not a devDependency`);
+        expect(unseenVerdicts([verdict], {})).toEqual([]);
+    });
+
+    test(`a probe that ran and found nothing is clear, with no prompt to spend a turn on`, () => {
+        const verdict = verdictFor(report({ repos: [{ repo: `app`, probes: [auditProbe([])], signals: signals() }] }), `security-advisories`);
+        expect(verdict.state).toBe(`clear`);
+        expect(verdict.prompt).toBeUndefined();
+    });
+});
+
+describe(`the ledger debounces; it cannot hide`, () => {
+    const withAdvisories = report({ repos: [{ repo: `app`, probes: [auditProbe([`left-pad`])], signals: signals() }] });
+    const ledgerEntry = (over: Partial<ChoreLedgerEntry> = {}): ChoreLedgerEntry => ({
+        repo: `app`,
+        chore: `security-advisories`,
+        ranAt: NOW - DAY,
+        runId: `r1`,
+        outcome: `acted`,
+        digest: verdictFor(withAdvisories, `security-advisories`).digest,
+        ...over,
+    });
+
+    test(`a run against this exact evidence leaves the chore due but settled — shown, never badged`, () => {
+        const verdict = verdictFor({ ...withAdvisories, ledger: [ledgerEntry()] }, `security-advisories`);
+        expect(verdict.state).toBe(`due`);
+        expect(verdict.settled).toBe(true);
+        expect(unseenVerdicts([verdict], {})).toEqual([]);
+    });
+
+    // The point of digesting evidence rather than stamping a time: a fix landing, or a NEW advisory arriving,
+    // both move the evidence and both deserve to be heard again.
+    test(`evidence that has moved since the run is unsettled again`, () => {
+        const moved = report({ repos: [{ repo: `app`, probes: [auditProbe([`left-pad`, `minimist`])], signals: signals() }], ledger: [ledgerEntry()] });
+        const verdict = verdictFor(moved, `security-advisories`);
+        expect(verdict.state).toBe(`due`);
+        expect(verdict.settled).toBe(false);
+        expect(unseenVerdicts([verdict], {})).toHaveLength(1);
+    });
+
+    test(`an agent reporting the findings did not hold up clears the chore until the evidence changes`, () => {
+        const verdict = verdictFor({ ...withAdvisories, ledger: [ledgerEntry({ outcome: `clean` })] }, `security-advisories`);
+        expect(verdict.state).toBe(`clear`);
+        expect(verdict.headline).toBe(`Checked — the findings did not hold up`);
+    });
+
+    test(`a snooze silences a due chore without hiding it, and lapses on its own`, () => {
+        const snoozed = verdictFor({ ...withAdvisories, ledger: [ledgerEntry({ snoozedUntil: NOW + DAY })] }, `security-advisories`);
+        expect(snoozed.state).toBe(`snoozed`);
+        expect(snoozed.detail).not.toEqual([]);
+        expect(unseenVerdicts([snoozed], {})).toEqual([]);
+
+        const lapsed = verdictFor({ ...withAdvisories, ledger: [ledgerEntry({ snoozedUntil: NOW - 1 })] }, `security-advisories`);
+        expect(lapsed.state).toBe(`due`);
+    });
+
+    /* A chore with a cadence expires its own settlement, so "we looked and chose not to act" cannot silence it
+     * for good. Security has no cadence on purpose — an advisory does not become interesting again because
+     * ninety days passed, it becomes interesting when the advisory set changes — so its settlement persists. */
+    test(`settlement expires with the chore's cadence, and persists for the chores that have none`, () => {
+        const dependencies = choreById(`dependencies-outdated`);
+        expect(dependencies?.cadenceMs).toBeGreaterThan(0);
+        expect(choreById(`security-advisories`)?.cadenceMs).toBe(0);
+
+        const old = { ...withAdvisories, ledger: [ledgerEntry({ ranAt: NOW - 400 * DAY })] };
+        expect(verdictFor(old, `security-advisories`).settled).toBe(true);
+    });
+});
+
+describe(`surveys are due because time passed, and say so`, () => {
+    const surveyLedger = (ranAt: number): ChoreLedgerEntry => ({
+        repo: `app`,
+        chore: `standardize-patterns`,
+        ranAt,
+        runId: `r1`,
+        outcome: `reported`,
+        digest: `whatever`,
+    });
+
+    test(`never run is due`, () => {
+        expect(verdictFor(report(), `standardize-patterns`).state).toBe(`due`);
+    });
+
+    test(`run inside the period is clear, and reports when it was read rather than claiming nothing to do`, () => {
+        const verdict = verdictFor({ ...report(), ledger: [surveyLedger(NOW - 10 * DAY)] }, `standardize-patterns`);
+        expect(verdict.state).toBe(`clear`);
+        expect(verdict.headline).toBe(`Surveyed 10 days ago`);
+    });
+
+    test(`run longer ago than the cadence is due again`, () => {
+        expect(verdictFor({ ...report(), ledger: [surveyLedger(NOW - 200 * DAY)] }, `standardize-patterns`).state).toBe(`due`);
+    });
+});
+
+describe(`the badge speaks about transitions, not about statistics`, () => {
+    const withAdvisories = report({ repos: [{ repo: `app`, probes: [auditProbe([`left-pad`])], signals: signals() }] });
+
+    test(`acknowledging a digest silences it, and the next distinct finding still gets through`, () => {
+        const first = verdictFor(withAdvisories, `security-advisories`);
+        expect(unseenVerdicts([first], {})).toHaveLength(1);
+
+        const seen = { [ledgerKey(`app`, `security-advisories`)]: first.digest };
+        expect(unseenVerdicts([first], seen)).toEqual([]);
+
+        const next = verdictFor(report({ repos: [{ repo: `app`, probes: [auditProbe([`left-pad`, `tar`])], signals: signals() }] }), `security-advisories`);
+        expect(unseenVerdicts([next], seen)).toHaveLength(1);
+    });
+
+    // The rule the whole surface is built to satisfy: a backlog that has been seen once must stop speaking, or
+    // the tile is lit every day and the rail stops being read at all.
+    test(`a standing backlog of undocumented packages goes quiet once seen, but a new package speaks`, () => {
+        const undocumented = (dirs: readonly string[]): ChoresReport =>
+            report({
+                repos: [{ repo: `app`, probes: [], signals: signals({ packages: dirs.map((dir) => pkg({ dir, name: dir, documented: false })) }) }],
+            });
+
+        const backlog = verdictFor(undocumented([`_libs/a`, `_libs/b`]), `documentation-refresh`);
+        expect(backlog.state).toBe(`due`);
+        const seen = { [ledgerKey(`app`, `documentation-refresh`)]: backlog.digest };
+        expect(unseenVerdicts([backlog], seen)).toEqual([]);
+
+        const grown = verdictFor(undocumented([`_libs/a`, `_libs/b`, `_libs/new`]), `documentation-refresh`);
+        expect(unseenVerdicts([grown], seen)).toHaveLength(1);
+    });
+});
+
+describe(`the findings themselves`, () => {
+    test(`complexity reports only files that are load-bearing or out of proportion, never just the ranking's top`, () => {
+        const hotspot = (path: string, complexity: number) => ({ path, commits: 20, adds: 100, dels: 50, complexity, score: complexity * 20, latestMs: NOW });
+        // An even ranking has no outlier and no key module in it: a healthy repository, and an empty finding.
+        const even = report({
+            repos: [{ repo: `app`, probes: [], signals: signals({ hotspots: [hotspot(`a.ts`, 30), hotspot(`b.ts`, 28), hotspot(`c.ts`, 26)] }) }],
+        });
+        expect(verdictFor(even, `complexity`).state).toBe(`clear`);
+
+        const outlier = report({
+            repos: [{ repo: `app`, probes: [], signals: signals({ hotspots: [hotspot(`a.ts`, 200), hotspot(`b.ts`, 28), hotspot(`c.ts`, 26)] }) }],
+        });
+        const verdict = verdictFor(outlier, `complexity`);
+        expect(verdict.state).toBe(`due`);
+        expect(verdict.detail).toHaveLength(1);
+        expect(verdict.detail[0]).toContain(`a.ts`);
+    });
+
+    test(`a half-built index says nothing rather than ranking what it has read so far`, () => {
+        const partial = report({
+            repos: [
+                {
+                    repo: `app`,
+                    probes: [],
+                    signals: signals({ indexed: false, hotspots: [{ path: `a.ts`, commits: 9, adds: 1, dels: 1, complexity: 900, score: 8100, latestMs: NOW }] }),
+                },
+            ],
+        });
+        expect(verdictFor(partial, `complexity`).state).toBe(`clear`);
+    });
+
+    test(`two libraries for one job is the finding; one is not`, () => {
+        const one = report({ repos: [{ repo: `app`, probes: [], signals: signals({ packages: [pkg({ dependencies: [`zod`] })] }) }] });
+        expect(verdictFor(one, `library-overlap`).state).toBe(`clear`);
+
+        const two = report({ repos: [{ repo: `app`, probes: [], signals: signals({ packages: [pkg({ dependencies: [`zod`, `yup`] })] }) }] });
+        const verdict = verdictFor(two, `library-overlap`);
+        expect(verdict.state).toBe(`due`);
+        expect(verdict.detail[0]).toContain(`schema validation`);
+    });
+
+    // The runtime table is static and offline by design; a major it does not know about must read as "not
+    // end-of-life", which is the safe direction to be wrong in.
+    test(`an unknown node major is not reported as end-of-life`, () => {
+        expect(verdictFor({ ...report(), node: `v99.0.0` }, `runtime-eol`).state).toBe(`clear`);
+    });
+
+    test(`a runtime past its end-of-life date is the one ordinary finding that reaches warning`, () => {
+        const verdict = verdictFor({ ...report(), node: `v18.20.0` }, `runtime-eol`);
+        expect(verdict.state).toBe(`due`);
+        expect(verdict.severity).toBe(`warning`);
+    });
+
+    test(`a supported runtime is clear`, () => {
+        expect(verdictFor({ ...report(), node: `v24.18.0` }, `runtime-eol`).state).toBe(`clear`);
+    });
+});
+
+describe(`the prompts`, () => {
+    const dueVerdict = () => verdictFor(report({ repos: [{ repo: `app`, probes: [auditProbe([`left-pad`])], signals: signals() }] }), `security-advisories`);
+
+    /* A prompt that counts without NAMING sends the agent off to re-derive a list we are already holding — slowly,
+     * and against a tree that has moved since. Every measured chore names its artefacts. */
+    test(`name the artefacts, not just how many there were`, () => {
+        const verdict = dueVerdict();
+        expect(verdict.prompt).toContain(`left-pad`);
+        expect(verdict.prompt).toContain(`app`);
+    });
+
+    test(`tell an acting chore to keep the diff reviewable and a reporting chore not to edit at all`, () => {
+        expect(dueVerdict().prompt).toContain(`separately explainable`);
+        const survey = verdictFor(report(), `standardize-patterns`);
+        expect(survey.prompt).toContain(`Change nothing.`);
+    });
+
+    test(`every chore that can be due can produce a prompt`, () => {
+        const verdicts = assessReport(
+            report({
+                repos: [
+                    {
+                        repo: `app`,
+                        probes: [
+                            auditProbe([`left-pad`]),
+                            probe({ id: `outdated`, facts: { id: `outdated`, packages: [{ name: `vue`, current: `1.0.0`, latest: `2.0.0`, kind: `major`, section: `dependencies` }] } }),
+                            probe({ id: `knip`, facts: { id: `knip`, deadCode: { files: 3, exports: 2, types: 0, dependencies: 1, devDependencies: 0, sample: [`a.ts`] } } }),
+                            probe({ id: `jscpd`, facts: { id: `jscpd`, duplication: { percentage: 9, clones: 4, top: [{ lines: 20, first: `a.ts`, second: `b.ts` }] } } }),
+                        ],
+                        signals: signals({ packages: [pkg({ documented: false, dependencies: [`zod`, `joi`] })] }),
+                    },
+                ],
+                node: `v18.20.0`,
+            }),
+            NOW,
+        );
+        const due = verdicts.filter((verdict) => verdict.state === `due`);
+        expect(due.length).toBeGreaterThanOrEqual(8);
+        for (const verdict of due) {
+            expect(verdict.prompt, verdict.chore.id).toBeTypeOf(`string`);
+            expect(verdict.digest, verdict.chore.id).not.toBe(``);
+        }
+        // Each measured chore's own artefact reaches its own prompt — the regression this whole test exists for.
+        const promptFor = (chore: string) => due.find((verdict) => verdict.chore.id === chore)?.prompt ?? ``;
+        expect(promptFor(`security-advisories`)).toContain(`left-pad`);
+        expect(promptFor(`dependencies-outdated`)).toContain(`vue 1.0.0 → 2.0.0`);
+        expect(promptFor(`dead-code`)).toContain(`a.ts`);
+        expect(promptFor(`duplication`)).toContain(`a.ts ↔ b.ts`);
+        expect(promptFor(`documentation-refresh`)).toContain(`_libs/thing`);
+        expect(promptFor(`library-overlap`)).toContain(`zod`);
+        expect(promptFor(`runtime-eol`)).toContain(`v18.20.0`);
+    });
+});
+
+/* APPLICABILITY — whether the chore is a QUESTION worth asking of this repository, as opposed to whether the
+ * answer is yes. Every case here is one where the previous design showed a row that could never be acted on:
+ * an offer to re-read documentation that was never written, to slim an image that does not exist, to tighten a
+ * pipeline nobody has. Each of those teaches the reader that this list was not written by someone who looked. */
+describe(`what does not apply here`, () => {
+    const withShape = (over: Partial<ChoreShape>): ChoresReport =>
+        report({ repos: [{ repo: `app`, probes: [], signals: signals({ shape: shape(over) }) }] });
+
+    test(`a repository with no documents is not asked to re-read its documentation`, () => {
+        const verdict = verdictFor(withShape({ docs: [] }), `documentation-drift`);
+        expect(verdict.state).toBe(`not-applicable`);
+        expect(verdict.headline).toBe(`this repository has no architecture documents to re-read`);
+        expect(verdict.prompt).toBeUndefined();
+    });
+
+    test(`a repository with no Dockerfile is not asked to slim its image`, () => {
+        expect(verdictFor(withShape({ dockerfiles: [] }), `docker-image`).state).toBe(`not-applicable`);
+    });
+
+    test(`a repository with no pipeline is not asked to tighten one`, () => {
+        expect(verdictFor(withShape({ ci: [] }), `ci-hygiene`).state).toBe(`not-applicable`);
+    });
+
+    test(`a repository that is not a Node project is not offered the npm-shaped chores`, () => {
+        const foreign = withShape({ packageManifest: false, lockfile: false });
+        for (const chore of [`dependencies-outdated`, `runtime-eol`, `dead-code`, `security-advisories`, `deprecated-apis`]) {
+            expect(verdictFor(foreign, chore).state, chore).toBe(`not-applicable`);
+        }
+    });
+
+    test(`a repository that is not a workspace is not asked about per-package documents or library overlap`, () => {
+        const single = report({ repos: [{ repo: `app`, probes: [], signals: signals({ packages: [] }) }] });
+        expect(verdictFor(single, `documentation-refresh`).state).toBe(`not-applicable`);
+        expect(verdictFor(single, `library-overlap`).state).toBe(`not-applicable`);
+    });
+
+    // A survey has no evidence to be absent — "90 days have passed" is true everywhere — so without a gate it
+    // fires forever in repositories where its subject does not exist. This is the regression that motivated
+    // making `applies` a required field on SurveySpec rather than an optional one.
+    test(`a tiny repository is not surveyed for cross-cutting patterns it cannot have`, () => {
+        const tiny = report({ repos: [{ repo: `app`, probes: [], signals: signals({ totals: { files: 4, symbols: 10, complexity: 5, hotspots: 0 } }) }] });
+        const verdict = verdictFor(tiny, `standardize-patterns`);
+        expect(verdict.state).toBe(`not-applicable`);
+        expect(verdict.headline).toContain(`4 indexed files`);
+    });
+
+    test(`applicability is decided before measurement, so a missing probe never masks it`, () => {
+        // dead-code needs the knip probe, which has not run; the gate still wins, because "we cannot ask this
+        // question here" outranks "we have not measured it".
+        expect(verdictFor(withShape({ packageManifest: false }), `dead-code`).state).toBe(`not-applicable`);
+    });
+
+    test(`a chore that does not apply can never reach the rail`, () => {
+        const verdicts = assessReport(withShape({ docs: [], dockerfiles: [], ci: [] }), NOW).filter((verdict) => verdict.state === `not-applicable`);
+        expect(verdicts.length).toBeGreaterThanOrEqual(3);
+        expect(unseenVerdicts(verdicts, {})).toEqual([]);
+    });
+
+    test(`a fully-equipped repository rules nothing out`, () => {
+        expect(assessReport(withShape({}), NOW).filter((verdict) => verdict.state === `not-applicable`)).toEqual([]);
+    });
+});
+
+/* THE CRITERION — the rule in words, next to the evidence that met it. A row that reports a number without the
+ * rule behind it is asking to be taken on trust, and the first row that turns out to be wrong costs the whole
+ * list its credibility. */
+describe(`every chore says what would make it due`, () => {
+    test(`every entry in the book carries a criterion`, () => {
+        for (const chore of CHORES) {
+            expect(chore.criterion, chore.id).toBeTypeOf(`string`);
+            expect(chore.criterion.length, chore.id).toBeGreaterThan(20);
+        }
+    });
+
+    test(`the criterion reaches the prompt, so the agent can tell us the rule was wrong`, () => {
+        const due = verdictFor(report({ repos: [{ repo: `app`, probes: [auditProbe([`left-pad`])], signals: signals() }] }), `security-advisories`);
+        expect(due.prompt).toContain(`You were woken because:`);
+        expect(due.prompt).toContain(due.chore.criterion);
+    });
+});

package/src/chores/verdict.ts

@@ -0,0 +1,167 @@
+import type { ChoreLedgerEntry, ChoresReport, ProbeId, ProbeResult } from "../schemas.js";
+import { type Chore, type ChoreContext, type ChoreFinding, CHORES, chorePrompt } from "./chores.js";
+import { probeSpec } from "./probes.js";
+
+/* FROM EVIDENCE TO A VERDICT — the one place that decides whether a chore is due, and the only place that is
+ * allowed to. Both the Maintenance panel and its rail badge run this function over the same report, so the number
+ * on the tile and the reason in the panel are the same computation and cannot drift apart.
+ *
+ * Five states, and the distinctions between them are the whole design:
+ *
+ *   not-applicable  this chore is not a QUESTION worth asking of this repository — there is no Dockerfile to
+ *                slim, no pipeline to tighten, no documentation to re-read. Dropped from the panel entirely
+ *                rather than shown as clear, because "clear" claims we checked, and there was nothing to check.
+ *                The reason survives as a footer, so "why is there no Docker chore here?" has an answer.
+ *   unavailable  we have not measured this. knip is not a devDependency; there is no lockfile to audit. Rendered
+ *                greyed, never badged, and never collapsed into `clear` — a maintenance surface reporting a green
+ *                repository it has never actually measured is worse than one that says nothing.
+ *   clear        we measured, and there is nothing to do. This is the common state, and it has to be visibly
+ *                reachable or the panel is just a list of complaints.
+ *   snoozed      the owner said "not now". Still listed, still showing its evidence, silent until it lapses.
+ *   due          there is something to do.
+ *
+ * The first three are all ways of saying "no", and keeping them apart is what makes the surface trustworthy: they
+ * mean we cannot ask, we did not measure, and we measured and found nothing — three different claims, and only
+ * the last one is reassurance.
+ *
+ * And one flag that is not a state: `settled`. A due chore whose evidence is UNCHANGED since a turn was already
+ * spent on it stays due — because it is — but must never light the rail again. This is what stops the surface
+ * repeating itself while a fix sits in review, and it is why the ledger stores a digest rather than a timestamp:
+ * "ran 3 days ago" cannot tell you whether it ran against THIS.
+ *
+ * Nothing here can hide a problem. Snoozing and settling change whether the rail SPEAKS; the panel still shows
+ * the chore, its evidence and its state. The one thing that removes a row entirely is `not-applicable`, and that
+ * is not hiding — it is the absence of a subject, recorded in the panel's footer with its reason. A maintenance
+ * surface you can quietly bury findings in is a maintenance surface nobody trusts. */
+
+export type ChoreState = "due" | "clear" | "snoozed" | "unavailable" | "not-applicable";
+
+export interface ChoreVerdict {
+    readonly chore: Chore;
+    readonly repo: string;
+    readonly state: ChoreState;
+    readonly severity: ChoreFinding["severity"];
+    // Always present, in every state — "nothing to do" and "not measured" are answers a reader deserves in words.
+    readonly headline: string;
+    readonly detail: readonly string[];
+    // The evidence identity. Empty for `unavailable`, where there is no evidence to identify.
+    readonly digest: string;
+    // The turn. Present only when there is something to do — a "start an agent" button on a clear chore is an
+    // invitation to spend money proving that nothing is wrong.
+    readonly prompt: string | undefined;
+    readonly lastRun: ChoreLedgerEntry | undefined;
+    // A turn has already been spent on exactly this evidence, and the chore's cadence has not lapsed since. Still
+    // due, still shown, never badged.
+    readonly settled: boolean;
+}
+
+// A survey that is clear is clear because it was READ recently, and saying so is the only way its row means
+// anything — "nothing to do" under a chore that has no measurement would be a claim about the code rather than
+// about the calendar.
+const clearHeadline = (chore: Chore, lastRun: ChoreLedgerEntry | undefined, nowMs: number): string =>
+    chore.survey === true && lastRun !== undefined ? `Surveyed ${Math.round((nowMs - lastRun.ranAt) / 86_400_000)} days ago` : `Nothing to do`;
+
+// Why a chore could not be assessed, in the words of the thing that could not do it. Never invented: an
+// `unavailable` probe carries the tool's own reason, and a probe that has simply not run yet says that.
+const unmeasuredDetail = (needs: readonly ProbeId[], probes: ReadonlyMap<ProbeId, ProbeResult>): string[] =>
+    needs.flatMap((id) => {
+        const probe = probes.get(id);
+        const spec = probeSpec(id);
+        if (probe === undefined) {
+            return [`${spec.title} · not measured yet`];
+        }
+        if (probe.state === `ok`) {
+            return [];
+        }
+        return [`${spec.title} · ${probe.state === `unavailable` ? `not available in this repository` : `failed`}${probe.reason === undefined ? `` : ` — ${probe.reason}`}`];
+    });
+
+export const assessChore = (chore: Chore, context: ChoreContext, ledger: ChoreLedgerEntry | undefined): ChoreVerdict => {
+    const base = { chore, repo: context.repo, lastRun: ledger, settled: false, prompt: undefined } as const;
+
+    /* APPLICABILITY FIRST, before anything is measured or any evidence is read. A chore that does not apply is
+     * not "clear" and not "unmeasured" — the question does not arise here, and every subsequent branch of this
+     * function would be answering it anyway. The reason is carried as the headline, because the panel's footer
+     * is the only place it will ever be read. */
+    const inapplicable = chore.applies?.(context.signals);
+    if (inapplicable !== undefined) {
+        return { ...base, state: `not-applicable`, severity: `info`, headline: inapplicable, detail: [], digest: `` };
+    }
+
+    const unmeasured = unmeasuredDetail(chore.needs, context.probes);
+    if (unmeasured.length > 0) {
+        return { ...base, state: `unavailable`, severity: `info`, headline: `Not measured`, detail: unmeasured, digest: `` };
+    }
+
+    const finding = chore.assess(context);
+    if (finding === undefined) {
+        return { ...base, state: `clear`, severity: `info`, headline: clearHeadline(chore, ledger, context.nowMs), detail: [], digest: `` };
+    }
+
+    /* Has the last run's settlement lapsed? A cadence of 0 means "this is decided by evidence alone" — an advisory
+     * does not become worth looking at again because ninety days passed, it becomes worth looking at again when
+     * the advisory set changes. Anything with a cadence expires its own settlement, so "we looked and chose not to
+     * act" cannot silence a chore for good. */
+    const lapsed = ledger !== undefined && chore.cadenceMs > 0 && context.nowMs - ledger.ranAt >= chore.cadenceMs;
+    const sameEvidence = ledger?.digest === finding.digest && !lapsed;
+
+    /* A SURVEY has no measurement, so the calendar is the whole trigger: it is due because it has been that long,
+     * and a run inside the current period settles it until the next one begins. Checked against the run's TIME
+     * rather than its digest, because a survey run three days into a quarter and one three days before its end
+     * are the same period but very different answers to "when was this last read?". */
+    if (chore.survey === true && ledger !== undefined && context.nowMs - ledger.ranAt < chore.cadenceMs) {
+        return { ...base, state: `clear`, severity: `info`, headline: clearHeadline(chore, ledger, context.nowMs), detail: finding.detail, digest: finding.digest };
+    }
+
+    const prompt = chorePrompt(chore, finding, context.repo);
+
+    if (ledger?.snoozedUntil !== undefined && ledger.snoozedUntil > context.nowMs) {
+        return { ...base, state: `snoozed`, severity: `info`, headline: finding.headline, detail: finding.detail, digest: finding.digest, prompt };
+    }
+
+    /* The agent looked at exactly this evidence and reported that there was nothing in it — knip's findings were
+     * all public entry points, the clones were all generated files. That verdict has to stick, or the next poll
+     * starts the same turn again and the surface has taught the owner that its rows are wrong. It stops sticking
+     * when the evidence changes (a different digest) or the cadence lapses. */
+    if (sameEvidence && ledger?.outcome === `clean`) {
+        return {
+            ...base,
+            state: `clear`,
+            severity: `info`,
+            headline: `Checked — the findings did not hold up`,
+            detail: finding.detail,
+            digest: finding.digest,
+        };
+    }
+
+    return { ...base, state: `due`, severity: finding.severity, headline: finding.headline, detail: finding.detail, digest: finding.digest, prompt, settled: sameEvidence };
+};
+
+// The ledger is keyed by repo + chore, which is the grain a verdict is decided at: the same chore in two repos is
+// two independent questions with two independent answers.
+export const ledgerKey = (repo: string, chore: string): string => `${repo}|${chore}`;
+
+/* Every chore in every repo, from one report. This is what both surfaces call — the panel groups the result, the
+ * badge filters it — so there is exactly one traversal of the book in the codebase and adding a chore to CHORES
+ * reaches both surfaces without touching either. */
+export const assessReport = (report: ChoresReport, nowMs: number): ChoreVerdict[] => {
+    const ledger = new Map(report.ledger.map((entry) => [ledgerKey(entry.repo, entry.chore), entry]));
+    return report.repos.flatMap(({ repo, probes, signals }) => {
+        const context: ChoreContext = { repo, probes: new Map(probes.map((probe) => [probe.id, probe])), signals, node: report.node, nowMs };
+        return CHORES.map((chore) => assessChore(chore, context, ledger.get(ledgerKey(repo, chore.id))));
+    });
+};
+
+/* WHAT THE RAIL IS ALLOWED TO SAY. A badge must mean "something happened here that you don't already know about",
+ * never "here is a statistic" — the extension API states that bar and this is the function that holds this
+ * surface to it. Three filters, and every one of them removes a case that would otherwise light the tile forever:
+ *
+ *   state === due   the obvious one.
+ *   !settled        a turn has already been spent on this exact evidence.
+ *   unseen digest   the owner has already LOOKED at this evidence in the panel. Acknowledgement is per digest
+ *                   rather than per chore, so acknowledging today's finding does not also swallow tomorrow's.
+ *
+ * `seen` maps ledgerKey → the digest last acknowledged. It lives in a file beside the ledger, because the badge is
+ * derived from files and its acknowledgement belongs in the same tree. */
+export const unseenVerdicts = (verdicts: readonly ChoreVerdict[], seen: Readonly<Record<string, string>>): ChoreVerdict[] =>
+    verdicts.filter((verdict) => verdict.state === `due` && !verdict.settled && seen[ledgerKey(verdict.repo, verdict.chore.id)] !== verdict.digest);

package/src/contracts/chores.contract.ts

@@ -0,0 +1,23 @@
+import { oc } from "@orpc/contract";
+import { ChoreLedgerWriteSchema, ChoreProbeRequestSchema, ChoresReportSchema, OkSchema } from "../schemas.js";
+
+/* Maintenance evidence: what every repo under /work currently measures, and what has already been done about it.
+ * Three routes, because there are exactly three things the surface does — read the evidence, ask for a
+ * measurement to be retaken, and record what a turn concluded.
+ *
+ * There is no `GET /chores/{id}` and no "run this chore" route on purpose. A chore RUN is an ordinary isolated
+ * fleet agent (`POST /agent` with a derived conversation id), the same as an acceptance run or a documentation
+ * generation — so the worktree, the live status, the cost, the transcript and the /agents/<id> page already
+ * exist, and adding a bespoke launcher here would be a second way to start a turn that has to be kept in step
+ * with the first. */
+export const choresContract = {
+    // Every repo's standing evidence in one read: cached probe results (with their age and state), the cheap
+    // resident signals, the ledger, and the daemon's node version. The rail badge polls this; so does the panel.
+    list: oc.route({ method: "GET", path: "/chores" }).output(ChoresReportSchema),
+    // Re-run one repo's probe now, ignoring its TTL — the panel's per-probe refresh. An ack: the runner works in
+    // the background and the result arrives on the next `list`, because a jscpd sweep outlives any sane request.
+    probe: oc.route({ method: "POST", path: "/chores/probe" }).input(ChoreProbeRequestSchema).output(OkSchema),
+    // Record what a chore turn concluded, or snooze one. Upsert by repo+chore: a chore has one current verdict,
+    // and a growing history of "we looked at this and it was fine" is not something any reader wants paged.
+    record: oc.route({ method: "POST", path: "/chores/ledger" }).input(ChoreLedgerWriteSchema).output(OkSchema),
+};

package/src/events.ts

@@ -192,8 +192,21 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
      * bind-mounted over the workspace root and the harness is rewriting tool paths into it instead. That
      * fallback covers what arrives as tool input and not what a subprocess computes for itself, so the
      * operator needs to know — this state used to be one line in the daemon log at boot, and the way it got
-     * noticed was files appearing in the main tree from agents that were supposed to be on branches. */
-    z.object({ kind: z.literal("worktree"), branch: z.string(), base: z.string(), unenforced: z.boolean().optional() }),
+     * noticed was files appearing in the main tree from agents that were supposed to be on branches.
+     *
+     * `sync` reports the pre-turn rebase (agents/sync.ts), and rides here because this frame is already the
+     * turn's "where you are standing" announcement. Present only when the branch was BEHIND the main line —
+     * `commits` is how many main-line commits it gained, `blocked` names the repos whose rebase would not apply
+     * and was rolled back. Both can be non-empty at once in a multi-repo composition. It is a notice and never
+     * a question: the user is answering their agent, and the alternative to rebasing is not "stay safe" but
+     * "conflict at land time", which interrupts them harder. */
+    z.object({
+        kind: z.literal("worktree"),
+        branch: z.string(),
+        base: z.string(),
+        unenforced: z.boolean().optional(),
+        sync: z.object({ commits: z.number(), blocked: z.array(z.string()) }).optional(),
+    }),
     // Emitted after a clean isolated turn whose delta auto-landed (or failed to): landed ⇒ the work is now
     // UNCOMMITTED changes in the main tree (the Changes panel is the review); conflicts ⇒ it stayed safely in
     // the worktree, and each named path carries WHY it would not apply (see LandConflictSchema) so the report

package/src/hostnames.ts

@@ -43,18 +43,16 @@ export const CATCH_ALL = { service: "http_status:404" } as const;
 // covers exactly one level), where <panel> is `<repo>` or `<repo>--<app>` and <sandboxId> pins the hostname to
 // this sandbox (the shared intentic zone hosts many sandboxes; without the id two users' panels would collide).
 // Port-forward scheme: `port-<slot>-<sandboxId>.<zone>` — the same shape with a `port-` prefix, where <slot>
-// is one of the sandbox's fixed forward slots (see PORT_SLOTS), not the port number itself: slots keep the
-// intentic-provided path's minted routes bounded and warm while dev servers churn ephemeral ports.
+// is one of the sandbox's forward slots (portSlotsFromToken in ./tunnel-ids), not the port number itself:
+// slots keep the intentic-provided path's minted routes bounded and warm while dev servers churn ephemeral
+// ports. The slot labels are salted with the connect token rather than being the letters a…h, so a forwarded
+// port's hostname is not derivable from the (public) sandbox id alone — see tunnel-ids for why that matters.
 //
 // A *label* is the first-DNS-label prefix before `-<sandboxId>` (`preview-<panel>` / `port-<slot>`) — the unit
 // the platform's /sandbox/preview-route mints, so one endpoint serves both schemes.
 export const previewLabel = (panel: string): string => `preview-${panel}`;
 export const portLabel = (slot: string): string => `port-${slot}`;
 
-// The fixed per-sandbox forward slots. Eight is deliberate: enough for a monorepo's worth of concurrent dev
-// servers, and the hard cap on preview DNS records a sandbox can ever cost the shared intentic zone.
-export const PORT_SLOTS = ["a", "b", "c", "d", "e", "f", "g", "h"] as const;
-
 // The hostname a label resolves to — what the platform's /sandbox/preview-route mints from the label alone.
 export const labelHostname = (label: string, id: string, zone: string): string => `${label}-${id}.${zone}`;
 export const previewHostname = (panel: string, id: string, zone: string): string => labelHostname(previewLabel(panel), id, zone);