fraim-framework 2.0.145 → 2.0.147

package/public/ai-hub/script.js

@@ -20,6 +20,9 @@ const state = {
   pollHandle: null,
   selectedJob: null,   // chosen in modal step 1
   selectedEmployeeId: null,
+  selectedPersonaKey: null,  // R4: null = "All employees"
+  modalPersonaFilter: null,  // R3+: filter inside new-job modal; null = "All jobs"
+  storedApiKey: null,        // R2: loaded from preferences, sent on bootstrap
 };
 
 const els = {};
@@ -32,13 +35,18 @@ function gatherElements() {
   const ids = [
     'project-button', 'project-name',
     'new-conv-btn', 'conv-list',
-    'empty', 'active-conv', 'active-title', 'active-job',
-    'progress', 'stage', 'latest', 'artifact-slot', 'messages',
-    'coach-text', 'send', 'micro-manage', 'micro-log',
-    'status-line',
+    // Issue #385: team roster
+    'team-roster',
+    'empty', 'active-conv', 'active-title', 'active-job', 'active-identity', 'run-state-pill', 'summary-strip',
+    'progress', 'stage', 'latest', 'artifact-slot', 'messages',
+    'coach-text', 'send', 'micro-manage', 'micro-log',
+    'status-line', 'coach-note',
     'modal', 'step1', 'step2',
     'cancel1', 'next1', 'back2', 'start',
     'job-search', 'job-catalog', 'job-pick-status',
+    // Issue #385: hire-required notice, persona job filter
+    'hire-notice', 'hire-notice-text', 'hire-notice-link', 'hire-notice-back',
+    'job-persona-filter',
     'picked-name', 'picked-desc', 'instructions',
     'employee-select', 'agent-install-panel', 'active-employee-select',
     'freeform-btn',
@@ -57,7 +65,8 @@ async function requestJson(url, options) {
   let payload = null;
   try { payload = await response.json(); } catch { /* may be empty */ }
   if (!response.ok) {
-    const message = (payload && payload.error) || `Request failed (${response.status}).`;
+    const errVal = payload && payload.error;
+    const message = (errVal && typeof errVal === 'object' ? errVal.message : errVal) || `Request failed (${response.status}).`;
     throw new Error(message);
   }
   return payload;
@@ -65,10 +74,16 @@ async function requestJson(url, options) {
 
 async function loadBootstrap(projectPath) {
   const query = projectPath ? `?projectPath=${encodeURIComponent(projectPath)}` : '';
-  const bootstrap = await requestJson(`/api/ai-hub/bootstrap${query}`);
+  const fetchOptions = {};
+  if (state.storedApiKey) fetchOptions.headers = { 'x-fraim-api-key': state.storedApiKey };
+  const bootstrap = await requestJson(`/api/ai-hub/bootstrap${query}`, fetchOptions);
   state.bootstrap = bootstrap;
   state.projectPath = bootstrap.project.path;
   state.selectedEmployeeId = state.selectedEmployeeId || bootstrap.preferences.employeeId;
+  // Restore persona selection persisted on the server side.
+  if (bootstrap.preferences && bootstrap.preferences.personaKey !== undefined) {
+    state.selectedPersonaKey = bootstrap.preferences.personaKey;
+  }
   // Render header project name + status line.
   els['project-name'].textContent = friendlyProjectName(bootstrap.project.path);
   els['status-line'].textContent = bootstrap.project.message || '';
@@ -165,6 +180,17 @@ function loadConversationsFromStorage() {
   } catch {
     state.activeId = null;
   }
+  // Retroactively fix titles that were saved as the generic "New job" fallback
+  // by re-deriving from the first manager message.
+  for (const convList of Object.values(state.conversations)) {
+    for (const conv of convList) {
+      if (conv.title !== 'New job') continue;
+      const firstMsg = (conv.messages || []).find((m) => m.role === 'manager');
+      if (!firstMsg) continue;
+      const rederived = deriveTitle(conv.jobTitle || '', firstMsg.text || '');
+      if (rederived !== 'New job') conv.title = rederived;
+    }
+  }
 }
 
 function persistConversations() {
@@ -221,28 +247,289 @@ function newConversationId() {
 // ---------------------------------------------------------------------------
 
 function renderRail() {
+  renderTeamRoster();
   els['conv-list'].innerHTML = '';
-  const list = projectConversations();
+  // R4: filter by selected persona when one is active.
+  const list = projectConversations().filter((conv) =>
+    !state.selectedPersonaKey || conv.personaKey === state.selectedPersonaKey
+  );
   for (const conv of list) {
     const btn = document.createElement('button');
     btn.type = 'button';
     btn.className = 'conv-item' + (state.activeId === conv.id ? ' active' : '');
     btn.dataset.conv = conv.id;
-    btn.innerHTML = `<span class="conv-title"></span><span class="conv-status"></span>`;
-    btn.querySelector('.conv-title').textContent = conv.title;
-    const status = btn.querySelector('.conv-status');
-    status.textContent = statusLabel(conv.status);
-    if (conv.status === 'running') status.classList.add('running');
-    if (conv.status === 'failed') status.classList.add('failed');
+    // Avatar chip — 34px visual anchor on the left for every item.
+    const personas = state.bootstrap?.personas || [];
+    let persona = null;
+    const chip = document.createElement('span');
+    if (conv.personaKey) {
+      persona = personas.find((p) => p.key === conv.personaKey) || null;
+      chip.className = 'conv-persona-chip';
+      chip.title = persona ? persona.displayName : conv.personaKey;
+      if (persona && persona.avatarUrl) {
+        const img = document.createElement('img');
+        img.src = persona.avatarUrl;
+        img.alt = persona.displayName;
+        chip.appendChild(img);
+      } else {
+        const label = persona ? persona.displayName : conv.personaKey;
+        chip.textContent = label.slice(0, 2).toUpperCase();
+      }
+    } else {
+      chip.className = 'conv-persona-chip conv-persona-chip--free';
+      chip.title = 'Free job';
+      chip.innerHTML = '<svg viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg" width="16" height="16"><circle cx="10" cy="7" r="3.5" stroke="currentColor" stroke-width="1.5"/><path d="M3 17c0-3.314 3.134-6 7-6s7 2.686 7 6" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/></svg>';
+    }
+    btn.appendChild(chip);
+    // Text body: persona name label (if persona) stacked above job title.
+    const bodyDiv = document.createElement('span');
+    bodyDiv.className = 'conv-body';
+    if (persona) {
+      const nameSpan = document.createElement('span');
+      nameSpan.className = 'conv-persona-name';
+      nameSpan.textContent = persona.displayName;
+      bodyDiv.appendChild(nameSpan);
+    }
+    const titleSpan = document.createElement('span');
+    titleSpan.className = 'conv-title';
+    titleSpan.textContent = conv.title || '';
+    bodyDiv.appendChild(titleSpan);
+    btn.appendChild(bodyDiv);
+    const statusSpan = document.createElement('span');
+    statusSpan.className = 'conv-status';
+    statusSpan.textContent = statusLabel(conv.status);
+    if (conv.status === 'running') statusSpan.classList.add('running');
+    if (conv.status === 'failed') statusSpan.classList.add('failed');
+    btn.appendChild(statusSpan);
     btn.addEventListener('click', () => switchToConversation(conv.id));
     els['conv-list'].appendChild(btn);
   }
 }
 
-function statusLabel(s) {
-  if (s === 'running') return 'Running';
-  if (s === 'failed') return 'Needs you';
-  return 'Done';
+function statusLabel(s) {
+  if (s === 'running') return 'Running';
+  if (s === 'failed') return 'Needs you';
+  return 'Done';
+}
+
+function personaMap() {
+  const map = new Map();
+  for (const persona of state.bootstrap?.personas || []) {
+    map.set(persona.key, persona);
+  }
+  return map;
+}
+
+function getConversationPersona(conv) {
+  if (!conv || !conv.personaKey) return null;
+  return personaMap().get(conv.personaKey) || null;
+}
+
+function getEmployeeStatus(employeeId) {
+  return (state.bootstrap?.employees || []).find((employee) => employee.id === employeeId) || null;
+}
+
+function getEmployeeTitle(conv) {
+  const persona = getConversationPersona(conv);
+  if (persona) return persona.role;
+  const employee = getEmployeeStatus(conv?.employeeId);
+  return employee ? employee.label : 'AI Employee';
+}
+
+function roleLabel(role, conv) {
+  if (role === 'manager') return 'Manager';
+  if (role === 'employee') {
+    const persona = getConversationPersona(conv);
+    return persona ? persona.displayName : 'Employee';
+  }
+  return 'System';
+}
+
+function initialBadge(text) {
+  const cleaned = String(text || '').replace(/[^A-Za-z]/g, '').toUpperCase();
+  return (cleaned.slice(0, 2) || 'FH');
+}
+
+// ---------------------------------------------------------------------------
+// Issue #385 — Persona UI (R3 + R4)
+// ---------------------------------------------------------------------------
+
+// Prefix a conversation title with its persona display name when a persona
+// is assigned, so the rail and header always show who is responsible.
+function conversationTitle(conv) {
+  if (!conv) return '';
+  if (!conv.personaKey) return conv.title || '';
+  const personas = state.bootstrap?.personas || [];
+  const persona = personas.find((p) => p.key === conv.personaKey);
+  const prefix = persona ? persona.displayName : conv.personaKey;
+  return `${prefix}: ${conv.title || ''}`;
+}
+
+// R4.2 — team roster: one avatar chip per hired persona above the conv list.
+// Only rendered when at least one persona is hired (subscription active).
+function renderTeamRoster() {
+  const roster = els['team-roster'];
+  if (!roster) return;
+  const personas = (state.bootstrap?.personas || []).filter((p) => p.status === 'hired');
+  if (personas.length === 0) {
+    roster.hidden = true;
+    // Reset persona selection when there's no active subscription.
+    if (state.selectedPersonaKey) state.selectedPersonaKey = null;
+    return;
+  }
+  roster.hidden = false;
+  roster.innerHTML = '';
+  const allChip = document.createElement('button');
+  allChip.type = 'button';
+  allChip.className = 'roster-chip roster-chip--all' + (!state.selectedPersonaKey ? ' active' : '');
+  allChip.title = 'All employees';
+  allChip.setAttribute('aria-label', 'All employees');
+  allChip.innerHTML = `
+    <span class="roster-avatar">All</span>
+    <span class="roster-copy">
+      <strong>All employees</strong>
+      <small>Show every hired employee</small>
+    </span>
+  `;
+  allChip.addEventListener('click', () => setSelectedPersona(null));
+  roster.appendChild(allChip);
+  for (const persona of personas) {
+    const chip = document.createElement('button');
+    chip.type = 'button';
+    chip.className = 'roster-chip' + (state.selectedPersonaKey === persona.key ? ' active' : '');
+    chip.title = persona.displayName;
+    chip.setAttribute('aria-label', persona.displayName);
+    const avatar = document.createElement('span');
+    avatar.className = 'roster-avatar';
+    if (persona.avatarUrl) {
+      const img = document.createElement('img');
+      img.src = persona.avatarUrl;
+      img.alt = persona.displayName;
+      avatar.appendChild(img);
+    } else {
+      avatar.textContent = persona.displayName.slice(0, 2).toUpperCase();
+    }
+    const copy = document.createElement('span');
+    copy.className = 'roster-copy';
+    const name = document.createElement('strong');
+    name.textContent = persona.displayName;
+    const role = document.createElement('small');
+    role.textContent = persona.role || 'AI Employee';
+    copy.appendChild(name);
+    copy.appendChild(role);
+    chip.appendChild(avatar);
+    chip.appendChild(copy);
+    chip.addEventListener('click', () => setSelectedPersona(persona.key));
+    roster.appendChild(chip);
+  }
+}
+
+// R4.3 — employee selector: compact dropdown above conv list (shown when ≥1 hired persona).
+function buildAvatarChip(persona, size) {
+  const chip = document.createElement('span');
+  chip.className = 'emp-avatar-sm';
+  chip.style.width = size + 'px';
+  chip.style.height = size + 'px';
+  chip.style.fontSize = Math.max(8, Math.floor(size * 0.42)) + 'px';
+  if (persona && persona.avatarUrl) {
+    const img = document.createElement('img');
+    img.src = persona.avatarUrl;
+    img.alt = persona.displayName;
+    chip.appendChild(img);
+  } else if (persona) {
+    chip.textContent = persona.displayName.slice(0, 2).toUpperCase();
+  }
+  return chip;
+}
+
+function setSelectedPersona(key) {
+  state.selectedPersonaKey = key || null;
+  renderRail();
+  savePersonaPreference(key || null);
+}
+
+async function savePersonaPreference(key) {
+  try {
+    await requestJson('/api/ai-hub/preferences', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ personaKey: key }),
+    });
+  } catch { /* best-effort */ }
+}
+
+// R3.2/R3.3 — show hire-required notice when a locked job is clicked.
+function showHireNotice(job) {
+  const personas = state.bootstrap?.personas || [];
+  const persona = personas.find((p) => p.key === job.requiredPersonaKey);
+  els['job-catalog'].hidden = true;
+  els['hire-notice'].hidden = false;
+  if (els['hire-notice-text']) {
+    els['hire-notice-text'].textContent = persona
+      ? `"${job.title}" requires ${persona.displayName} (${persona.pricingLabel}). Hire them to unlock this job.`
+      : `"${job.title}" requires a persona that is not yet hired. Go to Pricing to hire them.`;
+  }
+  if (els['hire-notice-link'] && persona && persona.hireUrl) {
+    // R3.3: append returnTo so the pricing page can redirect back after hire.
+    const returnTo = encodeURIComponent(window.location.href);
+    els['hire-notice-link'].href = `${persona.hireUrl}&returnTo=${returnTo}`;
+  }
+  state.selectedJob = null;
+  els['next1'].disabled = true;
+  els['job-pick-status'].textContent = 'Choose a job to continue';
+}
+
+function hideHireNotice() {
+  if (els['hire-notice']) els['hire-notice'].hidden = true;
+  if (els['job-catalog']) els['job-catalog'].hidden = false;
+}
+
+// R3+ — persona filter bar inside the New Job modal.
+// Shows "All jobs" + one chip per hired persona + "Free only".
+// Only rendered when at least one persona is hired (subscription active).
+function renderModalPersonaFilter() {
+  const container = els['job-persona-filter'];
+  if (!container) return;
+  const personas = (state.bootstrap?.personas || []).filter((p) => p.status === 'hired');
+  if (personas.length === 0) {
+    container.hidden = true;
+    state.modalPersonaFilter = null;
+    return;
+  }
+  container.hidden = false;
+  container.innerHTML = '';
+
+  function makeFilterChip(key, label, avatarUrl) {
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    btn.className = 'jf-chip' + (state.modalPersonaFilter === key ? ' active' : '');
+    if (avatarUrl) {
+      const img = document.createElement('img');
+      img.src = avatarUrl;
+      img.alt = label;
+      btn.appendChild(img);
+    }
+    const span = document.createElement('span');
+    span.textContent = label;
+    btn.appendChild(span);
+    btn.addEventListener('click', () => {
+      state.modalPersonaFilter = key;
+      // Reset job selection when filter changes.
+      state.selectedJob = null;
+      els['next1'].disabled = true;
+      els['job-pick-status'].textContent = 'Choose a job to continue';
+      hideHireNotice();
+      renderModalPersonaFilter();
+      renderJobCatalog(els['job-search'].value);
+    });
+    return btn;
+  }
+
+  container.appendChild(makeFilterChip(null, 'All jobs'));
+  for (const persona of personas) {
+    container.appendChild(makeFilterChip(persona.key, persona.displayName, persona.avatarUrl));
+  }
+  container.appendChild(makeFilterChip('__free__', 'Free only'));
 }
 
 // ---------------------------------------------------------------------------
@@ -253,30 +540,39 @@ function statusLabel(s) {
 // event rows are already in the DOM. Polling fires every second; without
 // this, every tick wiped the messages list and re-played the slidein
 // animation (= the screen flash the user reported as 'distracting').
-let renderedConvId = null;
-let renderedMessageCount = 0;
-let renderedEventCount = 0;
-let renderedArtifactKey = null;
-
-function renderActive() {
-  const conv = activeConversation();
-  if (!conv) {
-    els['empty'].hidden = false;
-    els['active-conv'].hidden = true;
-    renderedConvId = null;
-    renderedMessageCount = 0;
-    renderedEventCount = 0;
-    renderedArtifactKey = null;
-    return;
-  }
-  els['empty'].hidden = true;
-  els['active-conv'].hidden = false;
-  els['active-title'].textContent = conv.title;
-  els['active-job'].textContent = `Job: ${conv.jobTitle}`;
-
-  // Progress section. Plain text updates are cheap and don't animate.
-  const stage = derivedStage(conv);
-  els['stage'].textContent = stage.text;
+let renderedConvId = null;
+let renderedMessageCount = 0;
+let renderedEventCount = 0;
+let renderedArtifactKey = null;
+let renderedStatus = null;
+
+function renderActive() {
+  const conv = activeConversation();
+  if (!conv) {
+    els['empty'].hidden = false;
+    els['active-conv'].hidden = true;
+    renderedConvId = null;
+    renderedMessageCount = 0;
+    renderedEventCount = 0;
+    renderedArtifactKey = null;
+    renderedStatus = null;
+    return;
+  }
+  els['empty'].hidden = true;
+  els['active-conv'].hidden = false;
+  els['active-title'].textContent = conversationTitle(conv);
+  els['active-job'].textContent = `${conv.jobTitle} · ${friendlyProjectName(conv.projectPath || state.projectPath)} · ${getEmployeeStatus(conv.employeeId)?.label || conv.employeeId}`;
+  renderConversationIdentity(conv);
+  els['active-job'].textContent = `${conv.jobTitle} · ${friendlyProjectName(conv.projectPath || state.projectPath)}`;
+  renderRunStatePill(conv);
+  els['summary-strip'].textContent = buildConversationSummary(conv);
+  els['coach-note'].textContent = conv.status === 'running'
+    ? 'The employee is still working. Add coaching here to tighten the next step without losing context.'
+    : 'The employee is waiting on you. Send the next instruction to continue this run.';
+
+  // Progress section. Plain text updates are cheap and don't animate.
+  const stage = derivedStage(conv);
+  els['stage'].textContent = stage.text;
   els['progress'].classList.remove('done', 'attention', 'failed');
   if (stage.kind) els['progress'].classList.add(stage.kind);
   els['latest'].textContent = derivedLatest(conv);
@@ -284,15 +580,16 @@ function renderActive() {
   // If we switched conversations (or this is the first render), wipe and
   // start fresh. Otherwise we're going to do an incremental update below.
   const switchedConv = renderedConvId !== conv.id;
-  if (switchedConv) {
+  if (switchedConv) {
     els['artifact-slot'].innerHTML = '';
     els['messages'].innerHTML = '';
     els['micro-log'].textContent = '';
     renderedConvId = conv.id;
     renderedMessageCount = 0;
-    renderedEventCount = 0;
-    renderedArtifactKey = null;
-  }
+    renderedEventCount = 0;
+    renderedArtifactKey = null;
+  }
+  const statusChanged = renderedStatus !== conv.status;
 
   // Artifact callout — only re-render when the latest artifact actually
   // changed. Avoids the 'pulse' animation re-firing on every poll tick.
@@ -320,19 +617,24 @@ 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 messages = conv.messages || [];
-  if (messages.length < renderedMessageCount) {
-    els['messages'].innerHTML = '';
-    renderedMessageCount = 0;
-  }
-  for (let i = renderedMessageCount; i < messages.length; i += 1) {
-    appendMessageDom(messages[i].role, messages[i].text);
-  }
-  renderedMessageCount = messages.length;
-  // Keep the scroll pinned to the latest unless the user scrolled up.
-  const m = els['messages'];
-  if (m.scrollHeight - m.scrollTop - m.clientHeight < 80) {
-    m.scrollTop = m.scrollHeight;
-  }
+  if (messages.length < renderedMessageCount) {
+    els['messages'].innerHTML = '';
+    renderedMessageCount = 0;
+  }
+  for (let i = renderedMessageCount; i < messages.length; i += 1) {
+    appendMessageDom(messages[i].role, messages[i].text, conv);
+  }
+  const appendedMessages = messages.length - renderedMessageCount;
+  renderedMessageCount = messages.length;
+  // Running threads stay pinned near the newest work. Once the employee
+  // is done, snap to the review point instead of leaving the manager at
+  // a stale scroll offset.
+  const m = els['messages'];
+  if (conv.status === 'running' && m.scrollHeight - m.scrollTop - m.clientHeight < 80) {
+    m.scrollTop = m.scrollHeight;
+  } else if (switchedConv || statusChanged || appendedMessages > 0) {
+    scrollThreadForReview(conv);
+  }
 
   // Micro-manage — only append new events. textContent assignment on the
   // <pre> wipes the entire log every tick which is wasteful.
@@ -358,11 +660,58 @@ function renderActive() {
   // foldRunIntoConversation); for runs that have not yet polled we
   // simply hide the surfaces.
   renderTracker(conv);
-  renderTotals(conv);
-  syncTemplatePickerVisibility();
-  // Browser-tab title mirrors the active conversation (R3).
-  document.title = conv.title ? conv.title : 'AI Hub';
-}
+  renderTotals(conv);
+  syncTemplatePickerVisibility();
+  // Browser-tab title mirrors the active conversation (R3).
+  document.title = conv.title ? conv.title : 'AI Hub';
+  renderedStatus = conv.status;
+}
+
+function renderConversationIdentity(conv) {
+  const host = els['active-identity'];
+  if (!host) return;
+  const persona = getConversationPersona(conv);
+  const employee = getEmployeeStatus(conv.employeeId);
+  host.innerHTML = '';
+
+  const avatar = document.createElement(persona && persona.avatarUrl ? 'img' : 'span');
+  avatar.className = 'identity-avatar';
+  if (persona && persona.avatarUrl) {
+    avatar.src = persona.avatarUrl;
+    avatar.alt = persona.displayName;
+  } else {
+    avatar.textContent = initialBadge(employee?.label || 'Hub');
+  }
+
+  const text = document.createElement('span');
+  text.className = 'identity-copy';
+
+  const name = document.createElement('strong');
+  name.textContent = persona ? persona.displayName : (employee ? employee.label : 'AI Employee');
+
+  const title = document.createElement('small');
+  title.textContent = getEmployeeTitle(conv);
+
+  text.appendChild(name);
+  text.appendChild(title);
+  host.appendChild(avatar);
+  host.appendChild(text);
+}
+
+function renderRunStatePill(conv) {
+  const pill = els['run-state-pill'];
+  if (!pill) return;
+  pill.textContent = statusLabel(conv.status).toUpperCase();
+  pill.className = `run-state-pill ${conv.status}`;
+}
+
+function buildConversationSummary(conv) {
+  const employeeReply = latestEmployeeSurfaceText(conv);
+  if (employeeReply) return employeeReply;
+  if (conv.status === 'running') return 'The employee is working through your request.';
+  if (conv.status === 'failed') return 'This run needs your attention before it can continue.';
+  return 'The latest work is ready for review.';
+}
 
 // Render the inline employee selector shown in the coach section of an
 // active conversation. Allows switching agents without reopening the modal.
@@ -698,27 +1047,145 @@ function derivedStage(conv) {
   return { text: 'Done — please review', kind: 'done' };
 }
 
-function derivedLatest(conv) {
-  const messages = conv.messages || [];
-  for (let i = messages.length - 1; i >= 0; i -= 1) {
-    if (messages[i].role === 'employee') return messages[i].text;
-  }
-  if (conv.status === 'running') return 'Loading the work and getting started.';
-  return '';
-}
-
-function appendMessageDom(role, text) {
-  const div = document.createElement('div');
-  div.className = 'message ' + role;
-  const who = document.createElement('span');
-  who.className = 'who';
-  who.textContent = role === 'manager' ? 'You' : (role === 'employee' ? 'Employee' : 'System');
-  div.appendChild(who);
-  div.appendChild(document.createTextNode(text));
-  els['messages'].appendChild(div);
-}
-
-function syncSendButton() {
+function derivedLatest(conv) {
+  if (conv.status !== 'running') return '';
+  const employeeReply = latestEmployeeSurfaceText(conv);
+  if (employeeReply) return employeeReply;
+  if (conv.status === 'running') return 'Working on it…';
+  return '';
+}
+
+function humanizeSlug(slug) {
+  return String(slug || '')
+    .split('-')
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+function stripStubReference(text) {
+  return String(text || '')
+    .replace(/\n?\[Job stub:[^\]]+\]/gi, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function surfaceText(role, text, conv) {
+  const raw = stripStubReference(text);
+  if (!raw) return '';
+
+  if (role === 'manager') {
+    const invocationOnly = raw.match(/^(?:[$/]fraim)\s+([a-z0-9-]+)\s*$/i);
+    if (invocationOnly) return `Run ${humanizeSlug(invocationOnly[1])}.`;
+    const slugPattern = '[a-z0-9]+(?:-[a-z0-9]+)+';
+    const invocationWithSlug = new RegExp(`^(?:[$/]fraim)\\s+(${slugPattern})\\s*`, 'i');
+    return raw
+      .replace(invocationWithSlug, '')
+      .replace(/^(?:[$/]fraim)\s*/i, '')
+      .trim();
+  }
+
+  if (role === 'employee') {
+    const startedMatch = raw.match(/^Started\s+\w+:\s*(.*)$/i);
+    if (startedMatch) {
+      const cleaned = surfaceText('manager', startedMatch[1], conv);
+      if (conv.status === 'completed') return 'Done — please review.';
+      return cleaned ? `Working on: ${cleaned}` : 'Working on it…';
+    }
+  }
+
+  return raw;
+}
+
+function latestEmployeeSurfaceText(conv) {
+  const messages = conv.messages || [];
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    if (messages[i].role !== 'employee') continue;
+    const cleaned = surfaceText('employee', messages[i].text, conv);
+    if (cleaned) return cleaned;
+  }
+  return '';
+}
+
+function appendMessageDom(role, text, conv) {
+  const article = document.createElement('article');
+  article.className = 'message ' + role;
+
+  const meta = document.createElement('div');
+  meta.className = 'message-meta';
+
+  const avatar = document.createElement('span');
+  avatar.className = `message-avatar ${role}`;
+
+  if (role === 'employee') {
+    const persona = getConversationPersona(conv);
+    if (persona && persona.avatarUrl) {
+      const img = document.createElement('img');
+      img.src = persona.avatarUrl;
+      img.alt = persona.displayName;
+      avatar.appendChild(img);
+    } else {
+      avatar.textContent = initialBadge(roleLabel(role, conv));
+    }
+  } else if (role === 'manager') {
+    avatar.textContent = 'M';
+  } else {
+    avatar.textContent = '•';
+  }
+
+  const who = document.createElement('span');
+  who.className = 'who';
+  who.textContent = roleLabel(role, conv);
+
+  const lane = document.createElement('span');
+  lane.className = 'lane-label';
+  lane.textContent = role === 'manager'
+    ? 'Manager direction'
+    : role === 'employee'
+      ? 'Employee response'
+      : 'System update';
+
+  meta.appendChild(avatar);
+  meta.appendChild(who);
+  meta.appendChild(lane);
+  article.appendChild(meta);
+
+  const bubble = document.createElement('div');
+  bubble.className = 'bubble';
+  bubble.textContent = surfaceText(role, text, conv) || (
+    role === 'employee'
+      ? (conv.status === 'completed' ? 'Done — please review.' : 'Working on it…')
+      : text
+  );
+  if (role === 'manager') {
+    const raw = document.createElement('span');
+    raw.className = 'transport-raw';
+    raw.textContent = text;
+    article.appendChild(raw);
+  }
+  article.appendChild(bubble);
+  els['messages'].appendChild(article);
+}
+
+function scrollThreadForReview(conv) {
+  const host = els['messages'];
+  if (!host) return;
+  const nodes = [...host.querySelectorAll('.message')];
+  if (nodes.length === 0) return;
+
+  if (conv.status === 'running') {
+    host.scrollTop = host.scrollHeight;
+    return;
+  }
+
+  const target = [...nodes].reverse().find((node) =>
+    node.classList.contains('employee') || node.classList.contains('system')
+  ) || nodes[nodes.length - 1];
+
+  target.scrollIntoView({ block: 'center', behavior: 'smooth' });
+}
+
+function syncSendButton() {
   const conv = activeConversation();
   const hasText = els['coach-text'].value.trim().length > 0;
   // Send is enabled as soon as the host session exists. We deliberately
@@ -806,6 +1273,8 @@ function openModal(opts) {
   const filter = concept ? CONCEPT_PICKER_FILTERS[concept] : null;
   state.selectedJob = null;
   state.activeFilter = filter || null;
+  // Inherit the rail persona selection as the starting filter for the modal.
+  state.modalPersonaFilter = state.selectedPersonaKey || null;
   els['next1'].disabled = true;
   els['job-pick-status'].textContent = 'Choose a job to continue';
   els['job-search'].value = '';
@@ -813,6 +1282,9 @@ function openModal(opts) {
   els['start'].disabled = true;
   els['step1'].hidden = false;
   els['step2'].hidden = true;
+  // R3: always start with the catalog visible, hire-notice hidden.
+  if (els['hire-notice']) els['hire-notice'].hidden = true;
+  if (els['job-catalog']) els['job-catalog'].hidden = false;
   // Update the modal heading + subhead to match the filter context.
   const h = document.querySelector('#step1 .modal-header h2');
   const p = document.querySelector('#step1 .modal-header p');
@@ -826,6 +1298,7 @@ function openModal(opts) {
     p.textContent = 'Pick one job. You can always start a new job for different work.';
   }
   renderEmployeeSelect();
+  renderModalPersonaFilter();
   renderJobCatalog();
   els['modal'].hidden = false;
   els['modal'].classList.add('open');
@@ -850,8 +1323,10 @@ function renderJobCatalog(searchTerm = '') {
   const managers = state.bootstrap?.managerTemplates || [];
 
   // Decide which sources contribute given the active filter.
+  // Manager templates are hidden whenever a persona/free chip is active —
+  // they're meta-management jobs, not persona-specific work.
   const showEmployee = !filter || filter.kind === 'employee';
-  const showManager = !filter || filter.kind === 'manager';
+  const showManager = state.modalPersonaFilter == null && (!filter || filter.kind === 'manager');
 
   // Group employees by category.
   const employeeGroups = [];
@@ -860,7 +1335,13 @@ function renderJobCatalog(searchTerm = '') {
     for (const cat of cats) {
       const rows = employees.filter((j) =>
         j.categoryId === cat.id &&
-        (!f || j.title.toLowerCase().includes(f) || (j.intent || '').toLowerCase().includes(f))
+        (!f || j.title.toLowerCase().includes(f) || (j.intent || '').toLowerCase().includes(f)) &&
+        // R3+: modal persona filter; null = All, '__free__' = free jobs only,
+        // personaKey = only that persona's jobs (free jobs excluded).
+        (state.modalPersonaFilter == null ||
+          (state.modalPersonaFilter === '__free__'
+            ? j.requiredPersonaKey == null
+            : j.requiredPersonaKey === state.modalPersonaFilter))
       );
       if (rows.length > 0) employeeGroups.push({ label: cat.label, items: rows });
     }
@@ -885,11 +1366,22 @@ function renderJobCatalog(searchTerm = '') {
     const h4 = document.createElement('h4');
     h4.textContent = label;
     wrap.appendChild(h4);
+    const personas = state.bootstrap?.personas || [];
+    // Lock enforcement is only active when the workspace has an active subscription.
+    // Legacy workspaces (subscriptionActive = false) see the full catalog with no locks.
+    const personaSystemActive = state.bootstrap?.subscriptionActive ?? false;
     for (const job of items) {
       total += 1;
+      // R3.1: a job is locked when it requires a persona with status 'locked',
+      // but only when the persona system is active (subscription present).
+      const isLocked = personaSystemActive && job.requiredPersonaKey != null && personas.some(
+        (p) => p.key === job.requiredPersonaKey && p.status === 'locked'
+      );
       const btn = document.createElement('button');
       btn.type = 'button';
-      btn.className = 'job-option' + (state.selectedJob?.id === job.id ? ' selected' : '');
+      btn.className = 'job-option' +
+        (isLocked ? ' locked' : '') +
+        (state.selectedJob?.id === job.id ? ' selected' : '');
       btn.dataset.jobId = job.id;
       const strong = document.createElement('strong');
       strong.textContent = job.title;
@@ -897,7 +1389,20 @@ function renderJobCatalog(searchTerm = '') {
       span.textContent = job.intent || '';
       btn.appendChild(strong);
       btn.appendChild(span);
+      if (isLocked) {
+        // R3.1: inline lock badge showing persona display name.
+        const lockBadge = document.createElement('span');
+        lockBadge.className = 'lock-badge';
+        const persona = personas.find((p) => p.key === job.requiredPersonaKey);
+        lockBadge.textContent = `🔒 ${persona ? persona.displayName : job.requiredPersonaKey}`;
+        btn.appendChild(lockBadge);
+      }
       btn.addEventListener('click', () => {
+        if (isLocked) {
+          // R3.2: locked job click shows hire-required notice.
+          showHireNotice(job);
+          return;
+        }
         state.selectedJob = job;
         els['next1'].disabled = false;
         els['job-pick-status'].textContent = `Selected: ${job.title}`;
@@ -1093,13 +1598,20 @@ async function refreshEmployees() {
 // string, never just the instructions slice.
 function deriveTitle(jobTitle, instructions) {
   const trimmedJob = (jobTitle || '').trim();
-  const stripped = (instructions || '')
-    .trim()
+  const raw = (instructions || '').trim();
+  // Capture FRAIM job slug before stripping (e.g. "/fraim pricing-strategy-definition" → "pricing-strategy-definition")
+  const fraimSlugMatch = raw.match(/^[/$]fraim\s+([a-z0-9][a-z0-9-]*)(?:\s|$)/i);
+  const stripped = raw
     .replace(/^[/$]fraim(?:\s+[a-z0-9-]+)?\s*/i, '')
     .replace(/\s+/g, ' ')
     .trim();
   const words = stripped.split(' ').filter(Boolean).slice(0, 6);
   const intent = words.join(' ');
+  // When instructions are solely a FRAIM invocation, the slug IS the job — use it
+  // regardless of jobTitle (which may be the generic "Freeform task" placeholder).
+  if (!intent && fraimSlugMatch) {
+    return fraimSlugMatch[1].split('-').map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+  }
   if (!trimmedJob && !intent) return 'New job';
   if (!intent) return trimmedJob;
   // If the job title and the start of the instructions happen to be the
@@ -1177,6 +1689,8 @@ async function startRun(job, instructions, employeeId) {
     jobId: job.id,
     jobTitle: job.title,
     employeeId,
+    // R4: assign the persona key for this job (null for free jobs or freeform).
+    personaKey: (job.requiredPersonaKey != null ? job.requiredPersonaKey : null),
     runId: null,
     sessionId: null,
     status: 'running',
@@ -1310,6 +1824,10 @@ function foldRunIntoConversation(conv, run) {
   }
   // Track session for resumption.
   if (run.sessionId) conv.sessionId = run.sessionId;
+  // R4: persist the persona key from the server-side run record.
+  if (run.personaKey !== undefined && conv.personaKey == null) {
+    conv.personaKey = run.personaKey;
+  }
   // Update status.
   if (run.status === 'completed') conv.status = 'completed';
   else if (run.status === 'failed') conv.status = 'failed';
@@ -1438,6 +1956,10 @@ function wireEvents() {
   els['project-button'].addEventListener('click', pickProject);
   els['new-conv-btn'].addEventListener('click', openModal);
   els['cancel1'].addEventListener('click', closeModal);
+  // Issue #385: hire-required notice back button.
+  if (els['hire-notice-back']) {
+    els['hire-notice-back'].addEventListener('click', hideHireNotice);
+  }
   els['back2'].addEventListener('click', () => {
     els['step1'].hidden = false;
     els['step2'].hidden = true;