fraim-hub 2.0.310 → 2.0.312

package/public/ai-hub/script.js

@@ -1234,7 +1234,17 @@ const SERVER_OWNED_CONV_FIELDS = ['messages', 'events', 'artifacts', 'run', 'del
 // It is listed in CLIENT_ONLY_CONV_FIELDS so `cleanConversationHeader()` strips
 // any inbound value. That is what preserves issue #913: a marker arriving over
 // the wire is never trusted, only one this client set after a real fetch.
-const CLIENT_ONLY_CONV_FIELDS = ['_bodyLoaded', '_bodyFetched', '_stopping'];
+//
+// Issue #1634: `_bodyFetchedRunId`/`_bodyFetchedLastUpdatedAt` record the
+// runId/lastUpdatedAt that were true at the moment THIS CLIENT's currently-held
+// message/event content was last made current (a full body fetch, or a live-run
+// poll fold — see mergeConversationBody/foldRunIntoConversation). The 30s header
+// poll (bgRefreshConversations/hydrateProjectConversationHeaders) merges fresh
+// runId/lastUpdatedAt directly into the SAME conversation object findConversation()
+// returns — there is no separate header copy — so comparing those fields against
+// this fetch-time snapshot is what lets conversationBodyIsStale() detect that a
+// scheduled/webhook fire replaced the run out from under an already-open tab.
+const CLIENT_ONLY_CONV_FIELDS = ['_bodyLoaded', '_bodyFetched', '_bodyFetchedRunId', '_bodyFetchedLastUpdatedAt', '_stopping'];
 function slimConversationForPersist(conv) {
   if (!conv || typeof conv !== 'object') return conv;
   const slim = { ...conv };
@@ -1310,9 +1320,30 @@ function mergeConversationBody(existing, body) {
   // Issue #1090: the body request came back, so this conversation is hydrated
   // regardless of which fields the response happened to contain.
   merged._bodyFetched = true;
+  // Issue #1634: stamp the runId/lastUpdatedAt this fetch reflects, so a later
+  // header-poll-observed change can be detected as staleness (see
+  // conversationBodyIsStale / CLIENT_ONLY_CONV_FIELDS comment above).
+  merged._bodyFetchedRunId = body.runId;
+  merged._bodyFetchedLastUpdatedAt = body.lastUpdatedAt;
   return merged;
 }
 
+// Issue #1634 (Defect C): `conversationHasBody()` only answers "was a body ever
+// fetched" — true forever after the first fetch (issue #1090), even once a
+// scheduled/webhook fire replaces the run underneath an already-open tab. This
+// answers the separate question "is the body we're holding still current",
+// by comparing the runId/lastUpdatedAt in effect when we last made the body
+// current (mergeConversationBody / foldRunIntoConversation) against the same
+// object's own runId/lastUpdatedAt fields, which the 30s header poll keeps
+// fresh in place (mergeConversationHeader merges into the SAME object
+// findConversation() returns — there is no separate header copy to compare
+// against).
+function conversationBodyIsStale(existing) {
+  if (!existing || existing._bodyFetchedRunId === undefined) return false;
+  if (existing.runId !== existing._bodyFetchedRunId) return true;
+  return timestampMillis(existing.lastUpdatedAt) > timestampMillis(existing._bodyFetchedLastUpdatedAt);
+}
+
 function mergeConversationListHeaders(existingList, headers) {
   const existingById = new Map((existingList || []).map((conv) => [conv.id, conv]));
   return (headers || []).map((header) => mergeConversationHeader(existingById.get(header.id), header));
@@ -1346,7 +1377,7 @@ function clearConversationBodyPendingFor(conv, fallbackProjectPath, id) {
 async function hydrateConversationBody(projectPath, id, options = {}) {
   if (!id) return null;
   const existing = findConversation(id);
-  if (!options.force && conversationHasBody(existing)) {
+  if (!options.force && conversationHasBody(existing) && !conversationBodyIsStale(existing)) {
     clearConversationBodyPendingFor(existing, projectPath, id);
     return existing;
   }
@@ -1361,6 +1392,24 @@ async function hydrateConversationBody(projectPath, id, options = {}) {
       if (!body) return null;
       normalizeGeminiConversationMessages(body);
       const current = findConversation(body.id);
+      // A body hydrate can be in flight while a live run poll or continue POST
+      // folds a newer run snapshot into the same conversation. Do not let the
+      // slower, older body response replace fresh messages/events with the
+      // persisted copy it started from.
+      const currentUpdatedAt = timestampMillis(current && current.lastUpdatedAt);
+      const bodyUpdatedAt = timestampMillis(body.lastUpdatedAt);
+      if (
+        !options.force
+        && current
+        && current.runId === body.runId
+        && conversationHasBody(current)
+        && currentUpdatedAt
+        && bodyUpdatedAt
+        && currentUpdatedAt > bodyUpdatedAt
+      ) {
+        clearConversationBodyPendingFor(current, projectPath, current.id);
+        return current;
+      }
       const merged = mergeConversationBody(current, body);
       const bucket = convBucketKey(merged);
       const list = (state.conversations[bucket] || []).slice();
@@ -1398,7 +1447,15 @@ async function rehydrateConversationAfterRunNotFound(conv) {
 
 function ensureActiveConversationBody() {
   const conv = activeConversation();
-  if (!conv || conversationHasBody(conv)) return;
+  if (!conv) return;
+  // Issue #1634: this own early-return used to check only conversationHasBody(),
+  // which short-circuits BEFORE hydrateConversationBody()'s own staleness check
+  // ever runs — the exact call path the 30s background poll uses for an
+  // already-open, never-switched-away-from conversation (bgRefreshConversations
+  // -> ensureActiveConversationBody). Without this, a scheduled/webhook fire
+  // against the tab a manager is actively looking at would never be picked up
+  // by that poll at all, regardless of the hydrateConversationBody fix below.
+  if (conversationHasBody(conv) && !conversationBodyIsStale(conv)) return;
   const bucket = convBucketKey(conv);
   state.conversationBodiesPending = bucket;
   hydrateConversationBody(bucket, conv.id).catch((error) =>
@@ -3833,6 +3890,9 @@ function renderActive() {
     pendingAnchorShownAt = null;
     pendingAnchorGraceActiveLastTick = false;
     userScrolledAwayDuringPendingAnchor = false;
+    pendingAnchorForceStartedAt = 0;
+    window.__fraimPendingAnchorUserScroll = false;
+    delete els['messages'].dataset.pendingAnchorUserScroll;
     // A pending coaching job is scoped to the active conversation — discard it
     // whenever the user switches to a different conversation.
     clearPendingCoachingJob();
@@ -3853,7 +3913,14 @@ function renderActive() {
   // existing rows don't re-animate. If for some reason the data shrunk
   // (server revoked a message), fall back to a full re-render.
   const bodyReady = conversationHasBody(conv);
-  if (!bodyReady) ensureActiveConversationBody();
+  // Issue #1634: call unconditionally, not just when the body was never
+  // fetched. ensureActiveConversationBody() now does its own staleness check
+  // internally (conversationBodyIsStale) and is a cheap no-op when the body is
+  // both present and current; this is the render-path trigger that actually
+  // fires on every poll-driven re-render for the active conversation, so the
+  // fix only reaches this call site if it isn't gated behind the old
+  // conversationHasBody()-only condition.
+  ensureActiveConversationBody();
   const messages = bodyReady ? (conv.messages || []) : [];
   // Issue #820: while the two-phase hydrate is still fetching bodies, show a loading indicator
   // for the active conversation instead of an empty transcript. A dedicated node (kept separate
@@ -3913,6 +3980,14 @@ function renderActive() {
   // genuinely new messages, not every row a messagesMutated full rebuild just
   // re-appended (e.g. an existing message's badge disappearing).
   const priorRenderedMessageCount = renderedMessageCount;
+  const hadPendingRowsBeforeRebuild = !!els['messages'].querySelector('.message[data-pending="true"]');
+  if (
+    hadPendingRowsBeforeRebuild
+    && els['messages'].scrollTop <= 20
+    && els['messages'].scrollHeight - els['messages'].clientHeight > 80
+  ) {
+    userScrolledAwayDuringPendingAnchor = true;
+  }
   if (messages.length < renderedMessageCount || messagesMutated) {
     els['messages'].innerHTML = '';
     renderedMessageCount = 0;
@@ -5520,7 +5595,7 @@ function pendingBacklogScrollTop(host) {
   if (!firstPending) return host.scrollHeight;
   const backlogTop = firstPending.getBoundingClientRect().top - host.getBoundingClientRect().top + host.scrollTop;
   const maxScrollTop = host.scrollHeight - host.clientHeight;
-  return Math.max(0, Math.min(backlogTop, maxScrollTop));
+  return Math.max(0, Math.min(backlogTop - 16, maxScrollTop));
 }
 
 // Issue #1570: the #1249 anchor above never released. Once nearBottom went
@@ -5539,6 +5614,8 @@ let pendingAnchorShownAt = null;
 let pendingAnchorGraceActiveLastTick = false;
 let pendingAnchorScrollListenerHost = null;
 let userScrolledAwayDuringPendingAnchor = false;
+let pendingAnchorProgrammaticScrollUntil = 0;
+let pendingAnchorForceStartedAt = 0;
 
 // A manual scroll away from the anchor must be detected from a real user
 // gesture, not from the 'scroll' event a programmatic assignment ALSO fires —
@@ -5556,10 +5633,32 @@ let userScrolledAwayDuringPendingAnchor = false;
 function ensurePendingAnchorScrollListener(host) {
   if (pendingAnchorScrollListenerHost === host) return;
   pendingAnchorScrollListenerHost = host;
-  const markUserScroll = () => { userScrolledAwayDuringPendingAnchor = true; };
-  host.addEventListener('wheel', markUserScroll, { passive: true });
-  host.addEventListener('touchmove', markUserScroll, { passive: true });
+  const markUserScroll = () => {
+    userScrolledAwayDuringPendingAnchor = true;
+    host.dataset.pendingAnchorUserScroll = 'true';
+    window.__fraimPendingAnchorUserScroll = true;
+  };
+  host.addEventListener('wheel', markUserScroll, { passive: true, capture: true });
+  host.addEventListener('touchmove', markUserScroll, { passive: true, capture: true });
+  window.addEventListener('wheel', markUserScroll, { passive: true, capture: true });
+  window.addEventListener('touchmove', markUserScroll, { passive: true, capture: true });
   host.addEventListener('mousedown', (event) => { if (event.target === host) markUserScroll(); });
+  host.addEventListener('scroll', () => {
+    if (pendingAnchorShownAt === null) return;
+    if (Date.now() <= pendingAnchorProgrammaticScrollUntil) return;
+    const pendingRow = host.querySelector('.message[data-pending="true"]');
+    if (!pendingRow) return;
+    if (host.scrollTop <= 20 && host.scrollHeight - host.clientHeight > 80) markUserScroll();
+  }, { passive: true });
+}
+
+function setThreadScrollTop(host, top) {
+  pendingAnchorProgrammaticScrollUntil = Date.now() + 200;
+  host.scrollTop = top;
+}
+
+function pendingAnchorUserScrolled(host) {
+  return userScrolledAwayDuringPendingAnchor || host.dataset.pendingAnchorUserScroll === 'true' || window.__fraimPendingAnchorUserScroll === true;
 }
 
 function scrollThreadAfterViewportSync(conv, shouldScrollForUpdate, forceBottom) {
@@ -5569,19 +5668,56 @@ function scrollThreadAfterViewportSync(conv, shouldScrollForUpdate, forceBottom)
   if (!host) return;
   if (latest.status === 'running') {
     ensurePendingAnchorScrollListener(host);
+    if (!forceBottom && pendingAnchorUserScrolled(host)) {
+      host.scrollTop = 0;
+      return;
+    }
     const pendingRow = host.querySelector('.message[data-pending="true"]');
     // forceBottom is true exactly when a NEW pending (queued/redirecting)
     // message just arrived (see the caller's hasNewPendingDeliveryMessage) —
     // that's the moment to (re)start the grace window and trust the manager's
     // scroll position again, not every tick a pending row happens to exist.
     if (forceBottom) {
-      pendingAnchorShownAt = Date.now();
-      userScrolledAwayDuringPendingAnchor = false;
+      const now = Date.now();
+      const deferredSameForce = pendingAnchorForceStartedAt > 0 && (now - pendingAnchorForceStartedAt) < 250;
+      if (
+        deferredSameForce
+        && (
+          pendingAnchorUserScrolled(host)
+          || (
+            now > pendingAnchorProgrammaticScrollUntil
+            && host.scrollTop <= 20
+            && host.scrollHeight - host.clientHeight > 80
+          )
+        )
+      ) {
+        userScrolledAwayDuringPendingAnchor = true;
+        host.dataset.pendingAnchorUserScroll = 'true';
+        window.__fraimPendingAnchorUserScroll = true;
+      } else if (!deferredSameForce) {
+        userScrolledAwayDuringPendingAnchor = false;
+        delete host.dataset.pendingAnchorUserScroll;
+        window.__fraimPendingAnchorUserScroll = false;
+        pendingAnchorForceStartedAt = now;
+      }
+      pendingAnchorShownAt = now;
     } else if (!pendingRow) {
       pendingAnchorShownAt = null;
     }
     const anchorGraceActive = !!pendingRow && pendingAnchorShownAt !== null &&
       (Date.now() - pendingAnchorShownAt) < PENDING_ANCHOR_GRACE_MS;
+    if (
+      pendingRow
+      && pendingAnchorShownAt !== null
+      && !forceBottom
+      && Date.now() > pendingAnchorProgrammaticScrollUntil
+      && host.scrollTop <= 20
+      && host.scrollHeight - host.clientHeight > 80
+    ) {
+      userScrolledAwayDuringPendingAnchor = true;
+      host.dataset.pendingAnchorUserScroll = 'true';
+      window.__fraimPendingAnchorUserScroll = true;
+    }
     // Fires exactly once, on the tick where the anchor stops being active —
     // either the pending badge just cleared, or the grace window for a
     // still-unresolved pending row (e.g. Defect 1's kill still in flight)
@@ -5595,12 +5731,22 @@ function scrollThreadAfterViewportSync(conv, shouldScrollForUpdate, forceBottom)
     // #936: re-evaluate nearBottom at call time so deferred invocations respect
     // any scroll the user made between the render tick and this callback.
     const nearBottom = host.scrollHeight - host.scrollTop - host.clientHeight < 80;
-    if (catchUpToBottom && userScrolledAwayDuringPendingAnchor) return;
+    if (catchUpToBottom && host.scrollTop <= 20 && host.scrollHeight - host.clientHeight > 80) {
+      userScrolledAwayDuringPendingAnchor = true;
+      host.dataset.pendingAnchorUserScroll = 'true';
+      window.__fraimPendingAnchorUserScroll = true;
+    }
+    if (catchUpToBottom && pendingAnchorUserScrolled(host)) return;
+    if (forceBottom && pendingAnchorUserScrolled(host)) return;
+    if (anchorGraceActive && !pendingAnchorUserScrolled(host)) {
+      setThreadScrollTop(host, pendingBacklogScrollTop(host));
+      return;
+    }
     // Issue #1249: a message the manager just sent while the agent was
     // mid-turn (queued or redirecting) must be visible without the manager
     // having to scroll, even if they had scrolled up to review history.
     if (nearBottom || forceBottom || catchUpToBottom) {
-      host.scrollTop = anchorGraceActive ? pendingBacklogScrollTop(host) : host.scrollHeight;
+      setThreadScrollTop(host, anchorGraceActive ? pendingBacklogScrollTop(host) : host.scrollHeight);
     }
     return;
   } else if (shouldScrollForUpdate) {
@@ -7593,13 +7739,21 @@ function renderCpRows(searchText) {
     }
   }
 
-  // Build flat row list: recent first, then catalog jobs, then teach entries
-  // last. Teach entries go after the catalog jobs so the first runnable job
-  // stays the default keyboard selection (ArrowDown+Enter runs a job, not a
-  // teach flow). The flat order must match the render order below so
+  // Issue #1610 R13: pinned "Ad-hoc" row in the catalog list when a non-empty
+  // search yields zero catalog matches. Clicking calls startAdhoc with the
+  // current search text so the user's query seeds the freeform instructions.
+  const adhocRows = q && catalogJobs.length === 0
+    ? [{ type: 'adhoc', job: { id: 'adhoc-prompt', title: 'Ad-hoc', intent: 'run as custom instructions' }, instructions: '' }]
+    : [];
+
+  // Build flat row list: recent first, then adhoc (if shown), then catalog jobs,
+  // then teach entries last. Teach entries go after the catalog jobs so the first
+  // runnable job stays the default keyboard selection (ArrowDown+Enter runs a job,
+  // not a teach flow). The flat order must match the render order below so
   // click/keyboard indices line up.
   state.cpRows = [
     ...recentRows,
+    ...adhocRows,
     ...catalogJobs.map((j) => ({ type: 'job', job: j, instructions: '' })),
     ...teachRows,
   ];
@@ -7616,16 +7770,20 @@ function renderCpRows(searchText) {
     });
   }
 
-  // Render catalog section: catalog jobs first, then teach entries last.
-  // flatIndex continues from recentRows so it matches state.cpRows order.
+  // Render catalog section: adhoc pinned row first (when shown), then catalog
+  // jobs, then teach entries last. flatIndex continues from recentRows so it
+  // matches state.cpRows order.
   const catalogList = document.getElementById('cp-catalog-list');
   if (catalogList) {
     catalogList.innerHTML = '';
+    adhocRows.forEach((row, i) => {
+      catalogList.appendChild(buildCpRow(row, recentRows.length + i));
+    });
     catalogJobs.forEach((job, i) => {
-      catalogList.appendChild(buildCpRow({ type: 'job', job, instructions: '' }, recentRows.length + i));
+      catalogList.appendChild(buildCpRow({ type: 'job', job, instructions: '' }, recentRows.length + adhocRows.length + i));
     });
     teachRows.forEach((row, i) => {
-      catalogList.appendChild(buildCpRow(row, recentRows.length + catalogJobs.length + i));
+      catalogList.appendChild(buildCpRow(row, recentRows.length + adhocRows.length + catalogJobs.length + i));
     });
   }
 
@@ -7642,11 +7800,20 @@ function renderCpAgentPicker() {
   if (!picker) return;
   picker.innerHTML = '';
   const list = hubConfiguredAgents();
+  const hasAvailable = list.some((e) => e.available !== false && e.enabled !== false);
+  const footer = picker.closest('.cp-employee-footer');
+  if (footer) footer.hidden = !hasAvailable;
   const curOk = list.some((e) => e.id === state.cpEmployee && e.available !== false && e.enabled !== false);
   if (!curOk) {
     const firstAvail = list.find((e) => e.available !== false && e.enabled !== false);
     state.cpEmployee = firstAvail ? firstAvail.id : null;
   }
+  if (!hasAvailable) {
+    renderCpAgentInstallPanel();
+    const startBtn = document.getElementById('cp-start-btn');
+    if (startBtn) startBtn.disabled = true;
+    return;
+  }
   for (const e of list) {
     const pill = document.createElement('button');
     pill.type = 'button';
@@ -7675,7 +7842,7 @@ function buildCpRow(row, flatIndex) {
 
   const icon = document.createElement('span');
   icon.className = 'cp-row-icon';
-  icon.textContent = row.type === 'recent' ? '🕐' : row.type === 'teach' ? '🎓' : '📋';
+  icon.textContent = row.type === 'recent' ? '🕐' : row.type === 'teach' ? '🎓' : row.type === 'adhoc' ? '✨' : '📋';
 
   const body = document.createElement('span');
   body.className = 'cp-row-body';
@@ -7702,7 +7869,7 @@ function buildCpRow(row, flatIndex) {
   // #1340: this is the actual "+ Delegate Job" catalog (openModal → openPalette →
   // renderCpRows → buildCpRow) — the row never had a visualize affordance at all.
   // Teach rows carry a synthetic, non-catalog job object, so skip them.
-  if (row.type !== 'teach') {
+  if (row.type !== 'teach' && row.type !== 'adhoc') {
     el.appendChild(tfCreateJobVizControl(row.job));
   }
   if (row.job.requiredPersonaKey) {
@@ -7736,6 +7903,15 @@ function renderCpHighlight() {
 function selectCpRow(index) {
   const row = state.cpRows[index];
   if (!row) return;
+  // Issue #1610 R13: adhoc row launches freeform directly with the current search text.
+  // Close the palette first so the step-2 modal opens on a clean slate.
+  if (row.type === 'adhoc') {
+    const search = document.getElementById('cp-search');
+    const searchText = search ? search.value.trim() : '';
+    closePalette();
+    startAdhoc(searchText);
+    return;
+  }
   state.cpSelectedJob = row.job;
   state.cpHighlightIndex = index;
   renderCpHighlight();
@@ -7808,6 +7984,12 @@ function rerunLastJob() {
 function showRerunToast(msg) {
   const t = document.createElement('div');
   t.className = 'cp-rerun-toast';
+  // Issue #1627: matches this app's own convention for transient status text (#be-status,
+  // #status-line, etc.) so a screen reader announces the message instead of it being silently
+  // visual-only - relevant beyond the original re-run case now that this toast also carries the
+  // real reason a restart-to-latest attempt failed.
+  t.setAttribute('role', 'status');
+  t.setAttribute('aria-live', 'polite');
   t.textContent = msg;
   document.body.appendChild(t);
   setTimeout(() => { if (t.parentNode) t.parentNode.removeChild(t); }, 5000);
@@ -8079,11 +8261,122 @@ function renderCpAgentInstallPanel() {
     panel.innerHTML = '';
     return;
   }
-  renderAgentInstallPanelInto(panel, {
-    heading: 'Set up a CLI agent before starting',
-    intro: 'Install, sign in, and verify one Hub agent to enable Start.',
-    testPrefix: 'cp-agent',
+  // Keep setup guidance centralized in Manager -> AI Agents.
+  panel.hidden = false;
+  panel.innerHTML = '';
+
+  const heading = document.createElement('div');
+  heading.className = 'install-panel-heading';
+  heading.textContent = 'No AI agent is set up yet';
+  panel.appendChild(heading);
+
+  const intro = document.createElement('p');
+  intro.className = 'install-panel-copy';
+  intro.textContent = 'Install, sign in, and verify a CLI agent in Manager -> AI Agents, then come back here to start.';
+  panel.appendChild(intro);
+
+  const link = document.createElement('button');
+  link.type = 'button';
+  link.className = 'secondary small';
+  link.textContent = 'Go to Manager -> AI Agents';
+  link.setAttribute('data-testid', 'cp-cli-setup-goto-manager');
+  link.addEventListener('click', () => {
+    closePalette();
+    if (typeof tfShowArea === 'function') tfShowArea('manager');
+    const acc = document.getElementById('manager-agents-acc');
+    if (acc) {
+      acc.open = true;
+      acc.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    }
   });
+  panel.appendChild(link);
+}
+
+// Issue #1618 (R3): the single shared install/sign-in row builder. Used both by the job
+// composer's standalone panels (renderAgentInstallPanelInto's loop below) and by the
+// Manager AI Agents panel's per-card mount (renderConfiguredAgentsPanel), so the two
+// surfaces share one state machine and cannot drift out of sync. `options.testPrefix`
+// namespaces testids per mount point (e.g. 'hub-agent' vs 'manager-agent').
+// PR feedback (#1620): `options.showLabel` (default true) and `options.resetLabel`
+// (default 'Choose another agent') let a mount point adapt wording/labeling without a
+// second implementation. `options.buttonClass`/`options.secondaryButtonClass` (default
+// 'secondary small'/'ghost small', the job composer's own standalone-panel button style)
+// let a mount point match its own surrounding card/button language instead. The job
+// composer's 3 mounts pass none of these and are unchanged.
+function buildAgentInstallRow(emp, options) {
+  const buttonClass = options.buttonClass || 'secondary small';
+  const secondaryButtonClass = options.secondaryButtonClass || 'ghost small';
+
+  const row = document.createElement('div');
+  row.className = 'install-row';
+  row.id = `install-row-${emp.id}`;
+
+  if (options.showLabel !== false) {
+    const label = document.createElement('span');
+    label.className = 'install-label';
+    label.textContent = emp.label;
+    row.appendChild(label);
+  }
+
+  const status = document.createElement('span');
+  status.className = 'install-status';
+  status.id = `install-status-${emp.id}`;
+  status.textContent = agentInstallState[emp.id]?.statusText || '';
+  row.appendChild(status);
+
+  const btn = document.createElement('button');
+  btn.className = buttonClass;
+  btn.id = `install-btn-${emp.id}`;
+  btn.dataset.hubId = emp.id;
+
+  const st = agentInstallState[emp.id] || {};
+  if (!st.phase) {
+    btn.textContent = `Download / Install ${emp.label}`;
+    btn.setAttribute('data-testid', `${options.testPrefix || 'hub-agent'}-install-${emp.id}`);
+    btn.addEventListener('click', () => startAgentInstall(emp.id));
+  } else if (st.phase === 'installing') {
+    btn.textContent = 'Installing...';
+    btn.disabled = true;
+  } else if (st.phase === 'needs-login') {
+    btn.textContent = 'Sign In';
+    btn.addEventListener('click', () => triggerAgentLogin(emp.id));
+  } else if (st.phase === 'login-triggered') {
+    const checkBtn = document.createElement('button');
+    checkBtn.className = buttonClass;
+    checkBtn.textContent = 'Check if Ready';
+    checkBtn.setAttribute('data-testid', `${options.testPrefix || 'hub-agent'}-check-${emp.id}`);
+    checkBtn.addEventListener('click', () => checkAgentReady(emp.id));
+    row.appendChild(checkBtn);
+
+    const skipBtn = document.createElement('button');
+    skipBtn.className = secondaryButtonClass;
+    // PR feedback (#1620): "Choose another agent" describes the job composer's picker
+    // context (abandon this one, pick a different employee/tool). The Manager panel has
+    // no picker to return to — clicking this just resets THIS card's install phase — so
+    // that mount passes a clearer label via options.resetLabel.
+    skipBtn.textContent = options.resetLabel || 'Choose another agent';
+    skipBtn.setAttribute('data-testid', `${options.testPrefix || 'hub-agent'}-reset-${emp.id}`);
+    skipBtn.style.marginLeft = '6px';
+    skipBtn.addEventListener('click', () => {
+      delete agentInstallState[emp.id];
+      renderAgentInstallPanel();
+      renderHubAgentSetupPanel();
+      renderCpAgentInstallPanel();
+      renderConfiguredAgentsPanel();
+    });
+    row.appendChild(skipBtn);
+    return row;
+  } else if (st.phase === 'ready') {
+    btn.textContent = 'Ready';
+    btn.disabled = true;
+    btn.style.color = 'var(--accent)';
+  } else if (st.phase === 'error') {
+    btn.textContent = 'Retry';
+    btn.addEventListener('click', () => startAgentInstall(emp.id));
+  }
+
+  row.appendChild(btn);
+  return row;
 }
 
 function renderAgentInstallPanelInto(panel, options) {
@@ -8113,70 +8406,7 @@ function renderAgentInstallPanelInto(panel, options) {
   }
 
   for (const emp of unavailable) {
-    const row = document.createElement('div');
-    row.className = 'install-row';
-    row.id = `install-row-${emp.id}`;
-
-    const label = document.createElement('span');
-    label.className = 'install-label';
-    label.textContent = emp.label;
-    row.appendChild(label);
-
-    const status = document.createElement('span');
-    status.className = 'install-status';
-    status.id = `install-status-${emp.id}`;
-    status.textContent = agentInstallState[emp.id]?.statusText || '';
-    row.appendChild(status);
-
-    const btn = document.createElement('button');
-    btn.className = 'secondary small';
-    btn.id = `install-btn-${emp.id}`;
-    btn.dataset.hubId = emp.id;
-
-    const st = agentInstallState[emp.id] || {};
-    if (!st.phase) {
-      btn.textContent = `Download / Install ${emp.label}`;
-      btn.setAttribute('data-testid', `${options.testPrefix || 'hub-agent'}-install-${emp.id}`);
-      btn.addEventListener('click', () => startAgentInstall(emp.id));
-    } else if (st.phase === 'installing') {
-      btn.textContent = 'Installing...';
-      btn.disabled = true;
-    } else if (st.phase === 'needs-login') {
-      btn.textContent = 'Sign In';
-      btn.addEventListener('click', () => triggerAgentLogin(emp.id));
-    } else if (st.phase === 'login-triggered') {
-      const checkBtn = document.createElement('button');
-      checkBtn.className = 'secondary small';
-      checkBtn.textContent = 'Check if Ready';
-      checkBtn.setAttribute('data-testid', `${options.testPrefix || 'hub-agent'}-check-${emp.id}`);
-      checkBtn.addEventListener('click', () => checkAgentReady(emp.id));
-      row.appendChild(checkBtn);
-
-      const skipBtn = document.createElement('button');
-      skipBtn.className = 'ghost small';
-      skipBtn.textContent = 'Choose another agent';
-      skipBtn.setAttribute('data-testid', `${options.testPrefix || 'hub-agent'}-reset-${emp.id}`);
-      skipBtn.style.marginLeft = '6px';
-      skipBtn.addEventListener('click', () => {
-        delete agentInstallState[emp.id];
-        renderAgentInstallPanel();
-        renderHubAgentSetupPanel();
-        renderCpAgentInstallPanel();
-      });
-      row.appendChild(skipBtn);
-      panel.appendChild(row);
-      continue;
-    } else if (st.phase === 'ready') {
-      btn.textContent = 'Ready';
-      btn.disabled = true;
-      btn.style.color = 'var(--accent)';
-    } else if (st.phase === 'error') {
-      btn.textContent = 'Retry';
-      btn.addEventListener('click', () => startAgentInstall(emp.id));
-    }
-
-    row.appendChild(btn);
-    panel.appendChild(row);
+    panel.appendChild(buildAgentInstallRow(emp, options));
   }
 }
 
@@ -8186,6 +8416,10 @@ function setInstallState(hubId, phase, statusText) {
   renderHubAgentSetupPanel();
   renderCpAgentInstallPanel();
   renderCpAgentPicker();
+  // Issue #1618: the Manager AI Agents panel's per-card install row shares this same
+  // agentInstallState, so it must refresh at the same choke point as the job composer's
+  // three panels or it drifts out of sync with them.
+  renderConfiguredAgentsPanel();
 }
 
 // Issue #1256 (slice c, AC-C4): backstop above the server's own AGENT_INSTALL_TIMEOUT_MS
@@ -8257,6 +8491,9 @@ async function refreshEmployees() {
     renderAgentInstallPanel();
     renderHubAgentSetupPanel();
     renderCpAgentInstallPanel();
+    // Issue #1618: the Manager AI Agents panel's per-card install row depends on the same
+    // refreshed employee roster (e.g. after "Check if Ready" confirms a host is now available).
+    renderConfiguredAgentsPanel();
   } catch { /* best-effort */ }
 }
 
@@ -8738,6 +8975,12 @@ function foldRunIntoConversation(conv, run) {
   // can derive the correct pill without heuristics.
   if (run.pauseReason !== undefined) conv.pauseReason = run.pauseReason;
   conv.lastUpdatedAt = Date.now();
+  // Issue #1634: this fold just made conv's messages/events current for run.id,
+  // as of the lastUpdatedAt stamped above — record that so a subsequent
+  // hydrateConversationBody() call (e.g. on switch-away/switch-back while this
+  // same run is still live) sees the content as fresh and does not re-fetch.
+  conv._bodyFetchedRunId = run.id;
+  conv._bodyFetchedLastUpdatedAt = conv.lastUpdatedAt;
 }
 
 // Issue #442: fold the Direct (B) side run into the conversation's compareRun slot.
@@ -9166,6 +9409,26 @@ function renderConfiguredAgentsPanel() {
       const renderedAvailable = latestCheck ? latestCheck.available !== false : agent.available !== false;
       const renderedEnabled = agent.enabled !== false;
       const renderedReasons = latestCheck?.reasons || agent.reasons || [];
+
+      // Issue #1618 (R2/R3), moved up (PR feedback #1620): computed before the actions
+      // row so the redundant top-of-card "Check" button can be omitted whenever the
+      // install row itself is about to render — the install row's own state machine
+      // (Download/Install -> Sign In -> Check if Ready) already provides a live-check
+      // path once installed, and "Check" against a not-yet-installed host communicates
+      // nothing the status pill/status pill text does not already say.
+      //
+      // Gated strictly on the underlying host CLI's own readiness (`emp.available ===
+      // false`), never on the configured-agent's `enabled` flag or any other not-ready
+      // reason (PR feedback #1620: an earlier, broader formula also showed the row for a
+      // profile that was merely disabled, or one with a good host but a broken/missing
+      // setup script -- neither of which installing/signing-in the CLI would fix; Edit
+      // is the correct path for both). `renderedAvailable` already prefers a fresh
+      // `latestCheck` result over the possibly-stale roster snapshot, so clicking "Check
+      // if Ready" inside the row hides the row (and restores the top Check button)
+      // immediately once ready.
+      const emp = hubEmployees().find((e) => e.id === agent.baseHostId);
+      const showInstallRow = emp ? emp.available === false : false;
+
       const card = document.createElement('div');
       card.className = 'configured-agent-card';
       card.dataset.testid = 'configured-agent-card';
@@ -9181,21 +9444,23 @@ function renderConfiguredAgentsPanel() {
 
       const actions = document.createElement('div');
       actions.className = 'configured-agent-card-actions';
-      const check = document.createElement('button');
-      check.type = 'button';
-      check.className = 'configured-agent-icon-action';
-      check.textContent = 'Check';
-      check.addEventListener('click', async () => {
-        try {
-          const result = await requestJson(`/api/ai-hub/configured-agents/${encodeURIComponent(agent.id)}/check`, { method: 'POST' });
-          state.configuredAgentCheckResults[agent.id] = result;
-          showStatus(result.available ? `${agent.label} is ready.` : `${agent.label}: ${(result.reasons || []).join(' ') || 'Check setup.'}`, !result.available);
-          renderConfiguredAgentsPanel();
-        } catch (err) {
-          showStatus(err.message || 'Agent check failed.', true);
-        }
-      });
-      actions.appendChild(check);
+      if (!showInstallRow) {
+        const check = document.createElement('button');
+        check.type = 'button';
+        check.className = 'configured-agent-icon-action';
+        check.textContent = 'Check';
+        check.addEventListener('click', async () => {
+          try {
+            const result = await requestJson(`/api/ai-hub/configured-agents/${encodeURIComponent(agent.id)}/check`, { method: 'POST' });
+            state.configuredAgentCheckResults[agent.id] = result;
+            showStatus(result.available ? `${agent.label} is ready.` : `${agent.label}: ${(result.reasons || []).join(' ') || 'Check setup.'}`, !result.available);
+            renderConfiguredAgentsPanel();
+          } catch (err) {
+            showStatus(err.message || 'Agent check failed.', true);
+          }
+        });
+        actions.appendChild(check);
+      }
 
       const edit = document.createElement('button');
       edit.type = 'button';
@@ -9243,6 +9508,38 @@ function renderConfiguredAgentsPanel() {
       card.appendChild(head);
       card.appendChild(meta);
       card.appendChild(detail);
+
+      // Issue #1618 (R2/R3/R4): a per-card install/sign-in affordance for an agent
+      // that isn't ready, reusing the job composer's shared row builder rather than a
+      // second parallel implementation. `showInstallRow` is computed above (it also
+      // gates the top "Check" button). The buttons are styled with the card's own
+      // `.configured-agent-icon-action` class (PR feedback #1620: the job composer's
+      // `.secondary small`/`.ghost small` classes read as a visually different, duller
+      // button style next to Check/Edit/Delete) instead of the job composer's own
+      // standalone-panel button classes.
+      if (showInstallRow) {
+        const installWrap = document.createElement('div');
+        installWrap.className = 'configured-agent-install-row';
+        installWrap.appendChild(buildAgentInstallRow(
+          emp || { id: agent.baseHostId, label: agent.label, available: false },
+          // PR feedback (#1620): the card's own title already names this configured
+          // agent, so the row's own `emp.label` line (the underlying host's label,
+          // which can legitimately differ from a custom configured-agent label) is
+          // suppressed here to avoid reading as a second, unrelated agent name.
+          // "Choose another agent" is replaced with "Start over" since there is no
+          // agent picker on this panel to return to -- the button only resets this
+          // card's own install phase.
+          {
+            testPrefix: 'manager-agent',
+            showLabel: false,
+            resetLabel: 'Start over',
+            buttonClass: 'configured-agent-icon-action',
+            secondaryButtonClass: 'configured-agent-icon-action',
+          },
+        ));
+        card.appendChild(installWrap);
+      }
+
       panel.appendChild(card);
     }
   }
@@ -12746,6 +13043,21 @@ function buildDeploymentRow(dep) {
   title.className = 'dep-row-title';
   title.textContent = dep.label;
   body.appendChild(title);
+  // Issue #1610 R10: for adhoc-prompt deployments show the job name (resolved from
+  // catalog metadata) and the first 50 chars of instructions as a subtitle.
+  if (dep.jobId === 'adhoc-prompt') {
+    const depJobInfo = (state.bootstrap?.jobs ?? []).find((j) => j.id === dep.jobId);
+    const jobLabel = document.createElement('span');
+    jobLabel.className = 'dep-row-job-label';
+    jobLabel.textContent = (depJobInfo && depJobInfo.title) || dep.jobId;
+    body.appendChild(jobLabel);
+    if (dep.instructions) {
+      const sub = document.createElement('span');
+      sub.className = 'dep-row-sub';
+      sub.textContent = dep.instructions.slice(0, 50);
+      body.appendChild(sub);
+    }
+  }
   const meta = document.createElement('span');
   meta.className = 'assign-row-meta';
   const badge = document.createElement('span');
@@ -12916,6 +13228,23 @@ function populateAgentSelect(sel, currentHostId) {
   if (pick) sel.value = pick;
 }
 
+// Issue #1610 R8: sync the instructions label text and placeholder when the job
+// selection changes. adhoc-prompt requires instructions; all other jobs treat
+// them as optional context.
+function updateDepInstructionsLabel() {
+  const jobSel = document.getElementById('dep-job');
+  const labelEl = document.getElementById('dep-inst-optional-label');
+  const textarea = document.getElementById('dep-instructions');
+  const isAdhoc = jobSel && jobSel.value === 'adhoc-prompt';
+  if (labelEl) labelEl.textContent = isAdhoc ? '(required)' : '(optional)';
+  if (textarea) {
+    textarea.placeholder = isAdhoc
+      ? 'Describe what to do each run…'
+      : 'Optional message sent to the agent at the start of each run';
+    textarea.setAttribute('aria-required', isAdhoc ? 'true' : 'false');
+  }
+}
+
 // #693 R2: open the single consolidated assignment modal. `dep` present = edit;
 // its .type locks the segmented control. New assignments default to Scheduled.
 function openDeploymentModal(dep) {
@@ -12925,13 +13254,24 @@ function openDeploymentModal(dep) {
 
   const jobSel = document.getElementById('dep-job');
   jobSel.innerHTML = '';
-  // Issue #1451: sort alphabetically by title so the New Assignment job list is scannable.
-  for (const j of sortJobsByTitle(jobs)) {
+  const catalogJobs = jobs.filter((j) => j && j.id !== 'adhoc-prompt');
+  const deploymentJobs = sortJobsByTitle([
+    { id: 'adhoc-prompt', title: 'Ad-hoc (custom instructions)' },
+    ...catalogJobs,
+  ]);
+  // Issue #1451: sort alphabetically by the displayed title so the New
+  // Assignment job list is scannable. Ad-hoc remains available, but it is not
+  // pinned above catalog jobs because it requires instructions before saving.
+  for (const j of deploymentJobs) {
     const opt = document.createElement('option');
     opt.value = j.id; opt.textContent = j.title;
     jobSel.appendChild(opt);
   }
-  if (dep?.jobId) jobSel.value = dep.jobId;
+  const defaultCatalogJob = sortJobsByTitle(catalogJobs)[0];
+  const selectedJobId = dep?.jobId || defaultCatalogJob?.id || 'adhoc-prompt';
+  if (selectedJobId) jobSel.value = selectedJobId;
+  updateDepInstructionsLabel();
+  jobSel.onchange = updateDepInstructionsLabel;
 
   populateAgentSelect(document.getElementById('dep-agent'), dep?.configuredAgentId || dep?.hostId || 'claude');
   document.getElementById('dep-label').value = dep?.label ?? '';
@@ -12979,6 +13319,9 @@ async function saveDeployment() {
   const instructions = document.getElementById('dep-instructions').value.trim();
   const isEdit = _editingDepId !== null;
   if (!label) { errEl.textContent = 'Name is required.'; errEl.hidden = false; return; }
+  // Issue #1610 R9: adhoc-prompt has no fixed task — block save before any network
+  // request so the user gets immediate feedback rather than a server 400.
+  if (jobId === 'adhoc-prompt' && !instructions) { errEl.textContent = 'Instructions are required for ad-hoc assignments.'; errEl.hidden = false; return; }
 
   if (_depType === 'scheduled') {
     const isCustom = _activeSchPreset === 'custom';
@@ -16994,23 +17337,42 @@ function tfRestartHubToLatest(event) {
     badgeEl.textContent = '⬆️ Restarting…';
   }
   fetch('/api/ai-hub/restart-to-latest', { method: 'POST' })
-    .then((r) => (r.ok ? r.json() : Promise.reject(new Error(`status ${r.status}`))))
-    .then((info) => {
-      if (info && info.restarting) {
-        tfPollForHubRestart(info.latest || null, 0);
-      } else if (badgeEl) {
-        badgeEl.disabled = false;
-        badgeEl.textContent = '⬆️ Updates available';
+    .then((r) => r.json().catch(() => ({})).then((body) => ({ ok: r.ok, body })))
+    .then(({ ok, body }) => {
+      if (!ok) throw new Error((body && body.error) || 'Could not update FRAIM Hub.');
+      if (body && body.restarting) {
+        tfPollForHubRestart(body.latest || null, 0);
+        return;
       }
+      // Issue #1627: restarting:false used to be treated as "nothing to do" unconditionally, so a
+      // genuine materialization failure looked identical to "already current" and the badge just
+      // silently reverted with no explanation. An `error` here means the restart was attempted and
+      // failed - show the real reason instead of pretending the click did nothing.
+      tfShowHubRestartFailure(badgeEl, body && body.error);
     })
-    .catch(() => {
-      if (badgeEl) {
-        badgeEl.disabled = false;
-        badgeEl.textContent = '⬆️ Updates available';
-      }
+    .catch((err) => {
+      tfShowHubRestartFailure(badgeEl, err && err.message);
     });
 }
 
+// Issue #1627: how long the badge shows "Restart failed" before settling back to its steady
+// "an update is still available, click to try again" state.
+const HUB_RESTART_FAILURE_DISPLAY_MS = 8000;
+
+function tfShowHubRestartFailure(badgeEl, reason) {
+  const message = reason
+    ? `Could not update FRAIM Hub: ${reason}. Check your network or npm access, then click to try again.`
+    : 'Could not update FRAIM Hub. Check your network or npm access, then click to try again.';
+  showRerunToast(message);
+  if (!badgeEl) return;
+  badgeEl.disabled = false;
+  badgeEl.textContent = '⬆️ Restart failed';
+  badgeEl.title = message;
+  setTimeout(() => {
+    if (badgeEl.textContent === '⬆️ Restart failed') badgeEl.textContent = '⬆️ Updates available';
+  }, HUB_RESTART_FAILURE_DISPLAY_MS);
+}
+
 const HUB_RESTART_POLL_MS = 1000;
 const HUB_RESTART_POLL_MAX_ATTEMPTS = 45; // ~45s: generous for a fresh materialize-from-npm relaunch