@mattstack/rt-client 0.3.0 → 0.4.1

package/dist/index.js

@@ -1,3 +1,6 @@
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
 // src/transport.ts
 import { homedir } from "os";
 import { join } from "path";
@@ -39,6 +42,93 @@ function readMrsByBranch(repoName, branches, opts = {}) {
 function resolveForgeToken(repoName, forge, opts = {}) {
   return rtCommand("secrets:forge-token", { repoName, forge }, { sockPath: opts.sockPath, timeoutMs: 1e4 });
 }
+function listRuns(repo, opts = {}) {
+  const payload = {};
+  if (repo !== undefined)
+    payload.repo = repo;
+  return rtCommand("runs:list", payload, { sockPath: opts.sockPath, timeoutMs: 1e4 });
+}
+function getRun(runId, repo, opts = {}) {
+  const payload = { runId };
+  if (repo !== undefined)
+    payload.repo = repo;
+  return rtCommand("runs:get", payload, { sockPath: opts.sockPath, timeoutMs: 1e4 });
+}
+function abandonRun(runId, repo, reason, opts = {}) {
+  const payload = { runId };
+  if (repo !== undefined)
+    payload.repo = repo;
+  if (reason !== undefined)
+    payload.reason = reason;
+  return rtCommand("runs:abandon", payload, { sockPath: opts.sockPath, timeoutMs: 1e4 });
+}
+function chatJoin(a, o = {}) {
+  const payload = { 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("chat:join", payload, { sockPath: o.sockPath, timeoutMs: 1e4 });
+}
+function chatLeave(a, o = {}) {
+  return rtCommand("chat:leave", { room: a.room, handle: a.handle }, { sockPath: o.sockPath, timeoutMs: 1e4 });
+}
+function chatPost(a, o = {}) {
+  return rtCommand("chat:post", { room: a.room, handle: a.handle, body: a.body }, { sockPath: o.sockPath, timeoutMs: 1e4 });
+}
+function chatRead(a, o = {}) {
+  const payload = { 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("chat:read", payload, { sockPath: o.sockPath, timeoutMs: 1e4 });
+}
+function chatRooms(a, o = {}) {
+  return rtCommand("chat:rooms", { handle: a.handle }, { sockPath: o.sockPath, timeoutMs: 1e4 });
+}
+function chatWho(a, o = {}) {
+  return rtCommand("chat:who", { room: a.room }, { sockPath: o.sockPath, timeoutMs: 1e4 });
+}
+function chatMark(a, o = {}) {
+  const payload = { handle: a.handle };
+  if (a.room !== undefined)
+    payload.room = a.room;
+  return rtCommand("chat:mark", payload, { sockPath: o.sockPath, timeoutMs: 1e4 });
+}
+function chatMessages(a, o = {}) {
+  const payload = { room: a.room };
+  if (a.before !== undefined)
+    payload.before = a.before;
+  if (a.limit !== undefined)
+    payload.limit = a.limit;
+  return rtCommand("chat:messages", payload, { sockPath: o.sockPath, timeoutMs: 1e4 });
+}
+function chatArm(a, o = {}) {
+  const payload = { handle: a.handle };
+  if (a.room !== undefined)
+    payload.room = a.room;
+  return rtCommand("chat:arm", payload, { sockPath: o.sockPath, timeoutMs: 1e4 });
+}
+function chatTouch(a, o = {}) {
+  return rtCommand("chat:touch", { handle: a.handle }, { sockPath: o.sockPath, timeoutMs: 1e4 });
+}
+function chatDisarm(a, o = {}) {
+  return rtCommand("chat:disarm", { handle: a.handle }, { sockPath: o.sockPath, timeoutMs: 1e4 });
+}
+function chatUnreadWaking(a, o = {}) {
+  const payload = { handle: a.handle };
+  if (a.room !== undefined)
+    payload.room = a.room;
+  return rtCommand("chat:unread-waking", payload, { sockPath: o.sockPath, timeoutMs: 1e4 });
+}
+function eventsHead(o = {}) {
+  return rtCommand("events:head", {}, { sockPath: o.sockPath, timeoutMs: 1e4 });
+}
 // src/commands.ts
 var COMMAND_NAMES = [
   "project-mrs:read",
@@ -49,8 +139,22 @@ var COMMAND_NAMES = [
   "events:emit",
   "events:wait",
   "events:list",
+  "events:head",
   "runs:list",
-  "runs:get"
+  "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"
 ];
 // src/relay.ts
 var DEFAULT_WS_URL = "ws://127.0.0.1:9401/ws";
@@ -98,16 +202,48 @@ function subscribe(onEvent, opts = {}) {
 // src/repos.ts
 import { existsSync, readFileSync } from "fs";
 import { homedir as homedir2 } from "os";
-import { join as join2 } from "path";
+import { dirname, join as join2 } from "path";
 function defaultReposJsonPath() {
   return join2(homedir2(), ".mattstack", "rt", "repos.json");
 }
-function repoNameForPath(repoPath, reposJsonPath) {
-  const path = reposJsonPath ?? defaultReposJsonPath();
+function loadBunSqliteDatabase() {
+  try {
+    return __require("bun:sqlite").Database;
+  } catch {
+    return null;
+  }
+}
+function repoNameFromStateDb(repoPath, dbPath) {
+  if (!existsSync(dbPath))
+    return null;
+  const DatabaseCtor = loadBunSqliteDatabase();
+  if (!DatabaseCtor)
+    return null;
   try {
-    if (!existsSync(path))
+    const db = new DatabaseCtor(dbPath, { readonly: true });
+    try {
+      const rows = db.query("SELECT k, v FROM kv WHERE ns = 'repo-index';").all();
+      for (const row of rows) {
+        try {
+          if (JSON.parse(row.v) === repoPath)
+            return row.k;
+        } catch {
+          continue;
+        }
+      }
       return null;
-    const raw = readFileSync(path, "utf8");
+    } finally {
+      db.close();
+    }
+  } catch {
+    return null;
+  }
+}
+function repoNameFromJson(repoPath, reposJsonPath) {
+  try {
+    if (!existsSync(reposJsonPath))
+      return null;
+    const raw = readFileSync(reposJsonPath, "utf8");
     const index = JSON.parse(raw);
     for (const [repoName, value] of Object.entries(index)) {
       if (value === repoPath)
@@ -118,6 +254,14 @@ function repoNameForPath(repoPath, reposJsonPath) {
     return null;
   }
 }
+function repoNameForPath(repoPath, reposJsonPath) {
+  const jsonPath = reposJsonPath ?? defaultReposJsonPath();
+  const dbPath = join2(dirname(jsonPath), "state.db");
+  const fromDb = repoNameFromStateDb(repoPath, dbPath);
+  if (fromDb !== null)
+    return fromDb;
+  return repoNameFromJson(repoPath, jsonPath);
+}
 // src/settings/resolve.ts
 import { homedir as homedir4 } from "os";
 import { join as join5 } from "path";
@@ -278,7 +422,7 @@ var REGISTRY = [
     merge: "deep",
     repoScoped: true,
     migrated: true,
-    description: "Branch-naming templates. rt itself has no readers of this key yet — the VS Code extension still reads repos/<repo>/branch-naming.json by repo name, which stays authoritative until the extension ports over. Setting this key stores a value nothing consumes."
+    description: "Branch-naming templates, repoScoped. Read by the VS Code extension (extensions/vscode/rt-context), which lazily imports the legacy repos/<repo>/branch-naming.json into this key on first read; rt itself has no CLI-side reader."
   },
   {
     key: "rt.variations",
@@ -338,9 +482,8 @@ var REGISTRY = [
     scopes: ALL_SCOPES,
     merge: "deep",
     repoScoped: true,
-    migrated: false,
-    legacyFile: "repos/<repo>/hooks.json",
-    description: "User-defined lifecycle hooks rt runs around commands (pre/post command scripts)."
+    migrated: true,
+    description: "Per-repo git hook enable/disable state ({enabled, hooks: {<hookName>: boolean}}); ownership-latch port of repos/<repo>/hooks.json, store wins per field once it owns the key — including per-hook-name entries inside the nested hooks map, each defaulting to enabled when absent. The installed git-hook shim still greps repos/<repo>/hooks.json with zero process spawns (a hook fires on every git operation); that file is now a DERIVED CACHE this key writes through, kept current by commands/hooks.ts's regenerateHooksCache at every write seam."
   },
   {
     key: "mattstack.integrations",
@@ -363,6 +506,14 @@ var REGISTRY = [
     merge: "replace",
     description: "Absolute path to the installed mattstack.app bundle, written by the app at launch so rt stops hardcoding ~/Applications."
   },
+  {
+    key: "rt.integrations",
+    type: "object",
+    scopes: ["user"],
+    merge: "deep",
+    migrated: true,
+    description: "User-confirmed integration hosts (forgeHost, switchboardUrl), written only by an explicit `rt setup <id> connect --host` after that host validates a real credential. The one trusted source a credential is ever sent to — mattstack.integrations' team-declared host is shown to the user but never auto-used for a fetch."
+  },
   {
     key: "claude.marketplaces",
     type: "array",
@@ -551,6 +702,35 @@ var REGISTRY = [
     scopes: ["machine"],
     merge: "deep",
     description: "gitq checkout-board config: tracked repos, local port, and the herdr workspace it launches into."
+  },
+  {
+    key: "chat.handle",
+    type: "string",
+    scopes: ["user"],
+    merge: "replace",
+    description: "Explicit rt chat handle for this developer on this machine; overrides the derived <repo>-<dir> handle when set."
+  },
+  {
+    key: "chat.humanHandle",
+    type: "string",
+    scopes: ["user"],
+    default: "matt",
+    merge: "replace",
+    description: "The human's own chat handle, so agents can @-mention them by name."
+  },
+  {
+    key: "chat.push.provider",
+    type: "string",
+    scopes: ["user"],
+    merge: "replace",
+    description: "Push notification provider used to alert the human of chat mentions when away from a terminal."
+  },
+  {
+    key: "chat.push.target",
+    type: "string",
+    scopes: ["user"],
+    merge: "replace",
+    description: "Destination (topic/URL/token) the configured chat.push.provider sends to."
   }
 ];
 
@@ -992,7 +1172,7 @@ function explainSetting(key, opts = {}) {
 import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync4, renameSync, unlinkSync, writeFileSync } from "fs";
 import { applyEdits, modify, parseTree } from "jsonc-parser";
 import { randomBytes } from "crypto";
-import { dirname } from "path";
+import { dirname as dirname2 } from "path";
 var FORMAT = { tabSize: 2, insertSpaces: true, eol: `
 ` };
 function refuse(message) {
@@ -1022,6 +1202,30 @@ function setSetting(key, value, scope, opts = {}) {
   writeIntoStore(storePath, jsonPath, value, scope !== "team");
   console.error(`rt: wrote "${key}" to the local ${scope} store (${storePath}) — this is local only until you commit and push it.`);
 }
+function unsetSetting(key, scope, opts = {}) {
+  const def = getDef(key);
+  if (!def) {
+    refuse(`unknown setting "${key}" — not in the settings registry (see \`rt settings list\`)`);
+  }
+  if (!isMigrated(def)) {
+    refuse(migratedFalseMessage(key, def));
+  }
+  if (!def.scopes.includes(scope)) {
+    refuse(`"${key}" cannot be unset in the ${scope} store (allowed: ${def.scopes.join(", ")})`);
+  }
+  if (opts.repoIdentity !== undefined && def.repoScoped !== true) {
+    refuse(`"${key}" is not repo-scoped — omit the repo identity`);
+  }
+  const storePath = resolveStorePathForUnset(scope, opts);
+  if (storePath === null || !existsSync3(storePath))
+    return false;
+  const jsonPath = opts.repoIdentity !== undefined ? ["repos", opts.repoIdentity, key] : [key];
+  const removed = removeFromStore(storePath, jsonPath);
+  if (removed) {
+    console.error(`rt: removed "${key}" from the local ${scope} store (${storePath}) — this is local only until you commit and push it.`);
+  }
+  return removed;
+}
 function migratedFalseMessage(key, def) {
   const legacyPart = def.legacyFile ? ` — it is still read from ${def.legacyFile}` : "";
   return `"${key}" is not writable through the settings resolver yet${legacyPart}`;
@@ -1047,6 +1251,23 @@ function resolveStorePath(scope, opts) {
   }
   return teamSettingsPath(teams[0]);
 }
+function resolveStorePathForUnset(scope, opts) {
+  if (scope === "user")
+    return userSettingsPath();
+  if (scope === "machine")
+    return machineSettingsPath();
+  if (opts.team !== undefined) {
+    const path = teamSettingsPath(opts.team);
+    return existsSync3(path) ? path : null;
+  }
+  const teams = listTeams();
+  if (teams.length === 0)
+    return null;
+  if (teams.length > 1) {
+    refuse(`multiple local team stores found (${teams.join(", ")}) — pass opts.team to choose one`);
+  }
+  return teamSettingsPath(teams[0]);
+}
 function seedHeader() {
   return `// rt settings — created by \`rt settings set\`. JSONC: comments and trailing commas are fine.
 {}
@@ -1101,7 +1322,7 @@ function writeIntoStore(storePath, jsonPath, value, createIfMissing) {
     if (!createIfMissing) {
       refuse(`store file ${storePath} does not exist`);
     }
-    mkdirSync(dirname(storePath), { recursive: true });
+    mkdirSync(dirname2(storePath), { recursive: true });
     content = seedHeader();
   }
   const edits = modify(content, jsonPath, value, { formattingOptions: FORMAT });
@@ -1109,6 +1330,24 @@ function writeIntoStore(storePath, jsonPath, value, createIfMissing) {
   const finalText = next.endsWith(`
 `) ? next : `${next}
 `;
+  writeTempThenRename(storePath, finalText);
+}
+function removeFromStore(storePath, jsonPath) {
+  const content = readFileSync4(storePath, "utf8");
+  if (content.trim() === "")
+    return false;
+  assertEditableJsonc(storePath, content);
+  const edits = modify(content, jsonPath, undefined, { formattingOptions: FORMAT });
+  if (edits.length === 0)
+    return false;
+  const next = applyEdits(content, edits);
+  const finalText = next.endsWith(`
+`) ? next : `${next}
+`;
+  writeTempThenRename(storePath, finalText);
+  return true;
+}
+function writeTempThenRename(storePath, finalText) {
   const tmp = `${storePath}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
   try {
     writeFileSync(tmp, finalText);
@@ -1120,6 +1359,9 @@ function writeIntoStore(storePath, jsonPath, value, createIfMissing) {
     throw err;
   }
 }
+// src/settings/identity.ts
+import { existsSync as existsSync4, readFileSync as readFileSync5, realpathSync } from "fs";
+
 // src/settings/exec.ts
 async function runCapture(argv, opts = {}) {
   const captureStderr = opts.stderr === "pipe";
@@ -1156,6 +1398,27 @@ async function runCapture(argv, opts = {}) {
 // src/settings/identity.ts
 var URL_RE = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/(?:[^@/]+@)?([^/]+)\/(.+)$/;
 var SCP_RE = /^(?:[^@/\s]+@)?([^:/\s]+):(.+)$/;
+function serializeIdentity(id) {
+  return `${id.kind}:${encodeURIComponent(id.id)}`;
+}
+function parseIdentity(wire) {
+  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;
+  try {
+    id = decodeURIComponent(encoded);
+  } catch {
+    return null;
+  }
+  if (encodeURIComponent(id) !== encoded)
+    return null;
+  return { kind, id };
+}
 function normalizeRemote(remote) {
   const trimmed = remote.trim();
   if (!trimmed)
@@ -1186,9 +1449,10 @@ function identityFromRemote(remote) {
   if (overrides !== null && typeof overrides === "object" && !Array.isArray(overrides)) {
     const hit = overrides[remote];
     if (typeof hit === "string")
-      return hit;
+      return { kind: "remote", id: hit };
   }
-  return normalizeRemote(remote);
+  const normalized = normalizeRemote(remote);
+  return normalized === null ? null : { kind: "remote", id: normalized };
 }
 var memo = new Map;
 async function deriveRepoIdentity(repoPath) {
@@ -1197,43 +1461,96 @@ async function deriveRepoIdentity(repoPath) {
     return cached;
   const result = await (async () => {
     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;
+    }
+    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;
+    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)
+  if (result.kind === "remote")
     memo.set(repoPath, Promise.resolve(result));
   return result;
 }
 function clearIdentityMemo() {
   memo.clear();
 }
+function safeRealpath(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+async function resolveNameToIdentity(name, reposJsonPath) {
+  if (!existsSync4(reposJsonPath))
+    return null;
+  try {
+    const index = JSON.parse(readFileSync5(reposJsonPath, "utf8"));
+    const path = index[name];
+    if (typeof path !== "string")
+      return null;
+    return await deriveRepoIdentity(path);
+  } catch {
+    return null;
+  }
+}
 export {
   validateValue,
+  unsetSetting,
   subscribe,
   setSetting,
+  serializeIdentity,
   rtCommand,
+  resolveNameToIdentity,
   resolveForgeToken,
   repoNameForPath,
   readStore,
   readProjectMRs,
   readMrsByBranch,
   readDiscussions,
+  parseIdentity,
   normalizeRemote,
   listTeams,
   listSettings,
+  listRuns,
   isMigrated,
   identityFromRemote,
   getSetting,
+  getRun,
   getDef,
   explainSetting,
   expandVariables,
+  eventsHead,
   deriveRepoIdentity,
   clearIdentityMemo,
+  chatWho,
+  chatUnreadWaking,
+  chatTouch,
+  chatRooms,
+  chatRead,
+  chatPost,
+  chatMessages,
+  chatMark,
+  chatLeave,
+  chatJoin,
+  chatDisarm,
+  chatArm,
   allDefs,
+  abandonRun,
   SCOPE_ORDER,
   REGISTRY,
   DEFAULT_WS_URL,

package/dist/repos.d.ts

@@ -1,7 +1,13 @@
 /**
  * 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).
+ * `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 declare function repoNameForPath(repoPath: string, reposJsonPath?: string): string | null;

package/dist/settings/identity.d.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.
@@ -24,6 +25,20 @@
  *    through `identityFromRemote`, memoized per path so repeated callers in
  *    one process don't re-spawn git.
  */
+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 declare function serializeIdentity(id: RepoIdentity): string;
+export declare function parseIdentity(wire: string): RepoIdentity | null;
 /**
  * Pure normalization: `remote` → `host/path` (lowercase host, `.git` and
  * embedded credentials stripped) or null when the remote doesn't match a
@@ -36,21 +51,30 @@ export declare 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 declare function identityFromRemote(remote: string): string | null;
+export declare function identityFromRemote(remote: string): RepoIdentity | null;
 /**
  * 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 declare function deriveRepoIdentity(repoPath: string): Promise<string | null>;
+export declare function deriveRepoIdentity(repoPath: string): Promise<RepoIdentity>;
 /** Test-only: clear the derivation memo so a test can force re-derivation. */
 export declare function clearIdentityMemo(): void;
+/**
+ * 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 declare function resolveNameToIdentity(name: string, reposJsonPath: string): Promise<RepoIdentity | null>;

package/dist/settings/write.d.ts

@@ -108,3 +108,15 @@ export interface SetSettingOpts {
  * doc for the full refusal list and the team-selection rule.
  */
 export declare function setSetting(key: string, value: unknown, scope: SettingScope, opts?: SetSettingOpts): void;
+/**
+ * Removes `key` from the given scope's store, comment-preserving. The refusal
+ * ladder is `setSetting`'s minus the value check (there is no value): unknown
+ * key, unmigrated, scope not in `def.scopes`, repoIdentity on a non-repoScoped
+ * key, and the team-selection rule when ambiguous. Divergences from set, both
+ * because removal has nothing to act on: a store FILE that does not exist is a
+ * clean no-op rather than a refusal (an explicit `opts.team` naming a team
+ * with no local store included — nothing to remove is success, not an error),
+ * and a key not present in the store is a no-op. Returns whether anything was
+ * actually removed; the local-only reminder prints only on a real removal.
+ */
+export declare function unsetSetting(key: string, scope: SettingScope, opts?: SetSettingOpts): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mattstack/rt-client",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "type": "module",
   "exports": {
     ".": {