@saadnvd1/agent-os 0.3.715 → 0.3.723

package/lib/models/availability.ts

@@ -0,0 +1,91 @@
+/**
+ * Whether a model's server answers. Only endpoints on the local networks
+ * are probed (a cloud provider's key isn't proof and a probe costs), one
+ * short GET, cached for a while. Any HTTP answer means the server is up;
+ * what's down is a refused connection or no answer in time.
+ */
+
+export type AvailabilityState = "up" | "down" | "unknown";
+
+export interface Availability {
+  state: AvailabilityState;
+  checkedAt: string | null;
+  error?: string;
+}
+
+const TTL_MS = 30_000;
+const TIMEOUT_MS = 1_500;
+
+interface Entry extends Availability {
+  at: number;
+}
+const cache = new Map<string, Entry>();
+const probing = new Map<string, Promise<Entry>>();
+
+const UNKNOWN: Availability = { state: "unknown", checkedAt: null };
+
+// What a server of that API lists its models at.
+export const probeUrl = (baseUrl: string, api: "anthropic" | "openai") => {
+  const base = baseUrl.replace(/\/+$/, "");
+  return api === "anthropic" && !/\/v1$/.test(base)
+    ? `${base}/v1/models`
+    : `${base}/models`;
+};
+
+async function probe(url: string): Promise<Entry> {
+  const at = Date.now();
+  try {
+    await fetch(url, {
+      method: "GET",
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+      redirect: "manual",
+    });
+    return { state: "up", checkedAt: new Date(at).toISOString(), at };
+  } catch (error) {
+    const cause = (error as { cause?: { code?: string } }).cause?.code;
+    const timedOut = (error as Error).name === "TimeoutError";
+    return {
+      state: "down",
+      checkedAt: new Date(at).toISOString(),
+      at,
+      error: timedOut
+        ? `no answer in ${TIMEOUT_MS / 1000}s`
+        : (cause ?? (error as Error).message),
+    };
+  }
+}
+
+const strip = ({ at: _at, ...rest }: Entry): Availability => rest;
+
+// The last check of a URL, probing in the background when it's stale: a
+// request handler never waits on a probe.
+export function cachedAvailability(url: string): Availability {
+  const hit = cache.get(url);
+  if (!hit || Date.now() - hit.at >= TTL_MS) void checkAvailability(url);
+  return hit ? strip(hit) : UNKNOWN;
+}
+
+// A fresh enough answer, waiting for the probe if there isn't one.
+export async function checkAvailability(
+  url: string,
+  refresh = false
+): Promise<Availability> {
+  const hit = cache.get(url);
+  if (!refresh && hit && Date.now() - hit.at < TTL_MS) return strip(hit);
+  let running = probing.get(url);
+  if (!running) {
+    running = probe(url)
+      .then((e) => {
+        cache.set(url, e);
+        return e;
+      })
+      .finally(() => probing.delete(url));
+    probing.set(url, running);
+  }
+  return strip(await running);
+}
+
+export function clearAvailability(): void {
+  cache.clear();
+  probing.clear();
+}

package/lib/models/catalog.ts

