@mattstack/rt-client 0.3.0 → 0.4.1

package/src/client.ts

@@ -5,7 +5,20 @@
  */
 import { rtCommand } from "./transport.ts";
 import type { RtResponse, RtClientOptions } from "./transport.ts";
-import type { DemandDecl, ProjectMRsData, DiscussionsData, MrByBranchData, ForgeSlug, ForgeTokenData, RunSummary, RunDetail } from "./commands.ts";
+import type {
+  DemandDecl,
+  ProjectMRsData,
+  DiscussionsData,
+  MrByBranchData,
+  ForgeSlug,
+  ForgeTokenData,
+  RunSummary,
+  RunDetail,
+  WakeMode,
+  ChatMember,
+  ChatMessage,
+  RoomSummary,
+} from "./commands.ts";
 
 /**
  * One repo's project open-MR store. A cold repo forces a full paginated sync
@@ -90,3 +103,130 @@ export function getRun(
   if (repo !== undefined) payload.repo = repo;
   return rtCommand<RunDetail>("runs:get", payload, { sockPath: opts.sockPath, timeoutMs: 10_000 });
 }
+
+/**
+ * SKILLS-54. rt's only write path into run state, so a wedged run can be
+ * resolved by a person instead of lying in the data forever. The write happens
+ * in the daemon and is attributed there; consumers never touch the run DB.
+ */
+export function abandonRun(
+  runId: string,
+  repo?: string,
+  reason?: string,
+  opts: RtClientOptions = {},
+): Promise<RtResponse<{ ok: boolean }>> {
+  const payload: Record<string, unknown> = { runId };
+  if (repo !== undefined) payload.repo = repo;
+  if (reason !== undefined) payload.reason = reason;
+  return rtCommand<{ ok: boolean }>("runs:abandon", payload, { sockPath: opts.sockPath, timeoutMs: 10_000 });
+}
+
+// ─── Chat (RT-48 Task 6) ──────────────────────────────────────────────────
+// The web viewer's (plan 2's) entire dependency: it reaches the daemon
+// through these wrappers over the unix socket, so no /api/chat/* REST rows
+// ship and needsToken() stays untouched.
+
+export function chatJoin(
+  a: { room: string; handle: string; wakeOn?: WakeMode; cwd?: string; pane?: string },
+  o: RtClientOptions = {},
+): Promise<RtResponse<{ handle: string; memberCount: number; unread: number }>> {
+  const payload: Record<string, unknown> = { room: a.room, handle: a.handle };
+  if (a.wakeOn !== undefined) payload.wakeOn = a.wakeOn;
+  if (a.cwd !== undefined) payload.cwd = a.cwd;
+  if (a.pane !== undefined) payload.pane = a.pane;
+  return rtCommand<{ handle: string; memberCount: number; unread: number }>("chat:join", payload, { sockPath: o.sockPath, timeoutMs: 10_000 });
+}
+
+export function chatLeave(
+  a: { room: string; handle: string },
+  o: RtClientOptions = {},
+): Promise<RtResponse<Record<string, never>>> {
+  return rtCommand<Record<string, never>>("chat:leave", { room: a.room, handle: a.handle }, { sockPath: o.sockPath, timeoutMs: 10_000 });
+}
+
+export function chatPost(
+  a: { room: string; handle: string; body: string },
+  o: RtClientOptions = {},
+): Promise<RtResponse<{ id: number; recipients: string[] }>> {
+  return rtCommand<{ id: number; recipients: string[] }>("chat:post", { room: a.room, handle: a.handle, body: a.body }, { sockPath: o.sockPath, timeoutMs: 10_000 });
+}
+
+export function chatRead(
+  a: { handle: string; room?: string; limit?: number; sinceMs?: number },
+  o: RtClientOptions = {},
+): Promise<RtResponse<{ rooms: { room: string; messages: ChatMessage[] }[] }>> {
+  const payload: Record<string, unknown> = { handle: a.handle };
+  if (a.room !== undefined) payload.room = a.room;
+  if (a.limit !== undefined) payload.limit = a.limit;
+  if (a.sinceMs !== undefined) payload.sinceMs = a.sinceMs;
+  return rtCommand<{ rooms: { room: string; messages: ChatMessage[] }[] }>("chat:read", payload, { sockPath: o.sockPath, timeoutMs: 10_000 });
+}
+
+export function chatRooms(
+  a: { handle: string },
+  o: RtClientOptions = {},
+): Promise<RtResponse<{ rooms: RoomSummary[] }>> {
+  return rtCommand<{ rooms: RoomSummary[] }>("chat:rooms", { handle: a.handle }, { sockPath: o.sockPath, timeoutMs: 10_000 });
+}
+
+export function chatWho(
+  a: { room: string },
+  o: RtClientOptions = {},
+): Promise<RtResponse<{ members: ChatMember[] }>> {
+  return rtCommand<{ members: ChatMember[] }>("chat:who", { room: a.room }, { sockPath: o.sockPath, timeoutMs: 10_000 });
+}
+
+export function chatMark(
+  a: { handle: string; room?: string },
+  o: RtClientOptions = {},
+): Promise<RtResponse<Record<string, never>>> {
+  const payload: Record<string, unknown> = { handle: a.handle };
+  if (a.room !== undefined) payload.room = a.room;
+  return rtCommand<Record<string, never>>("chat:mark", payload, { sockPath: o.sockPath, timeoutMs: 10_000 });
+}
+
+export function chatMessages(
+  a: { room: string; before?: number; limit?: number },
+  o: RtClientOptions = {},
+): Promise<RtResponse<{ messages: ChatMessage[] }>> {
+  const payload: Record<string, unknown> = { room: a.room };
+  if (a.before !== undefined) payload.before = a.before;
+  if (a.limit !== undefined) payload.limit = a.limit;
+  return rtCommand<{ messages: ChatMessage[] }>("chat:messages", payload, { sockPath: o.sockPath, timeoutMs: 10_000 });
+}
+
+export function chatArm(
+  a: { handle: string; room?: string },
+  o: RtClientOptions = {},
+): Promise<RtResponse<Record<string, never>>> {
+  const payload: Record<string, unknown> = { handle: a.handle };
+  if (a.room !== undefined) payload.room = a.room;
+  return rtCommand<Record<string, never>>("chat:arm", payload, { sockPath: o.sockPath, timeoutMs: 10_000 });
+}
+
+export function chatTouch(
+  a: { handle: string },
+  o: RtClientOptions = {},
+): Promise<RtResponse<Record<string, never>>> {
+  return rtCommand<Record<string, never>>("chat:touch", { handle: a.handle }, { sockPath: o.sockPath, timeoutMs: 10_000 });
+}
+
+export function chatDisarm(
+  a: { handle: string },
+  o: RtClientOptions = {},
+): Promise<RtResponse<Record<string, never>>> {
+  return rtCommand<Record<string, never>>("chat:disarm", { handle: a.handle }, { sockPath: o.sockPath, timeoutMs: 10_000 });
+}
+
+export function chatUnreadWaking(
+  a: { handle: string; room?: string },
+  o: RtClientOptions = {},
+): Promise<RtResponse<{ rooms: { room: string; count: number; mentions: number; maxId: number }[] }>> {
+  const payload: Record<string, unknown> = { handle: a.handle };
+  if (a.room !== undefined) payload.room = a.room;
+  return rtCommand<{ rooms: { room: string; count: number; mentions: number; maxId: number }[] }>("chat:unread-waking", payload, { sockPath: o.sockPath, timeoutMs: 10_000 });
+}
+
+export function eventsHead(o: RtClientOptions = {}): Promise<RtResponse<{ cursor: number }>> {
+  return rtCommand<{ cursor: number }>("events:head", {}, { sockPath: o.sockPath, timeoutMs: 10_000 });
+}

