@intentic/sandbox-contract 1.248.0 → 1.249.0

package/src/schemas/maintenance.ts

@@ -1,23 +1,14 @@
 // maintenance: the standing evidence a chore is decided from
 import { z } from "zod";
 import { WorkspaceHotspotSchema, WorkspaceKeyModuleSchema } from "./codebase-health.js";
-/* THE DAEMON SERVES FACTS; THE BROWSER DECIDES. Everything below is measurement, what a tool reported, what the
- * manifests say, when a chore last ran. Not one field here says "you should do something", and that is the whole
- * boundary: which chore is DUE is computed by @intentic/sandbox-contract/chores, which both the Maintenance view and its rail
- * badge run, so the number on the tile and the reason in the panel can never disagree. Put the verdict on the wire
- * instead and a daemon one image behind would be quietly arguing with the browser about what needs doing.
- *
- * The split inside the evidence is by COST, not by subject:
- *   probes   subprocesses (pnpm outdated, pnpm audit, knip, jscpd), minutes, so they are cached on disk with a
- *            TTL and refreshed by a background runner. A route hit never waits on one.
- *   signals  things the daemon already knows, the resident iq index's health ranking, the package manifests it
- *            reads for the dependency graph, its own node version. Recomputed per request; all of it is cheap. */
+// The daemon serves facts, never a verdict: which chore is due is computed by shared code
+// (`@intentic/sandbox-contract/chores`) so the tile and panel can't disagree. Split by cost: probes (subprocesses,
+// cached with a TTL) vs signals (cheap, recomputed per request).
 
 export const PROBE_IDS = ["outdated", "audit", "knip", "jscpd", "ui", "bundle", "mutation"] as const;
 export const ProbeIdSchema = z.enum(PROBE_IDS);
 export type ProbeId = z.infer<typeof ProbeIdSchema>;
