@intentic/sandbox-contract 1.223.0 → 1.225.0

package/src/chores/verdict.test.ts

@@ -20,7 +20,7 @@ const pkg = (over: Partial<ChorePackage> = {}): ChorePackage => ({
     ...over,
 });
 
-// A repository that is a Node workspace with documents, a pipeline, an image and a Tailwind front-end — so every
+// A repository that is a Node workspace with documents, a pipeline, an image and a Tailwind front-end, 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`],
@@ -56,7 +56,7 @@ const auditProbe = (names: readonly string[]): ProbeResult =>
 const report = (over: Partial<ChoresReport> = {}): ChoresReport => ({
     repos: [{ repo: `app`, probes: [], signals: signals() }],
     ledger: [],
-    // Verdicts are about EVIDENCE, never about work in flight — a probe running does not make a chore more or
+    // Verdicts are about EVIDENCE, never about work in flight: a probe running does not make a chore more or
     // less due, it only makes the panel say so. Empty here because no assertion in this file should depend on it.
     running: [],
     node: `v24.18.0`,
@@ -111,7 +111,7 @@ describe(`the ledger debounces; it cannot hide`, () => {
         ...over,
     });
 
-    test(`a run against this exact evidence leaves the chore due but settled — shown, never badged`, () => {
+    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);
@@ -134,7 +134,7 @@ describe(`the ledger debounces; it cannot hide`, () => {
     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`);
+        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`, () => {
@@ -148,8 +148,8 @@ describe(`the ledger debounces; it cannot hide`, () => {
     });
 
     /* 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. */
+     * 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);
@@ -180,7 +180,7 @@ describe(`a measurement older than the work is not evidence about the work`, ()
     test(`a turn that landed after the measurement steps the chore down from due`, () => {
         const verdict = verdictFor({ ...withAdvisories, ledger: [ledgerEntry({ ranAt: NOW - 3_600_000 })] }, `security-advisories`);
         expect(verdict.state).toBe(`stale`);
-        // The evidence stays on the row — it is what the reader checks the claim against — and the claim comes off.
+        // The evidence stays on the row: it is what the reader checks the claim against, and the claim comes off.
         expect(verdict.detail).not.toEqual([]);
         expect(verdict.settled).toBe(false);
     });
@@ -194,7 +194,7 @@ describe(`a measurement older than the work is not evidence about the work`, ()
     });
 
     // Re-measuring is the whole cure: the same run, against evidence taken after it, is settled rather than stale.
-    test(`re-measuring after the turn restores the verdict — due, and now genuinely settled`, () => {
+    test(`re-measuring after the turn restores the verdict: due, and now genuinely settled`, () => {
         const remeasured = report({
             repos: [{ repo: `app`, probes: [{ ...auditProbe([`left-pad`]), ranAt: NOW - 60_000 }], signals: signals() }],
             ledger: [ledgerEntry({ ranAt: NOW - 3_600_000 })],
@@ -223,7 +223,7 @@ describe(`a measurement older than the work is not evidence about the work`, ()
     // Every measured row carries when it was taken, so no row can pass off a week-old count as this morning's.
     test(`every measured verdict says when it was measured, and the unmeasurable ones say nothing`, () => {
         expect(verdictFor(withAdvisories, `security-advisories`).measuredAt).toBe(NOW - DAY);
-        // A survey rests on no measurement — it is decided by the calendar, and has nothing to be out of date.
+        // A survey rests on no measurement: it is decided by the calendar, and has nothing to be out of date.
         expect(verdictFor(report(), `standardize-patterns`).measuredAt).toBeUndefined();
         // Nor does a probe that never ran.
         expect(verdictFor(report(), `security-advisories`).measuredAt).toBeUndefined();
@@ -363,7 +363,7 @@ 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,
+    /* 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();
@@ -420,7 +420,7 @@ describe(`the prompts`, () => {
             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.
+        // 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`);
@@ -432,7 +432,7 @@ describe(`the prompts`, () => {
     });
 });
 
-/* APPLICABILITY — whether the chore is a QUESTION worth asking of this repository, as opposed to whether the
+/* 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. */
@@ -468,7 +468,7 @@ describe(`what does not apply here`, () => {
         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
+    // 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`, () => {
@@ -498,7 +498,7 @@ describe(`what does not apply here`, () => {
 
     /* THE CAUSES HAVE TO GROUP, and that is a fact about the STRINGS rather than about the gates. The scope strip
      * prints one line per distinct cause with the chores it costs listed beside it, so two gates that both mean
-     * "there is no package.json here" and say it in different words print two lines — and a workspace root, where
+     * "there is no package.json here" and say it in different words print two lines, and a workspace root, where
      * a dozen chores are ruled out by three facts, is back to the paragraph-per-chore wall this phrasing replaced.
      * Bounded rather than enumerated: a new gate may invent a new cause, it may not invent a new sentence. */
     test(`applicability reasons are bare causes, so the ones that mean the same thing group`, () => {
@@ -515,7 +515,7 @@ describe(`what does not apply here`, () => {
     });
 });
 
-/* THE FRONT-END CHORES. Four chores over two probes, tested where they decide something — the share that makes a
+/* THE FRONT-END CHORES. Four chores over two probes, tested where they decide something: the share that makes a
  * bundle a finding, the names that make two components one component, and above all the digests, because three of
  * these four measure things that move every time anyone writes a line of markup. */
 const uiProbe = (scan: Partial<UiScan> = {}): ProbeResult =>
@@ -601,8 +601,8 @@ describe(`idioms the framework has replaced`, () => {
         expect(verdict.detail).toEqual([`3 files · the Options API → <script setup> with the Composition API`]);
     });
 
-    /* A migration in progress is a set that changes on every commit, so digesting the file identities — which is
-     * right for the documentation chore, whose set is packages — would badge continuously through exactly the
+    /* A migration in progress is a set that changes on every commit, so digesting the file identities, which is
+     * right for the documentation chore, whose set is packages: would badge continuously through exactly the
      * period someone is doing the work. The bucketed count moves on real progress and not on daily churn. */
     test(`one more file in a large migration is not news`, () => {
         const before = verdictFor(withProbes([uiProbe({ idioms: [idioms(`vue-options-api`, 40)] })]), `framework-idiom`);
@@ -668,7 +668,7 @@ describe(`components built twice`, () => {
     });
 
     /* Half a measurement would let the row claim it looked for shared logic in a repository where jscpd has never
-     * run — the "measured and found nothing" lie the unavailable state exists to prevent. */
+     * run: the "measured and found nothing" lie the unavailable state exists to prevent. */
     test(`without the clone sweep the chore is unavailable, not clear`, () => {
         expect(verdictFor(withProbes([components(`src/Button.vue`, `src/ui/Button.vue`)]), `component-overlap`).state).toBe(`unavailable`);
     });
@@ -692,7 +692,7 @@ describe(`hard-coded styles`, () => {
         expect(verdict.detail[0]).toBe(`src/Checkout.vue · 11 values`);
     });
 
-    // Tailwind gates this one alone — a Vue repository with no Tailwind has no theme scale to have bypassed, and
+    // Tailwind gates this one alone: a Vue repository with no Tailwind has no theme scale to have bypassed, and
     // a row saying so would be the surface inventing a subject.
     test(`a repository without Tailwind is not asked the question at all`, () => {
         const verdict = verdictFor(
@@ -713,7 +713,7 @@ describe(`hard-coded styles`, () => {
     });
 });
 
-/* THE CRITERION — the rule in words, next to the evidence that met it. A row that reports a number without the
+/* 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`, () => {

package/src/chores/verdict.ts

@@ -2,18 +2,18 @@ import type { ChoreLedgerEntry, ChoresReport, ProbeId, ProbeResult } from "../sc
 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
+/* 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.
  *
  * Six 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
+ *   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 in the scope strip, 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
+ *                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.
@@ -23,23 +23,23 @@ import { probeSpec } from "./probes.js";
  *   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
+ * 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 that has been RE-MEASURED since a turn was spent on
- * it, and whose evidence did not move, stays due — because it is — but must never light the rail again. This is
+ * it, and whose evidence did not move, 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.
  *
  * `stale` is the other half of that sentence, and it exists because the digest alone cannot tell the two apart.
  * A probe that never re-ran produces an unchanged digest for free, so "the fix did not move the numbers" and "we
- * have not looked since the fix" arrived at this function looking identical — and the panel showed the second as
+ * have not looked since the fix" arrived at this function looking identical, and the panel showed the second as
  * the first, quoting a week-old count an hour after the work that invalidated it. Comparing the run's time to the
  * MEASUREMENT's time is what separates them, and it is a comparison of two numbers the report already carries.
  *
  * 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, counted in the panel's scope strip and expandable to the reason.
+ * is not hiding, it is the absence of a subject, counted in the panel's scope strip and expandable to the reason.
  * A maintenance surface you can quietly bury findings in is a maintenance surface nobody trusts. */
 
 export type ChoreState = "due" | "clear" | "snoozed" | "stale" | "unavailable" | "not-applicable";
@@ -49,16 +49,16 @@ export interface ChoreVerdict {
     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.
+    // 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;
-    /* WHEN THE EVIDENCE WAS TAKEN — the fact every row shows beside its numbers, and the one whose absence let a
+    /* WHEN THE EVIDENCE WAS TAKEN, the fact every row shows beside its numbers, and the one whose absence let a
      * measurement from last Tuesday read as this morning's. Undefined when the verdict rests on no measurement at
      * all: a survey is decided by the calendar, and an unavailable chore has nothing to be out of date. */
     readonly measuredAt: number | undefined;
-    // The turn. Present only when there is something to do — a "start an agent" button on a clear chore is an
+    // 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;
@@ -68,7 +68,7 @@ export interface ChoreVerdict {
 }
 
 /* HOW OLD THE EVIDENCE IS: the OLDEST of the measurements a verdict rests on, because a claim is only as current
- * as the least current thing it was computed from. Undefined when it rests on none — a survey has no measurement,
+ * as the least current thing it was computed from. Undefined when it rests on none, a survey has no measurement,
  * and an unavailable chore's probe did not produce one. */
 const measurementAge = (needs: readonly ProbeId[], probes: ReadonlyMap<ProbeId, ProbeResult>): number | undefined => {
     const taken = needs.flatMap((id) => {
@@ -79,7 +79,7 @@ const measurementAge = (needs: readonly ProbeId[], probes: ReadonlyMap<ProbeId,
 };
 
 // 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
+// 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`;
@@ -102,16 +102,16 @@ const unmeasuredDetail = (needs: readonly ProbeId[], probes: ReadonlyMap<ProbeId
         if (probe.state === `unavailable`) {
             return [`${spec.title} · ${probe.reason ?? `not available in this repository`}`];
         }
-        return [`${spec.title} · failed${probe.reason === undefined ? `` : ` — ${probe.reason}`}`];
+        return [`${spec.title} · 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 cause is carried as the headline, because the scope strip — which
-     * groups these rows BY it — is the only place it will ever be read. */
+     * not "clear" and not "unmeasured", the question does not arise here, and every subsequent branch of this
+     * function would be answering it anyway. The cause is carried as the headline, because the scope strip, which
+     * groups these rows BY it, 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: ``, measuredAt: undefined };
@@ -138,7 +138,7 @@ export const assessChore = (chore: Chore, context: ChoreContext, ledger: ChoreLe
         };
     }
 
-    /* Has the last run's settlement lapsed? A cadence of 0 means "this is decided by evidence alone" — an advisory
+    /* 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. */
@@ -176,7 +176,7 @@ export const assessChore = (chore: Chore, context: ChoreContext, ledger: ChoreLe
         };
     }
 
-    /* The agent looked at exactly this evidence and reported that there was nothing in it — knip's findings were
+    /* 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. */
@@ -185,7 +185,7 @@ export const assessChore = (chore: Chore, context: ChoreContext, ledger: ChoreLe
             ...base,
             state: `clear`,
             severity: `info`,
-            headline: `Checked — the findings did not hold up`,
+            headline: `Checked, the findings did not hold up`,
             detail: finding.detail,
             digest: finding.digest,
             measuredAt,
@@ -193,10 +193,10 @@ export const assessChore = (chore: Chore, context: ChoreContext, ledger: ChoreLe
     }
 
     /* THE MEASUREMENT IS OLDER THAN THE WORK. A turn landed after the last time we looked, so the evidence below
-     * describes a tree that no longer exists — an hour after a run deleted the dead code, the row was still
+     * describes a tree that no longer exists, an hour after a run deleted the dead code, the row was still
      * quoting the count from six days before it. `sameEvidence` cannot catch this: an unchanged digest is exactly
      * what a probe that never re-ran produces, so the flag says "settled" at its most confident when it knows
-     * least. The chore steps down instead — evidence stays on the row, the CLAIM comes off it — and carries no
+     * least. The chore steps down instead, evidence stays on the row, the CLAIM comes off it, and carries no
      * prompt, because the honest next move is to measure again rather than to spend a second turn on a finding
      * nobody has re-checked. It cannot badge either, which is what stops the tile lighting for work already done. */
     if (ledger !== undefined && measuredAt !== undefined && ledger.ranAt > measuredAt) {
@@ -220,8 +220,8 @@ export const assessChore = (chore: Chore, context: ChoreContext, ledger: ChoreLe
 // 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
+/* 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]));
@@ -232,10 +232,10 @@ export const assessReport = (report: ChoresReport, nowMs: number): ChoreVerdict[
 };
 
 /* 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
+ * 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 — and it is also what keeps `stale` silent, since a measurement taken before
+ *   state === due   the obvious one, and it is also what keeps `stale` silent, since a measurement taken before
  *                   the last turn is not a fact anyone should be interrupted about.
  *   !settled        a turn has been spent on this chore and the re-measured evidence did not move.
  *   unseen digest   the owner has already LOOKED at this evidence in the panel. Acknowledgement is per digest

package/src/contract-lock.test.ts

@@ -2,7 +2,7 @@ import { readFileSync } from "node:fs";
 import { expect, test } from "vitest";
 import { currentLock } from "./contract-lock.js";
 
-/* The committed lock and the code must say the same thing — see contract-lock.ts for what the pair buys.
+/* The committed lock and the code must say the same thing: see contract-lock.ts for what the pair buys.
  *
  * This is the HALF that runs everywhere the tests run; the other half (a shrunk lock needs a declared break)
  * lives in prepass.mjs, which has git and this suite does not. */

package/src/contract-lock.ts

@@ -1,24 +1,24 @@
-/* THE WIRE SURFACE, AS ONE COMPARABLE DOCUMENT — every zod schema this package exports, serialized to JSON
+/* THE WIRE SURFACE, AS ONE COMPARABLE DOCUMENT, every zod schema this package exports, serialized to JSON
  * Schema and sorted into a canonical shape. `contract.lock.json` at the package root is this function's
  * committed output, and the pair is what makes "did the contract change?" a question git can answer.
  *
  * Two readers depend on that answer. contract-lock.test.ts fails whenever the committed file is out of step
- * with the code, so a contract change always lands WITH its lock diff — visible in review, attributable to a
+ * with the code, so a contract change always lands WITH its lock diff, visible in review, attributable to a
  * commit. And prepass.mjs (invariant 6) compares the committed lock against its merge-base to insist that a
- * SHRUNK surface — a schema or field removed, a type changed — arrives as a `!` commit carrying a
+ * SHRUNK surface, a schema or field removed, a type changed, arrives as a `!` commit carrying a
  * `Breaking-Note:` trailer, which is what feeds the release's "Breaking changes" section and the update card's
  * warning. Additions pass freely; every persisted-manifest reader parses loosely, so growth breaks nobody.
  *
  * Serialized from the package's EXPORTS rather than a hand-kept list, on the repo's own rule (AGENTS.md:
  * "guard invariants by discovery, not enumeration"): a schema added tomorrow is in the lock tomorrow, and a
  * schema that stops being exported is a removal the lock shows. `unrepresentable: "any"` keeps the rare
- * function-valued corner from throwing — it serializes as `{}`, which still diffs when it moves. */
+ * function-valued corner from throwing, it serializes as `{}`, which still diffs when it moves. */
 
 import { z } from "zod";
 import * as contract from "./index.js";
 
 // Canonical ordering, so two runs of the same code are byte-identical and a lock diff is a contract diff
-// rather than a key-order shuffle. Arrays keep their order — for `required` and `enum` lists the order zod
+// rather than a key-order shuffle. Arrays keep their order, for `required` and `enum` lists the order zod
 // emits is stable, and sorting them would hide a reorder that is genuinely no change at all anyway.
 const sorted = (value: unknown): unknown => {
     if (Array.isArray(value)) {
@@ -43,7 +43,7 @@ export const currentLock = (): Record<string, unknown> => {
         }
         try {
             const schema = sorted(z.toJSONSchema(value, { unrepresentable: "any" })) as Record<string, unknown>;
-            // The dialect banner is identical on all ~500 entries — pure weight, no surface.
+            // The dialect banner is identical on all ~500 entries, pure weight, no surface.
             delete schema["$schema"];
             lock[name] = schema;
         } catch {
@@ -55,7 +55,7 @@ export const currentLock = (): Record<string, unknown> => {
     return lock;
 };
 
-/* ONE LINE PER SCHEMA, on purpose — not JSON.stringify(lock, null, 4). Pretty-printed, the lock is a 35k-line
+/* ONE LINE PER SCHEMA, on purpose, not JSON.stringify(lock, null, 4). Pretty-printed, the lock is a 35k-line
  * wall nobody scrolls; a line per export keeps it ~500 lines and makes `git diff` read as the list of WHICH
  * surfaces moved, which is the level a reviewer reviews at. The path-level detail lives in the tooling: the
  * lock test diffs parsed objects and prepass invariant 6 names the exact removed paths, so nothing is lost by

package/src/contracts/activity.contract.ts

@@ -1,7 +1,7 @@
 import { oc } from "@orpc/contract";
 import { ActivityListSchema, ActivityQuerySchema, ActivityStatusSchema } from "../schemas.js";
 
-// The activity audit feed (provider-agnostic; Discord is the first source). Read-only by design —
+// The activity audit feed (provider-agnostic; Discord is the first source). Read-only by design,
 // events are appended daemon-side only, so the log stays a trustworthy record of what the agent did.
 export const activityContract = {
     list: oc.route({ method: "GET", path: "/activity" }).input(ActivityQuerySchema).output(ActivityListSchema),

package/src/contracts/agent.contract.ts

@@ -14,7 +14,7 @@ import {
 } from "../schemas.js";
 
 // A turn EXECUTES as a detached daemon-side run: `run` starts it and acks with the run id; any number of
-// clients render it via `attach` (replay from a seq cursor, then live) — the initiating window holds no
+// clients render it via `attach` (replay from a seq cursor, then live), the initiating window holds no
 // special stream, so a reload, a second window, or another device attaches identically. `reply` un-parks a
 // turn waiting on any interactive card (plan approval, clarifying questions, a per-tool permission prompt);
 // steer injects a user message into the running turn; stop hard-cancels it daemon-side.
@@ -25,7 +25,7 @@ export const agentContract = {
     steer: oc.route({ method: "POST", path: "/agent/steer" }).input(SteerSchema).output(OkSchema),
     stop: oc.route({ method: "POST", path: "/agent/stop" }).input(StopTurnSchema).output(OkSchema),
     // Go back to a message: restore the workspace to that turn's checkpoint, drop the messages after it, and
-    // forget the provider session. CONFLICT while a turn is running — a restore cannot overwrite files an
+    // forget the provider session. CONFLICT while a turn is running, a restore cannot overwrite files an
     // agent is editing. NOT_FOUND when that message has no checkpoint to go back to.
     rewind: oc.route({ method: "POST", path: "/agent/rewind" }).input(RewindTurnSchema).output(RewindResultSchema),
     // The provider's slash commands as last published by one of its turns, so a conversation's `/` popover is

package/src/contracts/agents.contract.ts

@@ -24,14 +24,14 @@ import {
 
 // The fleet: every registered conversation-agent (see AgentSummarySchema). Registry-level actions (read,
 // rename, seen, archive) apply uniformly. For branch-backed conversations, `diff` is the worktree's CUMULATIVE
-// multi-repo delta vs its recorded per-repo bases — one flat change set per repo
+// multi-repo delta vs its recorded per-repo bases, one flat change set per repo
 // (AgentChanges), each file flagged `landed` or not, deliberately not the working tree's staged/unstaged
 // shape: a worktree the user never checks out has no index they could stage into. `land` merges the worktree
 // branches into the main tree (per-repo, conflicts reported, nothing lost on failure); `discard` removes
 // worktrees + branches + registry entry. Those branch actions reject workspace conversations explicitly. An
 // unknown {id} is NOT_FOUND; land/discard while the turn runs is CONFLICT.
-// `rename` sets the user-chosen display title — legal mid-turn (it touches no worktree state).
-// `seen`/`seenAll` stamp the read marker behind the cards' unread badge (AgentSummarySchema.seenAt) — also
+// `rename` sets the user-chosen display title, legal mid-turn (it touches no worktree state).
+// `seen`/`seenAll` stamp the read marker behind the cards' unread badge (AgentSummarySchema.seenAt), also
 // legal mid-turn, and like `rename` they never bump `updatedAt` (reading is not activity).
 //
 // ARCHIVE is the non-destructive counterpart to discard, and the one the board leans on: for an isolated
@@ -41,7 +41,7 @@ import {
 // surviving branch. Archiving a running agent is CONFLICT, same as land/discard.
 //
 // PURGE empties the archive, and it is `discard` applied to every agent already in there: worktree remnants,
-// branches and entries all go. Deliberately the whole archive and not a list of ids — the archive is the pile
+// branches and entries all go. Deliberately the whole archive and not a list of ids, the archive is the pile
 // of agents the user has already decided are over, so "clean it up" is one act with one confirmation, and a
 // per-id purge would be `discard`, which already exists. Never touches a running agent (a turn un-archives its
 // own agent, so there should be none) and answers with what it actually deleted: a teardown that fails on one
@@ -49,31 +49,31 @@ import {
 export const agentsContract = {
     list: oc.route({ method: "GET", path: "/agents" }).output(AgentsListSchema),
     archived: oc.route({ method: "GET", path: "/agents/archived" }).output(AgentsListSchema),
-    // The board's filter. Answers over BOTH halves of the fleet — the live roster and the archive — because
+    // The board's filter. Answers over BOTH halves of the fleet, the live roster and the archive, because
     // the board hides by design (the Finished lane windows to a handful, archived agents are off the roster
     // entirely), and a filter that reports "no matches" while the agent sits one click away is a lie. The
     // never-carded conversations that are neither are `sessions.list`'s query, which matches by the same rule.
     search: oc.route({ method: "GET", path: "/agents/search" }).input(AgentSearchQuerySchema).output(AgentSearchResultSchema),
     get: oc.route({ method: "GET", path: "/agents/{id}" }).input(AgentIdSchema).output(AgentSummarySchema),
     transcript: oc.route({ method: "GET", path: "/agents/{id}/transcript" }).input(AgentIdSchema).output(AgentTranscriptSchema),
-    /* SPEAK AS THE AGENT — append the user's words to the conversation's record as an assistant row, with no
+    /* SPEAK AS THE AGENT, append the user's words to the conversation's record as an assistant row, with no
      * turn behind them and no reply. The row is marked `placed` for human readers (RestoredMessageSchema); the
      * provider session is FORGOTTEN in the same breath, rewind-style, so the next real turn opens a fresh
-     * runtime session seeded from the record — where the placed line reads as the agent's own words, because
+     * runtime session seeded from the record, where the placed line reads as the agent's own words, because
      * the handoff renders every assistant row identically. A running turn is CONFLICT: the illusion can only be
      * established between turns, and a concurrent turn would resume the very session this exists to retire. */
     place: oc.route({ method: "POST", path: "/agents/{id}/place" }).input(AgentPlaceSchema).output(OkSchema),
     rename: oc.route({ method: "POST", path: "/agents/{id}/rename" }).input(AgentRenameSchema).output(AgentSummarySchema),
-    // This agent's own land-at-completion posture — an override of the sandbox-wide `autoLand` setting; null
+    // This agent's own land-at-completion posture, an override of the sandbox-wide `autoLand` setting; null
     // clears it back to "inherit". Legal mid-turn on purpose: the setting is read at turn COMPLETION, so
     // flipping it while the agent works is exactly "hold THIS turn's work for review", the press that matters.
     autoLand: oc.route({ method: "POST", path: "/agents/{id}/auto-land" }).input(AgentAutoLandSchema).output(AgentSummarySchema),
-    /* THIS conversation's answer to a provider outage — an override of the sandbox-wide `resumeAfterOutage`
+    /* THIS conversation's answer to a provider outage, an override of the sandbox-wide `resumeAfterOutage`
      * setting; null clears it back to "inherit". The chat's offer at the moment a turn dies writes this and
      * never the global: the press happens inside one conversation and means "finish this piece of work", so
-     * its honest blast radius is that conversation. Sandbox ▸ Agent owns the default for everything else.
+     * its honest scope is that conversation. Sandbox > Agent owns the default for everything else.
      *
-     * Legal mid-turn, and unlike autoLand it is legal for a WORKSPACE conversation too — an outage kills a
+     * Legal mid-turn, and unlike autoLand it is legal for a WORKSPACE conversation too, an outage kills a
      * main-tree chat exactly as readily as an isolated one, and there is no branch involved either way. */
     resumeAfterOutage: oc
         .route({ method: "POST", path: "/agents/{id}/resume-after-outage" })

package/src/contracts/automations.contract.ts

@@ -11,14 +11,14 @@ import {
 } from "../schemas.js";
 
 // The sandbox's automations manifest (scheduled agent wake-ups). `list` returns each automation with its recent
-// runs + next fire time. `upsert` adds or edits by id (nothing to provision — the scheduler picks it up on its
+// runs + next fire time. `upsert` adds or edits by id (nothing to provision, the scheduler picks it up on its
 // next poll); `setEnabled` changes only the switch, so a list-row action never has to reconstruct the record.
 // `remove` deletes.
 // The `pending*` routes are the owner's approval queue: a `requireApproval` automation holds each fire here
 // instead of waking; `approve` runs the held wake, `reject` drops it.
 export const automationsContract = {
     list: oc.route({ method: "GET", path: "/automations" }).output(AutomationsListSchema),
-    /* WHAT CAN WAKE AN AGENT HERE, and what to start from — the daemon's own sources and templates merged with
+    /* WHAT CAN WAKE AN AGENT HERE, and what to start from, the daemon's own sources and templates merged with
      * every installed extension's. The composer's entire vocabulary, so that adding a trigger to an area is a
      * change to that area and to nothing else. `upsert` below validates against the same merge, which is what
      * keeps the surface and the daemon from disagreeing about what is allowed. */
@@ -26,18 +26,18 @@ export const automationsContract = {
     upsert: oc.route({ method: "POST", path: "/automations" }).input(AutomationSchema).output(OkSchema),
     setEnabled: oc.route({ method: "POST", path: "/automations/{id}/enabled" }).input(AutomationEnabledInputSchema).output(OkSchema),
     remove: oc.route({ method: "DELETE", path: "/automations/{id}" }).input(AutomationIdParamSchema).output(OkSchema),
-    /* Fire one automation NOW, by hand — the answer to "I wrote a 3 a.m. cron and I have no way to try it".
+    /* Fire one automation NOW, by hand, the answer to "I wrote a 3 a.m. cron and I have no way to try it".
      * It runs the SAME path the real trigger runs: a schedule stays a headless main-tree wake, because a
      * test-fire that proves an isolated worktree works proves nothing about the fire it is standing in for. The
      * guard runs too ("skipped by guard" is the most useful thing this can report); only the approval gate is
      * skipped, since pressing the button IS the owner's approval.
      *
-     * Owner-explicit, so a DISABLED automation fires as well — trying a prompt before switching it on is the
+     * Owner-explicit, so a DISABLED automation fires as well, trying a prompt before switching it on is the
      * main reason to press this, and unlike the /automations/{id}/fire webhook there is no outside sender here to
      * fail closed against.
      *
      * NOT FOR A LISTENER, which is the one trigger whose fire is nothing without the thing that fired it. A
-     * listener's prompt is a brief about handling the events riding with it, and by hand there are none — so the
+     * listener's prompt is a brief about handling the events riding with it, and by hand there are none, so the
      * button could only ever produce an agent told to handle events, handed none, asking where they went. Worse,
      * that pointless run took the automation's turn: a real mention arriving while it ran had to wait behind it.
      * Refused here rather than hidden in the UI alone, because the honest answer to "how do I test this" is to

package/src/contracts/capabilities.contract.ts

@@ -19,14 +19,14 @@ import {
 /* The sandbox's unified capability manifest. `list` returns each active capability with its live status, the
  * non-secret echo of its config, and the NAMES of the credentials it holds. `add` upserts a capability and
  * STREAMS its apply (devops scaffolding / service provisioning emit ndjson progress; mcp/integration emit a
- * terminal frame), mirroring the /intentic runner. `remove` tears it down (devops refuses — deleting the repos
+ * terminal frame), mirroring the /intentic runner. `remove` tears it down (devops refuses, deleting the repos
  * is data loss). `status` re-probes a single capability for a lazy UI refresh. `marketplace` resolves a Claude
  * Code plugin marketplace repo into installable plugin-capability configs.
  *
  * `add` IS ALSO THE EDIT, because the write is an upsert: the same id with a changed config changes that
  * connection. A caller editing one has never been shown its credentials, so it sends VAULTED
  * (capability-secrets.ts) for each it is leaving alone and the daemon resolves those from what is stored before
- * anything runs — the only way to change one setting on a tunnel without re-typing its key. A marker with
+ * anything runs, the only way to change one setting on a tunnel without re-typing its key. A marker with
  * nothing behind it is refused rather than written. */
 export const capabilitiesContract = {
     list: oc.route({ method: "GET", path: "/capabilities" }).output(CapabilitiesListSchema),
@@ -34,24 +34,24 @@ export const capabilitiesContract = {
     remove: oc.route({ method: "DELETE", path: "/capabilities/{id}" }).input(CapabilityIdParamSchema).output(OkSchema),
     /* Give a connection a different name, carrying what the old one keyed: a browser profile with its logins,
      * a connected machine's enrollment, an extension's checkout. The name is the agent's handle for the thing,
-     * so this is a migration — add + remove would lose exactly the state that makes the connection worth
+     * so this is a migration, add + remove would lose exactly the state that makes the connection worth
      * keeping. A kind whose name is part of what it IS (the scaffolders, the one-per-sandbox cards) refuses. */
     rename: oc.route({ method: "POST", path: "/capabilities/{id}/rename" }).input(CapabilityRenameSchema).output(OkSchema),
     // Replace just the secret in a capability's config (the /secrets page's edit) and re-run its apply.
     setSecret: oc.route({ method: "POST", path: "/capabilities/{id}/secret" }).input(CapabilitySecretInputSchema).output(OkSchema),
     status: oc.route({ method: "GET", path: "/capabilities/{id}/status" }).input(CapabilityIdParamSchema).output(CapabilityStatusSchema),
-    /* One capability's stored config, secrets included — how an extension BACKEND dials the service behind a
+    /* One capability's stored config, secrets included, how an extension BACKEND dials the service behind a
      * connected capability (ext-deployments reads its Komodo's key pair through this). Never a browser's: the
      * handler refuses any caller with a member identity, so only the daemon's header grants reach it, and an
-     * extension's grant reaches it only when its manifest declares the route in `permissions.daemon` — which
+     * extension's grant reaches it only when its manifest declares the route in `permissions.daemon`, which
      * is the install dialog saying, in one line, "this extension can read connected credentials". */
     connection: oc.route({ method: "GET", path: "/capabilities/{id}/connection" }).input(CapabilityIdParamSchema).output(CapabilityConnectionSchema),
     marketplace: oc.route({ method: "POST", path: "/capabilities/marketplace" }).input(MarketplaceRequestSchema).output(MarketplaceSchema),
     // "Not needed": stop offering this card until the workspace evidence behind it changes. Nothing is torn
-    // down and nothing is remembered about the card itself — only the evidence it was declined against.
+    // down and nothing is remembered about the card itself, only the evidence it was declined against.
     dismiss: oc.route({ method: "DELETE", path: "/capabilities/recommendations/{card}" }).input(CapabilityCardParamSchema).output(OkSchema),
     // Start an agent-kind capability's interactive login (its declared loginCommand) in a visible terminal
-    // session the user types into — device-code sign-in flows. Returns the session the panel attaches to.
+    // session the user types into, device-code sign-in flows. Returns the session the panel attaches to.
     login: oc.route({ method: "POST", path: "/capabilities/{id}/login" }).input(CapabilityIdParamSchema).output(CapabilityLoginSchema),
     // Mint one TOTP code from the capability's stored seed (a field its card marks `totp`). The one capability
     // read the agent token is admitted to (see auth/grants): a code expires within its period and never reveals

package/src/contracts/chores.contract.ts

@@ -2,19 +2,19 @@ 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
+ * 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
+ * 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
+    // 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,