fraim-hub 2.0.311 → 2.0.312

package/dist/src/ai-hub/hosts.js

@@ -2501,15 +2501,13 @@ class CliHostRuntime {
         return isEmployeeDetectionRefreshing();
     }
     startRun(hostId, projectPath, message, handlers, sessionId, launchContext) {
-        // R11: start/startDirect mint sessions rather than resuming one, so they
-        // stay outside the continuation queue entirely.
-        return this.spawn(hostId, (0, configured_agents_1.decorateHostPlanWithConfiguredAgent)(buildStartPlan(hostId, message, sessionId), launchContext?.agent, launchContext?.env), projectPath, handlers);
+        return this.spawnStartAndRegister(hostId, projectPath, handlers, sessionId, (0, configured_agents_1.decorateHostPlanWithConfiguredAgent)(buildStartPlan(hostId, message, sessionId), launchContext?.agent, launchContext?.env));
     }
     continueRun(hostId, projectPath, sessionId, message, handlers, launchContext, deliveryIntent) {
         return this.guardedContinue(hostId, sessionId, { projectPath, message, handlers, launchContext, deliveryIntent });
     }
     startDirectRun(hostId, message, projectPath, handlers, sessionId, launchContext) {
-        return this.spawn(hostId, (0, configured_agents_1.decorateHostPlanWithConfiguredAgent)(buildDirectStartPlan(hostId, message, sessionId), launchContext?.agent, launchContext?.env), projectPath, handlers);
+        return this.spawnStartAndRegister(hostId, projectPath, handlers, sessionId, (0, configured_agents_1.decorateHostPlanWithConfiguredAgent)(buildDirectStartPlan(hostId, message, sessionId), launchContext?.agent, launchContext?.env));
     }
     continueDirectRun(hostId, sessionId, message, projectPath, handlers, launchContext, deliveryIntent) {
         // R10: continueDirectRun is protected by the same per-hostId::sessionId
@@ -2538,7 +2536,7 @@ class CliHostRuntime {
         if (active.escalationTimer != null)
             clearTimeout(active.escalationTimer);
         active.pending.splice(0);
-        this.activeContinueRuns.delete(key);
+        this.clearActiveRun(active);
         if (active.child.pid == null)
             return false;
         try {
@@ -2559,7 +2557,7 @@ class CliHostRuntime {
         const key = `${hostId}::${sessionId}`;
         const active = this.activeContinueRuns.get(key);
         if (!active) {
-            return this.spawnAndRegister(key, hostId, sessionId, entry);
+            return this.spawnAndRegister(hostId, sessionId, entry);
         }
         // R3/R31: an ordinary follow-up queues behind existing work; a course
         // correction (deliveryIntent 'stop') jumps to the front of the queue and
@@ -2579,11 +2577,49 @@ class CliHostRuntime {
         // through `entry.handlers` once it is actually dequeued and spawned.
         return active.child;
     }
-    spawnAndRegister(key, hostId, sessionId, entry) {
+    spawnStartAndRegister(hostId, projectPath, handlers, sessionId, plan) {
+        const deferredSessionIds = [];
+        let runEntry = null;
+        const registerSessionId = (value) => {
+            const discoveredSessionId = typeof value === 'string' ? value.trim() : '';
+            if (!discoveredSessionId)
+                return;
+            if (!runEntry) {
+                deferredSessionIds.push(discoveredSessionId);
+                return;
+            }
+            this.registerActiveRun(hostId, discoveredSessionId, runEntry);
+        };
+        const wrappedHandlers = {
+            ...handlers,
+            onEvent: (event, channel) => {
+                registerSessionId(event.sessionId);
+                handlers.onEvent(event, channel);
+            },
+        };
+        const child = this.spawn(hostId, plan, projectPath, wrappedHandlers);
+        runEntry = { child, pending: [], handlers: wrappedHandlers };
+        if (sessionId)
+            registerSessionId(sessionId);
+        for (const discoveredSessionId of deferredSessionIds) {
+            registerSessionId(discoveredSessionId);
+        }
+        child.once('close', () => {
+            if (!runEntry)
+                return;
+            if (runEntry.escalationTimer != null) {
+                clearTimeout(runEntry.escalationTimer);
+                runEntry.escalationTimer = undefined;
+            }
+            this.dequeueNext(hostId, runEntry);
+        });
+        return child;
+    }
+    spawnAndRegister(hostId, sessionId, entry) {
         const plan = (0, configured_agents_1.decorateHostPlanWithConfiguredAgent)(entry.direct ? buildDirectContinuePlan(hostId, sessionId, entry.message) : buildContinuePlan(hostId, sessionId, entry.message), entry.launchContext?.agent, entry.launchContext?.env);
         const child = this.spawn(hostId, plan, entry.projectPath, entry.handlers);
         const runEntry = { child, pending: [], handlers: entry.handlers };
-        this.activeContinueRuns.set(key, runEntry);
+        this.registerActiveRun(hostId, sessionId, runEntry);
         child.once('close', () => {
             // Issue #1570: a redirect kill that eventually takes (just slower than
             // the escalation window) must not leave its retry timer dangling past
@@ -2592,10 +2628,30 @@ class CliHostRuntime {
                 clearTimeout(runEntry.escalationTimer);
                 runEntry.escalationTimer = undefined;
             }
-            this.dequeueNext(key, hostId, sessionId, runEntry);
+            this.dequeueNext(hostId, runEntry);
         });
         return child;
     }
+    registerActiveRun(hostId, sessionId, runEntry) {
+        const key = `${hostId}::${sessionId}`;
+        const existing = this.activeContinueRuns.get(key);
+        if (existing && existing !== runEntry)
+            return;
+        if (!runEntry.keys)
+            runEntry.keys = new Set();
+        runEntry.keys.add(key);
+        runEntry.sessionId = sessionId;
+        this.activeContinueRuns.set(key, runEntry);
+    }
+    clearActiveRun(runEntry) {
+        const keys = runEntry.keys ? Array.from(runEntry.keys) : [];
+        for (const key of keys) {
+            if (this.activeContinueRuns.get(key) === runEntry) {
+                this.activeContinueRuns.delete(key);
+            }
+        }
+        runEntry.keys?.clear();
+    }
     // Issue #1570 (Defect 1): the redirect kill was previously fire-and-forget
     // — `killTree` was called once, with no way to know whether it actually
     // took, and no ceiling on how long the queued correction could sit behind
@@ -2660,11 +2716,14 @@ class CliHostRuntime {
     // batch uses the LAST entry's projectPath/handlers/launchContext unless a
     // 'stop' entry is present, in which case that correction's context wins —
     // it is the manager's most recent, most urgent instruction.
-    dequeueNext(key, hostId, sessionId, runEntry) {
-        this.activeContinueRuns.delete(key);
+    dequeueNext(hostId, runEntry) {
+        const sessionId = runEntry.sessionId;
+        this.clearActiveRun(runEntry);
         const batch = runEntry.pending.splice(0);
         if (!batch.length)
             return;
+        if (!sessionId)
+            return;
         const combinedMessage = batch.map((e) => e.message).join('\n\n');
         const primary = batch.find((e) => e.deliveryIntent === 'stop') ?? batch[batch.length - 1];
         try {
@@ -2674,7 +2733,7 @@ class CliHostRuntime {
             // R19: a synchronous spawn failure must not leave the queue permanently
             // stuck behind this key — clear it so the next continueRun call spawns
             // fresh instead of queueing behind a dead entry.
-            this.activeContinueRuns.delete(key);
+            this.clearActiveRun(runEntry);
         }
     }
 }

package/dist/src/ai-hub/restart-recovery-policy.js

@@ -67,6 +67,17 @@ class RestartRecoveryPolicy {
         if (['stopped', 'done', 'awaiting_review', 'awaiting_user'].includes(pauseReason)) {
             return { action: 'skip', reason: `pause_${pauseReason}` };
         }
+        // Issue #1634: `activeRunExists` is direct, in-process proof this run is not
+        // orphaned — it must outrank every "does this LOOK orphaned" heuristic below.
+        // A freshly-fired scheduled/webhook run legitimately has no sessionId yet (the
+        // host CLI hasn't reported one) for its entire lifetime if it is short-lived;
+        // checking `missing_session` first force-failed a run that was actively
+        // executing in this same process, the instant its status became observably
+        // 'running' (issue #1634's own fix for that visibility gap is what turned this
+        // from a narrow, mostly-unreachable window into a routinely-hit one).
+        if (options.activeRunExists) {
+            return { action: 'defer', reason: 'active_run_exists' };
+        }
         if (!conversation.sessionId || typeof conversation.sessionId !== 'string' || !conversation.sessionId.trim()) {
             return { action: 'skip', reason: 'missing_session' };
         }
@@ -81,9 +92,6 @@ class RestartRecoveryPolicy {
         if (conversation.reviewHandoff?.reviewRequired) {
             return { action: 'skip', reason: 'awaiting_review' };
         }
-        if (options.activeRunExists) {
-            return { action: 'defer', reason: 'active_run_exists' };
-        }
         // Issue #1159: `activeRunExists` only sees this process's run registry, so it
         // cannot tell that a *different* live Hub owns this run. Two Hubs on one
         // machine is the normal case here: the desktop Hub plus any Hub a job starts

package/dist/src/ai-hub/server.js

@@ -5010,6 +5010,9 @@ class AiHubServer {
                 'from the Hub job catalog, not the per-run tracking UUID returned by get_fraim_job\'s "Job ID" field.',
         };
     }
+    isAdhocPromptJobId(jobId) {
+        return typeof jobId === 'string' && jobId.trim() === 'adhoc-prompt';
+    }
     applySeekMentoringSignalToRun(run, signal) {
         // Issue #732: promote using the stable jobName slug, not the per-call UUID
         // jobId (resolveHubJob would never match a UUID, leaving a freeform run
@@ -7524,9 +7527,15 @@ class AiHubServer {
             // Issue #1477 R1/R2: reject a jobId that doesn't resolve to a known catalog entry
             // (e.g. the per-run tracking UUID from get_fraim_job, mistaken for this field in
             // the reported repro) before the deployment is ever persisted.
-            if (!this.resolveHubJob(resolvedProjectPath, jobId)) {
+            const isAdhocPrompt = this.isAdhocPromptJobId(jobId);
+            if (!isAdhocPrompt && !this.resolveHubJob(resolvedProjectPath, jobId)) {
                 return res.status(400).json(this.invalidScheduleJobIdError(jobId));
             }
+            // Issue #1610 R3: adhoc-prompt has no fixed task — the instructions field is its
+            // sole driver. An adhoc-prompt schedule with no instructions would silently do nothing.
+            if (isAdhocPrompt && !(typeof instructions === 'string' && instructions.trim())) {
+                return res.status(400).json({ error: 'Ad-hoc assignments require a non-empty instructions field.' });
+            }
             const normalizedConversationId = typeof conversationId === 'string' && conversationId.trim()
                 ? conversationId.trim()
                 : undefined;
@@ -7626,9 +7635,19 @@ class AiHubServer {
                 return res.status(404).json({ error: 'Deployment not found.' });
             // Issue #1477 R3: same catalog validation as create, applied only when jobId is
             // actually part of this update.
-            if (jobId !== undefined && !this.resolveHubJob(resolvedProjectPath !== undefined ? resolvedProjectPath : existing.projectPath, jobId)) {
+            if (jobId !== undefined && !this.isAdhocPromptJobId(jobId) && !this.resolveHubJob(resolvedProjectPath !== undefined ? resolvedProjectPath : existing.projectPath, jobId)) {
                 return res.status(400).json(this.invalidScheduleJobIdError(jobId));
             }
+            // Issue #1610 R4: guard the same invariant as POST — an adhoc-prompt deployment
+            // must always have non-empty instructions. Compute the effective post-update values
+            // before writing so we can reject before any state change.
+            const effectiveJobId = jobId !== undefined ? jobId : existing.jobId;
+            const effectiveInstructions = instructions !== undefined
+                ? (typeof instructions === 'string' ? instructions.trim() : undefined)
+                : existing.instructions;
+            if (effectiveJobId === 'adhoc-prompt' && !effectiveInstructions) {
+                return res.status(400).json({ error: 'Ad-hoc assignments require a non-empty instructions field.' });
+            }
             const nextHostId = hostId !== undefined && validHosts.includes(hostId) ? hostId : existing.hostId;
             const nextConfiguredAgentId = configuredAgentId !== undefined
                 ? (typeof configuredAgentId === 'string' && configuredAgentId.trim() ? configuredAgentId.trim() : undefined)
@@ -8382,6 +8401,13 @@ class AiHubServer {
         // can call runRegistry.update without "Run not found" throws.
         this.runRegistry.create(run, {});
         this.deploymentStore.update(deployment.id, (d) => { d.activeRunId = run.id; });
+        // Issue #1634 (Defect B): persist status: 'running' synchronously, before the
+        // host process is launched. Without this, the persisted conversation is only
+        // ever written on the first stream event (onEvent) or at exit (onExit) — a
+        // job fast enough to finish before its first stream event lands can go
+        // straight from one 'completed' state to the next, with 'running' never
+        // observably written for any poll to find.
+        this.persistRunConversation(run, run.conversationId || run.id);
         const handlers = {
             onEvent: (event, channel) => {
                 this.runRegistry.update(run.id, (current) => {
@@ -8404,19 +8430,17 @@ class AiHubServer {
                 if (updated)
                     this.scheduleRunConversationPersistence(updated, updated.conversationId || updated.id);
             },
-            onExit: (exitCode) => {
-                this.runRegistry.update(run.id, (r) => {
-                    r.exitCode = exitCode;
-                    r.status = exitCode === 0 ? 'completed' : 'failed';
-                    r.events.push((0, hosts_1.createHubEvent)('system', `Run exited with code ${exitCode ?? 'unknown'}.${hostErrorSuffix(r)}`));
-                    pushTerminalFailureToThread(r, exitCode);
-                });
-                const updated = this.runRegistry.get(run.id);
-                if (updated)
-                    this.persistRunConversation(updated, updated.conversationId || updated.id);
+            // Issue #1634 (Defect A): route through the shared handleRunExit()/classifyExit()
+            // chokepoint (issue #904), matching every other run-exit call site in this file
+            // (server.ts:4678, 4992, 7396, 7632, 7726, 9315 as of this change). The previous
+            // bespoke handler below set status/exitCode directly and never called
+            // classifyExit(), so a deployment-triggered exit's pauseReason was never computed
+            // — the recurringPark latch set mid-run (via the shared onEvent -> recordHostEvent
+            // path above) was silently discarded, and a compaction/background-task exit was
+            // force-terminated instead of auto-continuing like a manager-started run.
+            onExit: (exitCode) => this.handleRunExit(run.id, exitCode, () => {
                 this.deploymentStore.update(deployment.id, (d) => { d.activeRunId = undefined; });
-                this.runRegistry.dispose(run.id);
-            },
+            }),
         };
         const childLaunchContext = this.withHubRunIdEnv(launchContext, run.id);
         const child = existingHostSession

package/dist/src/cli/setup/ide-invocation-surfaces.js

@@ -72,7 +72,7 @@ ${buildDeferredToolBootstrapSection(profile)}1. **Confirm FRAIM activation**:
    If local FRAIM job stubs are present in the workspace, inspect those first and match the request locally. Also inspect \`fraim/personalized-employee/jobs/\` for local overrides or repo-specific jobs. If local files are missing or you cannot inspect workspace files, call \`list_fraim_jobs()\` to view the full catalog, including any proxy-discoverable personalized jobs.
 
 3. **Find the match**:
-   If the user names an exact FRAIM job, call \`get_fraim_job({ job: "<job-name>" })\` directly. Otherwise, match the user's request to a FRAIM job from the local stub catalog, \`fraim/personalized-employee/jobs/\`, or the full \`list_fraim_jobs()\` response. If no exact or high-confidence job match exists, say that no FRAIM job matches and continue with normal tools or ask one concise clarification. Do not pick the nearest catalog job.
+   If the user names an exact FRAIM job, call \`get_fraim_job({ job: "<job-name>" })\` directly. Otherwise, match the user's request to a FRAIM job from the local stub catalog, \`fraim/personalized-employee/jobs/\`, or the full \`list_fraim_jobs()\` response. If no exact or high-confidence job match exists, ask once: "No catalog job matches. Would you like to run this as an ad-hoc task?" On confirmation, call \`get_fraim_job({ job: "adhoc-prompt" })\` and execute it with the user's instructions as the task input — do not pick the nearest catalog job. Do not ask again if the user already provided instructions.
 
 4. **Load the full content**:
    - For jobs, call \`get_fraim_job({ job: "<matched-job-name>" })\`.

package/dist/src/cli/setup/user-level-sync.js

@@ -125,6 +125,10 @@ function ensureUserLevelDependencies(userFraimDir) {
     if (missing.length === 0) {
         return;
     }
+    if (process.env.FRAIM_SKIP_USER_LEVEL_DEP_INSTALL === '1') {
+        console.log(chalk_1.default.yellow(`TEST_MODE: skipping user-level runtime dependency install (${missing.join(', ')}).`));
+        return;
+    }
     console.log(chalk_1.default.blue(`📦 Installing user-level runtime dependencies (${missing.join(', ')})...`));
     try {
         (0, child_process_1.execSync)('npm install --no-audit --no-fund --no-save --no-package-lock --omit=dev', {

package/dist/src/config/persona-capability-bundles.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PERSONA_CAPABILITY_BUNDLES = exports.FREE_JOBS = exports.GENERIC_WORKER_PERSONA_KEY = void 0;
+exports.UNOWNED_EXEMPT_JOBS = exports.PERSONA_CAPABILITY_BUNDLES = exports.FREE_JOBS = exports.GENERIC_WORKER_PERSONA_KEY = void 0;
 exports.isFreeJob = isFreeJob;
 exports.getPersonaCapabilityBundle = getPersonaCapabilityBundle;
 exports.getProtectedPersonaForJob = getProtectedPersonaForJob;
@@ -315,6 +315,17 @@ const GENERIC_WORKER_OWNED_JOBS = new Set([
     'organization-onboarding',
     'organizational-learning-synthesis',
 ]);
+// Jobs intentionally left without a named persona owner. They resolve to null
+// from getProtectedPersonaForJob (runs ungated; Hub attributes them to the
+// DEFAULT_UNASSIGNED_PERSONA_KEY/MANdy — same behavior as today's adhoc runs).
+// validate-job-ownership exempts these from the "every job must have an owner"
+// assertion so the validator still catches accidentally unowned jobs.
+//
+// Issue #1610: adhoc-prompt is a manager-directed fallback job, not tied to any
+// specialist hire, matching the existing no-employee attribution of adhoc runs.
+exports.UNOWNED_EXEMPT_JOBS = new Set([
+    'adhoc-prompt',
+]);
 function getPersonaCapabilityBundle(personaKey) {
     return exports.PERSONA_CAPABILITY_BUNDLES[personaKey];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-hub",
-  "version": "2.0.311",
+  "version": "2.0.312",
   "description": "FRAIM Hub local companion package.",
   "author": "Sid Mathur <sid.mathur@gmail.com>",
   "homepage": "https://github.com/mathursrus/FRAIM#readme",
@@ -211,7 +211,7 @@
     "electron-updater": "^6.8.9",
     "express": "^5.2.1",
     "extract-zip": "^2.0.1",
-    "fraim": "2.0.311",
+    "fraim": "2.0.312",
     "mongodb": "^7.0.0",
     "node-cron": "4.2.1",
     "node-edge-tts": "^1.2.10",

package/public/ai-hub/index.html

@@ -1145,7 +1145,7 @@
           <p class="dep-trig-note">Runs when an external system POSTs to the inbound URL, generated after you add the assignment.</p>
         </div>
         <div class="hm-field">
-          <label for="dep-instructions">Instructions <span class="dep-optional">(optional)</span></label>
+          <label for="dep-instructions">Instructions <span class="dep-optional" id="dep-inst-optional-label">(optional)</span></label>
           <textarea id="dep-instructions" rows="2" placeholder="Optional message sent to the agent at the start of each run"></textarea>
         </div>
         <div class="dep-modal-actions">

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));
     });
   }
 
@@ -7684,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';
@@ -7711,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) {
@@ -7745,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();
@@ -8808,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.
@@ -12870,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');
@@ -13040,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) {
@@ -13049,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 ?? '';
@@ -13103,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';

package/public/ai-hub/styles.css

@@ -6000,6 +6000,9 @@ img.eh-av { object-fit: cover; background: var(--surface); }
 }
 .dep-row:hover { background: var(--soft); }
 .dep-row-title { font-size: 13px; font-weight: 400; font-style: italic; color: var(--text); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+/* Issue #1610 R10: ad-hoc job label and instructions subtitle in assignment rows. */
+.dep-row-job-label { display: block; font-size: 11px; font-weight: 600; color: var(--accent); margin-top: 1px; }
+.dep-row-sub { display: block; font-size: 11px; color: var(--muted); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; margin-top: 1px; }
 .assign-row-meta { display: flex; gap: 8px; align-items: center; margin-top: 3px; font-size: 11px; color: var(--muted); }
 .assign-badge { font-size: 10px; font-weight: 700; letter-spacing: .02em; padding: 1px 7px; border-radius: 999px; }
 .assign-badge--scheduled { background: rgba(0,113,227,.10); color: var(--accent); }