-// One dependency the registry has moved past. `kind` is the SEMVER distance, which is the whole reason this is
-// not one number: forty patch releases behind is a morning's work and one major is a project.
+// `kind` is the semver distance; that's why this isn't collapsed to one number.
 export const OutdatedPackageSchema = z.object({
     name: z.string().describe("The dependency."),
     current: z.string().describe("What you are on."),
@@ -27,14 +18,12 @@ export const OutdatedPackageSchema = z.object({
         .describe(
             "How far apart those are. This is not one number because forty patch releases behind is a morning's work and one major version is a project.",
         ),
-    // "dependencies" / "devDependencies" / "optionalDependencies", a dev-only major is a different risk.
+    // "dependencies" / "devDependencies" / "optionalDependencies".
     section: z
         .string()
         .describe("Which part of the manifest declares it. A major version behind on a build-time tool is a different risk from one that ships."),
 });
 export type OutdatedPackage = z.infer<typeof OutdatedPackageSchema>;
-// One advisory, reduced to what a decision needs. No CVSS vector and no reference list: those are for reading on
-// the advisory page, and carrying them would put a kilobyte of prose per finding on every poll of this route.
 export const AdvisorySchema = z.object({
     name: z.string().describe("The dependency it concerns."),
     severity: z.enum(["critical", "high", "moderate", "low", "info"]).describe("How bad it is said to be."),
@@ -43,29 +32,22 @@ export const AdvisorySchema = z.object({
         .describe(
             "What it is, in one line. No scoring vector and no reference list: those are for reading on the advisory's own page, and carrying them would put a kilobyte of prose per finding on every poll.",
         ),
-    // The range that fixes it, when the advisory names one. Absent ⇒ no patch published yet, which is the case
-    // where a chore must NOT offer to bump and say so instead.
     patched: z
         .string()
         .optional()
         .describe(
             "Which versions fix it. Absent means no fix has been published, which is exactly when nothing should offer to upgrade and something should say so instead.",
         ),
-    // Whether it reaches a production dependency path. A build-time-only tool's transitive CVE is a different
-    // problem, and the chore's prompt says so rather than treating every advisory alike.
     dev: z.boolean().describe("Whether it only reaches build-time tooling, which is a different problem from one that reaches what you ship."),
 });
 export type Advisory = z.infer<typeof AdvisorySchema>;
-// knip's counts, by the kind of thing it found unreachable. Counts plus a sample rather than the full list: the
-// agent re-runs knip itself against the live tree (a list from a probe hours old would send it at files that are
-// already gone), so what travels here only has to be enough to decide whether the turn is worth starting.
+// A stale sample could send the agent chasing files already gone; it re-runs knip live anyway.
 export const DeadCodeSchema = z.object({
     files: z.number().int().nonnegative().describe("Files nothing reaches."),
     exports: z.number().int().nonnegative().describe("Exported things nothing uses."),
     types: z.number().int().nonnegative().describe("Types nothing uses."),
     dependencies: z.number().int().nonnegative().describe("Declared dependencies nothing imports."),
     devDependencies: z.number().int().nonnegative().describe("The same, for build-time ones."),
-    // A handful of the unreferenced files, for the panel to show instead of asking the reader to take "31" on faith.
     sample: z
         .array(z.string())
         .describe(
@@ -73,8 +55,6 @@ export const DeadCodeSchema = z.object({
         ),
 });
 export type DeadCode = z.infer<typeof DeadCodeSchema>;
-// jscpd's headline plus the biggest clones. `percentage` is of scanned lines, which is the figure a threshold is
-// worth setting against, a clone COUNT grows with the repo and would mean something different every quarter.
 export const DuplicationSchema = z.object({
     percentage: z
         .number()
@@ -93,18 +73,11 @@ export const DuplicationSchema = z.object({
         .describe("The largest of them."),
 });
 export type Duplication = z.infer<typeof DuplicationSchema>;
-/* ONE SWEEP OF THE UI SOURCE, serving three chores. Component files, Tailwind classes that hard-code a value, and
- * files still on a replaced framework idiom are three questions about the same tree, and asking them in three
- * probes would walk it three times for nothing.
- *
- * Counts per FILE rather than the matched text. A reader deciding whether to open something is served better by
- * "Checkout.vue · 11 hard-coded values" than by eleven class attributes, and a file path is an identity a digest
- * can be built from while a class string is not. */
+// One sweep serving three chores (components, hard-coded values, outdated idioms) rather than three probes walking the
+// same tree three times.
 export const UiScanSchema = z.object({
-    // Framework-shaped source files, tests, stories and generated output excluded. The inventory that makes a
-    // duplication finding a COMPONENT duplication finding rather than a generic one.
+    // This inventory is what makes a duplication finding a component finding, not a generic one.
     components: z.array(z.string()).describe("The interface's own source files, with tests, stories and generated output left out."),
-    // Where the design system was routed around, and how often in each file.
     bypasses: z
         .array(
             z.object({
@@ -115,9 +88,8 @@ export const UiScanSchema = z.object({
         .describe(
             "Where the design system was routed around and a value hard-coded instead. Counted per file, because a reader deciding what to open is served by a file and a number, not by eleven snippets.",
         ),
-    // Files still on an idiom their framework has replaced, grouped by which one. `id` is looked up in the stack
-    // table rather than enumerated here: the rules are a product decision that ships with the browser, and a
-    // daemon an image behind must be able to report one this schema has never heard of.
+    // `id` is looked up in the stack table, not enumerated here, so an older daemon can still report an idiom this
+    // schema predates.
     idioms: z
         .array(
             z.object({
@@ -132,15 +104,8 @@ export const UiScanSchema = z.object({
         .describe("Files still written the way their framework has since replaced."),
 });
 export type UiScan = z.infer<typeof UiScanSchema>;
-/* WHAT THE LAST BUILD ACTUALLY PRODUCED. Measured from the build output already on disk, never by running the
- * build: a maintenance probe that mutates the owner's working tree, and `dist/` appearing in their `git status`
- * is exactly that, is a worse surprise than a measurement that is sometimes a commit behind. It also means this
- * never needs the env vars, secrets or network a real production build would.
- *
- * Gzip alongside raw because gzip is what crosses the wire, and the ratio between them is the difference between
- * "this chunk is big" and "this chunk is big and incompressible", which are different problems. */
+// Read from build output on disk, never by building (no working-tree mutation, no env vars, secrets or network needed).
 export const BundleSchema = z.object({
-    // Which directory was measured, so the panel can say what it is talking about rather than implying it built.
     dir: z
         .string()
         .describe(
@@ -165,43 +130,21 @@ export const BundleSchema = z.object({
         .describe("What is in it, piece by piece."),
 });
 export type Bundle = z.infer<typeof BundleSchema>;
-/* WHAT THE SUITE WOULD NOTICE IF THE CODE BROKE. Coverage says a line ran; this says an assertion depended on it.
- *
- * The distinction is the whole reason this probe exists, and it is not theoretical here. Measured on
- * sandbox-contract's chore module — 109 hand-written tests, every line covered — 16 of 58 mutants survived, and
- * one of them flips the zero boundary in `bucketOf` that digest.ts's own comment argues is load-bearing. The test
- * that was supposed to hold it (`expect(bucketOf(0)).not.toBe(bucketOf(1))`) is written in the careful,
- * deliberately un-brittle style, and that is exactly why it cannot see the change: with the boundary moved the two
- * values are still different, so the assertion still passes.
- *
- * That is the failure this measures and nothing else in the repository can. A linter sees the assertion's shape,
- * not its power; a coverage report sees the line, not whether anything checked it. Only killing the code and
- * watching what the suite says distinguishes a test from a test-shaped thing.
- *
- * SURVIVORS, NOT JUST A SCORE. A percentage is a mood; `bucketOf: count <= 0 → count < 0 survives` is a morning's
- * work with the answer already in it. The score decides whether the chore speaks, the survivors are what makes it
- * worth speaking about. */
+// Coverage says a line ran; this says an assertion depended on it — the only way to tell a real test from a test-shaped
+// one that can't see the code change under it.
 export const MutationScoreSchema = z.object({
     score: z
         .number()
         .describe("The share of injected faults the suite caught. Not a coverage figure: coverage says a line ran, this says an assertion depended on it."),
     killed: z.number().int().nonnegative().describe("Faults the suite caught."),
     survived: z.number().int().nonnegative().describe("Faults it did not: code that can be broken with every test still green."),
-    /* Mutants that never got a verdict: ones that would not compile, and ones the configuration ignored. Kept
-     * apart from both counts above, and OUT of the score, because an unmeasured mutant is not evidence either
-     * way — the same conflation `unavailable` exists to prevent one level up.
-     *
-     * A timeout is deliberately NOT here. Stryker counts it as detected, on the reasoning that a mutant which
-     * hangs the suite is one the suite noticed, and this follows Stryker's arithmetic rather than inventing a
-     * second definition of the same word: the number on the row has to mean what the tool that produced it
-     * means, or the row is quietly arguing with its own evidence. */
+    // A timeout counts as detected here (Stryker's own convention), not as inconclusive.
     inconclusive: z
         .number()
         .int()
         .nonnegative()
         .describe("Faults it never got a verdict on, because they would not compile or were configured out. Left out of the score entirely, since neither answer is known."),
-    /* The worst offenders, named. Capped, and the cap is the point: a survivor list is only useful while it is
-     * short enough to act on, and the rest are still there on the next run. */
+    // Capped on purpose: useful only while short enough to act on; the rest reappear next run.
     survivors: z
         .array(
             z.object({
@@ -214,21 +157,14 @@ export const MutationScoreSchema = z.object({
         .describe("The surviving faults themselves. A percentage is a mood; a named line with the change that went unnoticed is a morning's work."),
 });
 export type MutationScore = z.infer<typeof MutationScoreSchema>;
-/* One probe's cached result. The three states are deliberately distinct, because a panel that collapses them
- * lies about the most important case:
- *   ok           the tool ran and reported. `facts` carries its findings, including "nothing found", which is
- *                a real answer and the one that keeps a chore quiet.
- *   unavailable  the tool is not part of this repo (knip is not a devDependency, there is no lockfile to audit).
- *                Not a failure and not evidence of health: the chore renders as unmeasured, and can never badge.
- *   failed       the tool ran and broke, a network-less audit, a jscpd that ran out of memory. Says so, with
- *                the tail of what it printed, rather than reading as "clean".
- * Merging `unavailable` into `ok`-with-zeros is how a maintenance surface ends up reporting a green repository
- * it has never actually measured. */
+// One probe's cached state; collapsing these would lie about the most important case.
+// ok: the tool ran and reported (including "nothing found", a real answer).
+// unavailable: not part of this repo (no lockfile, tool not a dependency) — not evidence of health, never badges.
+// failed: the tool ran and broke; says so, with the tail of its output.
 export const ProbeStateSchema = z.enum(["ok", "unavailable", "failed"]);
 export type ProbeState = z.infer<typeof ProbeStateSchema>;
-// The findings, discriminated by which probe produced them. Absent while the probe has never completed, and on
-// `unavailable`/`failed`, a reader must go through `state` to reach facts, so there is no shape in which a
-// missing measurement can be mistaken for a zero.
+// Discriminated by probe id; absent until the probe completes. On unavailable/failed a reader must go through `state`,
+// so a missing measurement can never look like a zero.
 export const ProbeFactsSchema = z.discriminatedUnion("id", [
     z.object({ id: z.literal("outdated"), packages: z.array(OutdatedPackageSchema) }),
     z.object({ id: z.literal("audit"), advisories: z.array(AdvisorySchema) }),
@@ -244,18 +180,13 @@ export const ProbeResultSchema = z.object({
     state: ProbeStateSchema.describe(
         "Whether the tool ran and reported, is not part of this repository at all, or broke. The middle one is not evidence of health: the check simply cannot be made here.",
     ),
-    // When the probe last COMPLETED, the age the panel shows, and what the runner's TTL is measured from.
+    // Also what the runner's TTL is measured from.
     ranAt: z.number().describe("When it last finished, in milliseconds, which is what its age is measured from."),
-    // How long it took. Shown because a seven-minute jscpd is why the tier-2 refresh is weekly, and a reader
-    // deciding whether to force a refresh deserves to know what they are asking for.
+    // Slow probes are why some tiers refresh weekly rather than on every poll.
     tookMs: z.number().int().nonnegative().describe("How long it took. Worth knowing before asking for it again: some of these run for minutes."),
     facts: ProbeFactsSchema.optional().describe(
         "What it found, including finding nothing, which is a real answer and the one that keeps a chore quiet.",
     ),
-    // On `failed`, how it broke, a bounded quote of the tool's own output, never a summary of it. On
-    // `unavailable`, what is missing, in the probe spec's own words ("no lockfile"): there is no tool output to
-    // quote when the tool never ran, and the alternative, a sentence built from the probe's name, would have an
-    // unmeasured probe claiming there is nothing to measure.
     reason: z
         .string()
         .optional()
@@ -264,70 +195,41 @@ export const ProbeResultSchema = z.object({
         ),
 });
 export type ProbeResult = z.infer<typeof ProbeResultSchema>;
-// One workspace package as its manifest declares it, what the daemon already reads to build the dependency
-// graph, carried through so chores can reason about the repo's own shape without a probe. `documented` is the
-// one derived field: whether <dir>/README.md exists, a stat per package. A package's architecture document IS
-// its README in this workspace, which is what makes that a stat on the package itself rather than a lookup.
+// One workspace package as its manifest declares it, carried through so chores can reason about the repo's shape
+// without a probe.
 export const ChorePackageSchema = z.object({
     dir: z.string().describe("Where the package lives."),
     name: z.string().describe("What it declares itself as."),
-    // The manifest's `engines` map, verbatim, the runtime chore compares it against what the daemon is running.
+    // Compared against the daemon's own runtime by the version chore.
     engines: z.record(z.string(), z.string()).optional().describe("Which runtime versions it says it needs, verbatim."),
     dependencies: z.array(z.string()).describe("What it depends on."),
     devDependencies: z.array(z.string()).describe("What it needs only to build."),
     documented: z.boolean().describe("Whether it has a README, which in this workspace is what a package's own documentation is."),
 });
 export type ChorePackage = z.infer<typeof ChorePackageSchema>;
-/* The cheap half of the evidence: what the daemon knows without starting anything. `hotspots` and `keyModules`
- * are the same rankings GET /workspace/health serves, capped tighter, a chore only ever asks whether a file has
- * ENTERED the top of the ranking, so a leaderboard is enough and a full report per repo per poll is not. */
-/* WHAT THIS REPOSITORY IS MADE OF, the facts that decide whether a chore is a QUESTION worth asking of it at
- * all, as opposed to whether the answer happens to be yes.
- *
- * The distinction is the difference between a maintenance surface that reads as attentive and one that reads as
- * generic. "Re-read the documentation against the code" in a repository with no documentation is not a chore
- * that is currently clear, it is a chore that will never make sense here, and showing it teaches the owner that
- * this list was written by someone who had not looked. Same for a Docker chore with no Dockerfile, or a CI chore
- * with no pipeline.
- *
- * These are all paths, deliberately: presence of a FILE is checkable, cheap, and cannot be argued with, which is
- * the same evidence-over-identity rule the extension activation facts follow. Every field is a list rather than a
- * boolean where the paths themselves are worth showing, a chore that says "not applicable: no Dockerfile" is
- * useful, and one that says "3 Dockerfiles: ./Dockerfile, _editor/web/Dockerfile, …" is more so. */
+// The cheap half of the evidence: what the daemon already knows without starting anything (same rankings as GET
+// /workspace/health, capped tighter).
+// Facts that decide whether a chore is even a sensible question to ask, not whether the answer is yes. All paths, not
+// booleans: file presence is cheap and checkable, and the paths themselves are worth showing.
 export const ChoreShapeSchema = z.object({
-    // The repository MAP, when one exists (docs/architecture/*.md), capped, the count is what matters, and the
-    // drift survey needs to know there is something to re-read. Package pages are READMEs and are counted per
-    // package by `ChorePackage.documented`; a repo with a map has been through the documentation flow at all,
-    // which is the question this gate actually asks.
+    // Distinct from package READMEs, counted per package by `ChorePackage.documented`.
     docs: z
         .array(z.string())
         .describe(
             "The repository's own architecture documents, when it has any. Their existence is the question: a repository with none has never been through the documentation flow at all.",
         ),
     dockerfiles: z.array(z.string()).describe("Container definitions in it."),
-    // CI pipeline definitions: .github/workflows/*.yml, .gitlab-ci.yml, and the other single-file conventions.
+    // e.g. .github/workflows/*.yml, .gitlab-ci.yml.
     ci: z.array(z.string()).describe("Pipeline definitions in it."),
-    // Whether dependencies are resolved to a lockfile, what makes an audit mean anything.
     lockfile: z.boolean().describe("Whether dependencies are pinned to exact versions, which is what makes a security audit mean anything."),
-    // A package.json at the repo root. The gate for every chore whose subject is the JavaScript dependency tree:
-    // a Rust or Go repository has no majors to be behind on and no engines field to be pinned by, and offering it
-    // those chores would be this surface guessing at what it is looking at.
+    // Also gates the engines-version chore: a Rust/Go repo has none to pin.
     packageManifest: z
         .boolean()
         .describe(
             "Whether it is a JavaScript project at all. A Rust or Go repository has no majors to be behind on, and offering it those checks would be this surface guessing at what it is looking at.",
         ),
-    /* EVERY DEPENDENCY NAME DECLARED ANYWHERE IN THE REPO, the root manifest's blocks unioned with every
-     * workspace package's, sorted and deduplicated.
-     *
-     * It is here rather than derived from `packages` because `packages` is EMPTY for a repository that is not a
-     * pnpm workspace, and the repositories these names exist to recognise, a Vite app, a Next app, an Angular
-     * CLI project, are overwhelmingly single-package. A framework gate built on `packages` would be dark in
-     * exactly the repositories it was written for, silently, which is the worst way for a gate to be wrong.
-     *
-     * NAMES, not a `framework: "react"` verdict. Which names amount to "this is a React app" is a product
-     * decision, and product decisions live in the chore book that ships with the browser, a daemon baked into an
-     * image months ago must not be the thing that decides Svelte is not a UI framework. */
+    // Not derived from `packages`, which is empty for a non-pnpm-workspace repo — exactly the single-package repos this
+    // exists to recognise.
     deps: z
         .array(z.string())
         .describe(
@@ -352,21 +254,14 @@ export const ChoreSignalsSchema = z.object({
             hotspots: z.number().describe("How many files qualify as hotspots at all."),
         })
         .describe("The repository in numbers."),
-    // Whether the index these rankings came from is current. A chore must not fire on a half-built index, and
-    // this is how the browser knows to hold its verdict rather than act on a partial ranking.
     indexed: z.boolean().describe("Whether the index these rankings came from is finished. Nothing should act on a half-built one."),
 });
 export type ChoreSignals = z.infer<typeof ChoreSignalsSchema>;
-// What a finished chore turn left behind, written by the agent, read back to decide whether the chore is still
-// due. `clean` is the important one: an agent that looked and found the tool's findings to be false positives
-// must be able to say so, or the next poll starts the same turn again forever.
+// `clean` is the important value: without it, a false-positive finding restarts the same turn forever.
 export const ChoreOutcomeSchema = z.enum(["acted", "reported", "clean"]);
 export type ChoreOutcome = z.infer<typeof ChoreOutcomeSchema>;
-/* One chore's history in one repo. The DIGEST is what makes this a debounce rather than a suppression: it is a
- * hash of the evidence that was standing when the turn ran, so a chore whose evidence has since changed is due
- * again on its own merits while one whose evidence is unchanged stays quiet, with the run still visible in the
- * panel, saying when it ran and what it concluded. Nothing here can hide a chore from the view; it only decides
- * whether the rail is allowed to speak. */
+// A debounce, not a suppression: unchanged evidence keeps the rail quiet, but the run stays visible in the panel
+// regardless.
 export const ChoreLedgerEntrySchema = z.object({
     repo: z.string().describe("Which repository."),
     chore: z.string().describe("Which chore."),
@@ -380,8 +275,6 @@ export const ChoreLedgerEntrySchema = z.object({
         .describe(
             "A fingerprint of the evidence standing at the time. A chore whose evidence has since changed is due again on its own merits; one whose evidence has not stays quiet.",
         ),
-    // Set by the owner from the panel, the chore stays visible and stays out of the badge until this passes.
-    // Distinct from opting out, which is the absence of the chore from `enabled` in the sandbox's settings.
     snoozedUntil: z
         .number()
         .optional()
@@ -390,19 +283,11 @@ export const ChoreLedgerEntrySchema = z.object({
         ),
 });
 export type ChoreLedgerEntry = z.infer<typeof ChoreLedgerEntrySchema>;
-/* A measurement that is HAPPENING, as opposed to one that has happened. The probe cache can only ever describe
- * finished work, `ranAt` is the completion stamp, so a surface reading it alone has no way to say "we are
- * measuring this right now", and the panel's re-measure button spent its whole life looking like it did nothing:
- * the request is an ack, the sweep takes minutes, and every visible fact on the row went on describing the
- * measurement it was replacing.
- *
- * `startedAt` is when the probe actually began, absent while it is still waiting behind another one, the runner
- * has ONE lane across the whole sandbox, so "queued" is a real and common state, and a reader told "measuring"
- * about a probe that has not started is being lied to about how long it has left. */
+// A measurement in progress, distinct from the cache's `ranAt` (only ever a completion stamp) — otherwise a reader has
+// no way to say "measuring now".
 export const RunningProbeSchema = z.object({
     repo: z.string().describe("Which repository."),
     id: ProbeIdSchema.describe("Which measurement."),
-    // When this was asked for. Always present, so a waiting probe can still say how long it has been waiting.
     askedAt: z.number().describe("When it was asked for, in milliseconds, so one still waiting can say how long it has waited."),
     startedAt: z
         .number()
@@ -412,9 +297,7 @@ export const RunningProbeSchema = z.object({
         ),
 });
 export type RunningProbe = z.infer<typeof RunningProbeSchema>;
-// GET /chores, every discovered repo's standing evidence, plus the ledger, in one read. One route rather than
-// one per repo because the rail badge scans ALL of them on a timer, and N requests a minute to answer "is
-// anything due" is the kind of poll that shows up in a battery graph.
+// GET /chores: every discovered repo's standing evidence, plus the ledger, in one read.
 export const ChoresReportSchema = z.object({
     repos: z
         .array(
@@ -430,17 +313,11 @@ export const ChoresReportSchema = z.object({
             "Every repository's standing evidence. One answer for all of them, because a badge polls this on a timer and one request per repository is the kind of poll that shows up in a battery graph.",
         ),
     ledger: z.array(ChoreLedgerEntrySchema).describe("What has already been done about all of it."),
-    // What the runner is measuring and what is waiting behind it, right now. Part of the standing read rather
-    // than a route of its own: it is the same question ("what does this repo currently say") asked about work in
-    // flight, and a panel that had to ask twice would show the two halves disagreeing.
     running: z
         .array(RunningProbeSchema)
         .describe(
             "What is being measured right now and what is waiting behind it. Part of this read rather than a route of its own, because a screen that had to ask twice would show the two halves disagreeing.",
         ),
-    // The daemon's own runtime, for the chore that asks whether this sandbox is running something end-of-life.
-    // Read off the process rather than a manifest: what is INSTALLED is the fact that matters, and an `engines`
-    // range is a wish.
     node: z
         .string()
         .describe(
@@ -448,18 +325,16 @@ export const ChoresReportSchema = z.object({
         ),
 });
 export type ChoresReport = z.infer<typeof ChoresReportSchema>;
-// POST /chores/probe, force one probe to re-run now, ahead of its TTL. Returns immediately; the runner does the
-// work and the next GET /chores carries the result, the same shape the panel already polls.
+// POST /chores/probe: force a re-run ahead of its TTL. Returns immediately; the result arrives on the next GET /chores.
 export const ChoreProbeRequestSchema = z.object({
     repo: z.string().min(1).describe("Which repository."),
     id: ProbeIdSchema.describe("Which measurement to retake, ahead of its usual schedule."),
 });
-// POST /chores/ledger, record a run, or snooze. Written daemon-side rather than by the browser so a chore turn
-// started from anywhere (the panel, an automation, the agent itself) lands in one ledger.
+// POST /chores/ledger: record a run, or snooze. Daemon-written so a turn started from anywhere (panel, automation,
+// agent) lands in one ledger.
 export const ChoreLedgerWriteSchema = ChoreLedgerEntrySchema;
-/* One publishability check and what it found. `warn` is a real third state, not a soft failure: the permissions
- * check has nothing to say about an extension nobody has exercised yet, and reporting that as a pass would be
- * the check lying at the exact moment it matters most. */
+// `warn` is a real third state, not a soft failure: reporting "pass" when nothing has been exercised yet would be the
+// check lying.
 export const ReadinessCheckSchema = z.object({
     id: z.string().describe("Which check."),
     label: z.string().describe("What it is called."),

package/src/schemas/panels.ts

@@ -1,66 +1,43 @@
 // panels: per-repository dev servers + the content facts extensions detect on
 import { z } from "zod";
-// Every discovered git repo under /work is one list row: its runnable-panel runtime status (a `dev` script at
-// operator/ or the repo root; the daemon runs it, auto-assigns a free port, and the preview proxy routes
-// preview-<panelKey>-<sandboxId>.<zone> to it) PLUS content facts, evidence the web app's extensions run their
-// detect() over, computed daemon-side in one pass so the browser never scans /work file-by-file.
+// Every discovered repo under /work is one row: runnable-panel status (a `dev` script the daemon runs and auto-assigns
+// a port, proxied at preview-<panelKey>-<sandboxId>.<zone>) plus content facts extensions run detect() over, computed
+// daemon-side so the browser never scans /work.
 
-/* WHERE A START THE SANDBOX IS RUNNING HAS GOT TO, between the click and the first byte served. The process
- * manager watches the pane's foreground command every couple of seconds (processes/managed-processes.ts), and
- * these four words are what that sampling can honestly say: the shell is still coming up; the install that
- * runs first when node_modules is missing is still going; the dev command is running but nothing listens yet;
- * or the command has already exited back to a prompt, which is the one a person needs told at once, because
- * the "Preparing the preview…" it would otherwise sit behind never ends. Absent once the preview proxy has
- * something to serve, and absent for anything the sandbox is not starting. */
+// Between click and first byte; `exited` matters most, since without it "Preparing the preview…" would never end.
+// Absent once something serves.
 export const PanelLaunchSchema = z.enum(["launching", "installing", "starting", "exited"]);
 export type PanelLaunch = z.infer<typeof PanelLaunchSchema>;
 
 export const PanelSummarySchema = z.object({
-    // The repo id: its root-relative dir under /work (slashes become `--` in the preview subdomain label).
+    // Root-relative dir under /work; slashes become `--` in the preview subdomain label.
     repo: z.string().describe("Which repository."),
-    // Whether the repo ships a runnable dev server (a package.json `dev` script at operator/ or the root).
+    // A package.json `dev` script at operator/ or the repo root.
     hasPanel: z.boolean().describe("Whether it has anything runnable at all."),
     running: z.boolean().describe("Whether the sandbox has it running."),
-    /* Whether its dependencies are on disk, a node_modules at the directory Start runs in. What decides what a
-     * Start COSTS: seconds when true, an install first when false, and the Start screen's copy says which
-     * instead of promising "a few minutes" over a tree that is already installed (the starter site's is: the
-     * image bakes it). True for a repo with nothing runnable, which has nothing to install for. */
+    // True for a repo with nothing runnable — nothing to install for.
     installed: z
         .boolean()
         .describe("Whether its dependencies are installed, which is what decides whether a start takes seconds or an install first."),
     launch: PanelLaunchSchema.optional().describe(
         "Where a start the sandbox is running has got to: its shell coming up, installing, its dev command running with nothing listening yet, or exited back to a prompt. Absent when nothing is starting and once it serves.",
     ),
-    // Whether anything this repo owns is answering, see `servers`. Not the same question as `running`: a panel
-    // whose install is still going is running and not yet healthy, and a dev server someone started in their own
-    // terminal is healthy without the daemon running it.
     healthy: z
         .boolean()
         .describe(
             "Whether anything it owns is actually answering. A different question: a server still installing is running and not yet healthy, and one somebody started by hand is healthy without the sandbox running it.",
         ),
-    // The dev server's OS-assigned port; absent when not running. What the daemon TOLD the repo to bind (the
-    // preview proxy forwards it), `servers` is what the repo actually bound, which for a repo that pins its own
-    // ports is a different number entirely.
     port: z
         .number()
         .optional()
         .describe(
             "The port the sandbox told it to use. What it actually bound is below, and for a repository that pins its own ports those are different numbers.",
         ),
-    // Every dev server the repo is really serving, discovered from the sandbox's listening sockets and probed for
-    // the scheme each speaks (a Vite on a committed dev cert serves https). One entry for the ordinary repo; a
-    // monorepo whose `dev` fans out across packages has one per app, which is why `dir` is here, `_editor/web` vs
-    // `_site/site` is the only thing that tells them apart. Empty when nothing answers.
-    //
-    // `session` is the terminal it is running in: the panel's own when the daemon started it, the user's when
-    // they ran it by hand, and ABSENT when nothing in the sandbox owns it. That last case is the one worth
-    // designing for, the repo is plainly answering, and no terminal here can show, stop or restart it.
+    // One entry per app for a monorepo whose `dev` fans out across packages (`dir` is what tells them apart); `session`
+    // absent means nothing in the sandbox owns it, worth designing for.
     servers: z
         .array(
             z.object({
-                // The port itself, not just the URL it appears in: forwarding one is how a repo answering on
-                // several ports becomes previewable at all, and that call takes a number.
                 port: z.number().describe("The port it is listening on, which is what forwarding it takes."),
                 url: z.string().describe("Where it answers, with the right scheme: a server on its own certificate is served over https."),
                 dir: z
@@ -78,26 +55,24 @@ export const PanelSummarySchema = z.object({
             }),
         )
         .describe("Every server this repository is really serving, found by looking at what is listening. Empty when nothing answers."),
-    /* https://preview-<repo>-<sandboxId>.<zone>, and ONLY where that address actually serves this repo: absent
-     * on a sandbox with no zone or connect token (loopback/tests), and absent whenever the preview proxy has
-     * nothing to route it to — nothing running, still starting, or (the ordinary monorepo) several dev servers
-     * on ports of their own, none of which one hostname can stand for. Present ⇒ safe to open or frame, which
-     * is what stops a surface from showing a 502 as if it were the app. */
+    // `https://preview-<repo>-<sandboxId>.<zone>`; absent whenever no single hostname could stand for what's running
+    // (nothing up, still starting, several servers).
     previewUrl: z
         .string()
         .optional()
         .describe("Where to open it from outside, present only while that address really serves it. Absent on a sandbox with no outside address."),
-    // The workspace role this repo dir occupies (the three fixed dirs); absent for extra clones.
     role: z
         .enum(["intent", "desired-state", "app"])
         .optional()
         .describe("Which of the workspace's three fixed roles this repository fills. Absent for one that was simply cloned in."),
-    // Content facts: deploy.config.ts (the intent ledger's day-one marker), desired-state.json (present after
-    // the first resolve), .intentic/ui/index.html (a sandboxed directory UI), pnpm-workspace.yaml +
-    // turbo.json (a pnpm+turbo monorepo), vitest evidence (a root vitest.config.ts, or "vitest" in the
-    // root manifest / workspace catalog), docs/user-stories (a directory of stories an agent can test
-    // against the running app, the one fact here that says nothing about the repo's language), and
-    // docs/architecture (the repo carries generated architecture documentation).
+    // Detected from specific files:
+    // deployConfig: deploy.config.ts.
+    // desiredState: desired-state.json (present after the first resolve).
+    // directoryUi: .intentic/ui/index.html.
+    // monorepo: pnpm-workspace.yaml + turbo.json.
+    // vitest: a root vitest.config.ts, or "vitest" in the manifest/workspace catalog.
+    // userStories: docs/user-stories.
+    // docs: docs/architecture.
     deployConfig: z.boolean().describe("It declares infrastructure."),
     desiredState: z.boolean().describe("That declaration has been resolved at least once."),
     directoryUi: z.boolean().describe("It carries a small interface of its own."),