mixdog 0.9.24 → 0.9.26

package/src/runtime/shared/webhooks-db.mjs

@@ -0,0 +1,405 @@
+/**
+ * PG-backed webhook store — the single source of truth for webhook endpoint
+ * definitions (schema `webhooks`, table `webhooks.endpoints`) and the
+ * delivery dedup log (`webhooks.deliveries`).
+ *
+ * This module mirrors schedules-db.mjs: a lazy connection keyed per resolved
+ * dataDir runs idempotent DDL exactly once per process, serialized across
+ * concurrent first-boot processes on the adapter's schema-bootstrap advisory
+ * lock. It covers the file-store API surface currently in
+ * channels/lib/webhook/deliveries.mjs (loadEndpointConfig, appendDelivery,
+ * deliveryExists, _readEndpointSecret) so call sites can migrate off the
+ * per-endpoint WEBHOOK.md + deliveries.jsonl files later. No call-site
+ * changes are made in this scope.
+ *
+ * All queries fully-qualify their tables so they are correct regardless of
+ * the connection search_path.
+ */
+
+import { ensurePgInstance, withSchemaBootstrapLock } from '../memory/lib/pg/adapter.mjs';
+import { resolvePluginData } from './plugin-paths.mjs';
+import { readdirSync, readFileSync, rmSync, rmdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { readMarkdownDocument } from './markdown-frontmatter.mjs';
+
+const SCHEMA = 'webhooks';
+
+// ---------------------------------------------------------------------------
+// Lazy connection + one-shot idempotent DDL (keyed per resolved dataDir).
+// ---------------------------------------------------------------------------
+
+const _ready = new Map(); // dataDir → Promise<db>
+
+const DDL = `
+CREATE SCHEMA IF NOT EXISTS webhooks;
+CREATE TABLE IF NOT EXISTS webhooks.endpoints (
+  name         text PRIMARY KEY,
+  description  text NOT NULL DEFAULT '',
+  channel_id   text,
+  role         text NOT NULL DEFAULT 'webhook-handler',
+  model        text,
+  parser       text,
+  secret       text,
+  instructions text NOT NULL DEFAULT '',
+  enabled      boolean NOT NULL DEFAULT true,
+  created_at   timestamptz NOT NULL DEFAULT now(),
+  updated_at   timestamptz NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS webhooks.deliveries (
+  endpoint        text NOT NULL,
+  delivery_id     text NOT NULL,
+  status          text NOT NULL DEFAULT 'pending',
+  event           text,
+  error           text,
+  headers_summary jsonb,
+  payload_preview text,
+  created_at      timestamptz NOT NULL DEFAULT now(),
+  updated_at      timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT deliveries_endpoint_id_uniq UNIQUE (endpoint, delivery_id)
+);
+`;
+
+async function getDb(dataDir = resolvePluginData()) {
+  if (_ready.has(dataDir)) return _ready.get(dataDir);
+  const p = (async () => {
+    const { db, pool } = await ensurePgInstance(dataDir, { schema: SCHEMA });
+    // Serialize the CREATE TABLE across concurrent first-boot processes on the
+    // same cluster-global advisory lock the adapter uses for schema bootstrap,
+    // so racing first calls can't run the DDL simultaneously.
+    await withSchemaBootstrapLock(pool, () => db.exec(DDL));
+    await migrateLegacyWebhooks(db, dataDir);
+    return db;
+  })();
+  _ready.set(dataDir, p);
+  try {
+    return await p;
+  } catch (err) {
+    _ready.delete(dataDir); // let the next call retry DDL after a transient failure
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// One-time legacy WEBHOOK.md migration (additive; runs once per dataDir on
+// first getDb, right after DDL). Imports every `<dataDir>/webhooks/<name>/
+// WEBHOOK.md` (+ its `secret` side file) not already present in the table (by
+// name), then DELETES the webhooks/ directory. The legacy file reading is
+// inlined here on purpose so this migration never depends on the file-store
+// deliveries.mjs module (which another scope may remove). Old per-endpoint
+// deliveries files are intentionally NOT imported — dedup history resets,
+// which is acceptable. Partial failure keeps the directory in place and logs,
+// so the next boot retries the un-imported entries idempotently.
+// ---------------------------------------------------------------------------
+async function migrateLegacyWebhooks(db, dataDir) {
+  const dir = join(dataDir, 'webhooks');
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return; // no legacy webhooks/ dir -> nothing to migrate
+  }
+  let imported = 0;
+  let skipped = 0;
+  const failed = [];
+  // Per-endpoint dirs safe to delete this run: those imported now, or already
+  // present in the table (a prior run imported them). Anything unrecognized —
+  // a dir with no WEBHOOK.md, a stray file, a failed import — is left in place.
+  const removable = [];
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    const name = ent.name;
+    try {
+      const { rows } = await db.query('SELECT 1 FROM webhooks.endpoints WHERE name = $1', [name]);
+      if (rows.length) { skipped++; removable.push(name); continue; }
+      let md;
+      try { md = readFileSync(join(dir, name, 'WEBHOOK.md'), 'utf8'); }
+      catch { skipped++; continue; }
+      const { frontmatter, body } = readMarkdownDocument(md);
+      let secret = null;
+      try { secret = String(readFileSync(join(dir, name, 'secret'), 'utf8')).trim() || null; }
+      catch { secret = null; }
+      const channel = String(frontmatter.channel || '').trim();
+      const enabled = frontmatter.enabled !== 'false' && frontmatter.enabled !== false;
+      await db.query(
+        `INSERT INTO webhooks.endpoints
+           (name, description, channel_id, role, model, parser, secret, instructions, enabled)
+         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9)
+         ON CONFLICT (name) DO NOTHING`,
+        [
+          name,
+          String(frontmatter.description || '').trim(),
+          channel || null,
+          'webhook-handler',
+          frontmatter.model ? String(frontmatter.model).trim() : null,
+          frontmatter.parser ? String(frontmatter.parser).trim() : null,
+          secret,
+          String(body || '').trim(),
+          enabled,
+        ],
+      );
+      imported++;
+      removable.push(name);
+    } catch (err) {
+      failed.push(name);
+      console.error(`[webhooks] migration failed for "${name}": ${err?.message || err}`);
+    }
+  }
+  // User chose deletion over a `.migrated` rename. Delete only the recognized
+  // per-endpoint dirs (imported now or already in the table); never blow away
+  // unimported/unrelated entries. Failed imports keep their dir for the next
+  // boot to retry (idempotent via the name check above).
+  for (const name of removable) {
+    try { rmSync(join(dir, name), { recursive: true, force: true }); }
+    catch (err) { console.error(`[webhooks] could not delete migrated dir "${name}": ${err?.message || err}`); }
+  }
+  // Remove the parent webhooks/ only once it is empty — anything unrecognized
+  // (stray files, WEBHOOK.md-less dirs, failed imports) keeps it alive.
+  let parentGone = false;
+  try {
+    if (readdirSync(dir).length === 0) { rmdirSync(dir); parentGone = true; }
+  } catch (err) {
+    console.error(`[webhooks] could not remove empty webhooks/: ${err?.message || err}`);
+  }
+  const tail = failed.length ? `${failed.length} failed (${failed.join(', ')}); ` : '';
+  console.error(`[webhooks] migrated ${imported} legacy webhook(s) (${skipped} skipped); ${tail}${parentGone ? 'removed webhooks/' : 'kept webhooks/ (non-empty)'}`);
+}
+
+// ---------------------------------------------------------------------------
+// Row <-> def mapping
+// ---------------------------------------------------------------------------
+
+const ENDPOINT_COLS = 'name, description, channel_id, role, model, parser, secret, instructions, enabled, created_at, updated_at';
+
+function rowToEndpoint(row) {
+  if (!row) return null;
+  return {
+    name:         row.name,
+    description:  row.description,
+    channelId:    row.channel_id,
+    role:         row.role,
+    model:        row.model,
+    parser:       row.parser,
+    // Never project the plaintext secret through list/load config paths;
+    // callers get a presence flag and must fetch the value via
+    // readEndpointSecret (the single, explicit secret-read path).
+    secretSet:    Boolean(row.secret && String(row.secret).trim()),
+    instructions: row.instructions,
+    enabled:      row.enabled,
+    createdAt:    row.created_at,
+    updatedAt:    row.updated_at,
+  };
+}
+
+const DELIVERY_COLS = 'endpoint, delivery_id, status, event, error, headers_summary, payload_preview, created_at, updated_at';
+
+function rowToDelivery(row) {
+  if (!row) return null;
+  return {
+    endpoint:       row.endpoint,
+    deliveryId:     row.delivery_id,
+    status:         row.status,
+    event:          row.event,
+    error:          row.error,
+    headersSummary: row.headers_summary,
+    payloadPreview: row.payload_preview,
+    createdAt:      row.created_at,
+    updatedAt:      row.updated_at,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Endpoint definitions
+// ---------------------------------------------------------------------------
+
+export async function listEndpoints({ dataDir } = {}) {
+  const db = await getDb(dataDir);
+  const { rows } = await db.query(`SELECT ${ENDPOINT_COLS} FROM webhooks.endpoints ORDER BY name`);
+  return rows.map(rowToEndpoint);
+}
+
+/**
+ * Full endpoint config by name (replaces loadEndpointConfig's file read):
+ * the frontmatter fields as one object, or null when absent.
+ */
+export async function loadEndpointConfig(name, { dataDir } = {}) {
+  if (!name) return null;
+  const db = await getDb(dataDir);
+  const { rows } = await db.query(`SELECT ${ENDPOINT_COLS} FROM webhooks.endpoints WHERE name = $1`, [name]);
+  return rowToEndpoint(rows[0]);
+}
+
+/**
+ * Per-endpoint HMAC secret only (replaces _readEndpointSecret's side-file
+ * read). Returns the trimmed secret or null.
+ */
+export async function readEndpointSecret(name, { dataDir } = {}) {
+  if (!name) return null;
+  const db = await getDb(dataDir);
+  const { rows } = await db.query('SELECT secret FROM webhooks.endpoints WHERE name = $1', [name]);
+  const s = rows[0]?.secret;
+  return s ? String(s).trim() || null : null;
+}
+
+/**
+ * Insert-or-replace an endpoint by name. On re-upsert every column is reset
+ * from the incoming def (enabled and other stale fields included) so a
+ * re-registration is a clean redefinition, mirroring upsertSchedule.
+ */
+export async function upsertEndpoint(def, { dataDir } = {}) {
+  if (!def || !def.name) throw new Error('upsertEndpoint: def.name is required');
+  const db = await getDb(dataDir);
+  const params = [
+    def.name,
+    def.description ?? '',
+    def.channelId ?? null,
+    def.role ?? 'webhook-handler',
+    def.model ?? null,
+    def.parser ?? null,
+    def.secret ?? null,
+    def.instructions ?? '',
+    def.enabled ?? true,
+  ];
+  const { rows } = await db.query(
+    `INSERT INTO webhooks.endpoints
+       (name, description, channel_id, role, model, parser, secret, instructions, enabled)
+     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9)
+     ON CONFLICT (name) DO UPDATE SET
+       description  = EXCLUDED.description,
+       channel_id   = EXCLUDED.channel_id,
+       role         = EXCLUDED.role,
+       model        = EXCLUDED.model,
+       parser       = EXCLUDED.parser,
+       secret       = EXCLUDED.secret,
+       instructions = EXCLUDED.instructions,
+       enabled      = EXCLUDED.enabled,
+       updated_at   = now()
+     RETURNING ${ENDPOINT_COLS}`,
+    params,
+  );
+  return rowToEndpoint(rows[0]);
+}
+
+export async function setEndpointEnabled(name, enabled, { dataDir } = {}) {
+  const db = await getDb(dataDir);
+  const { rows } = await db.query(
+    `UPDATE webhooks.endpoints SET enabled = $2, updated_at = now() WHERE name = $1 RETURNING ${ENDPOINT_COLS}`,
+    [name, !!enabled],
+  );
+  return rowToEndpoint(rows[0]);
+}
+
+export async function deleteEndpoint(name, { dataDir } = {}) {
+  const db = await getDb(dataDir);
+  // Atomically drop the endpoint AND its delivery log in one statement: a
+  // data-modifying CTE deletes the deliveries, the outer DELETE removes the
+  // endpoint row, so no orphan deliveries can survive a removed endpoint.
+  const { rowCount } = await db.query(
+    `WITH del AS (DELETE FROM webhooks.deliveries WHERE endpoint = $1 RETURNING 1)
+     DELETE FROM webhooks.endpoints WHERE name = $1`,
+    [name],
+  );
+  return rowCount > 0;
+}
+
+// ---------------------------------------------------------------------------
+// Delivery dedup log
+// ---------------------------------------------------------------------------
+
+/**
+ * Atomically claim a delivery id for an endpoint. INSERT ... ON CONFLICT DO
+ * NOTHING makes the claim a single indivisible step, so two concurrent POSTs
+ * of the same id cannot both win: exactly one insert affects a row.
+ * Returns { claimed: true, row } for the winner and { claimed: false,
+ * duplicate: true, row } for the loser (row = the existing claim).
+ */
+export async function claimDelivery(endpoint, deliveryId, fields = {}, { dataDir } = {}) {
+  if (!endpoint || !deliveryId) throw new Error('claimDelivery: endpoint and deliveryId are required');
+  const db = await getDb(dataDir);
+  const params = [
+    endpoint,
+    deliveryId,
+    fields.status ?? 'pending',
+    fields.event ?? null,
+    fields.headersSummary ?? null,
+    fields.payloadPreview ?? null,
+  ];
+  const { rows } = await db.query(
+    `INSERT INTO webhooks.deliveries
+       (endpoint, delivery_id, status, event, headers_summary, payload_preview)
+     VALUES ($1,$2,$3,$4,$5,$6)
+     ON CONFLICT (endpoint, delivery_id) DO NOTHING
+     RETURNING ${DELIVERY_COLS}`,
+    params,
+  );
+  if (rows[0]) return { claimed: true, duplicate: false, row: rowToDelivery(rows[0]) };
+  // Lost the race (or a prior claim exists): return the existing row.
+  const { rows: existing } = await db.query(
+    `SELECT ${DELIVERY_COLS} FROM webhooks.deliveries WHERE endpoint = $1 AND delivery_id = $2`,
+    [endpoint, deliveryId],
+  );
+  return { claimed: false, duplicate: true, row: rowToDelivery(existing[0]) };
+}
+
+/**
+ * True when a delivery id has already been recorded for the endpoint (any
+ * status). Callers wanting terminal-vs-inflight semantics inspect the row via
+ * getDelivery; claimDelivery is the race-safe gate.
+ */
+export async function deliveryExists(endpoint, deliveryId, { dataDir } = {}) {
+  if (!endpoint || !deliveryId) return false;
+  const db = await getDb(dataDir);
+  const { rows } = await db.query(
+    'SELECT 1 FROM webhooks.deliveries WHERE endpoint = $1 AND delivery_id = $2',
+    [endpoint, deliveryId],
+  );
+  return rows.length > 0;
+}
+
+export async function getDelivery(endpoint, deliveryId, { dataDir } = {}) {
+  const db = await getDb(dataDir);
+  const { rows } = await db.query(
+    `SELECT ${DELIVERY_COLS} FROM webhooks.deliveries WHERE endpoint = $1 AND delivery_id = $2`,
+    [endpoint, deliveryId],
+  );
+  return rowToDelivery(rows[0]);
+}
+
+/**
+ * Update the status (and optional event/error) of an existing delivery,
+ * keyed by (endpoint, delivery_id). Returns the updated row or null.
+ */
+export async function updateDeliveryStatus(endpoint, deliveryId, status, fields = {}, { dataDir } = {}) {
+  if (!endpoint || !deliveryId) throw new Error('updateDeliveryStatus: endpoint and deliveryId are required');
+  const db = await getDb(dataDir);
+  const { rows } = await db.query(
+    `UPDATE webhooks.deliveries
+        SET status = $3,
+            event = COALESCE($4, event),
+            error = COALESCE($5, error),
+            updated_at = now()
+      WHERE endpoint = $1 AND delivery_id = $2
+      RETURNING ${DELIVERY_COLS}`,
+    [endpoint, deliveryId, status, fields.event ?? null, fields.error ?? null],
+  );
+  return rowToDelivery(rows[0]);
+}
+
+/**
+ * Append a delivery record (claim-or-update convenience covering the old
+ * appendDelivery). First write for an id claims it; a later write with the
+ * same id updates its status/fields latest-wins.
+ *
+ * Returns the claim outcome — { claimed, duplicate, row } — NOT a bare row,
+ * so a pre-dispatch caller can detect a concurrent duplicate (claimed:false,
+ * duplicate:true) and skip re-dispatching an in-flight delivery. `row` is the
+ * freshly claimed row when claimed, else the existing row after the
+ * latest-wins status/fields update.
+ */
+export async function appendDelivery(endpoint, entry = {}, { dataDir } = {}) {
+  const deliveryId = entry.deliveryId ?? entry.id;
+  if (!endpoint || !deliveryId) throw new Error('appendDelivery: endpoint and deliveryId are required');
+  const claim = await claimDelivery(endpoint, deliveryId, entry, { dataDir });
+  if (claim.claimed) return claim;
+  const row = await updateDeliveryStatus(endpoint, deliveryId, entry.status ?? claim.row?.status, entry, { dataDir });
+  return { claimed: false, duplicate: true, row };
+}

package/src/session-runtime/channel-config-api.mjs

@@ -16,7 +16,7 @@ import {
 // worker handle, soft reload).
 export function createChannelConfigApi({ flushBackendSave, channels, reloadChannelsSoon }) {
   return {
-    getChannelSetup() {
+    async getChannelSetup() {
       // Flush a pending debounced backend switch first so setup readers
       // (Settings → Channel Setting, remote toggles) never observe the
       // previous backend during the 150ms debounce window.
@@ -36,33 +36,33 @@ export function createChannelConfigApi({ flushBackendSave, channels, reloadChann
       reloadChannelsSoon();
       return result;
     },
-    saveSchedule(entry) {
-      const result = saveSchedule(entry);
+    async saveSchedule(entry) {
+      const result = await saveSchedule(entry);
       reloadChannelsSoon();
       return result;
     },
-    deleteSchedule(name) {
-      const result = deleteSchedule(name);
+    async deleteSchedule(name) {
+      const result = await deleteSchedule(name);
       reloadChannelsSoon();
       return result;
     },
-    setScheduleEnabled(name, enabled) {
-      const result = setScheduleEnabled(name, enabled);
+    async setScheduleEnabled(name, enabled) {
+      const result = await setScheduleEnabled(name, enabled);
       reloadChannelsSoon();
       return result;
     },
-    saveWebhook(entry) {
-      const result = saveWebhook(entry);
+    async saveWebhook(entry) {
+      const result = await saveWebhook(entry);
       reloadChannelsSoon();
       return result;
     },
-    deleteWebhook(name) {
-      const result = deleteWebhook(name);
+    async deleteWebhook(name) {
+      const result = await deleteWebhook(name);
       reloadChannelsSoon();
       return result;
     },
-    setWebhookEnabled(name, enabled) {
-      const result = setWebhookEnabled(name, enabled);
+    async setWebhookEnabled(name, enabled) {
+      const result = await setWebhookEnabled(name, enabled);
       reloadChannelsSoon();
       return result;
     },

package/src/session-runtime/lifecycle-api.mjs

@@ -29,11 +29,21 @@ export function createLifecycleApi(deps) {
     invalidateContextStatusCache, invalidatePreSessionToolSurface,
     applyResolvedCwd, resolveRoute, applyDeferredToolSurface, standaloneTools,
     pushTranscriptRebind,
+    flushPendingUpdate,
   } = deps;
   return {
     async close(reason = 'cli-exit', options = {}) {
       const detach = options?.detach === true || options?.wait === false || options?.waitForExit === false;
       setCloseRequested(true);
+      // Deferred self-update: arm-at-boot, install-on-quit. Only a real
+      // process exit (not a /clear session reset) triggers the npm install;
+      // the spawn itself is deferred to AFTER teardown below so npm overwrites
+      // the install once this process has released its file handles.
+      const isProcessExit = /exit|quit|shutdown|sighup|sigint|sigterm/.test(String(reason || '').toLowerCase());
+      const flushUpdateOnExit = () => {
+        if (!isProcessExit) return;
+        try { flushPendingUpdate?.(); } catch { /* exit must never wedge on the update spawn */ }
+      };
       // SessionEnd: bridge teardown to the standard hook bus. reason mapped to
       // standard values ('clear'/'exit' where applicable, else 'other'). Short
       // await guard so a slow hook cannot wedge teardown; best-effort.
@@ -140,6 +150,7 @@ export function createLifecycleApi(deps) {
         for (const stop of [mcpStop, openaiWsStop, patchStop]) {
           Promise.resolve(stop).catch(() => {});
         }
+        flushUpdateOnExit();
         return ok;
       }
       await Promise.allSettled([
@@ -151,6 +162,9 @@ export function createLifecycleApi(deps) {
         withTeardownDeadline(shellJobsStop, 1500, false),
         withTeardownDeadline(bashSessionsStop, 1500, false),
       ]);
+      // After teardown: file handles (channels/mcp/memory/shell/patch) are
+      // released, so npm can now overwrite the install without TAR_ENTRY_ERROR.
+      flushUpdateOnExit();
       return ok;
     },
     abort(reason = 'cli-abort') {

package/src/session-runtime/runtime-core.mjs

@@ -15,7 +15,7 @@ import { writeLastSessionCwd } from '../runtime/shared/user-cwd.mjs';
 import { cancelBackgroundTasks } from '../runtime/shared/background-tasks.mjs';
 import { createTranscriptWriter } from '../runtime/shared/transcript-writer.mjs';
 import { mixdogHome } from '../runtime/shared/plugin-paths.mjs';
-import { checkLatestVersion, runGlobalUpdate, localPackageVersion } from '../runtime/shared/update-checker.mjs';
+import { checkLatestVersion, runGlobalUpdate, localPackageVersion, isDevInstall } from '../runtime/shared/update-checker.mjs';
 import {
   modelVisibleToolCompletionMessage,
   shouldPersistModelVisibleToolCompletion,
@@ -634,6 +634,12 @@ export async function createMixdogSessionRuntime({
   };
   // phase: 'idle' | 'checking' | 'installing' | 'installed' | 'failed'
   let updateProcessState = { phase: 'idle', version: null, error: null };
+  // Boot detects an available update but DEFERS the actual npm install to the
+  // graceful shutdown path (flushPendingUpdate, invoked from close()). Running
+  // `npm install -g` while the process is live overwrites the very .mjs files
+  // node has loaded → Windows TAR_ENTRY_ERROR file-locks. Installing on quit
+  // lets the parent release those handles first.
+  let pendingUpdateInstall = false;
 
   function autoUpdateEnabled() {
     return config?.update?.auto !== false;
@@ -662,6 +668,9 @@ export async function createMixdogSessionRuntime({
     if (updateProcessState.phase === 'installing') {
       return { ...updateProcessState, alreadyInstalling: true, error: 'update already in progress' };
     }
+    // A manual install consumes the boot-armed deferred install so quitting
+    // afterwards can't spawn a second redundant `npm install -g`.
+    pendingUpdateInstall = false;
     updateProcessState = { phase: 'installing', version: null, error: null };
     try {
       const result = await runGlobalUpdate();
@@ -678,36 +687,45 @@ export async function createMixdogSessionRuntime({
 
   // Non-blocking boot hook: fires after the runtime object below is fully
   // constructed (setTimeout(0) defers past the synchronous return), so a
-  // slow/hanging registry request or npm install can never delay session
-  // boot. Auto-update defaults to ON unless config.update.auto is explicitly
-  // false; a failed check or install is
-  // swallowed — getUpdateStatus()/getUpdateSettings() are the only surfaces,
-  // there is no push notice channel from runtime -> TUI today.
+  // slow/hanging registry request can never delay session boot. The check
+  // ALWAYS runs (populates updateCheckState for the maintenance picker), but
+  // the boot hook only DETECTS + arms a deferred install — the actual
+  // runGlobalUpdate now happens on graceful shutdown (flushPendingUpdate via
+  // close()) so npm never overwrites files the live process holds.
   // force:true — always hit the registry at boot (the 24h disk cache went
   // stale-visible: it kept reporting an older "latest" than the installed
   // version). checkLatestVersion() still falls back to the cache offline.
+  // isDevInstall() gate: a git checkout / clone (or non-node_modules install)
+  // must never self-update — `npm install -g` would fight the working tree.
   const updateBootTimer = setTimeout(() => {
     void (async () => {
       await checkForUpdateInternal({ force: true });
-      if (autoUpdateEnabled() && updateCheckState.updateAvailable) {
-        const result = await runUpdateNowInternal();
-        // Surface the boot auto-update outcome as a UI-only notice (TUI maps
-        // meta.kind 'update-notice' to a transcript notice, never a
-        // model-visible message). Silent before: installed-but-needs-restart
-        // and failed installs were invisible unless the user opened the
-        // maintenance picker.
-        if (result?.phase === 'installed') {
-          const v = result.version && result.version !== 'unknown'
-            ? `v${result.version}` : (updateCheckState.latestVersion ? `v${updateCheckState.latestVersion}` : 'latest');
-          emitRuntimeNotification(`mixdog ${v} installed — restart to apply.`, { kind: 'update-notice', tone: 'info' });
-        } else if (result?.phase === 'failed') {
-          emitRuntimeNotification(`mixdog auto-update failed: ${result.error || 'unknown error'}`, { kind: 'update-notice', tone: 'warn' });
-        }
+      if (autoUpdateEnabled() && !isDevInstall() && updateCheckState.updateAvailable) {
+        pendingUpdateInstall = true;
+        const v = updateCheckState.latestVersion ? `v${updateCheckState.latestVersion}` : 'latest';
+        // UI-only notice (TUI maps meta.kind 'update-notice' to a transcript
+        // notice, never a model-visible message). tone 'info': non-urgent,
+        // the install fires quietly on quit.
+        emitRuntimeNotification(`mixdog ${v} available — installs when you quit.`, { kind: 'update-notice', tone: 'info' });
       }
     })().catch(() => {});
   }, 0);
   updateBootTimer.unref?.();
 
+  // Invoked from the graceful shutdown path (lifecycle close() on exit/quit).
+  // Spawns the deferred npm install fire-and-forget: runGlobalUpdate() detaches
+  // (POSIX) / unrefs its child, so we neither await it nor block teardown —
+  // the parent exits, releasing file handles, while npm installs in the hidden
+  // background child. No-op unless an update was armed at boot.
+  function flushPendingUpdate() {
+    if (!pendingUpdateInstall) return;
+    pendingUpdateInstall = false;
+    // Re-check at flush time: the user may have turned update.auto off after
+    // the boot notice armed the install — respect the current setting.
+    if (!autoUpdateEnabled()) return;
+    try { void runGlobalUpdate(); } catch { /* best-effort: exit must not wedge */ }
+  }
+
   function emitRuntimeNotification(content, meta = {}) {
     const text = String(content || '').trim();
     if (!text) return false;
@@ -1985,6 +2003,7 @@ export async function createMixdogSessionRuntime({
     resolveRoute,
     applyDeferredToolSurface,
     standaloneTools,
+    flushPendingUpdate,
   });
   const resourceApi = createResourceApi({
     getConfig: () => config,

package/src/standalone/agent-tool.mjs

@@ -1587,17 +1587,48 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
           if (!fallbackTag || fallbackTag.startsWith('sess_') || !isDeadTarget) throw err;
           const prompt = clean(args.message || args.prompt);
           if (!prompt) throw err;
-          // Inherit the dead session's agent/cwd from the tag registry so the
-          // auto-respawn doesn't die on "agent spawn: agent is required" when
-          // Lead's send (correctly) omitted them. Read BEFORE forgetTag wipes
-          // the registry entries.
-          const inheritedAgent = clean(args.agent) || clean(tagAgents.get(fallbackTag));
-          const inheritedCwd = clean(args.cwd) || clean(tagCwds.get(fallbackTag));
-          if (!inheritedAgent) throw err;
-          // Clear the terminal trace so the fresh spawn isn't rejected by
-          // the lingering-trace guard, then run the normal deferred spawn.
-          try { forgetTag(fallbackTag); } catch {}
-          try { removeWorkerRow({ tag: fallbackTag }); } catch {}
+          // Inherit the dead session's agent/cwd so the auto-respawn doesn't
+          // die on "agent spawn: agent is required" when Lead's send (correctly)
+          // omitted them. Read BEFORE forgetTag wipes the registry entries.
+          //
+          // Root cause of the surfaced "target not found" errors: when a tag is
+          // FULLY reaped (session gone past the 5m grace window), the in-memory
+          // tagAgents/tagCwds maps are cleared, so inheritedAgent came back empty
+          // and this path re-threw instead of respawning. Recover the agent/cwd
+          // from the persisted worker row, then fall back to the default `worker`
+          // agent so an unknown-but-plausible tag still cold-respawns. The guards
+          // above (empty tag / raw sess_ id / non-dead error) keep plainly invalid
+          // targets erroring.
+          // readWorkerRows is already scoped to THIS terminal (clientHostPid,
+          // via rowMatchesContext), so inheritedRow — and every mutation below
+          // keyed on its sessionId — never touches another terminal's same-tag
+          // worker row.
+          let inheritedRow = null;
+          try {
+            inheritedRow = readWorkerRows(scopedContext).find((row) => clean(row.tag) === fallbackTag) || null;
+          } catch { inheritedRow = null; }
+          // Gate the respawn on evidence the tag previously existed IN THIS
+          // terminal: a persisted, clientHostPid-scoped worker row. The
+          // in-memory tags/tagAgents/tagCwds maps are NOT reliable evidence —
+          // closeAll() calls refreshTagsFromSessions() with NO context
+          // (see ~L1501), which populates them from EVERY terminal's rows
+          // (readWorkerRows({}) — rowMatchesContext returns true with no pid),
+          // so they can hold a peer terminal's tag. A typo'd / never-existed
+          // tag has no scoped row and must keep the original "not found" error.
+          if (!inheritedRow) throw err;
+          const inheritedSessionId = clean(inheritedRow.sessionId);
+          const inheritedAgent = clean(args.agent) || clean(inheritedRow.agent) || 'worker';
+          const inheritedCwd = clean(args.cwd) || clean(inheritedRow.cwd) || clean(callerCwd);
+          // Drop this terminal's in-memory trace and remove ONLY the persisted
+          // row matching inheritedRow.sessionId. Do NOT call forgetTag here: it
+          // does a tag-wide removeWorkerRow({tag,sessionId}) (L556) whose OR
+          // match (L395) would delete peer terminals' same-tag rows. The map
+          // deletes are guarded on the tag pointing at OUR sessionId so a peer
+          // cache entry (see above) is left intact (it rebuilds from rows).
+          if (tags.get(fallbackTag) === inheritedSessionId) {
+            try { tags.delete(fallbackTag); tagAgents.delete(fallbackTag); tagCwds.delete(fallbackTag); } catch {}
+          }
+          if (inheritedSessionId) { try { removeWorkerRow({ sessionId: inheritedSessionId }); } catch {} }
           const spawnArgs = {
             ...args,
             type: 'spawn',