@adhdev/daemon-core 0.9.82-rc.49 → 0.9.82-rc.490

package/src/providers/external-sources.ts

@@ -0,0 +1,218 @@
+/**
+ * External provider sources — registry + active-selection state.
+ *
+ * A user can register one or more 3rd-party git URLs as provider sources.
+ * Each source clones into ~/.adhdev/external/<source-name>/, namespaced so
+ * that two sources can disk-coexist providing the same provider type.
+ *
+ * When two sources expose the same type, only one is "active" at a time.
+ * The active selection is persisted so a user's choice survives daemon
+ * restarts. When only one source provides a type, no explicit selection
+ * is needed and the loader falls through to that source.
+ */
+'use strict';
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+export interface ExternalSource {
+    /** Unique short identifier, e.g. "@vendor-x". User-supplied or derived from the URL. */
+    name: string;
+    /** Full git URL (https://, git@, …). */
+    url: string;
+    /** Branch / tag / commit-ish to track. Defaults to `main`. */
+    ref: string;
+    /** ISO timestamp when first registered. */
+    addedAt: string;
+}
+
+export interface ExternalSourcesFile {
+    /** Schema version — bump if shape changes. */
+    schema: 1;
+    sources: ExternalSource[];
+}
+
+/**
+ * Per-type active source selection. Only types reachable from more than
+ * one source need an entry — single-source types have no ambiguity.
+ *
+ * Shape: { active: { "<type>": "<source-name>" } }
+ */
+export interface ProvidersActiveFile {
+    schema: 1;
+    active: Record<string, string>;
+}
+
+const SOURCES_FILENAME = 'providers-sources.json';
+const ACTIVE_FILENAME = 'providers-active.json';
+
+function adhdevDir(): string {
+    return path.join(os.homedir(), '.adhdev');
+}
+
+export function externalRoot(): string {
+    return path.join(adhdevDir(), 'external');
+}
+
+export function sourcesFilePath(): string {
+    return path.join(adhdevDir(), SOURCES_FILENAME);
+}
+
+export function activeFilePath(): string {
+    return path.join(adhdevDir(), ACTIVE_FILENAME);
+}
+
+function ensureAdhdevDir(): void {
+    const d = adhdevDir();
+    if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+}
+
+export function loadExternalSources(): ExternalSourcesFile {
+    const p = sourcesFilePath();
+    if (!fs.existsSync(p)) return { schema: 1, sources: [] };
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        if (!raw || typeof raw !== 'object') return { schema: 1, sources: [] };
+        const sources = Array.isArray(raw.sources) ? raw.sources.filter(isValidSource) : [];
+        return { schema: 1, sources };
+    } catch {
+        return { schema: 1, sources: [] };
+    }
+}
+
+export function saveExternalSources(file: ExternalSourcesFile): void {
+    ensureAdhdevDir();
+    const tmp = sourcesFilePath() + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(file, null, 2) + '\n', 'utf-8');
+    fs.renameSync(tmp, sourcesFilePath());
+}
+
+export function loadProvidersActive(): ProvidersActiveFile {
+    const p = activeFilePath();
+    if (!fs.existsSync(p)) return { schema: 1, active: {} };
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        if (!raw || typeof raw !== 'object') return { schema: 1, active: {} };
+        const active = raw.active && typeof raw.active === 'object' ? raw.active : {};
+        return { schema: 1, active };
+    } catch {
+        return { schema: 1, active: {} };
+    }
+}
+
+export function saveProvidersActive(file: ProvidersActiveFile): void {
+    ensureAdhdevDir();
+    const tmp = activeFilePath() + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(file, null, 2) + '\n', 'utf-8');
+    fs.renameSync(tmp, activeFilePath());
+}
+
+function isValidSource(x: unknown): x is ExternalSource {
+    if (!x || typeof x !== 'object') return false;
+    const s = x as Record<string, unknown>;
+    return typeof s.name === 'string' && s.name.length > 0
+        && typeof s.url === 'string' && s.url.length > 0
+        && typeof s.ref === 'string' && s.ref.length > 0
+        && typeof s.addedAt === 'string';
+}
+
+/**
+ * Derive a short identifier from a git URL when the user didn't supply one.
+ *   https://github.com/vendor/extra-providers.git → "@vendor-extra-providers"
+ *   git@github.com:vendor/extra-providers       → "@vendor-extra-providers"
+ *
+ * Idempotent; safe to call before validation since it produces a string
+ * regardless of input shape.
+ */
+export function deriveSourceName(url: string): string {
+    const m = url.match(/[/:]([^/:]+)\/([^/]+?)(?:\.git)?$/);
+    if (!m) return '@source';
+    const owner = m[1].toLowerCase().replace(/[^a-z0-9_-]/g, '-');
+    const repo = m[2].toLowerCase().replace(/[^a-z0-9_-]/g, '-');
+    return `@${owner}-${repo}`;
+}
+
+/**
+ * Return the per-source category/type tree currently on disk under
+ * ~/.adhdev/external/<source>/. Used by the conflict detector and by
+ * list_provider_sources.
+ */
+export interface SourceInventoryEntry {
+    sourceName: string;
+    /** Map: category → list of provider types. */
+    providers: Record<string, string[]>;
+}
+
+export function inventoryExternalSources(): SourceInventoryEntry[] {
+    const root = externalRoot();
+    if (!fs.existsSync(root)) return [];
+    const out: SourceInventoryEntry[] = [];
+    let entries: fs.Dirent[];
+    try { entries = fs.readdirSync(root, { withFileTypes: true }); }
+    catch { return []; }
+    for (const sourceEntry of entries) {
+        if (!sourceEntry.isDirectory()) continue;
+        const sourceName = sourceEntry.name;
+        const sourceDir = path.join(root, sourceName);
+        const providers: Record<string, string[]> = {};
+        let categoryEntries: fs.Dirent[];
+        try { categoryEntries = fs.readdirSync(sourceDir, { withFileTypes: true }); }
+        catch { continue; }
+        for (const categoryEntry of categoryEntries) {
+            if (!categoryEntry.isDirectory()) continue;
+            const category = categoryEntry.name;
+            const categoryDir = path.join(sourceDir, category);
+            let typeEntries: fs.Dirent[];
+            try { typeEntries = fs.readdirSync(categoryDir, { withFileTypes: true }); }
+            catch { continue; }
+            const types: string[] = [];
+            for (const typeEntry of typeEntries) {
+                if (!typeEntry.isDirectory()) continue;
+                // Only count it as a provider if a manifest file exists
+                const typeDir = path.join(categoryDir, typeEntry.name);
+                const hasV1 = fs.existsSync(path.join(typeDir, 'provider.v1.json'));
+                const hasV0 = fs.existsSync(path.join(typeDir, 'provider.json'));
+                if (hasV1 || hasV0) types.push(typeEntry.name);
+            }
+            if (types.length > 0) providers[category] = types;
+        }
+        out.push({ sourceName, providers });
+    }
+    return out;
+}
+
+/**
+ * For a given category+type, list every source that currently exposes it.
+ * Returns source names in disk-walk order; callers can use the first one
+ * when no explicit active selection exists.
+ */
+export function sourcesProviding(category: string, type: string): string[] {
+    const inventory = inventoryExternalSources();
+    return inventory
+        .filter(s => (s.providers[category] || []).includes(type))
+        .map(s => s.sourceName);
+}
+
+/**
+ * Resolve which source should be active for a given category+type.
+ *   - If exactly one source provides it → that source.
+ *   - If multiple sources provide it → the one named in providers-active.json
+ *     (when present) or null (ambiguous; loader should warn and pick
+ *     the first deterministically so daemon doesn't refuse to boot).
+ *   - If none → null.
+ */
+export function resolveActiveSource(
+    category: string,
+    type: string,
+    activeFile?: ProvidersActiveFile,
+): { source: string | null; ambiguous: boolean; candidates: string[] } {
+    const candidates = sourcesProviding(category, type);
+    if (candidates.length === 0) return { source: null, ambiguous: false, candidates };
+    if (candidates.length === 1) return { source: candidates[0], ambiguous: false, candidates };
+    const explicit = (activeFile ?? loadProvidersActive()).active[type];
+    if (explicit && candidates.includes(explicit)) {
+        return { source: explicit, ambiguous: false, candidates };
+    }
+    return { source: candidates[0], ambiguous: true, candidates };
+}

