@intentic/sandbox-contract 1.248.0 → 1.250.0

package/src/schemas/extension-updates.ts

@@ -1,53 +1,46 @@
-// extensions: installed extension-kind capabilities resolved to their manifests
-// extension updates: what the registry check found, and what the owner decided to do about such findings
+// Extensions: installed extension-kind capabilities resolved to their manifests; extension updates: what the registry
+// check found and what the owner decided to do about it.
 import { z } from "zod";
 import { ExtensionManifestSchema } from "@intentic/extension-manifest";
-// What the web extension host boots from: each row is an extension capability whose checkout still parses,
-// the approved manifest (contribution declarations), and the checked-out commit (the code identity; the bundle
-// route's ETag). A rotted checkout is skipped here; its capability row still shows status.
-// The routing handle: a git-installed extension uses its capability entry id; an image-baked one has no
-// capability entry and is addressed by the manifest-derived publisher.name, hence the dot in the pattern.
+// Each extension is addressed by its capability entry id (git-installed) or its manifest's `publisher.name`
+// (image-baked, no entry), hence the dot allowed here. A rotted checkout is skipped; its capability row still shows
+// status.
 const extensionId = z
     .string()
     .min(1)
     .max(121)
     .regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/);
-// The owner's per-extension update posture. `updates` is the ladder: `notify` (badge and wait, the default),
-// `agent` (the discovery also prepares an agent diff-read of the new sha), `auto` (apply unattended, but only
-// a verified listing whose powers didn't grow, health-watched with auto-revert, anything less falls back to
-// notify). `advisories` is separate because its safe direction is the opposite: disabling runs no new code, so
-// `auto-disable` is the default and `notify` is the opt-out.
+// Owner's per-extension update posture.
+// updates: notify (default, badge and wait), agent (also prepares an agent diff-read), auto (apply unattended if
+// verified and powers didn't grow, health-watched with auto-revert; otherwise falls back to notify).
+// advisories: auto-disable (default, since disabling runs no new code) or notify.
 export const ExtensionUpdatePolicySchema = z.object({
     updates: z.enum(["notify", "agent", "auto"]),
     advisories: z.enum(["auto-disable", "notify"]),
 });
 export type ExtensionUpdatePolicy = z.infer<typeof ExtensionUpdatePolicySchema>;