@@ -0,0 +1,156 @@
+/**
+ * The one list of models every picker shows, built on the server: each
+ * enabled provider's models, and the models Pi reaches (local servers in its
+ * models.json). Nothing about a model, provider or its locality is decided
+ * in the browser.
+ */
+
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { effectiveModels, type EffectiveModels } from "./config";
+import { ANTHROPIC } from "./roles";
+import { PI, type ModelProvider } from "./providers";
+import { hostLocality, type Locality } from "./locality";
+import {
+  cachedAvailability,
+  checkAvailability,
+  probeUrl,
+  type Availability,
+} from "./availability";
+
+export interface ModelChoice {
+  // "anthropic/claude-opus-5-5", "pi/local/qwen3-27b"
+  ref: string;
+  label: string;
+  // The provider's name: "Anthropic", "DeepSeek", "Pi · local".
+  group: string;
+  // What runs it: Claude Code, or the Pi agent.
+  agent: "claude" | "pi";
+  locality: Locality;
+  availability: Availability;
+  // May serve a merge gate: Claude Code can run it.
+  gateCapable: boolean;
+  // Where the server is (never a key).
+  endpoint?: string;
+}
+
+interface PiProvider {
+  id: string;
+  baseUrl: string;
+  models: { id: string; name?: string }[];
+}
+
+const piModelsFile = () =>
+  process.env.AGENTOS_PI_MODELS_FILE ||
+  path.join(os.homedir(), ".pi", "agent", "models.json");
+
+// The providers in Pi's own config. A missing or unreadable file means Pi
+// has no servers of ours to list.
+export function piProviders(file = piModelsFile()): PiProvider[] {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return [];
+  }
+  const providers = (raw as { providers?: Record<string, unknown> })?.providers;
+  if (!providers || typeof providers !== "object") return [];
+  const out: PiProvider[] = [];
+  for (const [id, p] of Object.entries(providers)) {
+    const q = p as { baseUrl?: unknown; models?: unknown };
+    if (typeof q?.baseUrl !== "string" || !Array.isArray(q.models)) continue;
+    const models = q.models
+      .map((m) =>
+        typeof m === "string"
+          ? { id: m }
+          : {
+              id: (m as { id?: unknown })?.id,
+              name: (m as { name?: unknown })?.name,
+            }
+      )
+      .filter(
+        (m): m is { id: string; name?: string } => typeof m.id === "string"
+      )
+      .map((m) => ({
+        id: m.id,
+        ...(typeof m.name === "string" ? { name: m.name } : {}),
+      }));
+    out.push({ id, baseUrl: q.baseUrl, models });
+  }
+  return out;
+}
+
+const providerEndpoint = (p: ModelProvider) =>
+  p.baseUrl ? probeUrl(p.baseUrl, p.api) : undefined;
+
+export function modelCatalog(
+  effective: EffectiveModels = effectiveModels(),
+  pi: PiProvider[] = piProviders()
+): ModelChoice[] {
+  const out: ModelChoice[] = [];
+  for (const p of effective.providers.filter((x) => x.enabled)) {
+    const endpoint = providerEndpoint(p);
+    const locality = hostLocality(p.baseUrl);
+    const availability: Availability =
+      p.id === ANTHROPIC
+        ? { state: "up", checkedAt: null }
+        : locality === "local" && endpoint
+          ? cachedAvailability(endpoint)
+          : { state: "unknown", checkedAt: null };
+    for (const m of p.models)
+      out.push({
+        ref: `${p.id}/${m}`,
+        label: m,
+        group: p.label,
+        agent: "claude",
+        locality,
+        availability,
+        gateCapable: p.api === "anthropic",
+        endpoint: p.baseUrl,
+      });
+  }
+  for (const p of pi) {
+    const locality = hostLocality(p.baseUrl);
+    const endpoint = probeUrl(p.baseUrl, "openai");
+    const availability: Availability =
+      locality === "local"
+        ? cachedAvailability(endpoint)
+        : { state: "unknown", checkedAt: null };
+    for (const m of p.models)
+      out.push({
+        ref: `${PI}/${p.id}/${m.id}`,
+        label: m.name ?? m.id,
+        group: `Pi · ${p.id}`,
+        agent: "pi",
+        locality,
+        availability,
+        gateCapable: false,
+        endpoint: p.baseUrl,
+      });
+  }
+  return out;
+}
+
+export const choiceFor = (
+  ref: string,
+  effective?: EffectiveModels
+): ModelChoice | undefined =>
+  modelCatalog(effective).find((c) => c.ref === ref);
+
+// Whether the model's server answers now, waiting for a probe. Cloud and
+// unlisted models aren't probed: they count as available.
+export async function modelAvailability(
+  ref: string,
+  effective?: EffectiveModels,
+  refresh = false
+): Promise<Availability> {
+  const choice = choiceFor(ref, effective);
+  if (!choice || choice.locality !== "local" || !choice.endpoint)
+    return { state: "unknown", checkedAt: null };
+  const url =
+    choice.agent === "pi"
+      ? probeUrl(choice.endpoint, "openai")
+      : probeUrl(choice.endpoint, "anthropic");
+  return checkAvailability(url, refresh);
+}

package/lib/models/config.ts

@@ -138,25 +138,35 @@ const subagentMap = z
         });
   });
 