package/src/providers/ide-provider-instance.ts

@@ -20,7 +20,7 @@ import { LOG } from '../logging/logger.js';
 import { buildPersistedProviderEffectMessage, normalizeProviderEffects } from './control-effects.js';
 import { validateReadChatResultPayload } from './read-chat-contract.js';
 import type { ChatMessage } from '../types.js';
-import { formatAutoApprovalMessage, pickApprovalButton } from './approval-utils.js';
+import { formatAutoApprovalMessage, pickAutoApprovalButton } from './approval-utils.js';
 import { mergeProviderPatchState, resolveProviderStateSurface } from './provider-patch-state.js';
 import { buildChatMessage, buildRuntimeSystemChatMessage, normalizeChatMessages, extractFinalSummaryFromMessages } from './chat-message-normalization.js';
 import { getProviderSessionCapabilities, IDE_PROVIDER_SESSION_CAPABILITIES_BASE } from './open-panel-support.js';
@@ -43,6 +43,20 @@ type ReadChatPayload = {
     [key: string]: unknown;
 };
 
+async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T> {
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise<never>((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+            }),
+        ]);
+    } finally {
+        if (timer) clearTimeout(timer);
+    }
+}
+
 export class IdeProviderInstance implements ProviderInstance {
     readonly type: string;
     readonly category = 'ide' as const;
@@ -91,8 +105,8 @@ export class IdeProviderInstance implements ProviderInstance {
  // Sync Monitor config
         this.monitor.updateConfig({
             approvalAlert: this.settings.approvalAlert !== false,
-            longGeneratingAlert: this.settings.longGeneratingAlert !== false,
-            longGeneratingThresholdSec: this.settings.longGeneratingThresholdSec || 180,
+            noProgressAlert: (this.settings.noProgressAlert ?? this.settings.longGeneratingAlert) !== false,
+            noProgressThresholdSec: this.settings.noProgressThresholdSec ?? this.settings.longGeneratingThresholdSec ?? 180,
         });
     }
 
@@ -245,11 +259,16 @@ export class IdeProviderInstance implements ProviderInstance {
     }
 
     updateSettings(newSettings: Record<string, any>): void {
-        this.settings = { ...newSettings };
+        // Merge (not replace): a key omitted from newSettings preserves its existing
+        // value, a key present (even false) overrides. Mirrors cli-provider-instance —
+        // a partial mesh relay-stamp must not wipe launch-time settings such as
+        // autoApprove, while the dashboard toggle's full settings object still applies
+        // an explicit autoApprove:false. See cli-provider-instance.updateSettings.
+        this.settings = { ...this.settings, ...newSettings };
         this.monitor.updateConfig({
             approvalAlert: this.settings.approvalAlert !== false,
-            longGeneratingAlert: this.settings.longGeneratingAlert !== false,
-            longGeneratingThresholdSec: this.settings.longGeneratingThresholdSec || 180,
+            noProgressAlert: (this.settings.noProgressAlert ?? this.settings.longGeneratingAlert) !== false,
+            noProgressThresholdSec: this.settings.noProgressThresholdSec ?? this.settings.longGeneratingThresholdSec ?? 180,
         });
     }
 
@@ -320,7 +339,7 @@ export class IdeProviderInstance implements ProviderInstance {
                 if (webviewScript) {
                     const matchText = this.provider.webviewMatchText;
                     const matchFn = matchText ? (body: string) => body.includes(matchText) : undefined;
-                    const webviewRaw = await cdp.evaluateInWebviewFrame(webviewScript, matchFn);
+                    const webviewRaw = await withTimeout(cdp.evaluateInWebviewFrame(webviewScript, matchFn), 30000, 'evaluateInWebviewFrame');
                     if (webviewRaw) {
                         raw = typeof webviewRaw === 'string' ? (() => { try { return JSON.parse(webviewRaw); } catch { return null; } })() : webviewRaw;
                     }
@@ -331,7 +350,7 @@ export class IdeProviderInstance implements ProviderInstance {
             if (!raw) {
                 const readChatScript = this.getReadChatScript();
                 if (!readChatScript) return;
-                raw = await cdp.evaluate(readChatScript, 30000);
+                raw = await withTimeout(cdp.evaluate(readChatScript, 30000), 30000, 'evaluate.readChatScript');
                 if (typeof raw === 'string') {
                     try { raw = JSON.parse(raw); } catch { return; }
                 }
@@ -398,7 +417,7 @@ export class IdeProviderInstance implements ProviderInstance {
             const persistedMessages = chat.messages || messages;
             if (persistedMessages.length > 0) {
                 let toSave = persistedMessages;
-                if (chat.status === 'generating' || chat.status === 'long_generating') {
+                if (chat.status === 'generating' || chat.status === 'no_progress' || chat.status === 'long_generating') {
  // Find and exclude last assistant message
                     const lastIdx = toSave.length - 1;
                     if (lastIdx >= 0 && toSave[lastIdx].role === 'assistant') {
@@ -489,7 +508,11 @@ export class IdeProviderInstance implements ProviderInstance {
         }
 
  // Monitor check (cooldown based notification)
-        const monitorEvents = this.monitor.check(agentKey, agentStatus, now, progressFingerprint);
+        // Approval pending is detected from the raw status: auto-approve synthesizes
+        // `waiting_approval` → 'generating', so the no-progress watchdog must be told
+        // to hold its timer during the wait rather than count it as a stall.
+        const approvalPending = rawAgentStatus === 'waiting_approval';
+        const monitorEvents = this.monitor.check(agentKey, agentStatus, now, progressFingerprint, approvalPending);
         for (const me of monitorEvents) {
             this.pushEvent({ event: me.type, agentKey: me.agentKey, message: me.message, elapsedSec: me.elapsedSec, timestamp: me.timestamp });
         }
@@ -694,7 +717,7 @@ export class IdeProviderInstance implements ProviderInstance {
 
         this.autoApproveBusy = true;
         try {
-            const { label: targetButton } = pickApprovalButton(_chatData?.activeModal?.buttons, this.provider);
+            const { label: targetButton } = pickAutoApprovalButton(_chatData?.activeModal?.buttons);
 
             const script = scriptFn({ action: 'approve', button: targetButton, buttonText: targetButton });
             if (!script) return;
@@ -706,7 +729,7 @@ export class IdeProviderInstance implements ProviderInstance {
             );
 
             LOG.info('IdeInstance', `[IdeInstance:${this.type}] autoApprove: executing resolveAction for "${targetButton}"`);
-            let rawResult = await cdp.evaluate(script, 10000);
+            let rawResult = await withTimeout(cdp.evaluate(script, 10000), 10000, 'evaluate.autoApprove');
             if (typeof rawResult === 'string') {
                 try { rawResult = JSON.parse(rawResult); } catch { }
             }

package/src/providers/manual-attendance.ts

@@ -0,0 +1,105 @@
+/**
+ * ManualAttendanceTracker — provider-agnostic "is a human driving this session
+ * right now" signal, used to suppress auto-approve while the user is taking
+ * manual control of a session from the dashboard.
+ *
+ * Why this exists
+ * ---------------
+ * When `autoApprove` is on, an approval modal is auto-dismissed within a few
+ * hundred ms of appearing. For a background mesh worker that is exactly the
+ * desired delegated behavior. But for a session the user is actively watching
+ * and operating (a base-node / foreground session), the auto-fire closes the
+ * modal before the human can pick a button — and likewise fights their use of
+ * the controlbar. The fix is to give the human a short quiet window: while they
+ * are attending the session by hand, auto-approve holds; once they go idle it
+ * resumes.
+ *
+ * The tracker holds only a timestamp. The *signal* — which commands count as
+ * "a human attending" — is decided by the caller (the command handler), and is
+ * the same set for every provider: foreground tab selection (select_session /
+ * open_panel), controlbar use (invoke_provider_script / set_mode / change_model
+ * / set_thought_level), manual approval (resolve_action) and manual terminal
+ * input (pty_input). Notably NOT send_chat, which is also how a coordinator
+ * delegates a task to a worker — counting it would wrongly suppress the
+ * worker's delegated auto-approve.
+ *
+ * Because a background worker never receives any of those attending commands,
+ * it is never "attended", so its delegated auto-approve is unaffected. The
+ * mechanism is therefore provider-common AND preserves worker auto-approve
+ * without any per-provider branching.
+ */
+
+/**
+ * How long after the last manual interaction auto-approve stays suppressed.
+ *
+ * Trade-off: long enough that after foregrounding a session's tab the user has
+ * a realistic chance to act on an incoming approval (the auto-approve settle
+ * window is only ~600ms, so a human cannot out-race it), yet short enough that
+ * a session left unattended — e.g. a worker tab the user briefly peeked at —
+ * resumes auto-approving within about a minute. Re-armed on every attending
+ * command, so a user who keeps interacting keeps the window fresh.
+ */
+export const AUTO_APPROVE_MANUAL_ATTENDANCE_SUPPRESS_MS = 60_000;
+
+export class ManualAttendanceTracker {
+    private lastInteractionAt = 0;
+
+    constructor(private readonly suppressMs: number = AUTO_APPROVE_MANUAL_ATTENDANCE_SUPPRESS_MS) {}
+
+    /** Record that a human just drove this session by hand. */
+    note(now = Date.now()): void {
+        this.lastInteractionAt = now;
+    }
+
+    /** True while a manual interaction is recent enough to suppress auto-approve. */
+    isAttended(now = Date.now()): boolean {
+        return this.lastInteractionAt > 0 && (now - this.lastInteractionAt) < this.suppressMs;
+    }
+
+    /**
+     * Milliseconds remaining in the current suppression window, or 0 when not
+     * attended. Used to re-arm a re-check timer so auto-approve fires the moment
+     * the window lapses even if the PTY/agent has since gone silent.
+     */
+    remainingMs(now = Date.now()): number {
+        if (this.lastInteractionAt <= 0) return 0;
+        return Math.max(0, this.suppressMs - (now - this.lastInteractionAt));
+    }
+}
+
+/**
+ * The session-scoped commands that count as "a human is attending this session
+ * by hand". Shared so the command handler and any forward path agree on one
+ * definition. Deliberately excludes send_chat (coordinator task delegation) and
+ * pure read commands (read_chat / list_chats — passive polling, not driving).
+ */
+export const MANUAL_ATTENDANCE_COMMANDS: ReadonlySet<string> = new Set([
+    'select_session',
+    'open_panel',
+    'invoke_provider_script',
+    'set_mode',
+    'change_model',
+    'set_thought_level',
+    'resolve_action',
+    'pty_input',
+]);
+
+/**
+ * The subset of {@link MANUAL_ATTENDANCE_COMMANDS} that are PASSIVE view-only
+ * actions — foregrounding a session's tab / opening its panel. They convey "I am
+ * looking at this session", not "I am driving it", and carry no user input.
+ *
+ * For a foreground (base-node) session these still attend: a user who
+ * foregrounds their own session should get the quiet window so an incoming
+ * approval stays visible for them to act on. But for a DELEGATED worker session
+ * a passive peek must NOT attend — a coordinator merely opening a worker's panel
+ * to watch progress would otherwise suppress that worker's delegated
+ * auto-approve for the whole window (secondary cause, #137). The per-instance
+ * hook decides: it drops a passive stamp only when the session is a delegated
+ * worker, so explicit input (controlbar / resolve_action / pty_input) still
+ * attends a worker and a foreground session is unaffected.
+ */
+export const MANUAL_ATTENDANCE_PASSIVE_VIEW_COMMANDS: ReadonlySet<string> = new Set([
+    'select_session',
+    'open_panel',
+]);

package/src/providers/native-history/antigravity-claim-registry.ts

@@ -0,0 +1,138 @@
+/**
+ * antigravity-claim-registry — daemon-local conversation ownership map.
+ *
+ * Antigravity CLI writes each conversation into its own per-session SQLite db
+ * at ~/.gemini/antigravity-cli/conversations/<uuid>.db. But before a daemon
+ * session has resolved its provider session id, the discovery resolver used to
+ * fall back to "the newest .db on disk by mtime". Two sessions started within a
+ * few ms of each other on ONE daemon therefore both grabbed the SAME newest
+ * store — so one session's injected prompt and the other's assistant completion
+ * cross-routed, and an unrelated turn completed the wrong task (RCA: a
+ * coordinator session ended up reading the owner's conversation .db, and the
+ * coordinator's own injected instruction was absent from the bound store).
+ *
+ * This registry records which live daemon session currently owns a given
+ * conversation uuid. The discovery resolver (dispatcher.resolveAntigravityPath)
+ * consults it to:
+ *   (1) never hand a conversation already owned by a DIFFERENT live session to
+ *       an as-yet-unbound one — two sessions can never resolve to the same .db;
+ *   (2) LOCK a session to the first conversation it binds, so a later, newer
+ *       .db on disk cannot re-bind an already-bound session on a subsequent
+ *       mtime-ordered read.
+ *
+ * Ownership is keyed by a per-session owner token (see antigravityOwnerToken)
+ * that BOTH the resolver and the provider instance derive identically from the
+ * same inputs (workspace + spawn time, or the instance id), so the instance can
+ * release its claims deterministically on shutdown.
+ *
+ * A claim not refreshed within CLAIM_STALE_MS is treated as abandoned — a
+ * safety net for a session that died without an explicit release. Live sessions
+ * poll native history far more frequently than this window, so an active owner
+ * never lapses; only a crashed/leaked owner's claim ages out.
+ *
+ * OSS code (AGPL-3.0). Must not import from packages/ (proprietary).
+ */
+'use strict';
+
+interface ConversationClaim {
+  owner: string;
+  /** Last time this owner (re)confirmed the claim. Only consulted by the
+   *  stale-claim safety net; an active owner refreshes it on every resolve. */
+  refreshedAtMs: number;
+}
+
+const claimsByUuid = new Map<string, ConversationClaim>();
+
+/** A claim older than this with no refresh is reclaimable (owner presumed dead). */
+export const CLAIM_STALE_MS = 10 * 60 * 1000;
+
+function normalizeUuid(uuid: string): string {
+  return String(uuid || '').trim().toLowerCase();
+}
+
+/**
+ * Derive the per-session owner token, keyed ONLY on the stable instanceId
+ * (== the session registry sessionId == the read path's targetSessionId). Both
+ * the dispatcher (read side) and the provider instance (claim/release side) pass
+ * this same id, so their tokens always agree and the claim isolation holds.
+ *
+ * Returns '' when no instanceId is available — the caller then skips claiming
+ * (the exclusion checks still run against existing claims). This is the SSOT
+ * rule: there is exactly ONE token form. The removed legacy fallback derived a
+ * `spawn:<workspace>:<sessionStartedAtMs>` token from the spawn timestamp when
+ * the instanceId was missing; because one session's spawn time is sampled
+ * independently at three sites (instance startedAt, adapter spawnedAtMs, registry
+ * spawnedAtMs) those never matched, so the SAME session's instance-side and
+ * read-side tokens silently diverged and the claim mutual-exclusion collapsed
+ * (the antigravity conversation crosswire). An empty token (skip-claim) is
+ * strictly safer than a token that disagrees with the same session's other
+ * token. workspace/sessionStartedAtMs are kept in the signature for call-site
+ * compatibility but no longer affect the token.
+ */
+export function antigravityOwnerToken(
+  workspace: string,
+  sessionStartedAtMs: number,
+  instanceId?: string,
+): string {
+  void workspace; void sessionStartedAtMs;
+  const iid = typeof instanceId === 'string' ? instanceId.trim() : '';
+  return iid ? `iid:${iid}` : '';
+}
+
+/**
+ * Claim `uuid` for `owner`. Succeeds (and refreshes) when the conversation is
+ * unclaimed, already owned by this owner, or held by a stale (abandoned) owner.
+ * Fails when a DIFFERENT live owner holds it. Returns whether `owner` holds the
+ * claim after the call.
+ */
+export function claimAntigravityConversation(uuid: string, owner: string, now: number = Date.now()): boolean {
+  const key = normalizeUuid(uuid);
+  if (!key || !owner) return false;
+  const existing = claimsByUuid.get(key);
+  if (existing && existing.owner !== owner && (now - existing.refreshedAtMs) < CLAIM_STALE_MS) {
+    return false;
+  }
+  claimsByUuid.set(key, { owner, refreshedAtMs: now });
+  return true;
+}
+
+/** True when `uuid` is held by a live owner OTHER than `owner`. */
+export function isAntigravityConversationClaimedByOther(uuid: string, owner: string, now: number = Date.now()): boolean {
+  const key = normalizeUuid(uuid);
+  if (!key) return false;
+  const existing = claimsByUuid.get(key);
+  if (!existing) return false;
+  if (existing.owner === owner) return false;
+  return (now - existing.refreshedAtMs) < CLAIM_STALE_MS;
+}
+
+/** The live owner of `uuid`, or undefined when unclaimed or stale. */
+export function antigravityConversationOwner(uuid: string, now: number = Date.now()): string | undefined {
+  const key = normalizeUuid(uuid);
+  if (!key) return undefined;
+  const existing = claimsByUuid.get(key);
+  if (!existing) return undefined;
+  if ((now - existing.refreshedAtMs) >= CLAIM_STALE_MS) return undefined;
+  return existing.owner;
+}
+
+/** Release a single conversation, only if held by `owner` (or `owner` empty). */
+export function releaseAntigravityConversation(uuid: string, owner?: string): void {
+  const key = normalizeUuid(uuid);
+  if (!key) return;
+  const existing = claimsByUuid.get(key);
+  if (existing && (!owner || existing.owner === owner)) claimsByUuid.delete(key);
+}
+
+/** Release every conversation held by `owner` (called on session shutdown). */
+export function releaseAntigravityOwner(owner: string): void {
+  if (!owner) return;
+  for (const [key, claim] of claimsByUuid) {
+    if (claim.owner === owner) claimsByUuid.delete(key);
+  }
+}
+
+/** Test-only: wipe all claims so each test starts from a clean registry. */
+export function __resetAntigravityClaimRegistry(): void {
+  claimsByUuid.clear();
+}