-// A newer sha the registry lists for an installed extension, the "update available" badge's substance. The
-// pointer (url/path) rides along because updating follows the ROW as it stands now, not the install as it was.
+// A newer sha the registry lists, the update-available badge's substance. `url`/`path` ride along because updating
+// follows this row as it stands now, not the original install.
 export const ExtensionUpdateSchema = z.object({
     ref: z.string().describe("The commit being offered."),
     version: z.string().optional().describe("What it calls itself."),
     url: z.string().describe("Where it comes from."),
     path: z.string().optional().describe("Where inside that repository it lives."),
     trust: z.enum(["verified", "listed"]).describe("Whether anybody vouched for it, or it is merely listed."),
-    // The listing says this release fixes a security problem in earlier ones, the badge goes loud, because
-    // here the OLD version is the dangerous one.
+    // The badge renders loud (urgent) when this is set.
     securityFix: z
         .boolean()
         .optional()
         .describe("This release fixes a security problem in earlier ones, so here the old version is the dangerous one."),
     registry: z.string().describe("Which registry said so."),
     at: z.string().describe("When it was published."),
-    // Why the auto rung refused this one and fell back to notify ("powers grew", "not verified"), the card
-    // leads with it so the owner knows the click is theirs for a reason.
+    // The card leads with this, so the owner knows why the decision is theirs.
     needsReview: z
         .string()
         .optional()
         .describe(
             "Why this one was not taken automatically and is asking for a person instead: it wants more than it used to, or nobody has vouched for it.",
         ),
-    // The agent-prepared rung's work: the conversation where the owner's agent already read the diff between
-    // the installed sha and this one. The card links it instead of offering to start it.
     review: z
         .object({
             conversationId: z.string().describe("Where to read what it found."),
@@ -59,8 +52,7 @@ export const ExtensionUpdateSchema = z.object({
         ),
 });
 export type ExtensionUpdate = z.infer<typeof ExtensionUpdateSchema>;
-// The registry blocked this installed extension's listing. Delisting protects people browsing; this record is
-// for the person already running it, the reason verbatim, and whether the daemon already pulled the switch.
+// This installed extension was delisted; the record is for someone still running it.
 export const ExtensionAdvisorySchema = z.object({
     reason: z
         .string()
@@ -72,9 +64,7 @@ export const ExtensionAdvisorySchema = z.object({
     autoDisabled: z.boolean().describe("Whether the sandbox has already switched it off."),
 });
 export type ExtensionAdvisory = z.infer<typeof ExtensionAdvisorySchema>;
-// The post-update watch: validation catches broken, not wrong, so for a minute after a swap the daemon checks
-// that what the new version declared actually came up (autoStart processes running, backend activated).
-// `fromRef` is the sha the kept-previous checkout holds, what a revert returns to.
+// Checks that the new version's declared autoStart processes and backend actually came up.
 export const ExtensionHealthSchema = z.object({
     state: z
         .enum(["watching", "healthy", "unhealthy"])
@@ -82,25 +72,22 @@ export const ExtensionHealthSchema = z.object({
     detail: z.string().optional().describe("What is going wrong, when something is."),
     fromRef: z.string().optional().describe("Which version it was updated from, which is what going back would return to."),
     at: z.string().describe("When the watching started."),
-    // The auto rung's failure path already ran: the update was rolled back unattended, and the record stays to
-    // say so rather than pretending the attempt never happened.
     autoReverted: z
         .boolean()
         .optional()
         .describe("The update was already rolled back without anybody asking. The record stays rather than pretending the attempt never happened."),
 });
 export type ExtensionHealth = z.infer<typeof ExtensionHealthSchema>;
-// The mechanical comparison of two manifests' declared reach (extension-manifest's diffPowers), plain
-// sentences, so the update dialog renders exactly what approval is being asked to cover.
+// Mechanical comparison of two manifests' declared reach (`diffPowers`), as plain sentences the update dialog can
+// render directly.
 export const PowersDiffSchema = z.object({
     added: z.array(z.string()).describe("What the new version asks for that the running one does not. The whole point of the comparison."),
     removed: z.array(z.string()).describe("What it no longer asks for."),
     unchanged: z.array(z.string()).describe("What stays the same."),
 });
 export type PowersDiff = z.infer<typeof PowersDiffSchema>;
-// What an owner reads before clicking Update: the offered sha's manifest folded to the version story, the
-// engines verdict, and the powers diff against the installed manifest. `ref` optional on the way in, absent
-// means "the update the check recorded", which is the only caller most of the time.
+// What an owner reads before clicking Update: the offered version's story, the engines verdict, and its powers diff
+// against what is installed.
 export const ExtensionUpdateActionSchema = z.object({
     id: extensionId.describe("Which extension."),
     ref: z
@@ -119,8 +106,7 @@ export const ExtensionUpdatePreviewSchema = z.object({
         "Exactly what the new code asks for that the running one does not. This is what approving an update is approving.",
     ),
 });
-// `rebuildNeeded` (update only): the new version's environment fragment changed the composed overlay, so the
-// card must say a one-time image rebuild is pending rather than let the update read as wholly landed.
+// Environment fragment change that alters the composed overlay; the update is not wholly landed until rebuilt.
 export const ExtensionUpdateAppliedSchema = z.object({
     ok: z.literal(true).describe("It went through."),
     ref: z.string().describe("Which commit is now running."),
@@ -147,43 +133,26 @@ export const ExtensionSummarySchema = z.object({
     id: extensionId.describe("The extension's id."),
     manifest: ExtensionManifestSchema.describe("What it declares about itself: what it contributes, what it needs, and what it may reach."),
     commit: z.string().describe("Exactly which commit is installed."),
-    /* Where the code comes from, which is also what the web varies per row: `builtin` (image-baked, no git
-     * checkout, not removable) hides the uninstall affordance, `installed` (a git capability) shows the pinned
-     * commit, `workspace` (a directory under .intentic/config/workspace-extensions/, created and edited in place,
-     * typically by an agent) is "uninstalled" by deleting its directory. */
+    // builtin: hides the uninstall affordance.
+    // installed: shows the pinned commit.
+    // workspace: "uninstalled" by deleting its directory.
     source: z
         .enum(["builtin", "installed", "workspace"])
         .describe(
             "Where the code comes from: baked into the sandbox image and not removable, installed from a repository at a pinned commit, or written in this workspace and edited in place.",
         ),
-    // The owner's switch (.intentic/config/extension-enablement.json). A disabled extension is still listed, that's
-    // what makes it switchable back on, but the daemon wires none of its contributions up and the web host
-    // doesn't activate it.
+    // Persisted at .intentic/config/extension-enablement.json.
     enabled: z
         .boolean()
         .describe(
             "The owner's switch. A switched-off extension is still listed, which is what makes it switchable back on, but nothing it contributes is wired up.",
         ),
-    /* THE SWITCH IS FIXED ON, this extension is the only control surface for an engine the daemon runs
-     * regardless. The automations scheduler fires turns on a clock whether or not anything draws them, and
-     * hiding the one page that can see, stop or approve those fires would not stop the spend, it would only
-     * remove the owner's ability to notice it. So the daemon refuses the flip, and the tab draws the switch as
-     * fixed with this fact as the reason.
-     *
-     * Declared by the CORE about its own engines' surfaces, never by a manifest: a field an extension could set
-     * on itself would be a pack making itself un-removable, which is a self-granted privilege the approval flow
-     * exists to prevent. */
     essential: z
         .boolean()
         .optional()
         .describe(
             "Its switch is fixed on, because it is the only way to see or stop an engine the sandbox runs regardless. Hiding that page would not stop the spending, only your ability to notice it. Declared by the core about its own surfaces, never by an extension about itself, which would be a pack making itself un-removable.",
         ),
-    /* How much of the reach this extension asked for it has actually used, keyed by the DECLARED entry so a row
-     * joins straight onto `permissions.sandbox`. Absent for an extension that has never been observed calling
-     * anything, which is a different claim from "uses none of them" and has to stay tellable: a freshly installed
-     * extension has an empty ledger and an unexercised one does too, and reading either as "these permissions are
-     * unnecessary" would turn this from evidence into a guess with a number on it. */
     usage: z
         .record(
             z.string(),
@@ -193,11 +162,7 @@ export const ExtensionSummarySchema = z.object({
         .describe(
             "How much of the reach it asked for it has actually used, keyed by what it declared. Absent means never observed doing anything, which is a different claim from uses none of them, and the two have to stay tellable apart: reading either as these permissions are unnecessary turns evidence into a guess with a number on it.",
         ),
-    /* The BACKEND half's state, present only for an extension whose manifest ships a `server` bundle: what the
-     * daemon's backend host reports for it (running / an activation error with its message), or what only the
-     * daemon can know (absent, the code is not in this image; incompatible, its engines exclude this daemon;
-     * starting/stopped, the host itself is between states). The tab renders it beside the row so a backend
-     * that failed to activate is a sentence, not a namespace that 404s. */
+    // starting/stopped mean the host itself is between states.
     backend: z
         .object({
             state: z
@@ -212,10 +177,12 @@ export const ExtensionSummarySchema = z.object({
         })
         .optional()
         .describe("Present only for an extension that ships a server half."),
-    /* The update lifecycle, present only where it can exist, a git-installed extension. `update` is the badge,
-     * `advisory` the alarm, `health` the after-the-click watch, `previous` the way back (the kept one-back
-     * checkout's sha), `updatePolicy` the owner's standing answer. A builtin updates with the image and a
-     * workspace one is live-edited, so all five stay absent for them. */
+    // Update lifecycle, present only for a git-installed extension (absent for builtin/workspace):
+    // update: the badge.
+    // advisory: the alarm.
+    // health: the after-the-click watch.
+    // previous: the way back (kept one-back checkout's sha).
+    // updatePolicy: the owner's standing answer.
     update: ExtensionUpdateSchema.optional().describe(
         "A newer version waiting. All five of these exist only for one installed from a repository: a built-in updates with the image and one written here is edited live.",
     ),
@@ -233,9 +200,7 @@ export const ExtensionSummarySchema = z.object({
     ),
 });
 export type ExtensionSummary = z.infer<typeof ExtensionSummarySchema>;
-// A workspace-extension directory that failed to enumerate, and why. Its only feedback channel: there is no
-// install moment to reject a bad manifest, so the parse failure (or id collision) rides the list instead of
-// silently dropping the row, the Extensions tab renders it, and an authoring agent reads it off GET /extensions.
+// Read by both the Extensions tab and an authoring agent off GET /extensions.
 export const InvalidWorkspaceExtensionSchema = z.object({
     dir: z.string().describe("Which folder."),
     error: z.string().describe("Why it could not be read."),
@@ -248,8 +213,6 @@ export const ExtensionsListSchema = z.object({
         .describe(
             "Extensions written here that could not be read at all. Listed rather than dropped, because there is no install moment at which to reject a broken one, so this is its only way of saying anything.",
         ),
-    // When the registry comparison last ran, absent until the first check completes. Serving it on the list is
-    // what lets the tab say "checked an hour ago" instead of presenting staleness as certainty.
     updatesCheckedAt: z
         .string()
         .optional()
@@ -257,10 +220,8 @@ export const ExtensionsListSchema = z.object({
             "When updates were last looked for. Absent until the first check has run. Sent so a screen can say checked an hour ago rather than presenting staleness as certainty.",
         ),
 });
-// The extension's contributes.settings values, persisted daemon-side (.intentic/config/extension-settings.json) keyed
-// by the manifest-derived extension id, the checkout stays pristine, so a re-clone update never loses them.
-// Secret-marked values are stripped from `settings`; `secretsSet` lists the secret keys that DO hold a value,
-// so the UI renders "•••• (set)" without ever receiving the secret back.
+// Persisted at .intentic/config/extension-settings.json, keyed by extension id so a re-clone never loses them. Secret
+// values are stripped from `settings`; `secretsSet` names which ones are set.
 export const ExtensionSettingsSchema = z.object({
     settings: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).describe("The values, minus anything marked secret."),
     secretsSet: z
@@ -274,16 +235,14 @@ export const ExtensionSettingsInputSchema = z.object({
         .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
         .describe("The values to write. A key the extension never declared is refused rather than quietly stored."),
 });
-// Flip one extension on or off. Persisted by publisher.name (like settings), so the choice outlives the
-// checkout; the daemon's immediate half of the flip, declared processes, converges in the same handler.
+// Persisted by publisher.name (like settings) so the choice outlives the checkout; declared processes converge in the
+// same handler.
 export const ExtensionEnabledInputSchema = z.object({
     id: z.string().describe("Which extension."),
     enabled: z.boolean().describe("On or off."),
 });
-/* Create a workspace extension: the identity, and deliberately nothing else. What gets written is the daemon's
- * decision, not a form the author fills in, the point of the action is that a running extension exists a second
- * after it is asked for, and shaping it happens by editing the files it wrote (or by asking an agent to). The two
- * slugs are the same shape the manifest schema demands, checked again here because `name` becomes a directory. */
+// Identity only; what gets written is the daemon's decision, not a form filled in — shaping happens by editing the
+// files afterward. Slugs match the manifest schema's shape, re-checked here because `name` becomes a directory.
 export const WorkspaceExtensionCreateSchema = z.object({
     publisher: z
         .string()
@@ -294,23 +253,19 @@ export const WorkspaceExtensionCreateSchema = z.object({
         .regex(/^[a-z0-9][a-z0-9-]*$/)
         .describe("What it is called."),
 });
-// Where it landed. `dir` is workspace-root-relative so the caller can name the files it should open next.
+// `dir` is workspace-root-relative, so the caller can name files to open next.
 export const WorkspaceExtensionCreatedSchema = z.object({
     id: z.string().describe("The id it was given."),
     dir: z.string().describe("Where its files are, so you can open them."),
 });
-/* Batches of calls the host observed against extensions' declared routes: extension id → declared entry → how
- * many since the last report. Counts rather than events, and declared entries rather than concrete paths,
- * because the question the ledger answers is "is this permission earned?": a finer record would be a log of
- * what the owner was doing, indexed by extension, which is not a thing this product should be accumulating to
- * answer it. Every extension rides one request so the bookkeeping cannot become its own request burst. */
+// Extension id → declared entry → count since last report; counts, not events, and declared entries, not paths, since
+// this answers whether a permission is earned, not logs activity. One request per batch across all extensions.
 export const ExtensionUsageBatchSchema = z.object({
     reports: z
         .record(z.string(), z.record(z.string(), z.number().int().positive()))
         .describe("Each extension that called something, and the counts against the declared powers it exercised."),
 });
-// One declared background process (contributes.processes), status/start/stop, addressed by the capability
-// entry id + the manifest's process name. Undeclared names are NOT_FOUND, the manifest-honesty rule again.
+// One declared background process, addressed by capability entry id + process name; an undeclared name is NOT_FOUND.
 export const ExtensionProcessParamSchema = z.object({
     id: z.string().describe("Which extension."),
     name: z.string().describe("Which of its declared processes."),

package/src/schemas/git-history.ts

@@ -1,15 +1,12 @@
-// git history graph (the "Git Graph" view over a repo's real commits)
+// The Git Graph view over a repo's real commits.
 import { z } from "zod";
 import { GitChangeSchema } from "./git.js";
 import { RefNameSchema } from "./internal.js";
 import { RepoParamSchema } from "./shared.js";
-// A hex sha (full or git-abbreviated): the only shape the graph ever sends back, so the per-commit routes
-// constrain to it rather than accepting an arbitrary git revision expression.
+// A hex sha, full or abbreviated; commit routes accept only this, never an arbitrary git revision expression.
 const ShaSchema = z.string().regex(/^[0-9a-f]{4,64}$/);
-// One commit in the graph. `parents` (0 = root, 1 = normal, 2+ = merge) drive the lane layout, computed
-// client-side. `refs` are the branch/tag decorations at this commit (tags keep their `tag: ` prefix; the bare
-// "HEAD" marker is lifted into `head` instead). `at` is author time in ms since epoch; `short` is git's
-// abbreviated sha; `body` is the message minus its subject line.
+// One commit in the graph. `parents` drives lane layout, computed client-side; `refs` keeps tags' `tag: ` prefix but
+// lifts a bare HEAD marker into `head` instead.
 export const GitCommitSchema = z.object({
     sha: z.string().describe("The commit, in full."),
     short: z.string().describe("The abbreviated form, for showing."),
@@ -27,15 +24,13 @@ export const GitCommitSchema = z.object({
     head: z.boolean().describe("Whether this is where the repository currently stands."),
 });
 export type GitCommit = z.infer<typeof GitCommitSchema>;
-// One repo's log: commits newest-first across ALL refs (branch topology is the point of a graph), plus the
-// checked-out branch (absent on a detached HEAD or an unborn repo).
+// One repo's log: commits newest-first across all refs, not just the checked-out branch, since branch topology is the
+// point of a graph.
 export const GitLogSchema = z.object({
     repo: z.string().describe("Which repository."),
     branch: z.string().optional().describe("Which branch these are from."),
     commits: z.array(GitCommitSchema).describe("The commits, newest first."),
-    // Whether a further page exists behind this one. The daemon learns it by asking git for one commit more than
-    // it returns, see commitLog. It is also what stops the oldest row of a page from being drawn as a ROOT
-    // commit, which is how a truncated history used to claim it began where the page happened to stop.
+    // Whether older commits remain behind this page; also stops the last row from being drawn as history's root.
     hasMore: z
         .boolean()
         .describe(
@@ -45,9 +40,7 @@ export const GitLogSchema = z.object({
 export type GitLog = z.infer<typeof GitLogSchema>;
 export const GitLogQuerySchema = RepoParamSchema.extend({
     limit: z.coerce.number().int().positive().max(2000).optional().describe("How many commits to return."),
-    // How many newer commits to step over, the page cursor. Paged rather than one big read because a large
-    // repository's log is tens of thousands of rows, and every one of them costs a zod validation, a wire
-    // payload and a lane computation before anything is drawn.
+    // Page cursor: how many newer commits to skip before returning results.
     skip: z.coerce
         .number()
         .int()
@@ -58,18 +51,13 @@ export const GitLogQuerySchema = RepoParamSchema.extend({
             "How many newer commits to step over, which is how you page further back. Paged rather than read whole, because a large repository's history is tens of thousands of rows.",
         ),
 });
-// Every real git repo under /work as root-relative dir ids ("root" is implicit, the /work repo itself).
+// Every real git repo under /work, as root-relative dir ids; "root" is the /work repo itself, implicit as an id.
 export const GitReposSchema = z.object({
     repos: z.array(z.string()).describe('Every repository\'s id. The workspace itself is always present as "root".'),
 });
 export type GitRepos = z.infer<typeof GitReposSchema>;
-/* WHERE EACH WORKSPACE REPO LIVES ONLINE, one entry per repo that has a parseable remote, as the host and the
- * `owner/name` project it names. Separate from `repos` above rather than folded into it because that route is
- * on the file tree's hot path and this costs a `git remote -v` per repo; a caller that wants to recognise a
- * workspace repo in somebody else's list (the publisher claim does exactly that) asks for it deliberately.
- *
- * A repo with no remote, or one naming a local path, is absent rather than present-and-empty: "this repo is
- * nowhere online" and "this repo is at X" are different answers and only one of them can be matched against. */
+// One entry per workspace repo with a parseable remote, as host and owner/name. Absent, not present-and-empty, when
+// there's no remote or it points at a local path.
 export const GitRemoteRepoSchema = z.object({
     repo: z.string().describe("The workspace repository."),
     host: z.string().describe("Which forge its remote points at."),
@@ -80,31 +68,15 @@ export const GitRemoteReposSchema = z.object({
     repos: z.array(GitRemoteRepoSchema).describe("Each repository matched to the project its remote points at."),
 });
 export type GitRemoteRepos = z.infer<typeof GitRemoteReposSchema>;
-/* PUT ONE FILE ON THE DEFAULT BRANCH AND PUBLISH IT, write, commit that path alone, push, in one call.
- *
- * One route rather than three because the interesting states are the ones BETWEEN the steps: a file written but
- * not committed, or committed but not pushed, is a repo the user now has to clean up by hand, and a browser
- * making three requests owns that mess without being able to describe it. Here the caller gets one answer that
- * says how far it got.
- *
- * `message` is the caller's because the commit shows up in the user's own history and a generic subject there
- * is litter. */
+// Writes one file to the default branch and publishes it: write, commit that path alone, push, in one call. `message`
+// is the caller's, since it lands in the user's own commit history.
 export const GitPublishFileSchema = RepoParamSchema.extend({
     path: z.string().min(1).describe("Which file, relative to the repository."),
     content: z.string().describe("Its whole new contents."),
     message: z.string().min(1).describe("The commit message."),
 });
-/* HOW FAR THE PUBLISH GOT, in the terms the screen has to explain it in. `ok` is "the file is on the default
- * branch of the remote" and nothing less, the only state that makes a public read of it succeed.
- *
- * The three steps are reported SEPARATELY because every boundary between them is a state a user can be left
- * in and would otherwise have to discover: a file written but not committed, a commit that exists locally but
- * was refused by the remote for credentials. Each of those needs a different sentence and a different next
- * move, and one `ok: false` cannot carry either. It is also what tells the daemon whether the worktree moved
- * at all, which decides whether this counts as a user write on the timeline.
- *
- * `branch` and `defaultBranch` ride along so a refusal can name both sides of the mismatch rather than saying
- * "wrong branch" at someone who cannot see which one they are on. */
+// `ok` is true only once the file is live on the default branch of the remote. `wrote`/`committed`/`pushed` mark each
+// step separately, and `branch`/`defaultBranch` name a wrong-branch mismatch.
 export const GitPublishFileResultSchema = z.object({
     ok: z.boolean().describe("Whether the whole thing went through."),
     wrote: z.boolean().describe("The file was written."),
@@ -121,9 +93,8 @@ export const GitPublishFileResultSchema = z.object({
 });
 export type GitPublishFileResult = z.infer<typeof GitPublishFileResultSchema>;
 export const GitCommitDiffQuerySchema = RepoParamSchema.extend({ sha: ShaSchema.describe("Which commit.") });
-// A commit's changed files (vs its first parent; a root commit vs the empty tree), the graph's detail tree
-// renders these (line stats included) and reuses the diff UI on click. Just GitChanges: the line stats live on
-// GitChange now, so working-tree and commit files share one shape.
+// A commit's changed files, diffed against its first parent (a root commit against the empty tree); reuses `GitChange`
+// so working-tree and commit diffs share one shape.
 export const GitCommitDiffSchema = z.object({
     files: z
         .array(GitChangeSchema)
@@ -136,13 +107,8 @@ export const GitCommitFileDiffQuerySchema = RepoParamSchema.extend({
     sha: ShaSchema.describe("Which commit."),
     path: z.string().min(1).describe("Which file in it."),
 });
-// Git write actions from the graph's commit context menu (VSCode "Git Graph" parity). Non-destructive: branch
-// and tag just add a ref (HEAD + worktree untouched, no checkpoint). Sequence ops (revert / cherry-pick /
-// merge / rebase / drop) add or replay commits and are auto-checkpointed daemon-side; a conflict aborts and
-// reports `ok:false` (an expected outcome, not a throw). Checkout and reset move HEAD (reset --hard discards
-// the worktree), also auto-checkpointed. A `{repo, sha}` names the target commit for every commit-scoped
-// action; a ref name (branch/tag) is validated structurally, git enforces the rest of ref-name legality
-// (RefNameSchema is declared above, with the branch schemas that first use it).
+// Git write actions from the graph's context menu. Branch/tag only add a ref (no checkpoint); sequence ops, checkout,
+// and reset are auto-checkpointed, and a conflict returns `ok:false` instead of throwing.
 export const GitBranchCreateSchema = RepoParamSchema.extend({
     sha: ShaSchema.describe("Which commit to start it at."),
     name: RefNameSchema.describe("The new branch's name."),
@@ -152,13 +118,12 @@ export const GitTagCreateSchema = RepoParamSchema.extend({
     name: RefNameSchema.describe("The tag's name."),
 });
 export const GitCheckoutSchema = RepoParamSchema.extend({ ref: RefNameSchema.describe("Where to switch to: a branch, a tag, or a commit.") });
-// Deleting a tag locally, and, when a remote is named, on that remote too. The remote half is best-effort: a
-// tag that was never pushed must not make deleting the local one report a failure.
+// Deletes a tag locally, and on the named remote too; a tag never pushed there does not fail the local delete.
 export const GitTagDeleteSchema = RepoParamSchema.extend({
     name: RefNameSchema.describe("Which tag."),
     remote: RefNameSchema.optional().describe("Also delete it there. Leave it out to remove it locally only."),
 });
-// Publishing ONE tag, named explicitly so it never drags every other unpushed tag along with it.
+// Pushes only the named tag, never every unpushed tag.
 export const GitTagPushSchema = RepoParamSchema.extend({
     name: RefNameSchema.describe("Which tag."),
     remote: RefNameSchema.describe("Which remote to send it to."),
@@ -182,21 +147,13 @@ export const GitActionResultSchema = z.object({
         ),
 });
 export type GitActionResult = z.infer<typeof GitActionResultSchema>;
-/* THE STASH, work set aside without committing it, and the one part of a repository's real state the workspace
- * used to be blind to entirely. A `git stash` in a terminal made the agent's (or the user's) work vanish from
- * every surface here.
- *
- * An entry IS a commit: it has a sha, a time, a diff, and parents (HEAD when it was taken, the index, and the
- * untracked tree when `-u` was used). What it does not have is a place in any branch's ancestry, so the graph
- * hangs it off the commit it was taken on rather than flowing it down a lane.
- *
- * `ref` (`stash@{0}`) is the handle every verb takes, and it is POSITIONAL, dropping one renumbers the rest, so
- * a caller must re-read the list after any mutation rather than holding an index across it. */
+// A stash entry is a commit (sha, time, diff, parents) with no place in any branch's ancestry. `ref` (`stash@{0}`) is
+// positional: dropping one renumbers the rest, so re-read the list after any mutation.
 export const StashEntrySchema = z.object({
     ref: z.string().describe("How to address it, which applying and dropping take."),
     sha: z.string().describe("The commit behind it, because a stash entry is a commit."),
     short: z.string().describe("The abbreviated form, for showing."),
-    // git's own `WIP on <branch>: …` scaffolding stripped, leaving what a reader would call the message.
+    // Git's `WIP on <branch>: ` prefix is stripped from the raw stash message.
     subject: z.string().describe("What it was set aside as, with git's own scaffolding stripped off."),
     branch: z.string().optional().describe("Which branch it was set aside from."),
     at: z.number().describe("When, in milliseconds."),
@@ -207,31 +164,21 @@ export const StashListSchema = z.object({
     repo: z.string().describe("Which repository."),
     stashes: z.array(StashEntrySchema).describe("What is set aside, newest first."),
 });
-// A stash ref as git numbers them. Constrained rather than free text because it reaches a shell argument.
+// A stash ref as git numbers it (`stash@{0}`); constrained because it reaches a shell argument.
 const StashRefSchema = z.string().regex(/^stash@\{\d{1,4}\}$/);
 export const StashPushSchema = RepoParamSchema.extend({
     message: z.string().max(500).optional().describe("What to call it, so you know what it was later."),
     includeUntracked: z.boolean().optional().describe("Also set aside files git is not yet tracking, which are otherwise left where they are."),
 });
-// `pop` drops the entry on a clean apply; `apply` keeps it. Git's own distinction, and both are things people
-// mean: pop is "resume this", apply is "try this here too".
+// `pop` drops the entry after a clean apply; `apply` keeps it, git's own resume-vs-try-again distinction.
 export const StashApplySchema = RepoParamSchema.extend({
     ref: StashRefSchema.describe("Which entry."),
     pop: z.boolean().optional().describe("Remove it from the stash once it has been applied cleanly."),
 });
 export const StashRefParamSchema = RepoParamSchema.extend({ ref: StashRefSchema.describe("Which entry.") });
 export const StashDiffQuerySchema = RepoParamSchema.extend({ ref: StashRefSchema.describe("Which entry.") });
-/* THE LAST THING THAT MOVED THIS BRANCH, and whether it can be walked back.
- *
- * Complements the Checkpoints timeline rather than duplicating it: a checkpoint restores the WORKING TREE, this
- * moves the BRANCH. After a bad rebase the files are often already right and only the ref is wrong, and
- * restoring a whole worktree snapshot to fix that would drag every unrelated edit since back with it.
- *
- * `description` is git's own reflog subject, so the button can name what it will undo in git's words rather than
- * a guess. `previousSha` is where the branch returns to, and it doubles as the CONCURRENCY TOKEN: the undo is
- * refused when the repository has moved since this was read, so an undo prepared against a stale view cannot
- * land somewhere the user never looked at. Absent = nothing to undo (a fresh branch, a detached HEAD, or a
- * halted operation, which ends by aborting rather than by moving the branch). */
+// The last ref move on this branch, and whether it can be undone; complements Checkpoints, which restores the working
+// tree instead. `previousSha` doubles as a concurrency token: refused if the branch moved since it was read.
 export const UndoKindSchema = z.enum(["commit", "amend", "merge", "rebase", "cherry-pick", "revert", "reset", "pull", "other"]);
 export type UndoKind = z.infer<typeof UndoKindSchema>;
 export const UndoableActionSchema = z.object({
@@ -244,8 +191,7 @@ export const UndoableActionSchema = z.object({
         .describe(
             "Where it would go back to. Send this with the undo as proof you looked, so one prepared against a view that has since moved is refused rather than landing somewhere unexamined.",
         ),
-    // The action rewrote FILES as well as the ref, so undoing it faithfully needs a hard reset. The UI uses this
-    // to decide whether it has to warn about losing work.
+    // True when undoing needs a hard reset, not just a ref move.
     changesWorkingTree: z
         .boolean()
         .describe("Undoing would rewrite files as well as moving the branch, so anything offering it should warn about losing work."),
@@ -256,7 +202,7 @@ export const GitUndoStateSchema = z.object({
     action: UndoableActionSchema.optional().describe("What undoing would reverse. Absent means there is nothing to go back from."),
 });
 export type GitUndoState = z.infer<typeof GitUndoStateSchema>;
-// `previousSha` is the position the caller was shown; `discardChanges` picks a hard reset over a soft one.
+// `previousSha` must match what the caller was shown; `discardChanges` picks a hard reset over a soft one.
 export const GitUndoSchema = RepoParamSchema.extend({
     previousSha: ShaSchema.describe(
         "Where to go back to, from the matching read. It is also proof you looked: one prepared against a stale view is refused.",