+// A role may name a model to start on when its own can't be reached.
+const fallbackMap = z.partialRecord(z.enum(MODEL_ROLES), roleRef);
+
 export const modelSettingsSchema = z.strictObject({
   roles: roleMap.optional(),
   subagents: subagentMap.optional(),
   providers: z.array(providerSchema).optional(),
   prices: z.record(z.string().regex(REF_PATTERN), price).optional(),
   planStep: z.boolean().optional(),
+  fallbacks: fallbackMap.optional(),
 });
 
 export const workspaceModelsSchema = z.strictObject({
   roles: roleMap.optional(),
 });
 
+export const projectModelsSchema = z.strictObject({
+  roles: roleMap.optional(),
+});
+
 export type ModelSettings = z.infer<typeof modelSettingsSchema>;
 export type WorkspaceModels = z.infer<typeof workspaceModelsSchema>;
+export type ProjectModels = z.infer<typeof projectModelsSchema>;
 export type RoleMap = Partial<Record<ModelRole, string>>;
 export const roleMapSchema = roleMap;
 
 const GLOBAL_KEY = "models";
 const workspaceKey = (id: string) => `models.workspace.${id}`;
+const projectKey = (id: string) => `models.project.${id}`;
 
 function read<T>(key: string, schema: z.ZodType<T>): T | null {
   const row = db
@@ -221,6 +231,23 @@ export function setWorkspaceModels(
   return saved;
 }
 
+// Set in Settings, never in the repo, so work can't choose its own models.
+export const projectModels = (projectId: string): ProjectModels =>
+  read(projectKey(projectId), projectModelsSchema) ?? {};
+
+export function setProjectModels(
+  projectId: string,
+  value: unknown
+): ProjectModels {
+  const saved = write(projectKey(projectId), projectModelsSchema, value);
+  if (!Object.keys(saved.roles ?? {}).length) clearProjectModels(projectId);
+  return saved;
+}
+
+export const clearProjectModels = (projectId: string): void => {
+  db.prepare(`DELETE FROM settings WHERE key = ?`).run(projectKey(projectId));
+};
+
 // The settings in force: the presets with any saved edits laid over them
 // (by id), saved providers that aren't presets, and every role filled.
 export interface EffectiveModels {

package/lib/models/locality.ts

@@ -0,0 +1,33 @@
+/**
+ * Whether a model endpoint is on this machine's own networks (local) or
+ * out on the internet (cloud), read from its host, never from a name.
+ * Imported by the browser too.
+ */
+
+export type Locality = "local" | "cloud";
+
+const PRIVATE_V4 = [
+  /^127\./,
+  /^10\./,
+  /^192\.168\./,
+  /^172\.(1[6-9]|2\d|3[01])\./,
+  /^169\.254\./,
+  // The tailnet: 100.64.0.0/10.
+  /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./,
+];
+
+export function hostLocality(url: string | null | undefined): Locality {
+  if (!url) return "cloud";
+  let host: string;
+  try {
+    host = new URL(url).hostname.toLowerCase();
+  } catch {
+    return "cloud";
+  }
+  host = host.replace(/^\[|\]$/g, "");
+  if (host === "localhost" || host === "::1" || host.endsWith(".localhost"))
+    return "local";
+  if (host.endsWith(".local") || host.endsWith(".ts.net")) return "local";
+  if (/^f[cd][0-9a-f]{2}:/.test(host)) return "local";
+  return PRIVATE_V4.some((re) => re.test(host)) ? "local" : "cloud";
+}

package/lib/models/providers.ts

@@ -63,6 +63,17 @@ export const ANTHROPIC_PROVIDER: ModelProvider = {
   enabled: true,
 };
 
+// Pi's own models ("pi/<its provider>/<model>"): local servers Pi reaches,
+// run by the Pi agent rather than through Claude Code's endpoint variables.
+export const PI = "pi";
+export const PI_PROVIDER: ModelProvider = {
+  id: PI,
+  label: "Pi",
+  api: "openai",
+  models: [],
+  enabled: true,
+};
+
 // Checked against each provider's docs on 2026-10-11: DeepSeek
 // (api-docs.deepseek.com/guides/anthropic_api) and Z.ai
 // (docs.z.ai/devpack/tool/claude). Off until a key reference is set.

package/lib/models/resolve.ts

@@ -12,11 +12,17 @@ import {
   effectiveModels,
   roleMapSchema,
   savedModelSettings,
+  projectModels,
   workspaceModels,
   type EffectiveModels,
   type RoleMap,
 } from "./config";
-import { ANTHROPIC_PROVIDER, type ModelProvider } from "./providers";
+import {
+  ANTHROPIC_PROVIDER,
+  PI,
+  PI_PROVIDER,
+  type ModelProvider,
+} from "./providers";
 import {
   ANTHROPIC,
   DEFAULT_ROLE_MODELS,
@@ -33,7 +39,14 @@ import {
   type SecretCommand,
 } from "./secrets";
 
-export type RoleSource = "task" | "workspace" | "settings" | "env" | "default";
+export type RoleSource =
+  | "task"
+  | "project"
+  | "workspace"
+  | "settings"
+  | "env"
+  | "inherited"
+  | "default";
 
 // The server's own environment can still stand in for a role's default:
 // what AgentOS read before model routing existed.
@@ -87,9 +100,15 @@ const overrideFor = (o: ModelOverride | null | undefined, role: ModelRole) =>
 // The provider by id, or throws why it can't be used.
 export function providerFor(
   id: string,
-  models: EffectiveModels = effectiveModels()
+  models: EffectiveModels = effectiveModels(),
+  allowPi = false
 ): ModelProvider {
   if (id === ANTHROPIC) return ANTHROPIC_PROVIDER;
+  if (id === PI) {
+    if (!allowPi)
+      throw new Error("Pi models run only in a session started in a role");
+    return PI_PROVIDER;
+  }
   const p = models.providers.find((x) => x.id === id);
   if (!p) throw new Error(`No model provider "${id}" (Settings > Models)`);
   if (!p.enabled) throw new Error(`The ${p.label} provider is turned off`);
@@ -104,10 +123,19 @@ export function providerFor(
 
 export function resolveRole(
   role: ModelRole,
-  opts: { workspaceId?: string | null; override?: ModelOverride | null } = {},
+  opts: {
+    workspaceId?: string | null;
+    projectId?: string | null;
+    override?: ModelOverride | null;
+    // A role session runs Pi models; a task or gate can't.
+    allowPi?: boolean;
+  } = {},
   models: EffectiveModels = effectiveModels()
 ): RoutedModel {
   const task = overrideFor(opts.override, role);
+  const proj = opts.projectId
+    ? projectModels(opts.projectId).roles?.[role]
+    : undefined;
   const ws = opts.workspaceId
     ? workspaceModels(opts.workspaceId).roles?.[role]
     : undefined;
@@ -117,20 +145,30 @@ export function resolveRole(
     saved === DEFAULT_ROLE_MODELS[role] && !savedModelSettings().roles?.[role]
       ? envModel(role)
       : undefined;
+  // The reviewer's advice follows the gate's model until it's set.
+  const named = !!savedModelSettings().roles?.[role];
+  const inherited =
+    role === "advise" && !env && !named
+      ? resolveRole("review", { ...opts, override: null }, models)
+      : null;
   const [ref, source]: [string, RoleSource] = task
     ? [task, "task"]
-    : ws
-      ? [ws, "workspace"]
-      : saved !== DEFAULT_ROLE_MODELS[role]
-        ? [saved, "settings"]
-        : env
-          ? [env, "env"]
-          : [saved, "default"];
+    : proj
+      ? [proj, "project"]
+      : ws
+        ? [ws, "workspace"]
+        : saved !== DEFAULT_ROLE_MODELS[role] || (role === "advise" && named)
+          ? [saved, "settings"]
+          : env
+            ? [env, "env"]
+            : inherited
+              ? [inherited.ref, "inherited"]
+              : [saved, "default"];
   const parsed = parseModelRef(ref);
   return {
     role,
     ref: formatModelRef(parsed),
-    provider: providerFor(parsed.provider, models),
+    provider: providerFor(parsed.provider, models, opts.allowPi),
     model: parsed.model,
     source,
   };

package/lib/models/roles.ts

@@ -9,6 +9,8 @@
 export const MODEL_ROLES = [
   "plan",
   "implement",
+  "analyze",
+  "advise",
   "orchestrator",
   "review",
   "scope",
@@ -28,6 +30,14 @@ export const ROLE_LABELS: Record<ModelRole, { label: string; hint: string }> = {
     label: "Task implementation",
     hint: "A task's agent, following the plan in its worktree",
   },
+  analyze: {
+    label: "Analyst",
+    hint: "Reads code, logs and a developer's work; explains and proposes",
+  },
+  advise: {
+    label: "Reviewer",
+    hint: "Advises on another role's diff. Not the merge gate",
+  },
   orchestrator: { label: "Orchestrator", hint: "A workspace's orchestrator" },
   review: {
     label: "Gate review",
@@ -58,6 +68,8 @@ export const DEFAULT_ROLE_MODELS: Record<ModelRole, string> = {
   plan: OPUS,
   review: OPUS,
   implement: SONNET,
+  analyze: OPUS,
+  advise: OPUS,
   orchestrator: OPUS,
   scope: SONNET,
   interactive: OPUS,

package/lib/needs-you.ts

@@ -17,7 +17,7 @@ export function markSeen(sessionId: string): void {
   notifyStatusChanged();
 }
 
-function latestChatItem(sessionId: string): ChatItem | null {
+export function latestChatItem(sessionId: string): ChatItem | null {
   const row = getDb()
     .prepare(
       `SELECT data FROM chat_items WHERE session_id = ? ORDER BY seq DESC LIMIT 1`

package/lib/orchestrator/facts.ts

@@ -13,7 +13,7 @@ import { peerStatus } from "../hosts/peer-sessions";
 import { chatCompacting, chatState } from "../chat/runner";
 import { chatActivityLine, chatStall, type Stall } from "../chat/activity";
 import { lastUserTask } from "../chat/store";
-import { needsYou } from "../needs-you";
+import { latestChatItem, needsYou } from "../needs-you";
 import { programSummary } from "../program-status/store";
 import { sessionRowInfo } from "../session-meta";
 import { taskView, type TaskPR, type TaskState } from "../tasks";
@@ -170,9 +170,14 @@ export async function statusOf(s: Session): Promise<{
     const state = chatState(s.id);
     const status: FactStatus =
       state === "running" ? "running" : needsYou(s, state) ? "waiting" : "idle";
+    const latest = status === "running" ? null : latestChatItem(s.id);
+    const early =
+      latest?.kind === "turn_end" && !latest.interrupted ? latest.ended : null;
     return {
       status,
-      activity: chatActivityLine(s.id) ?? lastUserTask(s.id),
+      activity: early
+        ? `ended its turn early (${early.reason}): the task is not finished`
+        : (chatActivityLine(s.id) ?? lastUserTask(s.id)),
       needsInput: state === "waiting",
     };
   }

package/lib/orchestrator/read.ts

@@ -91,7 +91,11 @@ function itemText(i: ChatItem): string | null {
     case "error":
       return `[error] ${i.message}`;
     case "turn_end":
-      return i.interrupted ? "[turn stopped]" : "[turn ended]";
+      return i.interrupted
+        ? "[turn stopped]"
+        : i.ended
+          ? `[turn ended early: ${i.ended.reason}] ${i.ended.notice}`
+          : "[turn ended]";
     case "command_output":
       return i.text;
     case "note":

package/lib/orchestrator/untrusted.ts

@@ -31,6 +31,10 @@ export const looksRandom = (s: string) =>
 export const SECRET_ASSIGNMENT =
   /^(\s*(?:export\s+)?[A-Z][A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|PASS|PWD|CREDENTIALS?|AUTH)[A-Z0-9_]*\s*[=:]\s*).+$/gm;
 
+// The same assignment inline, ahead of a command: API_TOKEN=... npm test.
+const INLINE_ASSIGNMENT =
+  /\b([A-Z][A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|PASS|PWD|CREDENTIALS?|AUTH)[A-Z0-9_]*=)(?!\[redacted\])("[^"]*"|'[^']*'|\S+)/g;
+
 // A URL's userinfo (https://key@host, postgres://user:pw@host) and a query
 // parameter that carries a credential (?token=, &api_key=).
 export const URL_USERINFO = /\b([a-z][a-z0-9+.-]*:\/\/)[^@\s/]+@/gi;
@@ -47,6 +51,7 @@ const URL_PASSWORD = /\b([a-z][a-z0-9+.-]*:\/\/[^:\s/@]+:)[^@\s]+@/gi;
 export function redact(text: string): string {
   let out = text
     .replace(SECRET_ASSIGNMENT, "$1[redacted]")
+    .replace(INLINE_ASSIGNMENT, "$1[redacted]")
     .replace(URL_PASSWORD, "$1[redacted]@");
   for (const p of TOKEN_PATTERNS) out = out.replace(p, "[redacted]");
   return out.replace(BASE64_RUN, (m) => (looksRandom(m) ? "[redacted]" : m));

package/lib/projects.ts

@@ -294,6 +294,7 @@ export function deleteProject(id: string): boolean {
 
   // Its merge settings override (lib/tasks/merge-policy.ts)
   db.prepare(`DELETE FROM settings WHERE key = ?`).run(`merge.project.${id}`);
+  db.prepare(`DELETE FROM settings WHERE key = ?`).run(`models.project.${id}`);
 
   // Delete project
   queries.deleteProject(db).run(id);

package/lib/session-artifacts/agentos-files.ts

@@ -0,0 +1,94 @@
+/**
+ * What a task saves under .agentos/mockups and .agentos/screenshots. Git
+ * ignores that folder (its .gitignore is `*`) and a Bash write isn't a
+ * file-writing tool call, so neither other source lists them.
+ */
+
+import fs from "fs";
+import path from "path";
+import { isSecretPath } from "../secret-paths";
+import { SCREENSHOT_DIR } from "../tasks/ui-brief";
+import { kindForPath, type Candidate } from "./derive";
+
+export const MOCKUP_DIR = ".agentos/mockups";
+export const AGENTOS_DIRS = [MOCKUP_DIR, SCREENSHOT_DIR];
+const MAX_DEPTH = 3;
+const MAX_LISTED = 200;
+
+const isAgentosFile = (rel: string) =>
+  AGENTOS_DIRS.some((d) => rel.startsWith(`${d}/`));
+
+function candidate(
+  worktree: string,
+  rel: string,
+  at: number
+): Candidate | null {
+  const file = path.join(worktree, rel);
+  if (isSecretPath(file)) return null;
+  return {
+    key: `file:${file}`,
+    kind: kindForPath(file),
+    name: path.basename(file),
+    at,
+    by: "shell",
+    source: { type: "file", path: file },
+  };
+}
+
+function walk(root: string, rel: string, depth: number, out: string[]): void {
+  if (out.length >= MAX_LISTED) return;
+  let names: fs.Dirent[];
+  try {
+    names = fs.readdirSync(path.join(root, rel), { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const d of names) {
+    const child = `${rel}/${d.name}`;
+    // Symlinks are skipped: they could point out of the worktree.
+    if (d.isFile()) out.push(child);
+    else if (d.isDirectory() && depth < MAX_DEPTH)
+      walk(root, child, depth + 1, out);
+  }
+}
+
+export function agentosFiles(worktree: string): { rel: string; at: number }[] {
+  const rels: string[] = [];
+  for (const dir of AGENTOS_DIRS) walk(worktree, dir, 1, rels);
+  return rels.slice(0, MAX_LISTED).flatMap((rel) => {
+    try {
+      return [{ rel, at: fs.statSync(path.join(worktree, rel)).mtimeMs }];
+    } catch {
+      return [];
+    }
+  });
+}
+
+export function fromAgentosDirs(
+  worktree: string,
+  known: Set<string>
+): Candidate[] {
+  return agentosFiles(worktree).flatMap(({ rel, at }) => {
+    const c = candidate(worktree, rel, at);
+    return c && !known.has(c.key) ? [c] : [];
+  });
+}
+
+// After the worktree is gone: the copies that were kept.
+export function fromKept(
+  worktree: string,
+  kept: string[],
+  at: number,
+  known: Set<string>
+): Candidate[] {
+  return kept.filter(isAgentosFile).flatMap((rel) => {
+    const c = candidate(worktree, rel, at);
+    return c && !known.has(c.key) ? [c] : [];
+  });
+}
+
+// Changes when a file is added, removed or rewritten there.
+export function agentosSignature(worktree: string): string {
+  const files = agentosFiles(worktree);
+  return `${files.length}:${files.reduce((m, f) => Math.max(m, f.at), 0)}`;
+}