teamshare-bridge 0.11.2 → 0.14.1

package/dist/bridge/daemon.js

@@ -16,6 +16,7 @@ const cache_cleaner_1 = require("../lib/cache-cleaner");
 const lock_1 = require("../lib/lock");
 const wake_state_1 = require("../lib/wake-state");
 const rate_gate_1 = require("../lib/rate-gate");
+const harness_models_1 = require("../lib/harness-models");
 /** IMP-917: wakes already deferred once for a rate-limit pause (bounded). */
 const rateDeferred = new Set();
 const bus_1 = require("../lib/workspace/bus");
@@ -143,6 +144,40 @@ function inQuietHours(quietHours) {
     return start <= end ? mins >= start && mins < end : mins >= start || mins < end;
 }
 async function runDaemon(portOverride) {
+    // IMP-9xx crash resilience: an unhandled rejection killed the daemon
+    // silently (Node >= 15 default) and nothing revived it. Rejections now
+    // log and stay alive; hard exceptions log and exit(1) on purpose so the
+    // platform watchdog (scheduled-task restart / LaunchAgent / systemd)
+    // brings a fresh instance up. Signals log the shutdown reason so future
+    // log gaps are diagnosable.
+    process.on('unhandledRejection', (reason) => {
+        log(`[fatal] unhandled rejection (continuing): ${reason instanceof Error ? reason.stack ?? reason.message : String(reason)}`);
+    });
+    process.on('uncaughtException', (err) => {
+        log(`[fatal] uncaught exception - exiting for watchdog restart: ${err.stack ?? err.message}`);
+        process.exit(1);
+    });
+    for (const sig of ['SIGTERM', 'SIGINT']) {
+        process.on(sig, () => {
+            log(`shutting down (${sig})`);
+            process.exit(0);
+        });
+    }
+    // Hidden drill hooks (IMP-9xx verification):
+    //   TS_DAEMON_TEST_CRASH=1      -> async REJECTION after 5s: must LOG and
+    //                                  SURVIVE (the silent-killer case)
+    //   TS_DAEMON_TEST_CRASH=throw  -> sync THROW after 5s: logs then exits(1),
+    //                                  platform watchdog revives
+    if (process.env.TS_DAEMON_TEST_CRASH === '1') {
+        setTimeout(() => {
+            void Promise.reject(new Error('TS_DAEMON_TEST_CRASH rejection drill'));
+        }, 5000);
+    }
+    else if (process.env.TS_DAEMON_TEST_CRASH === 'throw') {
+        setTimeout(() => {
+            throw new Error('TS_DAEMON_TEST_CRASH throw drill');
+        }, 5000);
+    }
     // Idempotency guard: a second `daemon` invocation (manual or autostart)
     // must never fight the live instance for ports - it would crash with
     // "no free probe port found" while the real daemon keeps running.
@@ -156,16 +191,44 @@ async function runDaemon(portOverride) {
     const port = portOverride ?? config.port;
     const apiBase = process.env.TEAMSHARE_API_URL ?? api_1.DEFAULT_API_URL;
     const wsBase = (process.env.TEAMSHARE_WS_URL ?? WS_DEFAULT).replace(/\/$/, '');
+    // IMP-9xx model catalog discovery: push each installed harness's native
+    // list to the backend so the web picker stays current. Best-effort -
+    // failures never gate sessions.
+    void (async () => {
+        const apiKey = config.agents[0]?.apiKey;
+        if (!apiKey)
+            return;
+        for (const harness of ['opencode', 'antigravity', 'codex', 'cursor']) {
+            try {
+                const batch = (0, harness_models_1.discoverHarnessModels)(harness);
+                if (!batch?.models.length)
+                    continue;
+                const stored = await (0, harness_models_1.pushHarnessCatalog)(apiBase, apiKey, harness, batch);
+                log(`[models] pushed ${stored} ${harness} model(s) (${batch.source})`);
+            }
+            catch (err) {
+                log(`[models] ${harness} discovery failed: ${(0, config_1.msg)(err)}`);
+            }
+        }
+    })();
     /** agentId -> queued wakes waiting for the session lock to free up. */
     const wakeQueue = new Map();
     /** dedupeKey -> last spawn timestamp (usage guard against wake storms). */
     const recentSpawns = new Map();
     /** agentId -> ISO timestamp of the last wake event (probe/status). */
     const lastWakeByAgent = new Map();
+    const handles = new Map();
+    /** Fresh config snapshot per wake - project links/wake rules apply live. */
+    const getConfig = () => (0, config_1.loadConfig)();
+    const credsOf = (h) => ({
+        agentId: h.agentId,
+        apiKey: h.apiKey,
+    });
     const getStatus = () => ({
         configPath: (0, config_1.configPath)(),
-        agents: config.agents.map((a) => {
-            const lock = (0, lock_1.readLock)(a.agentId);
+        agents: [...handles.values()].map((h) => {
+            const a = { agentId: h.agentId };
+            const lock = (0, lock_1.readLock)(h.agentId);
             const base = {
                 agentId: a.agentId,
                 lastWake: lastWakeByAgent.get(a.agentId),
@@ -187,7 +250,7 @@ async function runDaemon(portOverride) {
         registeredSchemes: false,
         projects: config.projects,
     });
-    const { server, port: boundPort } = await (0, local_server_1.startProbeServer)(port, getStatus);
+    const { server, port: boundPort } = await (0, local_server_1.startProbeServer)(port, getStatus, () => syncAgents());
     log(`probe server listening on http://localhost:${boundPort}/ping`);
     // Track this instance for stop/restart/status even when started in the
     // foreground (only detached `start` used to leave a pid file behind).
@@ -235,8 +298,17 @@ async function runDaemon(portOverride) {
         ? new orchestrator_1.OrchestratorClient(config.agents[0].apiKey, apiBase)
         : null;
     orchestratorClient?.connect();
-    for (const agent of config.agents) {
+    function startAgentLoop(agent) {
+        if (handles.has(agent.agentId))
+            return handles.get(agent.agentId);
+        log(`[agents] starting loop for ${agent.agentId}`);
         const api = api_1.TeamshareApi.forAgent(apiBase, agent);
+        // Per-wake fresh config: handleWake accepts a getter, so project link /
+        // wake-rule edits apply to the NEXT wake without a restart. Shadowing
+        // the outer snapshot keeps every existing `config,` call-site argument
+        // below valid and always current.
+        const config = getConfig;
+        const agentTimers = [];
         /** Keeps the agent marked online; errors are surfaced, never swallowed. */
         const heartbeat = () => {
             api
@@ -299,14 +371,15 @@ async function runDaemon(portOverride) {
             joinUntilReady(0);
             heartbeat();
             pushState();
-            timers.push(setInterval(heartbeat, 60_000));
-            timers.push(setInterval(pushState, 60_000));
+            agentTimers.push(setInterval(heartbeat, 60_000));
+            agentTimers.push(setInterval(pushState, 60_000));
             // Periodic mention poll (catches wakes lost while connected — WS
             // emits are best-effort; a silent hiccup loses the wake until the
             // next reconnect). Runs every 10 minutes and processes only
-            // mentions (never re-wakes open tasks to avoid repeated work).
+            // mentions + stranded task assignments (never re-wakes claimed or
+            // recently-spawned tasks to avoid repeated work).
             const MENTION_POLL_MS = 10 * 60_000;
-            timers.push(setInterval(async () => {
+            agentTimers.push(setInterval(async () => {
                 try {
                     const inbox = await api.inbox(agent.agentId);
                     for (const mention of inbox.mentions ?? []) {
@@ -318,13 +391,15 @@ async function runDaemon(portOverride) {
                             if (!projectId)
                                 continue;
                             log(`agent ${agent.agentId}: periodic poll wake chat.mention id=${mention.id}`);
-                            await handleWake(api_1.TeamshareApi.forAgent(apiBase, agent), agent.agentId, agent.apiKey, {
+                            const pollChatOutcome = await handleWake(api_1.TeamshareApi.forAgent(apiBase, agent), agent.agentId, agent.apiKey, {
                                 type: 'chat.mention',
                                 projectId,
                                 messageId: String(mention.id ?? ''),
                                 mention: String(mention.mention ?? ''),
                                 ...(mention.channelId ? { channelId: String(mention.channelId) } : {}),
                             }, config, { settings: settingsByAgent.get(agent.agentId), wakeQueue, recentSpawns });
+                            if (pollChatOutcome === 'queued' || pollChatOutcome === 'deferred' || pollChatOutcome === 'blocked')
+                                continue;
                             (0, wake_state_1.recordProcessed)(agent.agentId, 'chat.mention', key);
                         }
                         else if (String(mention.type) === 'comment') {
@@ -333,28 +408,65 @@ async function runDaemon(portOverride) {
                                 if (!projectId)
                                     continue;
                                 log(`agent ${agent.agentId}: periodic poll wake document.mention id=${mention.id}`);
-                                await handleWake(api_1.TeamshareApi.forAgent(apiBase, agent), agent.agentId, agent.apiKey, {
+                                const pollDocOutcome = await handleWake(api_1.TeamshareApi.forAgent(apiBase, agent), agent.agentId, agent.apiKey, {
                                     type: 'document.mention',
                                     documentId: String(mention.documentId),
                                     projectId,
                                     commentId: String(mention.id ?? ''),
                                     mention: String(mention.mention ?? ''),
                                 }, config, { settings: settingsByAgent.get(agent.agentId), wakeQueue, recentSpawns });
+                                if (pollDocOutcome === 'queued' || pollDocOutcome === 'deferred' || pollDocOutcome === 'blocked')
+                                    continue;
                                 (0, wake_state_1.recordProcessed)(agent.agentId, 'document.mention', key);
                             }
                             else if (mention.taskId) {
                                 log(`agent ${agent.agentId}: periodic poll wake comment.mention id=${mention.id}`);
-                                await handleWake(api_1.TeamshareApi.forAgent(apiBase, agent), agent.agentId, agent.apiKey, {
+                                const pollCommentOutcome = await handleWake(api_1.TeamshareApi.forAgent(apiBase, agent), agent.agentId, agent.apiKey, {
                                     type: 'comment.mention',
                                     taskId: String(mention.taskId),
                                     ...(mention.projectId ? { projectId: String(mention.projectId) } : {}),
                                     commentId: String(mention.id ?? ''),
                                     mention: String(mention.mention ?? ''),
                                 }, config, { settings: settingsByAgent.get(agent.agentId), wakeQueue, recentSpawns });
+                                if (pollCommentOutcome === 'queued' || pollCommentOutcome === 'deferred' || pollCommentOutcome === 'blocked')
+                                    continue;
                                 (0, wake_state_1.recordProcessed)(agent.agentId, 'comment.mention', key);
                             }
                         }
                     }
+                    // --- Stranded-assignment recovery (IMP-9xx): a task.assigned
+                    // wake that was BLOCKED (e.g. no linked folder) or lost mid-blip
+                    // used to strand forever - the backend only emits on assignment
+                    // and re-sync only runs on reconnect. Sweep open assigned tasks
+                    // that no session has claimed yet; 'blocked' outcomes stay
+                    // unmarked so the next cycle retries them automatically.
+                    const stranded = (inbox.tasks ?? []).filter((task) => String(task.status ?? '') === 'open' &&
+                        !task.claimedAt);
+                    let sweptCount = 0;
+                    for (const task of stranded) {
+                        if (sweptCount >= 3)
+                            break;
+                        const taskId = String(task.id ?? '');
+                        if (!taskId)
+                            continue;
+                        if ((0, wake_state_1.isRecentlyProcessed)(agent.agentId, 'task.assigned', taskId))
+                            continue;
+                        const lastSpawn = recentSpawns.get(`task:${taskId}`);
+                        if (lastSpawn && Date.now() - lastSpawn < TASK_WAKE_COOLDOWN_MS)
+                            continue;
+                        log(`agent ${agent.agentId}: stranded-task sweep wake ${taskId} (${String(task.title ?? '')})`);
+                        sweptCount++;
+                        const sweepOutcome = await handleWake(api_1.TeamshareApi.forAgent(apiBase, agent), agent.agentId, agent.apiKey, {
+                            type: 'task.assigned',
+                            taskId,
+                            projectId: task.projectId ?? undefined,
+                        }, config, { settings: settingsByAgent.get(agent.agentId), wakeQueue, recentSpawns });
+                        if (sweepOutcome !== 'queued' &&
+                            sweepOutcome !== 'deferred' &&
+                            sweepOutcome !== 'blocked') {
+                            (0, wake_state_1.recordProcessed)(agent.agentId, 'task.assigned', taskId);
+                        }
+                    }
                 }
                 catch {
                     // best-effort: don't crash the daemon on periodic poll failure
@@ -396,7 +508,7 @@ async function runDaemon(portOverride) {
                             if ((0, wake_state_1.isRecentlyProcessed)(agent.agentId, 'task.assigned', taskId))
                                 continue;
                             log(`agent ${agent.agentId}: re-sync wake task=${taskId} (${String(task.title ?? '')})`);
-                            await handleWake(api_1.TeamshareApi.forAgent(apiBase, agent), agent.agentId, agent.apiKey, {
+                            const resyncTaskOutcome = await handleWake(api_1.TeamshareApi.forAgent(apiBase, agent), agent.agentId, agent.apiKey, {
                                 type: 'task.assigned',
                                 taskId,
                                 projectId: task.projectId ?? undefined,
@@ -406,7 +518,11 @@ async function runDaemon(portOverride) {
                                 wakeQueue,
                                 recentSpawns,
                             });
-                            (0, wake_state_1.recordProcessed)(agent.agentId, 'task.assigned', taskId);
+                            if (resyncTaskOutcome !== 'queued' &&
+                                resyncTaskOutcome !== 'deferred' &&
+                                resyncTaskOutcome !== 'blocked') {
+                                (0, wake_state_1.recordProcessed)(agent.agentId, 'task.assigned', taskId);
+                            }
                             totalTasks++;
                         }
                         // --- 2. Process inbox.mentions (server-authoritative, replaces
@@ -423,7 +539,7 @@ async function runDaemon(portOverride) {
                                     continue;
                                 }
                                 log(`agent ${agent.agentId}: re-sync wake chat.mention id=${mention.id} project=${projectId}`);
-                                await handleWake(api_1.TeamshareApi.forAgent(apiBase, agent), agent.agentId, agent.apiKey, {
+                                const resyncChatOutcome = await handleWake(api_1.TeamshareApi.forAgent(apiBase, agent), agent.agentId, agent.apiKey, {
                                     type: 'chat.mention',
                                     projectId,
                                     messageId: String(mention.id ?? ''),
@@ -434,7 +550,11 @@ async function runDaemon(portOverride) {
                                     wakeQueue,
                                     recentSpawns,
                                 });
-                                (0, wake_state_1.recordProcessed)(agent.agentId, 'chat.mention', key);
+                                if (resyncChatOutcome !== 'queued' &&
+                                    resyncChatOutcome !== 'deferred' &&
+                                    resyncChatOutcome !== 'blocked') {
+                                    (0, wake_state_1.recordProcessed)(agent.agentId, 'chat.mention', key);
+                                }
                                 totalChatMentions++;
                             }
                             else if (String(mention.type) === 'comment') {
@@ -446,7 +566,7 @@ async function runDaemon(portOverride) {
                                         continue;
                                     }
                                     log(`agent ${agent.agentId}: re-sync wake document.mention id=${mention.id} doc=${mention.documentId}`);
-                                    await handleWake(api_1.TeamshareApi.forAgent(apiBase, agent), agent.agentId, agent.apiKey, {
+                                    const resyncDocOutcome = await handleWake(api_1.TeamshareApi.forAgent(apiBase, agent), agent.agentId, agent.apiKey, {
                                         type: 'document.mention',
                                         documentId: String(mention.documentId),
                                         projectId,
@@ -457,13 +577,17 @@ async function runDaemon(portOverride) {
                                         wakeQueue,
                                         recentSpawns,
                                     });
-                                    (0, wake_state_1.recordProcessed)(agent.agentId, 'document.mention', key);
+                                    if (resyncDocOutcome !== 'queued' &&
+                                        resyncDocOutcome !== 'deferred' &&
+                                        resyncDocOutcome !== 'blocked') {
+                                        (0, wake_state_1.recordProcessed)(agent.agentId, 'document.mention', key);
+                                    }
                                     totalDocMentions++;
                                 }
                                 else if (mention.taskId) {
                                     const projectId = String(mention.projectId ?? '');
                                     log(`agent ${agent.agentId}: re-sync wake comment.mention id=${mention.id} task=${mention.taskId}`);
-                                    await handleWake(api_1.TeamshareApi.forAgent(apiBase, agent), agent.agentId, agent.apiKey, {
+                                    const resyncCommentOutcome = await handleWake(api_1.TeamshareApi.forAgent(apiBase, agent), agent.agentId, agent.apiKey, {
                                         type: 'comment.mention',
                                         taskId: String(mention.taskId),
                                         ...(projectId ? { projectId } : {}),
@@ -474,7 +598,11 @@ async function runDaemon(portOverride) {
                                         wakeQueue,
                                         recentSpawns,
                                     });
-                                    (0, wake_state_1.recordProcessed)(agent.agentId, 'comment.mention', key);
+                                    if (resyncCommentOutcome !== 'queued' &&
+                                        resyncCommentOutcome !== 'deferred' &&
+                                        resyncCommentOutcome !== 'blocked') {
+                                        (0, wake_state_1.recordProcessed)(agent.agentId, 'comment.mention', key);
+                                    }
                                     totalCommentMentions++;
                                 }
                                 else {
@@ -515,7 +643,127 @@ async function runDaemon(portOverride) {
         });
         sockets.push(socket);
         wakeQueue.set(agent.agentId, []);
+        const handle = {
+            agentId: agent.agentId,
+            apiKey: agent.apiKey,
+            api,
+            socket,
+            timers: agentTimers,
+        };
+        handles.set(agent.agentId, handle);
+        return handle;
     }
+    /** Stops one agent loop. Caller must have verified lock/queue are drained. */
+    function stopAgentLoop(handle) {
+        log(`[agents] stopping loop for ${handle.agentId}`);
+        for (const t of handle.timers)
+            clearInterval(t);
+        try {
+            handle.socket.close();
+        }
+        catch {
+            /* already closed */
+        }
+        wakeQueue.delete(handle.agentId);
+        settingsByAgent.delete(handle.agentId);
+        handles.delete(handle.agentId);
+    }
+    // Start every configured agent, then keep the set in sync with config.json.
+    for (const agent of (0, config_1.loadConfig)().agents)
+        startAgentLoop(agent);
+    let removalPending = false;
+    /**
+     * Diff the live loops against config.json:
+     * - added agents   -> startAgentLoop immediately (zero impact on running
+     *                     sessions of other agents)
+     * - removed agents -> deferred while their lock is held / wakes queued;
+     *                     a 30s sweeper finishes the removal once drained.
+     */
+    function syncAgents() {
+        try {
+            // Guard against corrupt / mid-write reads: loadConfig() falls back to
+            // an EMPTY default config when JSON.parse fails (BOM, partial write),
+            // which would otherwise be misread as "remove every agent". A strict
+            // re-parse keeps the current loops alive until the file is readable.
+            if (!(0, node_fs_1.existsSync)((0, config_1.configPath)()))
+                return;
+            JSON.parse((0, node_fs_1.readFileSync)((0, config_1.configPath)(), 'utf8'));
+            JSON.parse(JSON.stringify((0, config_1.loadConfig)()));
+        }
+        catch {
+            return; // unreadable - keep current loops, next event retries
+        }
+        const fresh = (0, config_1.loadConfig)();
+        const wanted = new Map(fresh.agents.map((a) => [a.agentId, a]));
+        for (const [id, a] of wanted) {
+            if (!handles.has(id)) {
+                log(`[agents] hot-add ${id}`);
+                try {
+                    startAgentLoop(a);
+                }
+                catch (err) {
+                    log(`[agents] hot-add ${id} failed: ${(0, config_1.msg)(err)}`);
+                }
+            }
+        }
+        let deferred = false;
+        for (const [id, h] of [...handles.entries()]) {
+            if (wanted.has(id))
+                continue;
+            const busy = (0, lock_1.isLockBusy)(id);
+            const queued = wakeQueue.get(id)?.length ?? 0;
+            if (busy || queued > 0) {
+                log(`[agents] hot-remove ${id} deferred (busy=${busy}, queued=${queued})`);
+                deferred = true;
+                continue;
+            }
+            stopAgentLoop(h);
+        }
+        removalPending = deferred;
+    }
+    // Config watcher (debounced - saveConfig writes are not atomic): react to
+    // agent-set changes only; model/path edits already apply per-wake.
+    let lastAgentSig = '';
+    try {
+        lastAgentSig = JSON.stringify((0, config_1.loadConfig)().agents.map((a) => a.agentId).sort());
+    }
+    catch {
+        lastAgentSig = '';
+    }
+    let watchDebounce = null;
+    let cfgWatcher = null;
+    try {
+        cfgWatcher = (0, node_fs_1.watch)((0, config_1.configPath)(), () => {
+            if (watchDebounce)
+                clearTimeout(watchDebounce);
+            watchDebounce = setTimeout(() => {
+                watchDebounce = null;
+                let next;
+                try {
+                    // Strict parse - a corrupt read must never produce a "[]" signature
+                    // that wipes the live agent set (see syncAgents guard).
+                    const parsed = JSON.parse((0, node_fs_1.readFileSync)((0, config_1.configPath)(), 'utf8'));
+                    if (!parsed || !Array.isArray(parsed.agents))
+                        return;
+                    next = JSON.stringify(parsed.agents.map((a) => a.agentId).sort());
+                }
+                catch {
+                    return;
+                }
+                if (!next || next === lastAgentSig)
+                    return;
+                log(`[agents] config change detected (${lastAgentSig} -> ${next})`);
+                lastAgentSig = next;
+                syncAgents();
+            }, 2_000);
+        });
+    }
+    catch (err) {
+        log(`[agents] config watcher unavailable: ${(0, config_1.msg)(err)} - connect pings will still reload`);
+    }
+    // Finishes removals that were deferred behind a busy session.
+    timers.push(setInterval(() => { if (removalPending)
+        syncAgents(); }, 30_000));
     // Queue flush: spawn queued wakes once the agent's session lock frees up
     // (staleness-aware - a crashed session's dead-pid lock is treated as free).
     const flushInterval = setInterval(() => {
@@ -524,13 +772,18 @@ async function runDaemon(portOverride) {
                 continue;
             if ((0, lock_1.isLockBusy)(agentId))
                 continue; // still busy - keep waiting
-            const agent = config.agents.find((a) => a.agentId === agentId);
+            const h = handles.get(agentId);
             const event = queue.shift();
-            if (!agent || !event)
+            if (!h || !event) {
+                // Agent removed while queued - drop the stale wake.
+                if (!h)
+                    wakeQueue.delete(agentId);
                 continue;
+            }
+            const agent = credsOf(h);
             void (async () => {
                 const settings = await freshSettings(api_1.TeamshareApi.forAgent(apiBase, agent), agentId);
-                return spawnWake(api_1.TeamshareApi.forAgent(apiBase, agent), agentId, agent.apiKey, event, config, { settings, recentSpawns });
+                return spawnWake(api_1.TeamshareApi.forAgent(apiBase, agent), agentId, agent.apiKey, event, getConfig(), { settings, recentSpawns });
             })()
                 .then(() => {
                 log(`agent ${agentId}: spawned queued wake ${event.type}`);
@@ -554,6 +807,14 @@ async function runDaemon(portOverride) {
     timers.push(flushInterval);
     const shutdown = () => {
         log('shutting down');
+        if (watchDebounce)
+            clearTimeout(watchDebounce);
+        try {
+            cfgWatcher?.close();
+        }
+        catch {
+            /* watcher already gone */
+        }
         for (const t of timers)
             clearInterval(t);
         for (const s of sockets)
@@ -574,7 +835,11 @@ async function runDaemon(portOverride) {
         .filter((p) => typeof p === 'string' && p.length > 0);
     const sweep = () => {
         const fresh = (0, config_1.loadConfig)();
-        void (0, cache_cleaner_1.runCleanup)(fresh.cleanup, { projectPaths, agents: config.agents, log })
+        void (0, cache_cleaner_1.runCleanup)(fresh.cleanup, {
+            projectPaths,
+            agents: [...handles.values()].map(credsOf),
+            log,
+        })
             .catch((err) => log(`[cleanup] sweep failed: ${(0, config_1.msg)(err)}`));
     };
     try {
@@ -591,7 +856,8 @@ async function runDaemon(portOverride) {
         return typeof raw?.intervalHours === 'number' && raw.intervalHours >= 1 ? raw.intervalHours : 6;
     }
 }
-async function handleWake(api, agentId, apiKey, event, config, extra) {
+async function handleWake(api, agentId, apiKey, event, configInput, extra) {
+    const config = typeof configInput === 'function' ? configInput() : configInput;
     const { wakeQueue, settings, recentSpawns, orchestratorClient } = extra;
     // IMP-917: user rate-limited - defer ONCE until the shared gate lifts
     // (bounded single re-fire; the second pass proceeds and individual API
@@ -608,7 +874,7 @@ async function handleWake(api, agentId, apiKey, event, config, extra) {
                     rateDeferred.delete(deferKey);
                     void handleWake(api, agentId, apiKey, event, config, extra);
                 }, wait);
-                return;
+                return 'deferred';
             }
         }
     }
@@ -629,21 +895,21 @@ async function handleWake(api, agentId, apiKey, event, config, extra) {
         const now = Date.now();
         if (last && now - last < cooldownMs) {
             log(`agent ${agentId}: wake ${event.type} skipped (dedupe - spawned ${Math.round((now - last) / 1000)}s ago)`);
-            return;
+            return 'skipped';
         }
     }
     // Quiet hours: the per-agent setting wins; the bridge config is the
     // machine-wide fallback for agents without one.
     if (inQuietHours(settings?.quietHours ?? config.quietHours)) {
         log(`agent ${agentId}: wake ${event.type} skipped (quiet hours)`);
-        return;
+        return 'skipped';
     }
     if (event.taskId && config.wakeRules?.priorities?.length) {
         try {
             const task = await api.getTask(event.taskId);
             if (!config.wakeRules.priorities.includes(task.priority)) {
                 log(`agent ${agentId}: wake ${event.type} skipped (priority ${task.priority})`);
-                return;
+                return 'skipped';
             }
         }
         catch {
@@ -659,9 +925,9 @@ async function handleWake(api, agentId, apiKey, event, config, extra) {
         queue.push(event);
         wakeQueue.set(agentId, queue);
         log(`agent ${agentId}: wake ${event.type} queued (busy since ${lock.startedAt}, ${lock.kind}) - ${queue.length} waiting`);
-        return;
+        return 'queued';
     }
-    await spawnWake(api, agentId, apiKey, event, config, { settings, recentSpawns, orchestratorClient });
+    return await spawnWake(api, agentId, apiKey, event, config, { settings, recentSpawns, orchestratorClient });
 }
 async function spawnWake(api, agentId, apiKey, event, config, extra = {}) {
     log(`agent ${agentId}: wake ${event.type}${event.taskId ? ` task=${event.taskId}` : ''}`);
@@ -709,6 +975,26 @@ async function spawnWake(api, agentId, apiKey, event, config, extra = {}) {
             ? `project ${projectId} has no linked folder`
             : `could not determine the project (guard requires one)`;
         log(`agent ${agentId}: wake ${event.type} BLOCKED - ${why}`);
+        // IMP-9xx visible feedback: the error terminal is easy to miss, so tell
+        // people IN the project chat (once per event-type+project window) what
+        // blocked the session and exactly how to fix it.
+        if (projectId) {
+            const fbKey = `${event.type}:${projectId}`;
+            try {
+                if (!(0, wake_state_1.isRecentlyProcessed)(agentId, 'blocked', fbKey)) {
+                    const who = event.by?.name?.trim();
+                    await api.postChatMessage(projectId, `${who ? `${who} ` : 'Hi! '}I can't work here yet - this project has no linked folder on this machine.` +
+                        ` Set one in TeamShare (Edit project > Linked folder) or run:` +
+                        ` teamshare-agent set-folder --project ${projectId} --path C:\\path\\to\\folder` +
+                        ` - then mention or assign me again.`);
+                    (0, wake_state_1.recordProcessed)(agentId, 'blocked', fbKey);
+                    log(`agent ${agentId}: blocked-feedback posted to project chat (${fbKey})`);
+                }
+            }
+            catch (err) {
+                log(`agent ${agentId}: blocked-feedback chat failed: ${(0, config_1.msg)(err)}`);
+            }
+        }
         (0, spawn_1.openErrorTerminal)(`TeamShare agent ${agentId} cannot work: ${why}.\n\n` +
             `The project guard blocks sessions until a folder is linked.\n` +
             `Set one in the TeamShare UI (Edit agent / Edit project > Linked folder)\n` +
@@ -717,7 +1003,7 @@ async function spawnWake(api, agentId, apiKey, event, config, extra = {}) {
                 ? `  teamshare-agent set-folder --project ${projectId} --path C:\\path\\to\\your\\project-folder\n`
                 : `  teamshare-agent set-folder --project <projectId> --path C:\\path\\to\\your\\project-folder\n`) +
             `\nThen mention or assign the agent again.`);
-        return;
+        return 'blocked';
     }
     log(`agent ${agentId}: wake ${event.type} -> working folder ${cwd}`);
     // IMP-950 auto-worktree escalation (opt-in per project link): when another
@@ -768,35 +1054,38 @@ async function spawnWake(api, agentId, apiKey, event, config, extra = {}) {
     if (event.type === 'chat.mention') {
         if (!event.projectId) {
             log(`agent ${agentId}: chat.mention without projectId - skipping`);
-            return;
+            return 'skipped';
         }
         // Chat mentions spawn a chat-reply loop (no task context).
         // Pass messageId so the loop replies to only that specific message.
         (0, spawn_1.spawnChatSession)(agentId, apiKey, event.projectId, event.mention ?? '', extra.settings, undefined, cwd, event.messageId);
-        return;
+        return 'spawned';
     }
     if (event.type === 'document.mention') {
         if (!event.documentId) {
             log(`agent ${agentId}: document.mention without documentId - skipping`);
-            return;
+            return 'skipped';
         }
         // Document mentions spawn the document assistant loop (Phase F).
-        (0, spawn_1.spawnDocumentSession)(agentId, apiKey, event.documentId, event.mention ?? '', extra.settings, undefined, cwd);
-        return;
+        // IMP-9xx: pass the waking comment id so the loop answers ONLY that
+        // comment (answer-once guard still applies) instead of rescanning
+        // every historical mention in the thread.
+        (0, spawn_1.spawnDocumentSession)(agentId, apiKey, event.documentId, event.mention ?? '', extra.settings, undefined, cwd, event.commentId);
+        return 'spawned';
     }
     if (event.type === 'build.trigger') {
         if (!event.projectId) {
             log(`agent ${agentId}: build.trigger without projectId - skipping`);
-            return;
+            return 'skipped';
         }
         // Build mode: start (or restart) the project's build run.
         (0, spawn_1.spawnBuildSession)(agentId, apiKey, event.projectId, extra.settings, undefined, cwd);
-        return;
+        return 'spawned';
     }
     if (event.type === 'build.stop') {
         if (!event.projectId) {
             log(`agent ${agentId}: build.stop without projectId - skipping`);
-            return;
+            return 'skipped';
         }
         // Write the stop file - the running build loop honors it (wraps up the
         // current task and exits). Best-effort: if no build session is running,
@@ -809,7 +1098,7 @@ async function spawnWake(api, agentId, apiKey, event, config, extra = {}) {
         catch (err) {
             log(`agent ${agentId}: build.stop failed to write stop file: ${(0, config_1.msg)(err)}`);
         }
-        return;
+        return 'spawned';
     }
     if (event.type === 'question.answered') {
         // Resume-on-answer: spawn a build session when a build is actually
@@ -818,7 +1107,7 @@ async function spawnWake(api, agentId, apiKey, event, config, extra = {}) {
         // and resumes it. A stale answer for a finished build does nothing.
         if (!event.projectId) {
             log(`agent ${agentId}: question.answered without projectId - skipping`);
-            return;
+            return 'skipped';
         }
         const stateFile = (0, node_path_1.join)(BUILD_STATE_DIR, `${agentId}.${event.projectId}.json`);
         const hasBuildState = (0, node_fs_1.existsSync)(stateFile);
@@ -841,7 +1130,7 @@ async function spawnWake(api, agentId, apiKey, event, config, extra = {}) {
             }
             (0, spawn_1.spawnBuildSession)(agentId, apiKey, event.projectId, extra.settings, undefined, cwd);
         }
-        return;
+        return 'spawned';
     }
     if (event.type === 'question.expired') {
         // Expired-on-timeout: same wake path as question.answered — the agent
@@ -850,7 +1139,7 @@ async function spawnWake(api, agentId, apiKey, event, config, extra = {}) {
         // just wake the agent loop so it picks up the new state.
         if (!event.projectId) {
             log(`agent ${agentId}: question.expired without projectId - skipping`);
-            return;
+            return 'skipped';
         }
         const stateFile = (0, node_path_1.join)(BUILD_STATE_DIR, `${agentId}.${event.projectId}.json`);
         const hasBuildState = (0, node_fs_1.existsSync)(stateFile);
@@ -868,30 +1157,32 @@ async function spawnWake(api, agentId, apiKey, event, config, extra = {}) {
             }
             (0, spawn_1.spawnBuildSession)(agentId, apiKey, event.projectId, extra.settings, undefined, cwd);
         }
-        return;
+        return 'spawned';
     }
     if (event.type === 'comment.mention') {
         // Comment mentions on tasks spawn a task session (agent responds in
         // the task thread). Document comment mentions spawn the doc assistant.
         if (event.documentId) {
             if (projectId && cwd) {
-                (0, spawn_1.spawnDocumentSession)(agentId, apiKey, event.documentId, event.mention ?? '', extra.settings, undefined, cwd);
+                (0, spawn_1.spawnDocumentSession)(agentId, apiKey, event.documentId, event.mention ?? '', extra.settings, undefined, cwd, event.commentId);
+                return 'spawned';
             }
-            return;
+            return 'skipped';
         }
         // Fall through to the task-id check below for taskId-carrying comment mentions.
     }
     const taskId = event.taskId ?? '';
     if (!UUID_RE.test(taskId)) {
         log(`agent ${agentId}: wake ${event.type} skipped (no/malformed task id "${taskId}")`);
-        return;
+        return 'skipped';
     }
     // IMP-810: Worker mode — spawn the worker loop for orchestrator subtasks
     if (event.role === 'worker') {
         log(`agent ${agentId}: spawning worker session for task ${taskId}`);
         (0, spawn_1.spawnWorkerSession)(agentId, apiKey, taskId, event.orchestratorTaskId, extra.settings, undefined, cwd);
-        return;
+        return 'spawned';
     }
     (0, spawn_1.spawnAgentSession)(agentId, apiKey, taskId, extra.settings, undefined, cwd);
+    return 'spawned';
 }
 //# sourceMappingURL=daemon.js.map