@open-mercato/cezar 0.9.2-pr774.1069 → 0.9.2-pr776.1115

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patryk Lewczuk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -19,7 +19,7 @@ your phone, working your backlog while you're away.
 
 [A look inside](#a-look-inside) · [What cezar does best](#what-cezar-does-best) · [What it solves](#what-it-solves) · [Who it's for](#who-its-for) · [Quick start](#quick-start) · [How it works](#how-it-works) · [Core concepts](#core-concepts) · [Cockpit tour](#cockpit-tour) · [Agent backends](#coding-agent-backends) · [Remote access](#remote-access-host-cezar-on-a-server)
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](#license)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 ![Node 20+](https://img.shields.io/badge/Node-20%2B-339933)
 ![TypeScript 7.x](https://img.shields.io/badge/TypeScript-7.x-3178c6)
 ![Zero config](https://img.shields.io/badge/config-zero-success)
@@ -307,21 +307,12 @@ a GitHub page.
 ## Multiple projects, one cockpit
 
 One `cezar serve` hosts **every repo you work in**, not just the one you started
-it in. Projects live in a per-user registry at `~/.cezar/config.json` — the
-workspace file that also holds the global knobs
+it in. Each repo cezar boots in registers itself in a per-user registry at
+`~/.cezar/config.json` — the workspace file that also holds the global knobs
 (the parallel cap, the memory ceiling, the browse root, and the checkout root). Nothing is added to
 the repo: per-project state stays exactly where it was, in that repo's
 `.ai/cezar/`.
 
-**Your first run registers the repo you start it in** — that is the whole setup.
-After that the registry is yours to curate: starting cezar somewhere else serves
-that folder as usual (its own tasks, its own `.ai/cezar/`) but does not add it to
-the list behind your back. It shows up at the top of the sidebar marked **not
-saved**, and **Settings → Projects** lists it as *not registered* with an
-**Add project** button — so the folder you launched in is always one click from
-being kept, and never kept without the click. `cezar projects add` does the same
-from a terminal.
-
 Every view is project-scoped:
 
 ```
@@ -345,8 +336,8 @@ and task list — and the new-task composer names the project it will run in.
 
 Removing a project (**Settings → Projects**) drops the registry entry only — the
 repo and its `.ai/cezar/` are never touched, so re-adding it later finds all its
-tasks intact. The project cezar is currently serving can't be removed from the
-cockpit — stop the server and use `cezar projects remove <id>` instead.
+tasks intact. The project cezar is currently serving can't be removed: it
+re-registers itself at the next start.
 
 **From the terminal** — the same registry, no cockpit required (handy over ssh):
 
@@ -359,11 +350,12 @@ cezar projects remove api         # drop the registry entry; the repo is untouch
 These read and write `~/.cezar/config.json` directly, so they work with the
 server stopped, and `CEZ_HOME` selects which workspace they operate on.
 
-Settings split along the same line: **Agents**, **Worktrees**, **Bookmarklets**,
-**Prompt templates** and **MCP** describe one repo and live under
-`/p/<projectId>/settings`; **Appearance**, **Notifications**, **Resources**,
-**Projects** and **Keyboard** are yours or the machine's and live at
-`/settings/global`.
+Settings split along the same line: **General** (the project's folder, its
+registry facts, its parallel-task ceiling, and Remove), **Agents**,
+**Worktrees**, **Bookmarklets**, **Prompt templates** and **MCP** describe one
+repo and live under `/p/<projectId>/settings`; **Appearance**,
+**Notifications**, **Resources**, **Projects** and **Keyboard** are yours or the
+machine's and live at `/settings/global`.
 
 **Old page URLs keep working.** Every unprefixed page path — `/`, `/tasks/<id>`,
 `/settings` — still answers, bound to the project cezar was started in; the
@@ -721,4 +713,4 @@ Start here; graduate to cezar when a team needs shared visibility.
 
 ## License
 
-**MIT** © Patryk Lewczuk
+**MIT** © Patryk Lewczuk — full text in [LICENSE](LICENSE).

package/dist/contract/index.js

@@ -204,11 +204,12 @@ var diffStatSchema = z4.object({
   adds: z4.number(),
   dels: z4.number(),
   files: z4.number(),
-  /** Additive since #751, and present ONLY when true: the numbers cover uncommitted work
-   *  alone, because the worktree's HEAD had been repointed off the task's own branch (every
-   *  review/QA run does this) and the merge-base anchor would otherwise have reported the
-   *  checked-out branch's entire diff as this task's. Absent on every normal run and on every
-   *  record written before #751 — a consumer that ignores it sees exactly the old shape. */
+  /** Additive since #751, and present ONLY when true: the numbers were measured against a
+   *  branch the agent checked out into the task's worktree, as the run found it, because the
+   *  worktree's HEAD had been repointed off the task's own branch (every review/QA run does
+   *  this) and the merge-base anchor would otherwise have reported that branch's entire diff
+   *  as this task's. Absent on every normal run and on every record written before #751 — a
+   *  consumer that ignores it sees exactly the old shape. */
   repointed: z4.boolean().optional()
 });
 var queuedMessageSchema = z4.object({
@@ -333,7 +334,8 @@ var runRecordSchema = z4.object({
   /** Read receipt (#unread-done-items): ISO time the cockpit last opened this run's
    *  thread. A finished (`done`/`failed`) run reads as *unread* until seen since it
    *  finished — see `isUnread()` in the cockpit's `lib/read-state.ts`. Absent on old
-   *  runs and on any run not yet opened, both of which count as unread. */
+   *  runs, on any run not yet opened, and on one deliberately put back to unread via
+   *  `POST /runs/:id/unread` (#775) — all three count as unread. */
   seenAt: z4.string().optional(),
   currentStepId: z4.string().optional(),
   error: z4.string().optional(),
@@ -355,6 +357,40 @@ var runRecordSchema = z4.object({
 var apiRunSchema = runRecordSchema.extend({
   usage: processUsageSchema.optional()
 });
+var runIndexEntrySchema = z4.object({
+  /** The registered project this run belongs to. Joins against `GET /projects`. */
+  projectId: z4.string(),
+  id: z4.string(),
+  title: z4.string(),
+  titleSummary: z4.string().optional(),
+  titleOrigin: z4.enum(["user", "auto", "marker"]).optional(),
+  status: runStatusSchema,
+  activity: runActivitySchema.optional(),
+  createdAt: z4.string(),
+  finishedAt: z4.string().optional(),
+  /** With `status`/`finishedAt`/`archived`, the four inputs `isUnread` reads — what lets the
+   *  palette lead with "finished while you weren't looking" across every project, not just the
+   *  one you happen to be standing in. */
+  seenAt: z4.string().optional(),
+  /** Always present, like `RunRecord.archived`: absent would read as "not archived", and the
+   *  unread rule treats archiving as a stronger "done with this" than reading. */
+  archived: z4.boolean(),
+  /** A run parked by a provider usage limit is `failed` on the record with a resume booked
+   *  (spec 2026-08-03-auto-resume-after-usage-limit). Both `deriveAttention` and `isUnread` read
+   *  it, so without it here a cross-project row would show a red "failed" dot and land in
+   *  Recently finished for work that is simply waiting for its appointment. */
+  autoResumeAt: z4.string().optional()
+});
+var runsIndexResponseSchema = z4.object({
+  /** Newest first, across every registered project. Archived runs are included — `GET /runs`
+   *  carries them for the project you are standing in, and a finder that dropped them elsewhere
+   *  would make a task vanish the moment you left its project. */
+  runs: z4.array(runIndexEntrySchema),
+  /** The per-project cap that produced this list. */
+  perProjectLimit: z4.number(),
+  /** Ids of the projects that had more runs than the cap allowed. */
+  truncated: z4.array(z4.string())
+});
 var createRunResponseSchema = z4.union([
   runRecordSchema,
   z4.object({ runs: z4.array(runRecordSchema) })
@@ -766,13 +802,7 @@ var projectListEntrySchema = z7.object({
   forge: z7.literal("github").optional(),
   /** Per-project cap on concurrently running tasks (spec 2026-07-22). Omitted = inherit the
    *  workspace `resources.maxParallel`; a number pins this project. */
-  maxParallel: z7.number().optional(),
-  /** Set ONLY on the synthetic entry for the folder this server was started in when that folder
-   *  is not in the registry — the ordinary state since boot registration became seed-once. The
-   *  server serves it like any project (it owns the boot context), so the cockpit must be able to
-   *  reach it; but it is not persisted, so the rows that edit the registry (Remove, Max parallel)
-   *  do not apply and Settings offers "Add project" instead. Never present on a registry entry. */
-  unregistered: z7.literal(true).optional()
+  maxParallel: z7.number().optional()
 });
 var projectsResponseSchema = z7.object({
   projects: z7.array(projectListEntrySchema),
@@ -934,9 +964,11 @@ var workspaceLastLocationSchema = z8.strictObject({
   hash: z8.string().max(2048).startsWith("#").optional()
 });
 var workspaceUiStateSchema = z8.looseObject({
-  /** The sidebar's per-project collapse map (step 3.3) — `true` collapses a group, `false` pins
-   *  it open, absent means the default (the active project expands, the rest collapse). Loose for
-   *  the same round-trip reason as its parent. */
+  /** LEGACY — the sidebar's per-project collapse map (step 3.3). Still accepted and still
+   *  round-tripped so an older cockpit sharing this home keeps working, but the current cockpit
+   *  neither reads nor writes it: which groups are shut describes the WINDOW, not the workspace,
+   *  so it lives in that browser's localStorage (`packages/web/src/lib/sidebar-collapse.ts`).
+   *  One shared answer meant a phone collapsing a group collapsed it on the desktop too. */
   sidebar: z8.looseObject({ collapsed: z8.record(z8.string(), z8.boolean()).optional() }).optional(),
   /** Dismissed runtime-auth incident IDs, keyed by provider. An ID is only dismissed until the
    *  provider reports a different incident, so this stays workspace-global with the browser
@@ -952,8 +984,10 @@ var workspaceUiStateSchema = z8.looseObject({
   /** Settings → Notifications, GLOBAL since step 3.5 — one answer for the whole workspace, since
    *  the delivering browser is one browser whichever project you are looking at. */
   notifications: z8.looseObject({ enabled: z8.boolean().optional() }).optional(),
-  /** Last settled project-scoped page. Used only when entering at the exact bare root;
-   *  explicit deep links always win. */
+  /** LEGACY, exactly like `sidebar` above — the last settled project-scoped page, restored when
+   *  entering at the exact bare root. The shape is unchanged and still accepted, but the current
+   *  cockpit keeps it in localStorage (`packages/web/src/lib/last-location.ts`): stored here, the
+   *  last client to navigate decided where every OTHER client's next launch landed. */
   lastLocation: workspaceLastLocationSchema.optional(),
   /** The user's curated selection of default (vendor) skills. Tri-state: ABSENT means "not
    *  curated", so every default skill shows; a PRESENT array (even `[]`) means only those names
@@ -1081,6 +1115,14 @@ var openTargetSchema = z8.object({
 var openTargetsResponseSchema = z8.object({
   targets: z8.array(openTargetSchema)
 });
+var openProjectInSchema = z8.object({
+  // A short bound (#429): matched against a downstream allowlist, so an app id is never long.
+  target: z8.string().trim().min(1, "target required").max(200)
+});
+var openProjectInResponseSchema = z8.object({
+  opened: z8.literal(true),
+  path: z8.string()
+});
 
 // ../contract/src/skills.ts
 import { z as z9 } from "zod";
@@ -1538,6 +1580,8 @@ export {
   openAgentAccountFileInputSchema,
   openAgentAccountFileResponseSchema,
   openInCliResponseSchema,
+  openProjectInResponseSchema,
+  openProjectInSchema,
   openTargetSchema,
   openTargetsResponseSchema,
   parsedWorkflowSchema,
@@ -1568,12 +1612,14 @@ export {
   runCommitSchema,
   runCommitsResponseSchema,
   runEventSchema,
+  runIndexEntrySchema,
   runRecordSchema,
   runStatusSchema,
   runnerModelCatalogResponseSchema,
   runnerModelOptionSchema,
   runnerModelsSchema,
   runnerSchema,
+  runsIndexResponseSchema,
   saveWorkflowInputSchema,
   saveWorkflowResponseSchema,
   selectAgentProfileInputSchema,

package/dist/contract/projects.d.ts

@@ -36,7 +36,6 @@ export declare const projectListEntrySchema: z.ZodObject<{
     branch: z.ZodOptional<z.ZodString>;
     forge: z.ZodOptional<z.ZodLiteral<"github">>;
     maxParallel: z.ZodOptional<z.ZodNumber>;
-    unregistered: z.ZodOptional<z.ZodLiteral<true>>;
 }, z.core.$strip>;
 export type ProjectListEntry = z.infer<typeof projectListEntrySchema>;
 /** `GET /api/v1/projects` — the workspace registry. Workspace-level: never 404s, never scoped.
@@ -61,7 +60,6 @@ export declare const projectsResponseSchema: z.ZodObject<{
         branch: z.ZodOptional<z.ZodString>;
         forge: z.ZodOptional<z.ZodLiteral<"github">>;
         maxParallel: z.ZodOptional<z.ZodNumber>;
-        unregistered: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strip>>;
     bootProject: z.ZodString;
     projectsDir: z.ZodString;
@@ -91,7 +89,6 @@ export declare const registerProjectResponseSchema: z.ZodObject<{
         branch: z.ZodOptional<z.ZodString>;
         forge: z.ZodOptional<z.ZodLiteral<"github">>;
         maxParallel: z.ZodOptional<z.ZodNumber>;
-        unregistered: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strip>;
     error: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
@@ -129,7 +126,6 @@ export declare const updateProjectResponseSchema: z.ZodObject<{
         branch: z.ZodOptional<z.ZodString>;
         forge: z.ZodOptional<z.ZodLiteral<"github">>;
         maxParallel: z.ZodOptional<z.ZodNumber>;
-        unregistered: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type UpdateProjectResponse = z.infer<typeof updateProjectResponseSchema>;

package/dist/contract/runs.d.ts

@@ -445,6 +445,92 @@ export declare const apiRunSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ApiRun = z.infer<typeof apiRunSchema>;
+/**
+ * One run in the WORKSPACE-level index (`GET /api/v1/workspace/runs-index`) — the ⌘K palette's
+ * "find a task in any project" list.
+ *
+ * Deliberately a separate, slim shape rather than `ApiRun`. The index answers for every
+ * registered project at once, and `runRecordSchema` carries `steps[]` and `workflowDef` — a fat
+ * record whose cost is fine per project and absurd multiplied by the registry. These are exactly
+ * the fields a palette row renders: `runTitle`'s three (`title`, `titleSummary`, `titleOrigin`),
+ * `deriveAttention`'s `AttentionInput`, `isUnread`'s `ReadStateInput`, and the timestamps
+ * `shortAge` reads. Adding a field here is cheap; adding the whole record is what this exists to
+ * avoid — but note that widening either of those two `Pick`s means widening this too, or the
+ * palette's cross-project rows silently answer differently from every other surface.
+ *
+ * `projectId` is the join key, NOT the project name: the registry is already on the client and is
+ * authoritative for display names, and duplicating one here would let a renamed project show two
+ * different labels in one palette.
+ */
+export declare const runIndexEntrySchema: z.ZodObject<{
+    projectId: z.ZodString;
+    id: z.ZodString;
+    title: z.ZodString;
+    titleSummary: z.ZodOptional<z.ZodString>;
+    titleOrigin: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        marker: "marker";
+        user: "user";
+    }>>;
+    status: z.ZodEnum<{
+        cancelled: "cancelled";
+        done: "done";
+        failed: "failed";
+        queued: "queued";
+        review: "review";
+        running: "running";
+        waiting: "waiting";
+    }>;
+    activity: z.ZodOptional<z.ZodEnum<{
+        monitoring: "monitoring";
+    }>>;
+    createdAt: z.ZodString;
+    finishedAt: z.ZodOptional<z.ZodString>;
+    seenAt: z.ZodOptional<z.ZodString>;
+    archived: z.ZodBoolean;
+    autoResumeAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RunIndexEntry = z.infer<typeof runIndexEntrySchema>;
+/**
+ * `GET /workspace/runs-index`.
+ *
+ * `truncated` is not decoration: the index caps each project's contribution, and a capped list
+ * that says nothing reads as "your task is not here" when the honest answer is "not in the
+ * newest N". Naming the projects that hit the cap is what lets a consumer say so.
+ */
+export declare const runsIndexResponseSchema: z.ZodObject<{
+    runs: z.ZodArray<z.ZodObject<{
+        projectId: z.ZodString;
+        id: z.ZodString;
+        title: z.ZodString;
+        titleSummary: z.ZodOptional<z.ZodString>;
+        titleOrigin: z.ZodOptional<z.ZodEnum<{
+            auto: "auto";
+            marker: "marker";
+            user: "user";
+        }>>;
+        status: z.ZodEnum<{
+            cancelled: "cancelled";
+            done: "done";
+            failed: "failed";
+            queued: "queued";
+            review: "review";
+            running: "running";
+            waiting: "waiting";
+        }>;
+        activity: z.ZodOptional<z.ZodEnum<{
+            monitoring: "monitoring";
+        }>>;
+        createdAt: z.ZodString;
+        finishedAt: z.ZodOptional<z.ZodString>;
+        seenAt: z.ZodOptional<z.ZodString>;
+        archived: z.ZodBoolean;
+        autoResumeAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    perProjectLimit: z.ZodNumber;
+    truncated: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type RunsIndexResponse = z.infer<typeof runsIndexResponseSchema>;
 /**
  * `POST /runs` (201) — one record for ×1, a group for ×2/×3.
  *

package/dist/contract/workspace.d.ts

@@ -470,3 +470,21 @@ export declare const openTargetsResponseSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type OpenTargetsResponse = z.infer<typeof openTargetsResponseSchema>;
+/**
+ * `POST /api/v1/open-in` — open THIS PROJECT'S root in a detected app (Settings → the project
+ * folder row). The path is never sent: it is the scoped project's own registered root, resolved
+ * server-side, so the route has no traversal surface at all. `target` is an
+ * `/api/v1/open-targets` id; unlike the run route there is no `default`/`cli:` handling, because
+ * a repo root is a directory and an agent CLI belongs in a task worktree.
+ */
+export declare const openProjectInSchema: z.ZodObject<{
+    target: z.ZodString;
+}, z.core.$strip>;
+export type OpenProjectInRequest = z.infer<typeof openProjectInSchema>;
+/** The 200 for the above — `opened` is a literal because every failure is a 409 with `{ error }`,
+ *  so a `false` would be unreachable and would only invite a client to branch on it. */
+export declare const openProjectInResponseSchema: z.ZodObject<{
+    opened: z.ZodLiteral<true>;
+    path: z.ZodString;
+}, z.core.$strip>;
+export type OpenProjectInResponse = z.infer<typeof openProjectInResponseSchema>;

package/dist/git-diff-base.d.ts

@@ -6,22 +6,47 @@
  * to the task's own commits even after the base branch moves on, and even
  * after the task merges the base back in.
  *
- * The exception is a **repointed HEAD**. cezar hands the agent a worktree on
- * the task's own branch, but nothing stops the agent from checking out some
- * other branch in it — every `review/pr-NNN`, QA, and "continue someone
- * else's branch" run does exactly that. Anchoring at the merge-base then
- * silently redefines "this task's diff" as *the whole reviewed branch*, which
- * is how a task that committed nothing came to report `+22505 −2628`. When
- * HEAD is not on the task's branch the honest anchor is `HEAD` itself: the
- * uncommitted work in the tree is the only part this task can be said to have
- * produced.
- *
- * #591 established that rule for the Changes tab; #751 found the sidebar and
- * Tasks-table numbers still on the old anchor. It lives here so a third
- * surface cannot get it wrong again — callers hand in their own `git` runner
- * (`git-worktree.ts` and `server/git-changes.ts` each own a private one, and
- * `git-changes` needs its scratch-`GIT_INDEX_FILE` variant), so this module
- * stays a pure decision with no process-spawning of its own.
+ * Two things break that answer, and both are fixed here:
+ *
+ * **A stale local base ref.** `RunRecord.baseBranch` is a NAME (`main`),
+ * resolved to a ref once, when the worktree was created. Nothing ever
+ * fast-forwards the user's local `main` — cezar's agents only ever `git fetch`,
+ * which moves `origin/main` — so on a repo the user does not pull, the local
+ * ref drifts arbitrarily far behind. The merge-base then collapses onto that
+ * stale tip and every upstream commit the task forked from or merged in counts
+ * as the task's own work: an eight-line fix measured `+59514 −12160` against a
+ * `main` that was 98 commits and one monorepo restructure behind origin. So the
+ * base is re-resolved to the freshest ref it names at every call
+ * (`freshestBaseRef`) — the read-time twin of `resolveBaseRef`, which does the
+ * same thing at worktree-creation time and cannot know what happens later.
+ *
+ * **A repointed HEAD.** cezar hands the agent a worktree on the task's own
+ * branch, but nothing stops the agent from checking out another branch in it —
+ * every `review/pr-NNN` and QA run does exactly that, and so does every skill
+ * that opens its work on a named `feat/…` branch. The merge-base then silently
+ * redefines "this task's diff" as *the whole checked-out branch*, which is how
+ * a task that committed nothing came to report `+22505 −2628`. #591 and #751
+ * answered that with `HEAD` — uncommitted work only — which is right for a
+ * pure review and badly wrong for the far more common case of an agent that
+ * committed real work on a branch it created itself: those runs reported
+ * `+0 −0` for changes that were genuinely theirs.
+ *
+ * The honest anchor for a repointed HEAD is the branch as it stood **when this
+ * run first saw it** — its `<branch>@{<run start>}` reflog state. Diffing
+ * against that attributes exactly what the run did to the tree and nothing
+ * that was already there: a review run gets its `+0`, and a run that branched
+ * off the base and committed gets its real numbers. Where that baseline is
+ * itself stale — the run merged the base branch in afterwards, dragging the
+ * whole upstream delta behind it — the ordinary merge-base is the tighter
+ * answer, so the two candidates compete and the one that attributes FEWER
+ * CHANGED LINES to the task wins. The reported number is then never more than
+ * the least either measure can defend.
+ *
+ * It lives here so a third surface cannot get it wrong again — callers hand in
+ * their own `git` runner (`git-worktree.ts` and `server/git-changes.ts` each
+ * own a private one, and `git-changes` needs its scratch-`GIT_INDEX_FILE`
+ * variant), so this module stays a pure decision with no process-spawning of
+ * its own.
  */
 /** What a caller's `git` runner must answer with. Both existing runners are wider than this. */
 export interface GitRunResult {
@@ -38,23 +63,23 @@ export interface RepointedHead {
 export interface TaskDiffBase {
     /** The ref to diff against. */
     base: string;
-    /** Present only when HEAD left the task's branch — the reason `base` is `HEAD`. */
+    /** Present only when HEAD left the task's branch — the reason `base` is what it is. */
     repointedHead?: RepointedHead;
 }
 /**
- * Resolve the diff anchor for a task worktree. Never throws: a failing git
- * call degrades to the base branch name, which is what the un-guarded callers
- * did before this helper existed.
+ * Resolve the diff anchor for a task worktree. Never throws: a failing git call
+ * degrades to the base branch name, which is what the un-guarded callers did
+ * before this helper existed.
  *
  * `taskBranch` is optional because not every caller has one (the main working
- * tree has no task branch at all). Without it there is nothing to compare
- * HEAD against, so the merge-base anchor is used unchanged — that is the
- * pre-#751 behavior, preserved exactly.
+ * tree has no task branch at all). Without it there is nothing to compare HEAD
+ * against, so the merge-base anchor is used unchanged.
  *
- * A detached HEAD (`rev-parse --abbrev-ref HEAD` → `HEAD`) counts as
- * repointed: it is by definition not the task's branch, so the same
- * uncommitted-only anchor is the honest one.
+ * `runStartedAt` is what makes the repointed-HEAD answer a measurement instead
+ * of a guess; without it the anchor stays `HEAD` (uncommitted work only), the
+ * conservative #751 answer that can never claim someone else's commits.
  */
 export declare function resolveTaskDiffBase(runGit: GitRunner, baseBranch: string, opts?: {
     taskBranch?: string;
+    runStartedAt?: string;
 }): Promise<TaskDiffBase>;