package/src/commands.ts

@@ -58,12 +58,74 @@ export interface ForgeTokenData {
  */
 export interface EventsBusEvent { id: number; topic: string; payload: unknown; emittedAt: number }
 
+/**
+ * Duplicated shape on purpose, same reasoning as EventsBusEvent above:
+ * these mirror lib/state/chat-store.ts's types, which rt-client cannot
+ * import (it's outside lib/state/ and outside this package entirely).
+ */
+export type WakeMode = "mention" | "all" | "none";
+
+export interface ChatMember {
+  room: string;
+  handle: string;
+  joinedAt: number;
+  lastReadId: number;
+  wakeOn: WakeMode;
+  lastSeenAt?: number;
+  armedAt?: number;
+  cwd?: string;
+  pane?: string;
+}
+
+export interface ChatMessage {
+  id: number;
+  room: string;
+  handle: string;
+  body: string;
+  mentions: string[];
+  replyTo?: number;
+  postedAt: number;
+}
+
+export interface RoomSummary {
+  room: string;
+  memberCount: number;
+  unread: number;
+  mentions: number;
+  lastPostedAt?: number;
+}
+
+// SKILLS-53: one judgment, computed once in rt, so the console and the tray
+// never derive two verdicts that can disagree.
+export type Attention = {
+  needs: boolean;
+  reason: "failed" | "stale" | "stranded" | null;
+  evidence: string;
+};
+
 export interface RunSummary {
   id: string; repo: string; work_type: string; pipeline: string;
   status: string; current_stage: string | null; spawned_by: string | null;
   started_at: number; ended_at: number | null;
+  // v2. Null on runs written before schema v2; pack_dirty means the pack tree
+  // had uncommitted changes, so the as-run text may exist in no commit.
+  pack_commits: string | null; pack_dirty: number;
+  attention: Attention;
+  /** Max over stage, field, and decision timestamps; falls back to
+      `started_at` when the run has produced no events yet. The board orders
+      by silence, so this — not `started_at` — is its sort key. */
+  last_event_at: number;
+  /** Denormalized from the run's `ticket` / `branch` fields so the LIST view
+      can render and search them without a detail fetch per row. Null when
+      the run has not produced that field yet. */
+  ticket: string | null;
+  branch: string | null;
+}
+export interface RunStageRow {
+  name: string; status: string; attempt: number;
+  started_at: number | null; ended_at: number | null;
+  reason: string | null; detail_path: string | null;
 }
-export interface RunStageRow { name: string; status: string; attempt: number; started_at: number | null; ended_at: number | null; }
 export interface RunFieldRow { key: string; value: string; produced_by: string; at: number; }
 export interface RunDecisionRow { contract: string; scope: string; selection: string; decided_by: string; decided_at: number; }
 export interface RunDetail { run: RunSummary; stages: RunStageRow[]; fields: RunFieldRow[]; decisions: RunDecisionRow[]; schemaAhead: boolean; }
@@ -120,8 +182,22 @@ export interface Commands {
   "events:emit": { payload: { topic: string; payload?: unknown }; data: { id: number } };
   "events:wait": { payload: { pattern: string; after?: number; waitMs?: number }; data: { events: EventsBusEvent[]; cursor: number } };
   "events:list": { payload: { pattern: string; after?: number; limit?: number }; data: { events: EventsBusEvent[]; cursor: number } };
+  "events:head": { payload: Record<string, never>; data: { cursor: number } };
   "runs:list": { payload: { repo?: string }; data: { runs: RunSummary[] } };
   "runs:get": { payload: { runId: string; repo?: string }; data: RunDetail };
+  "runs:abandon": { payload: { runId: string; repo?: string; reason?: string }; data: { ok: boolean } };
+  "chat:join": { payload: { room: string; handle: string; wakeOn?: WakeMode; cwd?: string; pane?: string }; data: { handle: string; memberCount: number; unread: number } };
+  "chat:leave": { payload: { room: string; handle: string }; data: Record<string, never> };
+  "chat:post": { payload: { room: string; handle: string; body: string }; data: { id: number; recipients: string[] } };
+  "chat:read": { payload: { handle: string; room?: string; limit?: number; sinceMs?: number }; data: { rooms: { room: string; messages: ChatMessage[] }[] } };
+  "chat:rooms": { payload: { handle: string }; data: { rooms: RoomSummary[] } };
+  "chat:who": { payload: { room: string }; data: { members: ChatMember[] } };
+  "chat:mark": { payload: { handle: string; room?: string }; data: Record<string, never> };
+  "chat:messages": { payload: { room: string; before?: number; limit?: number }; data: { messages: ChatMessage[] } };
+  "chat:arm": { payload: { handle: string; room?: string }; data: Record<string, never> };
+  "chat:touch": { payload: { handle: string }; data: Record<string, never> };
+  "chat:disarm": { payload: { handle: string }; data: Record<string, never> };
+  "chat:unread-waking": { payload: { handle: string; room?: string }; data: { rooms: { room: string; count: number; mentions: number; maxId: number }[] } };
 }
 
 export type CommandName = keyof Commands;
@@ -135,6 +211,20 @@ export const COMMAND_NAMES: readonly CommandName[] = [
   "events:emit",
   "events:wait",
   "events:list",
+  "events:head",
   "runs:list",
   "runs:get",
+  "runs:abandon",
+  "chat:join",
+  "chat:leave",
+  "chat:post",
+  "chat:read",
+  "chat:rooms",
+  "chat:who",
+  "chat:mark",
+  "chat:messages",
+  "chat:arm",
+  "chat:touch",
+  "chat:disarm",
+  "chat:unread-waking",
 ];

package/src/index.ts

@@ -1,7 +1,28 @@
 export { rtCommand, DEFAULT_SOCK } from "./transport.ts";
 export type { RtResponse, RtClientOptions } from "./transport.ts";
 
-export { readProjectMRs, readDiscussions, readMrsByBranch, resolveForgeToken } from "./client.ts";
+export {
+  readProjectMRs,
+  readDiscussions,
+  readMrsByBranch,
+  resolveForgeToken,
+  listRuns,
+  getRun,
+  abandonRun,
+  chatJoin,
+  chatLeave,
+  chatPost,
+  chatRead,
+  chatRooms,
+  chatWho,
+  chatMark,
+  chatMessages,
+  chatArm,
+  chatTouch,
+  chatDisarm,
+  chatUnreadWaking,
+  eventsHead,
+} from "./client.ts";
 
 export { COMMAND_NAMES } from "./commands.ts";
 export type {
@@ -16,6 +37,16 @@ export type {
   CommandName,
   ForgeSlug,
   ForgeTokenData,
+  Attention,
+  RunSummary,
+  RunStageRow,
+  RunFieldRow,
+  RunDecisionRow,
+  RunDetail,
+  WakeMode,
+  ChatMember,
+  ChatMessage,
+  RoomSummary,
 } from "./commands.ts";
 
 export { subscribe, DEFAULT_WS_URL } from "./relay.ts";
@@ -37,7 +68,7 @@ export type {
   ExpandCtx,
 } from "./settings/resolve.ts";
 
-export { setSetting } from "./settings/write.ts";
+export { setSetting, unsetSetting } from "./settings/write.ts";
 export type { SetSettingOpts } from "./settings/write.ts";
 
 export { getDef, allDefs, validateValue, isMigrated } from "./settings/registry-machinery.ts";
@@ -47,4 +78,8 @@ export { REGISTRY } from "./settings/registry-defs.ts";
 export { readStore, listTeams } from "./settings/stores.ts";
 export type { StoreFile } from "./settings/stores.ts";
 
-export { normalizeRemote, identityFromRemote, deriveRepoIdentity, clearIdentityMemo } from "./settings/identity.ts";
+export {
+  normalizeRemote, identityFromRemote, deriveRepoIdentity, clearIdentityMemo,
+  serializeIdentity, parseIdentity, resolveNameToIdentity,
+  type RepoIdentity,
+} from "./settings/identity.ts";

package/src/repos.ts

@@ -1,13 +1,16 @@
 /**
- * Repo-name resolution against rt's global index (~/.mattstack/rt/repos.json),
- * a flat
- * `{ "<repoName>": "<absolute path>" }` map. Lets a client resolve "what
- * directory am I in" to "what does the daemon call this repo" without
- * maintaining its own copy of the mapping.
+ * Repo-name resolution against rt's global index. rt itself resolves this
+ * through state.db (~/.mattstack/rt/state.db); this module runs OUT OF
+ * PROCESS (gitq, mr-board, deck), so it has no handle on that db and reads
+ * a derived snapshot instead — state.db's kv `repo-index` namespace when
+ * reachable, falling back to the legacy `repos.json` mirror
+ * (~/.mattstack/rt/repos.json, a flat `{ "<repoName>": "<absolute path>" }`
+ * map) rt keeps in sync for exactly this purpose. See rt's
+ * lib/repo-index.ts `repoIndexCompatPath` for the write side.
  */
 import { existsSync, readFileSync } from "fs";
 import { homedir } from "os";
-import { join } from "path";
+import { dirname, join } from "path";
 
 function defaultReposJsonPath(): string {
   // Duplicates the ~/.mattstack/rt layout: rt-client has no dependency on rt's
@@ -16,17 +19,65 @@ function defaultReposJsonPath(): string {
   return join(homedir(), ".mattstack", "rt", "repos.json");
 }
 
+interface RepoIndexRow {
+  k: string;
+  v: string;
+}
+
+interface BunSqliteDatabase {
+  query(sql: string): { all(...params: unknown[]): unknown[] };
+  close(): void;
+}
+
+type BunSqliteDatabaseCtor = new (path: string, opts?: { readonly?: boolean }) => BunSqliteDatabase;
+
 /**
- * Exact-match lookup: returns the repo name whose recorded path equals
- * `repoPath`, or null if the file is missing, corrupt, or has no match.
- * Never throws -- a resolution failure just means the caller falls back to
- * whatever it had before (an unqualified path, a prompt, etc).
+ * Loads bun:sqlite defensively: only Bun's runtime provides this built-in.
+ * A non-Bun consumer throws resolving the specifier, caught here so the
+ * caller degrades to the repos.json path instead of throwing.
  */
-export function repoNameForPath(repoPath: string, reposJsonPath?: string): string | null {
-  const path = reposJsonPath ?? defaultReposJsonPath();
+function loadBunSqliteDatabase(): BunSqliteDatabaseCtor | null {
+  try {
+    return (require("bun:sqlite") as { Database: BunSqliteDatabaseCtor }).Database;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Exact-match lookup against state.db's `repo-index` kv namespace (ns=k=v
+ * rows written by rt's setKvValue, so `v` is a JSON-encoded string). Returns
+ * null (never throws) on any failure — missing db, unreadable, wrong
+ * schema, no match — so the caller always has repos.json as a fallback.
+ */
+function repoNameFromStateDb(repoPath: string, dbPath: string): string | null {
+  if (!existsSync(dbPath)) return null;
+  const DatabaseCtor = loadBunSqliteDatabase();
+  if (!DatabaseCtor) return null;
+  try {
+    const db = new DatabaseCtor(dbPath, { readonly: true });
+    try {
+      const rows = db.query("SELECT k, v FROM kv WHERE ns = 'repo-index';").all() as RepoIndexRow[];
+      for (const row of rows) {
+        try {
+          if (JSON.parse(row.v) === repoPath) return row.k;
+        } catch {
+          continue;
+        }
+      }
+      return null;
+    } finally {
+      db.close();
+    }
+  } catch {
+    return null;
+  }
+}
+
+function repoNameFromJson(repoPath: string, reposJsonPath: string): string | null {
   try {
-    if (!existsSync(path)) return null;
-    const raw = readFileSync(path, "utf8");
+    if (!existsSync(reposJsonPath)) return null;
+    const raw = readFileSync(reposJsonPath, "utf8");
     const index = JSON.parse(raw) as Record<string, unknown>;
     for (const [repoName, value] of Object.entries(index)) {
       if (value === repoPath) return repoName;
@@ -36,3 +87,23 @@ export function repoNameForPath(repoPath: string, reposJsonPath?: string): strin
     return null;
   }
 }
+
+/**
+ * Exact-match lookup: returns the repo name whose recorded path equals
+ * `repoPath`, or null if no source has a match. Never throws -- a
+ * resolution failure just means the caller falls back to whatever it had
+ * before (an unqualified path, a prompt, etc).
+ *
+ * Prefers state.db (authoritative, kept live by every rt process); falls
+ * back to the repos.json compat mirror when state.db is unreachable — a
+ * pre-upgrade rt install, a non-Bun consumer, or a state.db this process
+ * can't open. `reposJsonPath`, when passed, also relocates the state.db
+ * lookup: both files live side by side under the same rt data directory.
+ */
+export function repoNameForPath(repoPath: string, reposJsonPath?: string): string | null {
+  const jsonPath = reposJsonPath ?? defaultReposJsonPath();
+  const dbPath = join(dirname(jsonPath), "state.db");
+  const fromDb = repoNameFromStateDb(repoPath, dbPath);
+  if (fromDb !== null) return fromDb;
+  return repoNameFromJson(repoPath, jsonPath);
+}

package/src/settings/identity.ts

@@ -1,14 +1,15 @@
 /**
- * Repo identity: the normalized-remote string that keys `repos.<identity>`
- * sections in every settings store (RT-47 spec, "Repo identity").
+ * Repo identity: the tagged value that keys `repos.<identity>` sections in
+ * every settings store.
  *
- * Identity is `host/path` (lowercase host, path case preserved), derived from
- * `remote.origin.url` — never a filesystem path, so it is checkout-location
- * independent: every worktree of a repo shares the same remote and therefore
- * the same identity. A remote that doesn't match a recognized host form
- * (bare local paths are the main case — repos.json has two) normalizes to
- * null, meaning repo-scoped sections are unreachable for it and only global
- * scopes apply. That's an honest degrade, not a crash.
+ * A `remote`-kind identity is `host/path` (lowercase host, path case
+ * preserved), derived from `remote.origin.url` — checkout-location
+ * independent, since every worktree of a repo shares the same remote. When
+ * no usable remote exists, identity falls back to `path`-kind: the realpath
+ * of the *main* worktree, which is still shared across that repo's linked
+ * worktrees (see `deriveRepoIdentity`) even though it is filesystem-bound.
+ * `deriveRepoIdentity` therefore never returns null — every repo has at
+ * least a path-kind identity.
  *
  * Three entry points:
  *  - `normalizeRemote` is the pure string transform, no I/O.
@@ -25,6 +26,8 @@
  *    one process don't re-spawn git.
  */
 
+import { existsSync, readFileSync, realpathSync } from "fs";
+import { join } from "path";
 import { runCapture } from "./exec.ts";
 import { machineSettingsPath } from "./paths.ts";
 import { readStore } from "./stores.ts";
@@ -37,6 +40,40 @@ const URL_RE = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/(?:[^@/]+@)?([^/]+)\/(.+)$/;
 // so a Windows-drive-letter-free local remote never falsely matches.
 const SCP_RE = /^(?:[^@/\s]+@)?([^:/\s]+):(.+)$/;
 
+export type RepoIdentity =
+  | { kind: "remote"; id: string }
+  | { kind: "path"; id: string };
+
+/**
+ * The wire form crosses the daemon socket, sits in board config, and lands in
+ * console's `/runs/:repo/...` URL — all of which need one slash-free segment.
+ * `encodeURIComponent` guarantees that and is exactly reversible.
+ */
+export function serializeIdentity(id: RepoIdentity): string {
+  return `${id.kind}:${encodeURIComponent(id.id)}`;
+}
+
+export function parseIdentity(wire: string): RepoIdentity | null {
+  const colon = wire.indexOf(":");
+  if (colon === -1) return null;
+  const kind = wire.slice(0, colon);
+  if (kind !== "remote" && kind !== "path") return null;
+  const encoded = wire.slice(colon + 1);
+  let id: string;
+  try {
+    id = decodeURIComponent(encoded);
+  } catch {
+    return null;
+  }
+  // Canonical wires only: the id segment must be byte-for-byte what
+  // serializeIdentity emits. Guard sites validate with parseIdentity and then
+  // use the WIRE as a single path component (repoDataDir et al.) — a
+  // hand-built wire with a literal "/" ("path:../..") would otherwise parse
+  // and escape the state directory.
+  if (encodeURIComponent(id) !== encoded) return null;
+  return { kind, id };
+}
+
 /**
  * Pure normalization: `remote` → `host/path` (lowercase host, `.git` and
  * embedded credentials stripped) or null when the remote doesn't match a
@@ -75,47 +112,71 @@ export function normalizeRemote(remote: string): string | null {
  * Reads the machine store fresh each call (files are small; store reads are
  * not memoized anywhere in the resolver design).
  */
-export function identityFromRemote(remote: string): string | null {
+export function identityFromRemote(remote: string): RepoIdentity | null {
   const store = readStore(machineSettingsPath());
   const overrides = store.global["rt.repoIdentityOverrides"];
   if (overrides !== null && typeof overrides === "object" && !Array.isArray(overrides)) {
     const hit = (overrides as Record<string, unknown>)[remote];
-    if (typeof hit === "string") return hit;
+    if (typeof hit === "string") return { kind: "remote", id: hit };
   }
-  return normalizeRemote(remote);
+  const normalized = normalizeRemote(remote);
+  return normalized === null ? null : { kind: "remote", id: normalized };
 }
 
 // Per-process, per-repo-path memoization. Promise-valued so concurrent
 // callers for the same path share one spawn rather than racing.
-const memo = new Map<string, Promise<string | null>>();
+const memo = new Map<string, Promise<RepoIdentity>>();
 
 /**
  * Async derivation from a repo path: `git -C <repoPath> config --get
  * remote.origin.url`, then identityFromRemote (so overrides apply to
  * derivation too). Never a sync spawn — safe to call from daemon contexts.
+ * Never returns null: no usable remote falls back to a path-kind identity
+ * (the main worktree's realpath, via `git worktree list`, so every linked
+ * worktree of one repo still shares the same identity).
  *
- * Only a SUCCESSFUL derivation (non-null identity) is memoized, for the life
- * of the process; a remote change after that first success is NOT picked up
- * until clearIdentityMemo() — documented behavior, not a bug (see spec:
- * derivation is a one-time capture per process, not a live poll). A FAILED
- * derivation (no remote yet, git not initialized yet, etc.) is never cached
- * and is retried on every subsequent call — a caller racing repo
- * provisioning (mid-clone, daemon-startup) must not permanently lose
- * identity for a path just because it asked too early.
+ * Only a `remote`-kind result is memoized, for the life of the process; a
+ * remote change after that first success is NOT picked up until
+ * clearIdentityMemo() — documented behavior, not a bug (see spec: derivation
+ * is a one-time capture per process, not a live poll). A `path`-kind result
+ * is never cached and is retried on every subsequent call — cheap to
+ * recompute, and a caller racing repo provisioning (mid-clone,
+ * daemon-startup, a remote added after the fact) must not permanently lose
+ * the chance to pick up a real remote just because it asked too early.
  */
-export async function deriveRepoIdentity(repoPath: string): Promise<string | null> {
+export async function deriveRepoIdentity(repoPath: string): Promise<RepoIdentity> {
   const cached = memo.get(repoPath);
   if (cached) return cached;
 
-  const result = await (async (): Promise<string | null> => {
+  const result = await (async (): Promise<RepoIdentity> => {
     const spawned = await runCapture(["git", "-C", repoPath, "config", "--get", "remote.origin.url"]);
-    if (spawned.exitCode !== 0) return null;
-    const remote = spawned.stdout.trim();
-    if (!remote) return null;
-    return identityFromRemote(remote);
+    if (spawned.exitCode === 0) {
+      const remote = spawned.stdout.trim();
+      const fromRemote = remote ? identityFromRemote(remote) : null;
+      if (fromRemote) return fromRemote;
+    }
+    // Main worktree via `git worktree list` (main is always listed first) —
+    // NOT `--git-common-dir/..`, which points outside the tree under
+    // `--separate-git-dir` and would derive one shared identity for every
+    // repo whose metadata lives in the same parent directory. In that layout
+    // git lists the git DIR as the main entry, so the listed path is resolved
+    // through its own `--show-toplevel`, degrading to this worktree's
+    // toplevel when the entry isn't a work tree at all.
+    const listed = await runCapture(["git", "-C", repoPath, "worktree", "list", "--porcelain"]);
+    const first = listed.exitCode === 0 ? /^worktree (.+)$/m.exec(listed.stdout)?.[1]?.trim() : undefined;
+    let base: string | undefined;
+    if (first) {
+      const top = await runCapture(["git", "-C", first, "rev-parse", "--show-toplevel"]);
+      if (top.exitCode === 0 && top.stdout.trim()) base = top.stdout.trim();
+    }
+    if (!base) {
+      const own = await runCapture(["git", "-C", repoPath, "rev-parse", "--show-toplevel"]);
+      base = own.exitCode === 0 && own.stdout.trim() ? own.stdout.trim() : repoPath;
+    }
+    return { kind: "path", id: safeRealpath(base) };
   })();
 
-  if (result !== null) memo.set(repoPath, Promise.resolve(result));
+  if (result.kind === "remote") memo.set(repoPath, Promise.resolve(result));
   return result;
 }
 
@@ -123,3 +184,35 @@ export async function deriveRepoIdentity(repoPath: string): Promise<string | nul
 export function clearIdentityMemo(): void {
   memo.clear();
 }
+
+// realpath of a path that no longer exists throws ENOENT. A path-kind identity
+// may be derived for a worktree whose directory is already gone (dispose flows
+// call this on the tree being removed), and derivation must degrade to the
+// literal path there, never throw past its callers.
+function safeRealpath(p: string): string {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * One-shot helper for rewriting board's existing name-valued config to
+ * host/path identities. NOT a runtime path — the daemon never calls it.
+ * Resolves a repo name to the identity of the path it points at in repos.json.
+ */
+export async function resolveNameToIdentity(
+  name: string,
+  reposJsonPath: string,
+): Promise<RepoIdentity | null> {
+  if (!existsSync(reposJsonPath)) return null;
+  try {
+    const index = JSON.parse(readFileSync(reposJsonPath, "utf8")) as Record<string, unknown>;
+    const path = index[name];
+    if (typeof path !== "string") return null;
+    return await deriveRepoIdentity(path);
+  } catch {
+    return null;
+  }
+}