@remits/remits-cli 0.1.114 → 0.1.115

package/index.js

@@ -141,6 +141,10 @@ function hasExplicitDataModeFlag(flags) {
   );
 }
 
+function dataModeFlagSource(flags) {
+  return hasExplicitDataModeFlag(flags) ? 'explicitFlag' : 'cliDefault';
+}
+
 function canonicalSessionKey(accountId, baseUrl, dataMode) {
   const normalizedAccountId = Number(accountId);
   const normalizedBaseUrl = normalizeBaseUrl(baseUrl || DEFAULT_BASE_URL);
@@ -347,6 +351,7 @@ function resolveSessionIdentity(cwd, flags = {}) {
     // an account whose session is parked on prod cannot have a test run silently follow it. Report both
     // rather than a single number that governs only some commands.
     testRunDataMode: requestedDataMode || DEFAULT_DATA_MODE,
+    testRunDataModeSource: dataModeFlagSource(flags),
     baseUrl: normalizeBaseUrl((session && session.baseUrl) || requestedBaseUrl || DEFAULT_BASE_URL),
     updatedAt: session ? session.updatedAt : null,
     sessionResolutionWarning
@@ -366,7 +371,8 @@ function printSessionIdentity(identity, options = {}) {
     console.log('Branch:', identity.branchName || 'unresolved');
     console.log('Workspace:', identity.workspace || 'none (shared default lane)');
     console.log('Data mode:', (identity.dataMode || DEFAULT_DATA_MODE) + ' (applies to tool/tools/token)');
-    console.log('Data mode (test run):', identity.testRunDataMode || DEFAULT_DATA_MODE);
+    console.log('Data mode (test run):', identity.testRunDataMode || DEFAULT_DATA_MODE,
+      '[' + (identity.testRunDataModeSource || 'cliDefault') + ']');
     console.log('Base URL:', identity.baseUrl);
     return;
   }
@@ -396,6 +402,7 @@ function printSessionIdentity(identity, options = {}) {
   // prod would otherwise read as "prod" here while the next test run went to the test lane. Say so rather
   // than letting the tuple imply a lane it does not govern.
   console.log('  Data mode (test run):', identity.testRunDataMode,
+    '[' + (identity.testRunDataModeSource || 'cliDefault') + ']',
     identity.testRunDataMode === identity.dataMode ? '' : '— test run ignores the session lane; pass --data-mode prod to override');
   console.log('  Base URL:', identity.baseUrl);
   if (identity.updatedAt) {
@@ -767,14 +774,40 @@ function sha256(value) {
   return crypto.createHash('sha256').update(value).digest('hex');
 }
 
+/**
+ * The branch this directory is on.
+ *
+ * <p><b>Git is asked FIRST, and the environment override is only a fallback.</b> It used to be the other
+ * way round, which made `REMITS_GIT_BRANCH` able to lie about a real branch: this value keys the component
+ * staging scope, the landing lease, the run context and every promotion command, so a stale export in a
+ * shell silently mislabelled every one of them — staging into a lane the tree is not on, and taking the
+ * landing lease for a branch nobody is landing. Nothing warned, because both halves looked correct.</p>
+ *
+ * <p>The override exists for the one case where git genuinely cannot answer: a DETACHED worktree, where
+ * `rev-parse --abbrev-ref HEAD` returns the literal `HEAD`. A ticket worker that detaches declares the
+ * branch it is working, and that declaration is used only where there is no real answer to contradict.
+ * So the legitimate use is preserved and the footgun is gone — on a normal checkout the variable now
+ * cannot change what anything reports.</p>
+ */
 function currentBranch(cwd) {
   try {
-    return execSync('git rev-parse --abbrev-ref HEAD', { cwd, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', { cwd, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+    // `HEAD` means detached: git has no branch name to give, so a declared one is the only answer.
+    if (branch && branch !== 'HEAD') return branch;
+    return remitsGitBranchOverride() || branch;
   } catch (err) {
+    const override = remitsGitBranchOverride();
+    if (override) return override;
     return 'main';
   }
 }
 
+function remitsGitBranchOverride() {
+  const value = process.env.REMITS_GIT_BRANCH || process.env.REMITS_BRANCH_NAME;
+  const branch = value == null ? '' : String(value).trim();
+  return branch && branch !== 'HEAD' ? branch : null;
+}
+
 function shellQuote(value) {
   return '\'' + String(value).replace(/'/g, '\'\"\'\"\'' ) + '\'';
 }
@@ -2457,18 +2490,24 @@ async function pushComponentsCommand(flags) {
   // or, worse, conclude staging was broken and go on reading trunk. Scaled by payload size, floored at
   // the old default, and overridable.
   const api = buildAxios(baseUrl, session.token, stageTimeoutMs(components, flags));
-  const response = await loggedPost(api, cwd, '/cli/components', {
+  const response = await stageOrRefuse(api, cwd, {
     token: session.token,
     accountId,
     branchName,
     workspace,
     dataMode,
     mode,
+    // WHERE this stage is coming from. The platform derives a lightweight presence record from it, so an
+    // interactive agent that never ran `agent register` is still visible to every headless worker in the
+    // fleet — and so the edit-lease check below can tell "somebody else holds it" from "I hold it".
+    ...runContextPayload(flags),
+    agentId: flags['agent-id'] || process.env.REMITS_AGENT_ID || undefined,
+    acknowledge: flags.acknowledge || undefined,
     // A partial (--changed-only) stage must not trigger the server's reconcile pass: reconcile deletes
     // every staged entry absent from the manifest, which for a partial manifest is nearly all of them.
     replace: !changedOnly,
     components
-  }).then((r) => r.data);
+  });
   response.changedFromWorkingTree = changedFromWorkingTree || [];
   response.changedFromWorkingTreeAvailable = changedFromWorkingTree !== null;
 
@@ -2482,9 +2521,51 @@ async function pushComponentsCommand(flags) {
   printStagingLane(response.branchName || branchName, response.workspace || workspace, workspaceSource(cwd, flags));
   console.log('Data mode:', response.dataMode || dataMode);
   console.log('Mode:', response.mode || mode + (changedOnly ? ' (--changed-only)' : ''));
+  printComponentPolicy(response);
   printStageSummary(response, flags);
 }
 
+/**
+ * A policy refusal is an ANSWER, not a transport failure.
+ *
+ * The platform answers 409 with the sentence to act on ("another agent holds the edit lease on this
+ * repository and you are staging into the SHARED lane…"). That sentence must reach the caller intact —
+ * an axios stack trace teaches an agent nothing and it will retry the identical call.
+ */
+async function stageOrRefuse(api, cwd, payload) {
+  try {
+    return await loggedPost(api, cwd, '/cli/components', payload).then((r) => r.data);
+  } catch (err) {
+    const body = err && err.response && err.response.data;
+    const status = err && err.response && err.response.status;
+    if (status === 409 && body && body.message) {
+      if (body.editLease) {
+        console.error('Edit lease: ' + describeRunLocation(body.editLease));
+      }
+      const refusal = new Error(body.message);
+      refusal.refused = true;
+      throw refusal;
+    }
+    throw err;
+  }
+}
+
+/** What the account's rules said about this stage or commit — including "they could not be read". */
+function printComponentPolicy(response) {
+  const policy = response && response.policy;
+  const lease = response && response.editLease;
+  if (lease) {
+    console.log('Note: another agent holds the edit lease on this repository — ' +
+      (describeRunLocation(lease) || 'location not recorded') + '.');
+  }
+  if (!policy) return;
+  if (policy.error) {
+    console.error('POLICY NOT ENFORCED: this account has component rules that could not be parsed: ' + policy.error);
+  }
+  (policy.warnings || []).forEach((warning) => console.log('Policy warning: ' + warning));
+  (policy.overrides || []).forEach((id) => console.log('Policy override recorded for rule: ' + id));
+}
+
 function shouldPrintFullComponentResponse(flags) {
   return flagEnabled(flags.verbose);
 }
@@ -2577,9 +2658,45 @@ function printStatusSummary(response, flags) {
     console.log('  (* = this command\'s lane)');
   }
 
+  printAccountLanes(response);
+
   printComponentCommandResponse('Components staging', response, flags);
 }
 
+// Every staging lane on the ACCOUNT, across branches.
+//
+// The block above only ever covered lanes on the SAME git branch, because that is all its key pattern
+// could reach. So an agent on trunk could not learn that a sibling had components staged on a variant
+// branch of the same account — and those lanes are not merely differently named, they resolve and commit
+// into different worlds. "Am I working alone" was only answerable within one branch, which is the
+// narrower half of the question.
+//
+// Marked "as of" deliberately: this comes from the lane index, not from the staging keys. The caller's own
+// lane is still reported authoritatively above.
+function printAccountLanes(response) {
+  const lanes = Array.isArray(response.accountLanes) ? response.accountLanes : [];
+  const others = lanes.filter((lane) => !lane.mine);
+  if (!others.length) return;
+
+  console.log('');
+  console.log('Other staging lanes on this ACCOUNT (as of the last stage/clear in each):');
+  lanes.forEach((lane) => {
+    // null onTrunk means the owner could not be resolved. Say "unknown" rather than guessing a world.
+    const world = lane.onTrunk === true ? 'trunk'
+                : lane.onTrunk === false ? 'variant branch'
+                : 'branch world unknown';
+    const ws = lane.workspace ? ' [ws:' + lane.workspace + ']' : '';
+    const who = lane.userEmail ? '  ' + lane.userEmail : '';
+    const ttl = lane.expiresInSeconds != null
+      ? '  expires in ~' + Math.round(lane.expiresInSeconds / 60) + 'm' : '';
+    console.log('  ' + (lane.mine ? '* ' : '  ') + lane.branchName + ws
+      + '  (' + world + ')  — ' + (lane.stagedCountAsOf || 0) + ' component(s)' + who + ttl);
+  });
+  console.log('  (* = this command\'s lane)');
+  console.log('  A variant-branch lane layers over that branch\'s ComponentVariant overlays, and a commit');
+  console.log('  from it writes overlays — never the trunk rows a trunk lane commits to.');
+}
+
 // Make the working tree's meaning explicit. An agent may be standing in a TRUNK checkout or in a
 // VARIANT branch's checkout, and the two differ on BOTH ends of the loop: what a run resolves, and
 // what a commit writes. Inferring that from the branch name alone is exactly the kind of ambiguity
@@ -2623,8 +2740,8 @@ function printClearSummary(response, flags) {
  * `remits-cli workspace [show|use <name>|clear]`
  *
  * The ergonomic entry point for the staging workspace lane. `use --auto` names the lane after the
- * checkout directory, which is what makes `git worktree add ../ms-agent-a` + one command enough to give
- * an agent its own isolated staging lane on the SAME branch.
+ * checkout directory, which is what makes one workspace file per worktree enough to give an agent its own
+ * isolated staging lane on the SAME branch.
  */
 async function workspaceCommand(flags) {
   const cwd = process.cwd();
@@ -2808,6 +2925,12 @@ async function syncComponentsCommand(flags) {
     forceTombstones,
     dryRun,
     mode: 'sync',
+    // Identity and location, so the platform can take the landing lease for THIS session rather than for
+    // an anonymous caller — and so a re-acquire by the same session (the CLI already took it in
+    // `components commit` phase 1) succeeds instead of refusing itself.
+    ...runContextPayload(flags),
+    agentId: flags['agent-id'] || process.env.REMITS_AGENT_ID || undefined,
+    acknowledge: flags.acknowledge || undefined,
     components: []
   };
 
@@ -2851,7 +2974,9 @@ async function syncComponentsCommand(flags) {
     failOnSyncGate(preflightGate);
   }
 
-  const response = await loggedPost(api, cwd, '/cli/components', syncPayload).then((r) => r.data);
+  // Through the same refusal-aware door as `stage`: the landing lease and the account's commit rules both
+  // answer 409 with the sentence to act on, and that sentence must reach the caller intact.
+  const response = await stageOrRefuse(api, cwd, syncPayload);
 
   if (!response.success) {
     throw new Error(response.message || 'Server sync failed');
@@ -2871,6 +2996,7 @@ async function syncComponentsCommand(flags) {
   printResolvedBaseUrl(baseUrl);
   console.log('Data mode:', response.dataMode || dataMode);
   console.log('Mode:', response.mode || 'sync');
+  printComponentPolicy(response);
   if (response.sync && response.sync.dryRun) {
     console.log('Dry run: no variants were written and staging was not cleared.');
   }
@@ -3551,6 +3677,17 @@ async function commitComponentsCommand(flags) {
     throw new Error('components commit does not support --dry-run because it performs local git writes. Use `remits-cli components sync --dry-run`.');
   }
 
+  // Landing is serial and nothing can make it concurrent: `git add -A` sweeps a shared checkout, and the
+  // platform pushes a regenerated `account-info.json` back to the branch during sync, so two commits
+  // racing one branch collide on the remote.
+  //
+  // Taken HERE, before `git push`, and not after. Once the push has happened the platform can only refuse
+  // the SYNC, and a pushed-but-unsynced branch is a state nobody is watching.
+  //
+  // The honest limit: this cannot stop a raw `git push` somebody runs themselves. It makes `remits-cli
+  // components commit` serial, which is the path everything actually uses.
+  const landing = await acquireLandingLease(flags, accountId, branchName);
+  try {
   if (!skipGit) {
     console.log('Phase 1/3: local git commit/push');
     const status = runGit(cwd, 'git status --porcelain');
@@ -3610,6 +3747,71 @@ async function commitComponentsCommand(flags) {
       console.log('Verified local HEAD matches remits sync SHA:', expectedSha);
     }
   }
+  } finally {
+    // Give the branch back so the next agent lands in seconds rather than waiting out the TTL. Nothing
+    // depends on this happening — the lease expires on its own, which is what covers the run that is
+    // killed before it gets here.
+    await releaseLandingLease(landing);
+  }
+}
+
+/**
+ * Take the exclusive right to land this branch, or stop with the sentence saying who has it.
+ *
+ * Soft-fails on an OLDER PLATFORM that does not know the `land` mode (400/404): the CLI must keep working
+ * against a platform it is ahead of, and the server takes the lease itself on the sync anyway — so the
+ * worst case is that the refusal arrives one phase later than it should, not that it stops arriving.
+ */
+async function acquireLandingLease(flags, accountId, branchName) {
+  const cwd = process.cwd();
+  const { session } = resolveSessionContext(cwd, flags);
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const payload = {
+    token: session.token,
+    accountId,
+    branchName,
+    mode: 'land',
+    dataMode: resolveDataMode(flags, session),
+    ...runContextPayload(flags),
+    agentId: flags['agent-id'] || process.env.REMITS_AGENT_ID || undefined
+  };
+  try {
+    const response = await buildAxios(baseUrl, session.token, 20000)
+      .post('/cli/components', payload).then((r) => r.data);
+    if (response && response.success) {
+      console.log('Landing lease: held on ' + branchName + ' (' +
+        (response.ttlMinutes || '?') + 'm, renewed by the sync).');
+      return { flags, accountId, branchName, baseUrl, session, held: true };
+    }
+    throw new Error((response && response.message) || 'Could not take the landing lease.');
+  } catch (err) {
+    const body = err && err.response && err.response.data;
+    const status = err && err.response && err.response.status;
+    if (body && body.message && status === 409) {
+      throw new Error(body.message);
+    }
+    if (status === 400 || status === 404) {
+      return { held: false };
+    }
+    if (body && body.message) {
+      throw new Error(body.message);
+    }
+    throw err;
+  }
+}
+
+async function releaseLandingLease(landing) {
+  if (!landing || !landing.held) return;
+  try {
+    await buildAxios(landing.baseUrl, landing.session.token, 20000).post('/cli/components', {
+      token: landing.session.token,
+      accountId: landing.accountId,
+      branchName: landing.branchName,
+      mode: 'unland',
+      ...runContextPayload(landing.flags),
+      agentId: landing.flags['agent-id'] || process.env.REMITS_AGENT_ID || undefined
+    });
+  } catch (_) { /* best-effort: the lease expires on its own */ }
 }
 
 function webSocketUrl(baseUrl) {
@@ -3717,6 +3919,7 @@ async function testCommand(flags) {
   const dataMode = hasExplicitDataModeFlag(flags)
     ? resolveDataMode(flags, null)
     : DEFAULT_DATA_MODE;
+  const dataModeSource = dataModeFlagSource(flags);
   const testRef = flags.test || flags['test-id'] || flags.name;
 
   if (!testRef) {
@@ -3768,6 +3971,7 @@ async function testCommand(flags) {
     branchName,
     workspace,
     dataMode,
+    dataModeSource,
     testId: /^\d+$/.test(String(testRef)) ? Number(testRef) : undefined,
     testName: /^\d+$/.test(String(testRef)) ? undefined : String(testRef),
     tests: names
@@ -5283,6 +5487,7 @@ async function collectAgentSnapshot() {
         label: entry.label || entry.agentId,
         alive: !!(worker.pid && processIsAlive(worker.pid))
       }))), []),
+    recentWorkers: recentWorkerRuns(24),
     errors
   };
   agentSnapshotCache = { fetchedAtMs: nowMs, value };
@@ -5572,12 +5777,18 @@ function renderDashboardHtml(snapshot) {
         'function supportTicketDetails(state,ticket,key){const agents=((state.agents||{}).registered)||[];const ticketAccountId=String(ticket.accountId||"");const eligible=agents.filter(function(a){if(ticket.baseUrl&&a.baseUrl&&a.baseUrl!==ticket.baseUrl)return false;if(ticket.dataMode&&a.dataMode&&a.dataMode!==ticket.dataMode)return false;return (a.accounts||[]).some(function(acc){return String(acc.accountId)===ticketAccountId||acc.routingScope==="self_and_descendants";});});const options=[\'<option value="">- unrouted -</option>\'].concat(eligible.map(function(a){const sel=a.agentId===ticket.routedAgentId?" selected":"";return \'<option value="\'+escapeHtml(a.agentId)+\'"\'+sel+\'>\'+escapeHtml((a.label||a.userName||a.agentId)+" - "+(a.state||"idle")+(a.activity?" ("+a.activity+")":""))+\'</option>\';})).join("");const routeControl=eligible.length?(\'<div class="mini-card"><strong>Route To Agent</strong><div style="display:flex;gap:8px;margin-top:6px;"><select data-route-ticket="\'+escapeHtml(String(ticket.ticketId||""))+\'" data-route-account="\'+escapeHtml(ticketAccountId)+\'" data-route-base="\'+escapeHtml(ticket.baseUrl||"")+\'" data-route-mode="\'+escapeHtml(ticket.dataMode||"")+\'" style="flex:1;min-width:0;">\'+options+\'</select><button class="action-btn" data-action="route-ticket" data-ticket="\'+escapeHtml(String(ticket.ticketId||""))+\'">Route</button></div></div>\'):\'<div class="mini-card"><strong>Route To Agent</strong>No registered agent covers this account.</div>\';const lane=ticket.dataMode||"prod";const planning=[ticket.workstream?("Workstream "+ticket.workstream):"",ticket.plannedIn?("Planned "+ticket.plannedIn):"",ticket.boardStage?("Board "+ticket.boardStage):"",ticket.rank!==undefined&&ticket.rank!==null&&ticket.rank!==""?("Rank "+ticket.rank):"",ticket.size?("Size "+ticket.size):"",ticket.blockedBy?("Blocked by "+ticket.blockedBy):""].filter(Boolean).join(" / ");const command="remits-cli ticket read --ticket "+String(ticket.ticketId||"")+" --data-mode "+lane+"\\nremits-cli ticket accept --ticket "+String(ticket.ticketId||"")+" --data-mode "+lane;return \'<div class="stack"><div class="mini-grid"><div class="mini-card"><strong>Ticket</strong>\'+escapeHtml(ticket.ticketId||"n/a")+\'</div><div class="mini-card"><strong>Account</strong>\'+escapeHtml((ticket.accountName||"n/a")+" ("+(ticket.accountId||"n/a")+")")+\'</div><div class="mini-card"><strong>Type</strong>\'+escapeHtml(ticket.type||"n/a")+\'</div><div class="mini-card"><strong>Owned By</strong>\'+escapeHtml(ticket.assignedTo||"unassigned")+\'</div><div class="mini-card"><strong>Routed To</strong>\'+escapeHtml(ticket.routedAgentLabel||ticket.routedAgentId||"nobody")+\'</div><div class="mini-card"><strong>Implementation</strong>\'+escapeHtml((ticket.implementationAccountName||"n/a")+" ("+(ticket.implementationAccountId||"n/a")+")")+\'</div><div class="mini-card"><strong>Planning</strong>\'+escapeHtml(planning||"No planning fields")+\'</div></div>\'+routeControl+\'<div class="muted">\'+escapeHtml(ticket.affectedComponent||"No affected component recorded.")+\'</div>\'+codeBlock(key+":cmd",command)+\'</div>\';}' +
         'function renderWebsockets(state){const entries=Object.entries((state.websocket&&state.websocket.connections)||{});const target=document.getElementById("websocket-section");if(!entries.length){target.innerHTML=\'<div class="empty">No websocket connections are registered yet.</div>\';return;}target.innerHTML=entries.map(function(pair){const baseUrl=pair[0];const info=pair[1]||{};const topicEntries=Object.entries(info.topics||{});const recentMessages=Array.isArray(info.recentMessages)?info.recentMessages:[];const tone=info.status==="connected"?"ok":(info.status==="connecting"?"warn":"bad");const summaryMeta=badge(info.status||"unknown",tone)+\' <span class="muted">\' + escapeHtml(String(topicEntries.length)) + \' topic(s)</span>\' + \' <span class="muted">\' + escapeHtml(String(recentMessages.length)) + \' recent message(s)</span>\';const topicBody=topicEntries.length?topicEntries.map(function(topicPair){const topic=topicPair[0];const topicInfo=topicPair[1]||{};const mini=\'<div class="mini-grid"><div class="mini-card"><strong>Accounts</strong>\'+escapeHtml((topicInfo.accountIds||[]).join(", ")||"n/a")+\'</div><div class="mini-card"><strong>Subscribed</strong>\'+escapeHtml(formatTime(topicInfo.subscribedAt))+\'</div><div class="mini-card"><strong>Last Message</strong>\'+escapeHtml(formatTime(topicInfo.lastMessageAt))+\'</div></div>\';return detailsBlock("ws-topic:"+baseUrl+":"+topic,topic,"topic subscription",mini,false);}).join(""):\'<div class="empty">No topic subscriptions recorded.</div>\';const messageBody=recentMessages.length?recentMessages.map(function(message,index){const messageMeta=badge(message.duplicate?"duplicate":"handled",message.duplicate?"warn":"ok")+\' <span class="muted">\'+escapeHtml(message.source||"live")+\'</span>\' + \' <span class="muted">\'+escapeHtml(message.type||"unknown-type")+\'</span>\';const body=\'<div class="stack"><div class="mini-grid"><div class="mini-card"><strong>Message ID</strong>\'+escapeHtml(message.messageId||"n/a")+\'</div><div class="mini-card"><strong>Timestamp</strong>\'+escapeHtml(message.timestamp?String(message.timestamp):"n/a")+\'</div><div class="mini-card"><strong>Received</strong>\'+escapeHtml(formatTime(message.receivedAt))+\'</div><div class="mini-card"><strong>Accounts</strong>\'+escapeHtml((message.accountIds||[]).join(", ")||"n/a")+\'</div></div>\'+codeBlock("ws-msg:"+baseUrl+":"+(message.messageId||index),JSON.stringify(message.payload||{},null,2)) + \'</div>\';return detailsBlock("ws-message:"+baseUrl+":"+(message.messageId||index),(message.type||"message")+" "+(message.messageId||""),messageMeta,body,false);}).join(""):\'<div class="empty">No recent websocket messages have been recorded yet.</div>\';const body=\'<div class="stack"><div class="mini-grid"><div class="mini-card"><strong>Status</strong>\'+escapeHtml(info.status||"unknown")+\'</div><div class="mini-card"><strong>Connected</strong>\'+escapeHtml(formatTime(info.connectedAt))+\'</div><div class="mini-card"><strong>Last Message</strong>\'+escapeHtml(formatTime(info.lastMessageAt))+\'</div><div class="mini-card"><strong>Last Error</strong>\'+escapeHtml(info.lastError||"none")+\'</div></div><div class="stack">\'+detailsBlock("ws-recent:"+baseUrl,"Recent messages","latest live and missed-message traffic",messageBody,false)+topicBody+\'</div></div>\';return detailsBlock("ws:"+baseUrl,baseUrl,summaryMeta,body,entries.length===1);}).join("");}' +
         'function agentTone(agent){if(!agent||agent.online===false)return "bad";const s=agent.state||"idle";return s==="paused"?"warn":"ok";}' +
-        'function renderWorkers(state){const target=document.getElementById("worker-section");const workers=((state.agents||{}).workers)||[];if(!workers.length){target.innerHTML=\'<div class="empty">No autonomous ticket workers are running. Start one with <strong>remits-cli agent serve</strong> — it launches a fresh headless agent process per routed ticket, so no session accumulates context across tickets.</div>\';return;}target.innerHTML=workers.map(function(w,index){const meta=badge(w.agentType||"agent",w.alive?"ok":"bad")+\' \'+badge(w.alive?"running":"exited",w.alive?"ok":"bad")+\' <span class="muted">attempt \'+escapeHtml(String(w.attempt||1))+\'</span>\';const t=escapeHtml(String(w.ticketId||""));const body=\'<div class="stack"><div class="mini-grid"><div class="mini-card"><strong>Ticket</strong>\'+escapeHtml(String(w.ticketId||"?"))+\'</div><div class="mini-card"><strong>Doing Now</strong>\'+escapeHtml(w.activity||"nothing reported yet")+\'</div><div class="mini-card"><strong>Started</strong>\'+escapeHtml(formatTime(w.startedAt))+\'</div><div class="mini-card"><strong>Pid</strong>\'+escapeHtml(String(w.pid||"?"))+\'</div><div class="mini-card"><strong>Repo</strong>\'+escapeHtml(w.workingDirectory||"(none resolved)")+\'</div><div class="mini-card"><strong>Supervisor</strong>\'+escapeHtml(w.label||w.agentId||"?")+\'</div></div><div class="wlog-bar"><button class="action-btn" data-follow-ticket="\'+t+\'">Follow live</button><label class="muted"><input type="checkbox" data-follow-tail="\'+t+\'" checked> stick to bottom</label><span class="muted" data-follow-status="\'+t+\'"></span></div><div class="wlog" data-follow-log="\'+t+\'"><div class="muted">Press <strong>Follow live</strong> to stream this run.</div></div>\'+codeBlock("wlog-tail:"+t,"tail -f "+(w.logFile||""))+\'</div>\';return detailsBlock("worker:"+w.ticketId,"Ticket "+w.ticketId+" - "+(w.subject||"(no subject)"),meta,body,index===0);}).join("");restartActiveFollows();}' +
+        'function basename(value){return String(value||"").split(/[\\\\/]/).pop();}' +
+        'function workerRunKey(run){return run.logName||basename(run.logFile)||String(run.ticketId||"");}' +
+        'function workerControls(run){const key=escapeHtml(workerRunKey(run));const ticket=escapeHtml(String(run.ticketId||""));const log=escapeHtml(run.logName||basename(run.logFile)||"");return \'<div class="wlog-bar"><button class="action-btn" data-follow-key="\'+key+\'" data-follow-ticket="\'+ticket+\'" data-follow-run="\'+log+\'">Follow</button><button class="action-btn" data-unfollow-key="\'+key+\'" disabled>Stop</button><label class="muted"><input type="checkbox" data-follow-tail="\'+key+\'" checked> stick to bottom</label><span class="muted" data-follow-status="\'+key+\'"></span></div><div class="wlog" data-follow-log="\'+key+\'"><div class="muted">Press <strong>Follow</strong> to stream this transcript.</div></div>\';}' +
+        'function workerRunCard(run,index,prefix){const key=workerRunKey(run);const running=run.alive||run.running;const meta=badge(run.agentType||"worker",running?"ok":"warn")+" "+badge(running?"running":"finished",running?"ok":"warn")+" <span class=\\"muted\\">"+escapeHtml(formatTime(run.startedAt||run.updatedAt))+"</span>";const result=run.result?detailsBlock(prefix+":result:"+key,"Last message","worker closing summary",codeBlock(prefix+":result-code:"+key,run.result),false):"";const cardRows=[["Ticket",String(run.ticketId||"?")],["Doing Now",run.activity||"nothing reported"],["Started",formatTime(run.startedAt)],["Updated",formatTime(run.updatedAt)],["Pid",String(run.pid||"not running")],["Repo",run.workingDirectory||"(not recorded)"],["Target Branch",run.targetBranch||"n/a"],["Workspace",run.workspace||"n/a"],["Suggested Worktree",run.suggestedWorktree||"n/a"],["Log",run.logFile||""]];const cards=cardRows.map(function(pair){return "<div class=\\"mini-card\\"><strong>"+escapeHtml(pair[0])+"</strong>"+escapeHtml(pair[1])+"</div>";}).join("");const body="<div class=\\"stack\\"><div class=\\"mini-grid\\">"+cards+"</div>"+workerControls(run)+result+codeBlock(prefix+":tail:"+key,"tail -f "+(run.logFile||""))+"</div>";return detailsBlock(prefix+":"+key,"Ticket "+String(run.ticketId||"?")+" - "+(run.subject||basename(run.logFile)||"worker run"),meta,body,index===0);}' +
+        'function renderWorkers(state){const target=document.getElementById("worker-section");const workers=((state.agents||{}).workers)||[];const recent=((state.agents||{}).recentWorkers)||[];let html=\'<div class="mini-grid"><div class="mini-card"><strong>Running Now</strong>\'+escapeHtml(String(workers.length))+\'</div><div class="mini-card"><strong>Recent Transcripts</strong>\'+escapeHtml(String(recent.length))+\'</div></div>\';html+=workers.length?detailsBlock("workers:live","Running workers","active headless ticket processes",workers.map(function(w,index){return workerRunCard(w,index,"worker-live");}).join(""),true):\'<div class="empty">No autonomous ticket workers are running right now.</div>\';html+=recent.length?detailsBlock("workers:recent","Recent worker runs","finished and running local transcripts",recent.map(function(w,index){return workerRunCard(w,index,"worker-history");}).join(""),true):\'<div class="empty">No worker transcripts have been recorded yet.</div>\';target.innerHTML=html;restartActiveFollows();}' +
         'var followState={};' +
         'function eventHtml(ev){if(!ev)return "";const t=escapeHtml(ev.text||"");if(ev.kind==="command"){const bad=(ev.exitCode!==null&&ev.exitCode!==undefined&&ev.exitCode!==0);const out=ev.detail?\'<span class="out">\'+escapeHtml(String(ev.detail).slice(0,2000))+\'</span>\':"";return \'<div class="ev cmd\'+(bad?" bad":"")+\'">$ \'+t+(bad?\' <span class="muted">(exit \'+escapeHtml(String(ev.exitCode))+\')</span>\':"")+out+\'</div>\';}if(ev.kind==="message")return \'<div class="ev msg">\'+t+\'</div>\';if(ev.kind==="thinking")return \'<div class="ev think">\'+t+\'</div>\';if(ev.kind==="edit")return \'<div class="ev edit">\'+t+\'</div>\';if(ev.kind==="result")return \'<div class="ev res">\'+t+\'</div>\';if(ev.kind==="raw")return \'<div class="ev raw">\'+t+\'</div>\';return \'<div class="ev">\'+t+\'</div>\';}' +
-        'async function pollFollow(ticket){const st=followState[ticket];if(!st)return;const box=document.querySelector(\'[data-follow-log="\'+ticket+\'"]\');const status=document.querySelector(\'[data-follow-status="\'+ticket+\'"]\');if(!box){return;}try{const r=await fetch("/api/worker-log?ticket="+encodeURIComponent(ticket)+"&offset="+st.offset);const d=await r.json();if(d.missing){status&&(status.textContent="no transcript yet");}else{if(st.offset===0)box.innerHTML="";st.offset=d.offset||st.offset;const html=(d.events||[]).map(eventHtml).join("");if(html){box.insertAdjacentHTML("beforeend",html);const stick=document.querySelector(\'[data-follow-tail="\'+ticket+\'"]\');if(!stick||stick.checked)box.scrollTop=box.scrollHeight;}status&&(status.textContent=(d.running?"live":"finished")+" - "+(d.size||0)+" bytes");if(!d.running&&d.offset>=d.size){st.settleCount=(st.settleCount||0)+1;if(st.settleCount>2){clearInterval(st.timer);delete followState[ticket];return;}}else{st.settleCount=0;}}}catch(e){status&&(status.textContent="stream error");}}' +
-        'function startFollow(ticket){if(followState[ticket]){clearInterval(followState[ticket].timer);}followState[ticket]={offset:0,timer:null};pollFollow(ticket);followState[ticket].timer=setInterval(function(){pollFollow(ticket);},2000);}' +
-        'function restartActiveFollows(){Object.keys(followState).forEach(function(t){const box=document.querySelector(\'[data-follow-log="\'+t+\'"]\');if(!box){clearInterval(followState[t].timer);delete followState[t];return;}const st=followState[t];st.offset=0;box.innerHTML="";pollFollow(t);});}' +
+        'function setFollowButtons(key,following){document.querySelectorAll(\'[data-follow-key="\'+key+\'"]\').forEach(function(b){b.disabled=following;});document.querySelectorAll(\'[data-unfollow-key="\'+key+\'"]\').forEach(function(b){b.disabled=!following;});}' +
+        'async function pollFollow(key){const st=followState[key];if(!st)return;const box=document.querySelector(\'[data-follow-log="\'+key+\'"]\');const status=document.querySelector(\'[data-follow-status="\'+key+\'"]\');if(!box){stopFollow(key,true);return;}try{let url="/api/worker-log?ticket="+encodeURIComponent(st.ticket)+"&offset="+st.offset;if(st.logName)url+="&log="+encodeURIComponent(st.logName);const r=await fetch(url);const d=await r.json();if(d.missing){status&&(status.textContent="no transcript yet");}else{if(st.offset===0)box.innerHTML="";st.offset=d.offset||st.offset;const html=(d.events||[]).map(eventHtml).join("");if(html){box.insertAdjacentHTML("beforeend",html);const stick=document.querySelector(\'[data-follow-tail="\'+key+\'"]\');if(!stick||stick.checked)box.scrollTop=box.scrollHeight;}status&&(status.textContent=(d.running?"live":"finished")+" - "+(d.size||0)+" bytes");if(!d.running&&d.offset>=d.size){st.settleCount=(st.settleCount||0)+1;if(st.settleCount>2){stopFollow(key,false);return;}}else{st.settleCount=0;}}}catch(e){status&&(status.textContent="stream error");}}' +
+        'function startFollow(key,ticket,logName){if(followState[key])stopFollow(key,true);followState[key]={ticket:ticket,logName:logName,offset:0,timer:null};setFollowButtons(key,true);const box=document.querySelector(\'[data-follow-log="\'+key+\'"]\');if(box)box.innerHTML="";pollFollow(key);followState[key].timer=setInterval(function(){pollFollow(key);},2000);}' +
+        'function stopFollow(key,silent){const st=followState[key];if(st&&st.timer)clearInterval(st.timer);delete followState[key];setFollowButtons(key,false);const status=document.querySelector(\'[data-follow-status="\'+key+\'"]\');if(status&&!silent)status.textContent="stopped";}' +
+        'function restartActiveFollows(){Object.keys(followState).forEach(function(key){const box=document.querySelector(\'[data-follow-log="\'+key+\'"]\');if(!box){stopFollow(key,true);return;}const st=followState[key];st.offset=0;box.innerHTML="";setFollowButtons(key,true);pollFollow(key);});}' +
         'function renderAgents(state){const target=document.getElementById("agent-section");const info=state.agents||{};const agents=info.registered||[];const local=info.local||[];const errors=info.errors||[];let html=\'<div class="mini-grid"><div class="mini-card"><strong>Registered</strong>\'+escapeHtml(String(agents.length))+\'</div><div class="mini-card"><strong>On This Machine</strong>\'+escapeHtml(String(local.length))+\'</div><div class="mini-card"><strong>Fetched</strong>\'+escapeHtml(formatTime(info.fetchedAt))+\'</div></div>\';if(errors.length){html+=detailsBlock("agents:errors","Agent lookup errors",badge(String(errors.length)+" error(s)","warn"),codeBlock("agents-errors",JSON.stringify(errors,null,2),"log"),false);}if(!agents.length){target.innerHTML=html+\'<div class="empty">No local agent sessions are registered. In each terminal tab that should work tickets, run <strong>remits-cli agent register</strong>. Each tab becomes its own routable agent and stops receiving work when the tab closes.</div>\';return;}html+=agents.map(function(agent,index){const tone=agentTone(agent);const meta=badge(agent.state||"idle",tone)+\' \'+badge((agent.dataMode||"prod")+" lane",agent.dataMode==="test"?"warn":"ok")+\' <span class="muted">\'+escapeHtml(agent.baseUrl||"?")+\' · seen \'+escapeHtml(agent.secondsSinceSeen==null?"?":agent.secondsSinceSeen+"s ago")+\'</span>\';const accounts=(agent.accounts||[]).map(function(a){return (a.name||a.accountId)+" ("+a.accountId+(a.routingScope==="self_and_descendants"?", +descendants":"")+")";}).join(", ");const history=(agent.history||[]).map(function(h){return \'<li><span class="muted">\'+escapeHtml(formatTime(h.at))+\'</span> \'+escapeHtml((h.state||"")+(h.ticketId?" ticket "+h.ticketId:"")+(h.activity?" - "+h.activity:""))+\'</li>\';}).join("");const body=\'<div class="stack"><div class="mini-grid"><div class="mini-card"><strong>Doing Now</strong>\'+escapeHtml(agent.activity||"nothing reported")+\'</div><div class="mini-card"><strong>Ticket</strong>\'+escapeHtml(agent.ticketId||"none")+\'</div><div class="mini-card"><strong>Step</strong>\'+escapeHtml(agent.step||"n/a")+\'</div><div class="mini-card"><strong>User</strong>\'+escapeHtml(agent.userEmail||agent.userName||"n/a")+\'</div><div class="mini-card"><strong>Where</strong>\'+escapeHtml((agent.host||"?")+":"+(agent.cwd||"?"))+\'</div><div class="mini-card"><strong>Tickets Routed</strong>\'+escapeHtml(String(agent.ticketsAssigned||0))+\'</div></div><div class="mini-card"><strong>Covers</strong>\'+escapeHtml(accounts||"none")+\'</div><div><strong style="display:block;margin:12px 0 8px 0;">Recent activity</strong><ul style="margin:0;padding-left:18px;display:grid;gap:6px;">\'+(history||"<li>Nothing recorded yet.</li>")+\'</ul></div></div>\';return detailsBlock("agent:"+agent.agentId,(agent.label||agent.userName||agent.agentId),meta,body,index===0);}).join("");target.innerHTML=html;}' +
         'function renderActivity(state){const target=document.getElementById("activity-section");const logFile=(state.globalFiles||[]).find(function(file){return file.label==="activity.log (tail)";});target.innerHTML=detailsBlock("activity:log","Activity tail","service lifecycle, websocket, and agent events",codeBlock("activity-log",logFile&&logFile.content||"[missing]","log"),true);}' +
         'function renderGlobalFiles(state){const target=document.getElementById("global-files");const files=(state.globalFiles||[]).filter(function(file){return file.label!=="activity.log (tail)";});if(!files.length){target.innerHTML=\'<div class="empty">No global files found.</div>\';return;}target.innerHTML=files.map(function(file){const tone=file.exists?"ok":"warn";const meta=badge(file.exists?"present":"missing",tone)+\' <span class="muted">\'+escapeHtml(file.updatedAt?formatTime(file.updatedAt):"not found")+\'</span>\';const body=\'<div class="stack"><div class="mini-grid"><div class="mini-card"><strong>Path</strong>\'+escapeHtml(file.path||"")+\'</div><div class="mini-card"><strong>Size</strong>\'+escapeHtml(String(file.size||0))+\' bytes</div><div class="mini-card"><strong>Updated</strong>\'+escapeHtml(formatTime(file.updatedAt))+\'</div></div>\'+codeBlock("global:"+file.label,file.content)+(file.label==="service-state.json"?\'<div class="muted">Use this file to discover the dashboard URL and runtime websocket summary.</div>\':"")+\'</div>\';return detailsBlock("global:"+file.label,file.label,meta,body,false);}).join("");}' +
@@ -5586,7 +5797,7 @@ function renderDashboardHtml(snapshot) {
         'async function fetchState(){const res=await fetch("/api/state",{cache:"no-store"});if(!res.ok)throw new Error("State refresh failed with "+res.status);return res.json();}' +
         'function showToast(message){const toast=document.getElementById("toast");toast.textContent=message;toast.classList.add("show");clearTimeout(showToast._timer);showToast._timer=setTimeout(function(){toast.classList.remove("show");},2400);}' +
         'async function triggerAction(action,button,extra){if(actionInFlight)return;actionInFlight=true;button.disabled=true;try{let body="action="+encodeURIComponent(action);Object.keys(extra||{}).forEach(function(k){body+="&"+encodeURIComponent(k)+"="+encodeURIComponent(extra[k]==null?"":extra[k]);});const res=await fetch("/action",{method:"POST",headers:{"Content-Type":"application/x-www-form-urlencoded","Accept":"application/json"},body:body});if(!res.ok)throw new Error("Action failed with "+res.status);const payload=await res.json();renderAll(payload.state);if(payload.result&&payload.result.bundlePath){showToast("Issue bundle prepared at "+payload.result.bundlePath);}else{showToast(action.replace(/-/g," ")+" complete");}}catch(err){showToast(err.message||String(err));}finally{actionInFlight=false;button.disabled=false;}}' +
-        'document.addEventListener("click",function(event){const follow=event.target.closest?event.target.closest("[data-follow-ticket]"):null;if(follow){startFollow(follow.getAttribute("data-follow-ticket"));return;}const button=event.target.closest?event.target.closest("[data-action]"):null;if(!button)return;const action=button.getAttribute("data-action");let extra=null;if(action==="route-ticket"){const ticketId=button.getAttribute("data-ticket");const select=document.querySelector(\'[data-route-ticket="\'+ticketId+\'"]\');if(!select){showToast("No agent selector for that ticket.");return;}extra={ticketId:ticketId,accountId:select.getAttribute("data-route-account"),agentId:select.value,baseUrl:select.getAttribute("data-route-base"),dataMode:select.getAttribute("data-route-mode")};}triggerAction(action,button,extra);});' +
+        'document.addEventListener("click",function(event){const stop=event.target.closest?event.target.closest("[data-unfollow-key]"):null;if(stop){stopFollow(stop.getAttribute("data-unfollow-key"),false);return;}const follow=event.target.closest?event.target.closest("[data-follow-key]"):null;if(follow){startFollow(follow.getAttribute("data-follow-key"),follow.getAttribute("data-follow-ticket"),follow.getAttribute("data-follow-run"));return;}const button=event.target.closest?event.target.closest("[data-action]"):null;if(!button)return;const action=button.getAttribute("data-action");let extra=null;if(action==="route-ticket"){const ticketId=button.getAttribute("data-ticket");const select=document.querySelector(\'[data-route-ticket="\'+ticketId+\'"]\');if(!select){showToast("No agent selector for that ticket.");return;}extra={ticketId:ticketId,accountId:select.getAttribute("data-route-account"),agentId:select.value,baseUrl:select.getAttribute("data-route-base"),dataMode:select.getAttribute("data-route-mode")};}triggerAction(action,button,extra);});' +
         'renderAll(dashboardState);' +
         'setInterval(function(){fetchState().then(renderAll).catch(function(err){showToast(err.message||String(err));});},refreshMs);' +
       '})();' +
@@ -5785,6 +5996,118 @@ function workerTranscriptFor(ticketId, fromOffset) {
   };
 }
 
+function workerRunFromLogName(name) {
+  const match = /^(\d+)-(\d+)\.log$/.exec(String(name || ''));
+  if (!match) {
+    return null;
+  }
+  return { ticketId: match[1], timestampMs: Number(match[2]) || null };
+}
+
+function resultTextForWorkerLog(logFile) {
+  const parsed = workerRunFromLogName(path.basename(logFile || ''));
+  if (!parsed) {
+    return null;
+  }
+  const exact = logFile.replace(/\.log$/, '.result.txt');
+  if (fs.existsSync(exact)) {
+    return truncateText(fs.readFileSync(exact, 'utf8'), 4000);
+  }
+  const candidates = fs.existsSync(WORKER_LOG_DIR)
+    ? fs.readdirSync(WORKER_LOG_DIR)
+      .filter((name) => name.startsWith(parsed.ticketId + '-') && name.endsWith('.result.txt'))
+      .map((name) => {
+        const file = path.join(WORKER_LOG_DIR, name);
+        const stat = fileStat(file);
+        return stat ? { file, mtimeMs: stat.mtimeMs } : null;
+      })
+      .filter(Boolean)
+      .sort((a, b) => b.mtimeMs - a.mtimeMs)
+    : [];
+  if (!candidates.length) {
+    return null;
+  }
+  return truncateText(fs.readFileSync(candidates[0].file, 'utf8'), 4000);
+}
+
+/** Recent worker transcripts, including runs whose live worker row was cleared after release/exit. */
+function recentWorkerRuns(limit = 20) {
+  if (!fs.existsSync(WORKER_LOG_DIR)) {
+    return [];
+  }
+
+  const activeByLog = {};
+  for (const agent of listLocalAgents()) {
+    for (const worker of listWorkers(agent.agentId)) {
+      if (worker && worker.logFile) {
+        activeByLog[path.basename(worker.logFile)] = {
+          ...worker,
+          agentId: agent.agentId,
+          label: agent.label || agent.agentId
+        };
+      }
+    }
+  }
+
+  return fs.readdirSync(WORKER_LOG_DIR)
+    .map((name) => {
+      const parsed = workerRunFromLogName(name);
+      if (!parsed) {
+        return null;
+      }
+      const logFile = path.join(WORKER_LOG_DIR, name);
+      const stat = fileStat(logFile);
+      if (!stat) {
+        return null;
+      }
+      const active = activeByLog[name] || {};
+      const alive = !!(active.pid && processIsAlive(active.pid));
+      return {
+        ticketId: parsed.ticketId,
+        logName: name,
+        logFile,
+        size: stat.size,
+        updatedAt: stat.mtime.toISOString(),
+        startedAt: active.startedAt || (parsed.timestampMs ? new Date(parsed.timestampMs).toISOString() : null),
+        agentId: active.agentId || null,
+        label: active.label || null,
+        agentType: active.agentType || null,
+        pid: active.pid || null,
+        alive,
+        running: alive,
+        attempt: active.attempt || null,
+        workingDirectory: active.workingDirectory || null,
+        targetBranch: active.targetBranch || null,
+        suggestedWorktree: active.suggestedWorktree || null,
+        workspace: active.workspace || null,
+        subject: active.subject || null,
+        result: resultTextForWorkerLog(logFile)
+      };
+    })
+    .filter(Boolean)
+    .sort((a, b) => String(b.updatedAt || '').localeCompare(String(a.updatedAt || '')))
+    .slice(0, Math.max(1, Number(limit) || 20));
+}
+
+/** The transcript of one specific worker log, addressed by safe basename. */
+function workerTranscriptByLogName(logName, fromOffset) {
+  const parsed = workerRunFromLogName(path.basename(String(logName || '')));
+  if (!parsed) {
+    return { error: 'a valid worker log name is required' };
+  }
+  const logFile = path.join(WORKER_LOG_DIR, path.basename(logName));
+  const transcript = readWorkerTranscript(logFile, fromOffset);
+  return {
+    ticketId: parsed.ticketId,
+    logName: path.basename(logName),
+    logFile,
+    running: false,
+    pid: null,
+    follow: 'tail -f ' + logFile,
+    ...transcript
+  };
+}
+
 function startDashboardServer(preferredPort) {
   return new Promise((resolve, reject) => {
     const sendDashboardError = (res, err, wantsJson = true) => {
@@ -5878,9 +6201,11 @@ function startDashboardServer(preferredPort) {
 
       if (req.method === 'GET' && requestUrl.pathname === '/api/worker-log') {
         try {
-          const payload = workerTranscriptFor(
-            requestUrl.searchParams.get('ticket'),
-            Number(requestUrl.searchParams.get('offset')) || 0);
+          const offset = Number(requestUrl.searchParams.get('offset')) || 0;
+          const logName = requestUrl.searchParams.get('log');
+          const payload = logName
+            ? workerTranscriptByLogName(logName, offset)
+            : workerTranscriptFor(requestUrl.searchParams.get('ticket'), offset);
           res.statusCode = 200;
           res.setHeader('Content-Type', 'application/json');
           res.end(JSON.stringify(payload));
@@ -6340,6 +6665,7 @@ const AGENT_STATES = ['idle', 'working', 'paused'];
 // ---------------------------------------------------------------------------------------------
 
 const WORKER_LOG_DIR = path.join(SESSION_DIR, 'workers');
+const TICKET_WORKTREE_DIRNAME = 'ticket-worktrees';
 const AGENT_SERVE_POLL_MS = Number(process.env.REMITS_CLI_AGENT_SERVE_POLL_MS || 20000);
 const AGENT_SERVE_IDLE_POLL_MS = Number(process.env.REMITS_CLI_AGENT_SERVE_IDLE_POLL_MS || 60000);
 // After this many consecutive empty polls, back off to the idle cadence. An agent waiting all night
@@ -6608,6 +6934,57 @@ function resolveTicketWorkingDirectory(ticket, ownCwd = null) {
   return null;
 }
 
+function gitBranchNameInDirectory(cwd) {
+  if (!cwd) return null;
+  try {
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd,
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).toString().trim();
+    return branch && branch !== 'HEAD' ? branch : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function defaultGitBranchInDirectory(cwd) {
+  if (!cwd) return null;
+  try {
+    const branch = execSync('git symbolic-ref --short refs/remotes/origin/HEAD', {
+      cwd,
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).toString().trim().replace(/^[^/]+\//, '');
+    return branch && branch !== 'HEAD' ? branch : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function ticketTargetBranch(ticket, baseDirectory) {
+  const facts = (ticket && ticket.briefFacts) || {};
+  const candidates = [
+    facts.componentBranch,
+    ticket && ticket.componentBranch,
+    facts.branch,
+    ticket && ticket.branch,
+    defaultGitBranchInDirectory(baseDirectory),
+    gitBranchNameInDirectory(baseDirectory)
+  ];
+  for (const candidate of candidates) {
+    const branch = candidate == null ? '' : String(candidate).trim();
+    if (branch && branch !== 'HEAD') return branch;
+  }
+  // No guess. This used to fall back to 'main', which is a guess presented to the worker as a fact — and
+  // wrong on any repo whose default is `master`, or whose work belongs on a variant branch. A worker told
+  // the wrong target branch does not fail; it does the work in the wrong place and reports success.
+  // Absent is a real answer, and the brief omits the line rather than naming a branch nobody resolved.
+  return null;
+}
+
+function ticketWorktreePath(baseDirectory, ticketId) {
+  return path.join(baseDirectory, '.remits-cli', TICKET_WORKTREE_DIRNAME, 'ticket-' + ticketId);
+}
+
 /**
  * Which account this directory is a checkout OF, read from the directory itself.
  *
@@ -6718,6 +7095,21 @@ function processIsAlive(pid) {
   }
 }
 
+async function waitForProcessExit(pid, timeoutMs = 5000) {
+  const numeric = Number(pid);
+  if (!Number.isFinite(numeric) || numeric <= 0) {
+    return true;
+  }
+  const deadline = Date.now() + Math.max(0, Number(timeoutMs) || 0);
+  while (Date.now() < deadline) {
+    if (!processIsAlive(numeric)) {
+      return true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  return !processIsAlive(numeric);
+}
+
 /**
  * The locally-known agent sessions, dropping any whose anchor process has gone.
  *
@@ -6921,6 +7313,23 @@ function agentAccountClaims(cwd) {
   return claims;
 }
 
+/**
+ * `--serves support,incident` -> ['support','incident'].
+ *
+ * Opaque strings: an account's workstream names are its own and neither the CLI nor the platform learns
+ * what any of them means. Lower-cased and de-duplicated here so one machine's `--serves SDLC` and
+ * another's `--serves sdlc` are the same declaration rather than two queues that never overlap.
+ */
+function parseServedWorkstreams(value) {
+  if (value === undefined || value === null || value === true) {
+    return [];
+  }
+  return String(value)
+    .split(',')
+    .map((entry) => entry.trim().toLowerCase())
+    .filter((entry, index, all) => entry && all.indexOf(entry) === index);
+}
+
 async function agentRegisterCommand(flags, options = {}) {
   const cwd = process.cwd();
   try { updateAccountRepoIndex(cwd); } catch (_) { /* not in an account repo */ }
@@ -6964,6 +7373,15 @@ async function agentRegisterCommand(flags, options = {}) {
     // platform stops routing past it, so a supervisor at capacity is not handed work it cannot start.
     maxConcurrent: options.serve ? options.serve.maxConcurrent : (flags['max-concurrent'] ? parsePositiveInt(flags['max-concurrent'], 1) : undefined),
     autonomous: options.serve ? true : undefined,
+    // The autonomy bound and the queues this session covers, on the PRESENCE record rather than only on
+    // the work poll. Routing chooses from presence, so without these `dispatch(...)` would hand a code
+    // change to a session launched read-only while an edit-capable one sat idle, and would ignore
+    // `--serves` entirely. Both are omitted rather than sent empty when not declared, so a re-register
+    // after a TTL lapse cannot silently un-specialise a machine.
+    mode: options.serve ? options.serve.mode : undefined,
+    serves: (options.serve && options.serve.serves && options.serve.serves.length)
+      ? options.serve.serves
+      : (parseServedWorkstreams(flags.serves).length ? parseServedWorkstreams(flags.serves) : undefined),
     state: flags.state && AGENT_STATES.includes(String(flags.state)) ? String(flags.state) : 'idle',
     activity: flags.activity || null,
     source: flags.source || 'repo'
@@ -7001,6 +7419,7 @@ async function agentRegisterCommand(flags, options = {}) {
     if (options.serve) {
       entry.workerAgent = options.serve.workerAgent;
       entry.mode = options.serve.mode;
+      entry.serves = options.serve.serves || [];
       entry.maxConcurrent = options.serve.maxConcurrent;
     }
     rememberLocalAgent(entry);
@@ -7036,6 +7455,9 @@ async function agentRegisterCommand(flags, options = {}) {
     console.log('  worker     ' + serve.workerAgent + '  (' + serve.mode + ' mode)');
     console.log('             ' + serve.workerAgentWhy);
     console.log('  capacity   ' + serve.maxConcurrent + ' ticket(s) at a time');
+    console.log('  serves     ' + ((serve.serves && serve.serves.length)
+      ? serve.serves.join(', ') + '  (only these workstreams are routed here, and only these are swept)'
+      : 'every workstream on these accounts'));
     console.log('');
     console.log('When a ticket is routed here it launches a fresh ' + serve.workerAgent + ' process for that');
     console.log('ticket, in that account\'s repo, and that process exits when the ticket is done — so no');
@@ -7079,6 +7501,16 @@ async function agentServeCommand(flags) {
   }
   const mode = String(flags.mode || (flagEnabled(flags['investigate-only']) ? 'investigate' : 'edit'))
     .toLowerCase() === 'investigate' ? 'investigate' : 'edit';
+  const serves = parseServedWorkstreams(flags.serves);
+  if (serves.length) {
+    console.log('');
+    console.log('Serving workstreams: ' + serves.join(', '));
+    console.log('  This session is offered ONLY tickets in those workstreams, and its sweep takes only');
+    console.log('  those. A workstream no live session covers is routed to nobody — the platform reports');
+    console.log('  that as no_agent_serves_workstream rather than quietly handing it here anyway.');
+    console.log('  Drop --serves to serve every workstream on these accounts.');
+    console.log('');
+  }
 
   // Say what this supervisor CANNOT work, before it starts rather than one ticket at a time. A worker
   // pointed at an account with no usable checkout parks correctly, but the operator only learns that
@@ -7114,6 +7546,7 @@ async function agentServeCommand(flags) {
       workerAgent,
       workerAgentWhy: choice.why,
       mode,
+      serves,
       maxConcurrent: Math.max(1, parsePositiveInt(flags['max-concurrent'], 1))
     }
   });
@@ -7188,7 +7621,11 @@ async function agentWorkersCommand(flags) {
     console.log('    ' + (worker.subject || '(no subject)'));
     console.log('    since   ' + worker.startedAt + '  attempt ' + (worker.attempt || 1));
     console.log('    in      ' + (worker.workingDirectory || '(no repo resolved)') +
+      (worker.targetBranch ? '  target branch ' + worker.targetBranch : '') +
       (worker.workspace ? '  workspace ' + worker.workspace : ''));
+    if (worker.suggestedWorktree) {
+      console.log('    suggest ' + worker.suggestedWorktree);
+    }
     console.log('    doing   ' + (worker.activity || 'nothing reported yet'));
     console.log('    log     ' + worker.logFile);
   }
@@ -7225,6 +7662,13 @@ function startAgentHeartbeatDaemon(entry, serve = null) {
       '--worker-agent', serve.workerAgent,
       '--mode', serve.mode,
       '--max-concurrent', String(serve.maxConcurrent));
+    // The daemon is DETACHED: nothing about its process tree recovers what the operator typed, so any
+    // declaration that must survive into the supervisor loop has to travel on the command line. Omitted
+    // when empty so the daemon's own `parseServedWorkstreams` sees "not declared" rather than "declared
+    // as nothing", which are different facts on the registration payload.
+    if (serve.serves && serve.serves.length) {
+      args.push('--serves', serve.serves.join(','));
+    }
   }
   const child = spawn(process.execPath, args, { detached: true, stdio: 'ignore', env: { ...process.env } });
   child.unref();
@@ -7404,8 +7848,8 @@ async function postAgentStatus(context, agentId, update) {
  * Launch one headless agent process for one ticket, and see it through to its exit.
  *
  * The brief comes from the platform ({@code SupportTicketBrief}) so all three agent types are told
- * the same thing; only the working directory is resolved here, because only this machine knows
- * where the account is checked out.
+ * the same thing. Only the local supervisor can add machine-local repository hints; the worker owns the
+ * final grounding step, including creating or choosing a git worktree before it edits.
  */
 function spawnTicketWorker(context, ctx, ticket) {
   const { spawn } = require('child_process');
@@ -7420,18 +7864,61 @@ function spawnTicketWorker(context, ctx, ticket) {
     return { pid: null, done: Promise.resolve({ ticketId, ok: false, reason: 'unsupported_agent' }) };
   }
 
-  const workingDirectory = resolveTicketWorkingDirectory(ticket, ctx && ctx.cwd);
+  const baseWorkingDirectory = resolveTicketWorkingDirectory(ticket, ctx && ctx.cwd);
+  const repositoryWork = !((ticket && ticket.requiresRepositoryWork === false) ||
+    (ticket && ticket.briefFacts && ticket.briefFacts.requiresRepositoryWork === false));
+  const targetBranch = repositoryWork ? ticketTargetBranch(ticket, baseWorkingDirectory) : gitBranchNameInDirectory(baseWorkingDirectory);
+  const suggestedWorktree = repositoryWork && baseWorkingDirectory ? ticketWorktreePath(baseWorkingDirectory, ticketId) : null;
+  const workingDirectory = baseWorkingDirectory;
   // The brief is rendered server-side without the local path (the platform cannot know it), so the
-  // resolved directory is appended here. When nothing resolved, the server-rendered brief already
+  // resolved local repository hint is appended here. When nothing resolved, the server-rendered brief already
   // tells the worker to find it rather than guess — do not paper over that with a default.
   // The staging lane is set BY THIS FUNCTION (REMITS_WORKSPACE below) and the worker has no other way to
   // learn it: `components status` would show it a lane it never chose, and anything it reports about "the
   // staged code" is ambiguous until it knows which lane it means. Telling it is one line; making it guess
   // is the whole class of defect the lane exists to remove.
   const workerWorkspace = 'ticket-' + ticketId;
-  const brief = String(ticket.brief || '') + (workingDirectory
-    ? '\n\n## Resolved working directory\n\n`' + workingDirectory + '`\n'
-    : '') +
+  // A branch nobody resolved is OMITTED, never guessed: a worker told the wrong target branch does not
+  // fail, it does the work in the wrong place and reports success.
+  const localWorktreeText = workingDirectory && repositoryWork
+    ? '\n\n## Local repository grounding\n\n' +
+      'The supervisor resolved the repository account to this local checkout:\n\n`' + workingDirectory + '`\n\n' +
+      (targetBranch
+        ? 'Target git/component branch: `' + targetBranch + '`.\n'
+        : 'No target branch resolved. Read `remits-cli ticket where --ticket ' + ticketId + '` and the\n' +
+          'repository itself before you decide which branch this work belongs on — do not assume `main`.\n') +
+      'Suggested per-ticket worktree path: `' + suggestedWorktree + '`.\n\n' +
+      'Before editing, establish your own isolated git worktree for this ticket and move into it, so the\n' +
+      'operator\'s launch checkout is not modified underneath them. **You own this decision** — the\n' +
+      'supervisor is a plain local process and cannot reason about repository state. The command below is\n' +
+      'a starting point, not a script to follow blindly; it must start from the remote branch tip, not a\n' +
+      'stale local ref:\n\n' +
+      '```\n' +
+      (targetBranch
+        ? 'git -C ' + shellQuote(workingDirectory) + ' fetch origin ' + shellQuote(targetBranch) + '\n'
+        : 'git -C ' + shellQuote(workingDirectory) + ' fetch origin\n') +
+      'git -C ' + shellQuote(workingDirectory) + ' worktree add --force ' + shellQuote(suggestedWorktree) +
+        (targetBranch ? ' ' + targetBranch : ' <branch>') + '\n' +
+      'cd ' + shellQuote(suggestedWorktree) + '\n' +
+      (targetBranch
+        ? 'git pull --ff-only origin ' + shellQuote(targetBranch) + '\n' +
+          'git rev-list --left-right --count HEAD...origin/' + shellQuote(targetBranch) + '   # must print: 0  0\n'
+        : 'git pull --ff-only origin <branch>\n' +
+          'git rev-list --left-right --count HEAD...origin/<branch>   # must print: 0  0\n') +
+      'remits-cli components status\n' +
+      '```\n\n' +
+      'If the pull cannot fast-forward, or either side of that rev-list count is non-zero, stop and settle\n' +
+      'the branch before editing. A worktree and workspace isolate this worker from the launch checkout and\n' +
+      'from other staging lanes; they do not prove which commit the files are based on.\n\n' +
+      'If git still refuses because the branch is already checked out elsewhere, add `--detach`, and in THAT case\n' +
+      'only, export `REMITS_GIT_BRANCH=' + (targetBranch || '<branch>') + '` so the branch this run reports\n' +
+      '(staging scope, landing lease, run context) matches the branch it is working — git cannot name a\n' +
+      'branch for a detached worktree, so nothing else can answer. On a normal worktree do not set it and\n' +
+      'do not need to: git is asked first and the variable is ignored whenever git has a real answer.\n'
+    : (workingDirectory
+        ? '\n\n## Resolved local repository\n\n`' + workingDirectory + '`\n'
+        : '');
+  const brief = String(ticket.brief || '') + localWorktreeText +
     '\n\n## Your staging lane\n\n' +
     'Every `remits-cli` command you run stages into the **`' + workerWorkspace + '`** workspace lane, not the\n' +
     'shared one. This is set for you; you do not need to pass `--workspace`. It means your staged components\n' +
@@ -7446,6 +7933,12 @@ function spawnTicketWorker(context, ctx, ticket) {
   // worker spent its run fighting a restriction nobody had mentioned. The platform now returns the phase
   // it derived from the repository's edit lease, and that is the authority. The session's own --mode can
   // only narrow it: an operator who asked for a read-only agent gets one even when the lease is free.
+  //
+  // `working` is a THIRD phase, and it must fall on the edit side of this branch: it means the account
+  // declared that this ticket touches no repository, so no lease was taken and none was refused. A run
+  // like that is not restricted — it simply has no checkout to be exclusive about. Testing for
+  // `!== 'investigating'` rather than `=== 'editing'` is what keeps a new phase from silently demoting
+  // every non-repository worker to read-only.
   const effectiveMode = (ctx.mode === 'investigate' || ticket.phase === 'investigating')
     ? 'investigate'
     : 'edit';
@@ -7498,15 +7991,22 @@ function spawnTicketWorker(context, ctx, ticket) {
     sandbox: built.sandbox || null,
     startedAt: new Date().toISOString(),
     workingDirectory: workingDirectory || null,
+    targetBranch: targetBranch || null,
+    suggestedWorktree: suggestedWorktree || null,
     accountId: ticket.accountId || null,
     subject: ticket.subject || null,
     logFile
   });
   appendGlobalActivityLog('agent', 'worker.started', {
     agentId, ticketId, agentType, pid: child.pid, attempt, workingDirectory: workingDirectory || null,
+    targetBranch: targetBranch || null,
+    suggestedWorktree: suggestedWorktree || null,
     // Which phase a run started in is the first thing anyone asks when its output looks thin, so it is
     // on the record rather than inferable from a sandbox flag nobody logged.
-    phase: effectiveMode === 'investigate' ? 'investigating' : 'editing',
+    // Report the phase the PLATFORM derived, not the one this launcher collapsed it to: an operator
+    // reading `editing` on a ticket that never involved a repository would go looking for a lease that
+    // was correctly never taken.
+    phase: effectiveMode === 'investigate' ? 'investigating' : (ticket.phase || 'editing'),
     editLease: ticket.editLease ? { agentId: ticket.editLease.agentId, ticketId: ticket.editLease.ticketId } : null
   });
   if (ticket.phase === 'investigating' && ticket.editLeaseMessage) {
@@ -7637,6 +8137,7 @@ async function agentHeartbeatDaemonCommand(flags) {
     // worker kind must come from the flag it was started with, never from re-detection.
     workerAgent: workerAgentType(flags['worker-agent'] || flags.agent),
     mode: String(flags.mode || 'edit').toLowerCase() === 'investigate' ? 'investigate' : 'edit',
+    serves: parseServedWorkstreams(flags.serves),
     maxConcurrent: Math.max(1, parsePositiveInt(flags['max-concurrent'], 1)),
     runId: 'run-' + Date.now().toString(36)
   };
@@ -7742,6 +8243,31 @@ async function agentHeartbeatDaemonCommand(flags) {
           });
         }
 
+        // A supervisor sitting idle beside a full queue is either broken or doing exactly what it was
+        // told, and those look identical from outside. Logged ONCE per stretch of empty polls, because a
+        // reason repeated every few seconds is a log nobody reads.
+        const sweep = (response && response.sweep) || {};
+        if (emptyPolls === 0) {
+          if ((sweep.needsHumanTicketIds || []).length) {
+            appendGlobalActivityLog('agent', 'serve.needs_human', {
+              agentId,
+              ticketIds: sweep.needsHumanTicketIds,
+              message: sweep.needsHumanTicketIds.length + ' ticket(s) have been through this account\'s ' +
+                'autonomous-run limit (' + sweep.autonomousRunLimit + ') and are no longer offered to ' +
+                'workers. Answer, reopen or route one by hand: remits-cli ticket queue --min-runs 1'
+            }, 'warn');
+          }
+          if ((sweep.outOfScopeTicketIds || []).length) {
+            appendGlobalActivityLog('agent', 'serve.out_of_scope', {
+              agentId,
+              ticketIds: sweep.outOfScopeTicketIds,
+              message: sweep.outOfScopeTicketIds.length + ' unrouted ticket(s) are outside the workstreams ' +
+                'this session serves (' + (sweep.serves || []).join(', ') + '). That is the declaration ' +
+                'working; another session has to cover them.'
+            });
+          }
+        }
+
         for (const ticket of (response && response.tickets) || []) {
           const ticketId = String(ticket.id || ticket.ticketId || '');
           if (!ticketId || inFlight.has(ticketId)) {
@@ -7772,7 +8298,12 @@ async function agentHeartbeatDaemonCommand(flags) {
             'max-concurrent': String(ctx.maxConcurrent),
             json: 'true'
           },
-          { spawnHeartbeat: false }
+          // Re-register with THIS supervisor's declared bound and queues. The platform treats an absent
+          // `mode`/`serves` as "unchanged", which is right for a heartbeat against a live record and wrong
+          // here: this path runs precisely because the record EXPIRED, so there is nothing left to be
+          // unchanged from, and a specialised machine would come back as a generalist that can edit.
+          { spawnHeartbeat: false,
+            serve: { mode: ctx.mode, serves: ctx.serves, maxConcurrent: ctx.maxConcurrent } }
         ).catch((err) => {
           appendGlobalActivityLog('agent', 'heartbeat.reregister_failed',
             { agentId, error: describeError(err) }, 'error');
@@ -7908,6 +8439,28 @@ async function agentWorkCommand(flags) {
  * record, so the same commands work on every Remits platform — which is what an autonomous worker
  * needs, since its brief has to be written before anyone knows which platform it will run on.
  */
+/**
+ * Say that this ticket is governed, and say it loudly when the policy could not be parsed.
+ *
+ * A worker that only ever learns a rule exists by being refused by it has already wasted the call that
+ * hit it — the same argument that inlines the rules into a worker brief instead of pointing at them.
+ */
+function printTicketPolicy(response) {
+  const policy = response && response.policy;
+  if (!policy) return;
+  if (policy.error) {
+    console.error('POLICY NOT ENFORCED: this account has support-ticket rules that could not be parsed: ' +
+      policy.error);
+    console.error('  Report this on the ticket. Do not read the absence of a refusal as permission.');
+    return;
+  }
+  if (policy.ruleCount) {
+    console.log('Policy: ' + policy.ruleCount +
+      (policy.ruleCount === 1 ? ' rule governs' : ' rules govern') +
+      ' this ticket (' + (policy.ruleIds || []).join(', ') + ').');
+  }
+}
+
 async function ticketCommand(flags, subcommand) {
   const action = String(subcommand || 'read').toLowerCase();
 
@@ -7987,6 +8540,15 @@ async function ticketCommand(flags, subcommand) {
     size: planningFlagValue(flags.size),
     blockedBy: planningFlagValue(firstDefined(flags['blocked-by'], flags.blockedBy)),
     workstream: planningFlagValue(flags.workstream),
+    // Relations and commitments clear the same way a planning slot does — the flag with no value — so
+    // `--caused-by` alone detaches a ticket from its cluster rather than being read as "no change".
+    duplicateOf: planningFlagValue(firstDefined(flags['duplicate-of'], flags.duplicateOf)),
+    causedBy: planningFlagValue(firstDefined(flags['caused-by'], flags.causedBy)),
+    dueAt: planningFlagValue(firstDefined(flags['due-at'], flags.due, flags.dueAt)),
+    respondBy: planningFlagValue(firstDefined(flags['respond-by'], flags.respondBy)),
+    // Tri-state on the wire: 'true'/'false' are the two answers and absent is "not saying", which the
+    // platform reads as "keeps today's behaviour". Coercing here would erase the third state.
+    requiresRepositoryWork: firstDefined(flags['repo-work'], flags['requires-repository-work']),
     tags: flags.tags ? String(flags.tags).split(',').map((v) => v.trim()).filter(Boolean) : undefined,
     label: flags.label,
     url: flags.url,
@@ -8013,6 +8575,11 @@ async function ticketCommand(flags, subcommand) {
     agentId: flags['agent-id'] || process.env.REMITS_AGENT_ID || undefined,
     runId: flags['run-id'] || process.env.REMITS_WORKER_RUN_ID || undefined,
     agentLabel: flags['agent-label'] || undefined,
+    // The acknowledgement that gets a caller past a `require` rule. It is deliberately NOT enough on its
+    // own: the platform honours it only for an actor the rule permits, and it decides "human" from the
+    // ABSENCE of a run identity — which a worker process always sends. So a headless worker passing this
+    // is refused, and told so. The override, when it is honoured, is written to the ticket worklog.
+    acknowledge: flags.acknowledge || undefined,
     // WHERE this run is working, sent with every lifecycle call so the lease and the claim record THIS
     // process's checkout rather than the supervisor's. A ticket worker runs in its own workspace lane
     // (REMITS_WORKSPACE=ticket-<id>) and may run in its own worktree, so the two genuinely differ.
@@ -8045,6 +8612,8 @@ async function ticketCommand(flags, subcommand) {
     return;
   }
 
+  printTicketPolicy(response);
+
   if (flagEnabled(flags.json) || action === 'read' || action === 'deliveries') {
     console.log(JSON.stringify(response, null, 2));
     return;
@@ -8161,6 +8730,20 @@ async function ticketQueueCommand(flags) {
       boardStage: flags['board-stage'] || flags.boardStage,
       blockedBy: flags['blocked-by'] || flags.blockedBy,
       search: flags.search || flags.q,
+      // Every one of these reads a field the platform already mirrored and already projected, and that
+      // no surface could ask about. `syncState` in particular is how a broken integration is found:
+      // a failed sync retries forever, so it sits in pendingSync looking exactly like a healthy one.
+      syncStates: csv(flags['sync-state'] || flags.syncState),
+      overdue: flagEnabled(flags.overdue) || undefined,
+      relatedTo: flags['related-to'] || flags.relatedTo,
+      duplicateOf: flags['duplicate-of'] || flags.duplicateOf,
+      causedBy: flags['caused-by'] || flags.causedBy,
+      hasCause: flagEnabled(flags['has-cause'] || flags.hasCause) || undefined,
+      dueBefore: flags['due-before'] || flags.dueBefore,
+      dueAfter: flags['due-after'] || flags.dueAfter,
+      // "Which tickets has the fleet already tried and handed back." A mirrored field with no filter is a
+      // mirrored field nobody can act on — the same defect awaitingResponse and externalSyncState each had.
+      minAutonomousRuns: parsePositiveInt(flags['min-runs'] || flags.minRuns, 0) || undefined,
       sortBy: flags['sort-by'] || flags.sortBy,
       sortDirection: flags['sort-direction'] || flags.sortDirection,
       includeChildren: flags['include-children'] === 'false' ? false : undefined,
@@ -8181,7 +8764,15 @@ async function ticketQueueCommand(flags) {
   console.log(String(response.totalCount != null ? response.totalCount : tickets.length) +
     ' ticket(s) — ' + (counts.unrouted || 0) + ' unrouted, ' + (counts.unassigned || 0) + ' unassigned' +
     ', ' + (counts.awaitingResponse || 0) + ' waiting on a human' +
+    ((counts.needsHuman || 0) ? ', ' + counts.needsHuman + ' NEEDS A PERSON' : '') +
     '   [' + (response.dataMode || '?') + ' lane]');
+  if (counts.needsHuman) {
+    // The one count that measures a backlog the automation deliberately created. Without it the fleet
+    // reports healthy activity while the queue quietly stops going down.
+    console.log('  ' + counts.needsHuman + ' ticket(s) have been through this account\'s autonomous-run limit ' +
+      'and are no longer offered to workers.');
+    console.log('  Find them: remits-cli ticket queue --min-runs 1 --unassigned    (then answer, reopen, or route one by hand)');
+  }
   console.log('');
   // Board position is printed only when some ticket in this queue actually has one. An always-on column
   // would be blank for every account that does not run a board, and a blank column reads as missing data.
@@ -8199,6 +8790,7 @@ async function ticketQueueCommand(flags) {
     // and truncating `awaiting_customer_confirmation` to fit a column makes it unrecognisable.
     const marks = [
       t.awaitingResponseSince ? 'WAITING ON A HUMAN' : '',
+      t.autonomousRuns > 1 ? 'run ' + t.autonomousRuns + ' by workers' : '',
       showsBoard && t.boardStage ? 'stage ' + t.boardStage : '',
       showsBoard && t.plannedIn ? 'in ' + t.plannedIn : '',
       showsBoard && t.blockedBy ? 'BLOCKED BY ' + t.blockedBy : ''
@@ -8367,6 +8959,19 @@ function printTicketHelp() {
   console.log('            --planned-in --blocked-by --sort-by --sort-direction --limit --json');
   console.log('      --awaiting-response lists only tickets parked on a human. A status filter cannot');
   console.log('      ask that: `ask` parks a ticket in pending_review, which also means "done, review me".');
+  console.log('      --overdue lists tickets past a due time their account committed to; --sort-by due');
+  console.log('      ranks by it (soonest first; undated sorts last, in BOTH directions).');
+  console.log('      --sync-state failed finds tickets that cannot reach the system this account syncs');
+  console.log('      with. A failed sync retries forever, so it is indistinguishable from a healthy');
+  console.log('      pending one in `pendingSync` — this is how a broken integration is found before the');
+  console.log('      partner reports it.');
+  console.log('      --related-to ID lists the cluster around one ticket; --has-cause lists every ticket');
+  console.log('      that defers to another one.');
+  console.log('      --min-runs N finds tickets autonomous workers have already picked up N times and');
+  console.log('      handed back. Past this account\'s limit the sweep stops offering them, so they are a');
+  console.log('      backlog the automation deliberately created and nothing else surfaces: answer one');
+  console.log('      (`ticket answer`), reopen it, or route it by hand — an explicit route is never');
+  console.log('      vetoed by the limit.');
   console.log('  create --subject "..." --type defect|question|task|incident|enhancement');
   console.log('      Raise a ticket. Use it when you find a SECOND problem while working one — file it');
   console.log('      rather than widening the ticket you were given. [--priority --description --tags');
@@ -8407,8 +9012,9 @@ function printTicketHelp() {
   console.log('  reopen | assign --assignee EMAIL');
   console.log('  route --agent AGENT_ID                 Hand it to a registered agent session.');
   console.log('  unroute                               Clear its routing, e.g. when that session is gone.');
-  console.log('  tag --tags a,b                        Mark it. The cheapest way to make a cluster of');
-  console.log('      near-identical tickets visible as one cluster to whoever looks next.');
+  console.log('  tag --tags a,b                        Mark it, for a HUMAN reading the queue. When the');
+  console.log('      tickets genuinely share a cause, use `relate` instead or as well: the platform reads');
+  console.log('      that one, and a tag it cannot read will not stop a cluster being worked N times.');
   console.log('  artifact --type TYPE --label "..." [--url U | --content "..."]');
   console.log('      Attach evidence — a log, a query result, a repro. Better than pasting it into a');
   console.log('      worklog summary, where it is neither typed nor retrievable.');
@@ -8420,6 +9026,20 @@ function printTicketHelp() {
   console.log('  planning [--workstream V] [--planned-in V] [--board-stage V] [--rank N] [--size V] [--blocked-by V]');
   console.log('      Update organization-owned planning fields without changing platform lifecycle status.');
   console.log('      Pass a flag with no value to CLEAR that slot, e.g. --blocked-by');
+  console.log('  relate [--caused-by ID | --duplicate-of ID] [--reason "..."]');
+  console.log('      Say this ticket is part of a CLUSTER: N tickets, N requesters, one root cause.');
+  console.log('      Unlike a tag, the platform READS it — a ticket whose cause is being worked is not');
+  console.log('      handed out again while that work runs, so a cluster costs one worker and not N.');
+  console.log('      --duplicate-of: no separate work at all. --caused-by: this requester still needs');
+  console.log('      their own outcome once the cause is settled. A flag with no value clears it.');
+  console.log('  due --due-at 2026-09-08T17:00:00Z [--respond-by ...]');
+  console.log('      Record the times YOUR organization committed to. The platform stores, sorts and');
+  console.log('      filters these and never acts on them: no timer, no escalation. Build those as an');
+  console.log('      Action sweeping `ticket queue --overdue`.');
+  console.log('  repo-work --repo-work false');
+  console.log('      Declare that this ticket does not involve the repository — a documented answer, or');
+  console.log('      something only a person can do. A worker then takes no repository edit lease for it');
+  console.log('      and blocks nobody who needs the checkout. Absent means it DOES; nothing is inferred.');
   console.log('  force-unlease [--reason "..."]        Break a stale repository lease somebody else holds.');
   console.log('      For an operator only: unlease returns YOUR lease, this one takes away theirs, and it');
   console.log('      records a handoff worklog entry on the ticket so the intervention is visible.');
@@ -8458,6 +9078,23 @@ function runContextPayload(flags = {}) {
  * and they are opposite facts: the shared lane is exactly the one where concurrent agents overwrite
  * each other's staged components.
  */
+/**
+ * What a session was launched to do: the workstreams it covers and whether it may edit.
+ *
+ * Returns null for an unrestricted, edit-capable session — the default — so the line only ever appears
+ * when there IS a restriction to know about. A line that renders for everybody is a line nobody reads.
+ */
+function describeAgentScope(record) {
+  if (!record) return null;
+  const serves = Array.isArray(record.serves) ? record.serves.filter(Boolean) : [];
+  const readOnly = record.mode === 'investigate' || record.canEdit === false;
+  if (!serves.length && !readOnly) return null;
+  const parts = [];
+  parts.push(serves.length ? 'serves ' + serves.join(', ') : 'serves every workstream');
+  parts.push(readOnly ? 'investigate only (never edits or stages)' : 'may edit');
+  return parts.join('  ·  ');
+}
+
 function describeRunLocation(record) {
   if (!record) return '';
   const dir = record.workingDirectory || record.cwd || record.claimedWorkingDirectory;
@@ -8533,6 +9170,11 @@ async function agentWorkMapCommand(flags) {
         (agent.secondsSinceSeen != null ? '  seen ' + agent.secondsSinceSeen + 's ago' : ''));
       const at = describeRunLocation(agent);
       if (at) console.log('        ' + at);
+      // What this session is FOR, beside where it is. An operator reading a map of idle machines beside a
+      // full queue needs to see that they are idle BY DECLARATION — read-only, or serving other
+      // workstreams — not that routing is broken.
+      const bound = describeAgentScope(agent);
+      if (bound) console.log('        ' + bound);
       if (agent.activity) console.log('        ' + String(agent.activity).slice(0, 100));
     }
     console.log('');
@@ -8590,6 +9232,7 @@ async function agentListCommand(flags) {
     console.log('    lane     ' + (agent.dataMode || 'prod') +
       '   capacity ' + (agent.activeTicketCount || 0) + '/' + (agent.maxConcurrent || 1) +
       (agent.hasCapacity === false ? '  (at capacity — not routable)' : ''));
+    console.log('    serves   ' + (describeAgentScope(agent) || 'every workstream, and may edit'));
     if (agent.activity) console.log('    doing    ' + agent.activity);
     // Through describeRunLocation, which reads BOTH the canonical `workingDirectory` and the historical
     // `cwd`: a record written by an older platform, or still in Redis from before this field was
@@ -8715,6 +9358,7 @@ async function agentReleaseCommand(flags) {
   if (daemonPid) {
     workersStopped = listWorkers(agentId).length;
     try { process.kill(daemonPid, 'SIGTERM'); } catch (_) { /* already gone */ }
+    await waitForProcessExit(daemonPid, 5000);
   }
 
   const context = agentSessionFor(flags, local);
@@ -8750,6 +9394,7 @@ function printAgentHelp() {
   console.log('Usage: remits-cli agent <subcommand>');
   console.log('');
   console.log('  serve [--worker-agent claude|codex|gemini] [--max-concurrent N] [--mode edit|investigate]');
+  console.log('        [--serves support,incident,sdlc]');
   console.log('      Run this in a PLAIN TERMINAL TAB — that tab becomes the agent host. It returns');
   console.log('      immediately; a background supervisor launches ONE fresh headless agent process per');
   console.log('      routed ticket, in that account\'s repo, and that process exits when the ticket is');
@@ -8760,10 +9405,17 @@ function printAgentHelp() {
   console.log('      session is running (when you start it from inside one), else your');
   console.log('      `remits-cli config set --agent NAME` default. It prints which it chose and why.');
   console.log('      --mode investigate runs workers read-only (no file edits).');
+  console.log('      --serves declares which WORKSTREAMS this machine covers, so a fleet can be a set of');
+  console.log('      queues rather than interchangeable machines: --serves sdlc on one box, --serves');
+  console.log('      support,incident on another. Only those tickets are routed here and only those are');
+  console.log('      swept. Omit it to serve everything, which is the default. A workstream no live');
+  console.log('      session covers goes unrouted and is reported as no_agent_serves_workstream — the');
+  console.log('      declaration is honoured rather than quietly overridden, so check `agent map` after');
+  console.log('      specialising a fleet.');
   console.log('');
   console.log('  workers [--json]                     What this session is running right now.');
   console.log('');
-  console.log('  register [--label NAME] [--data-mode test|prod] [--base-url URL]');
+  console.log('  register [--label NAME] [--data-mode test|prod] [--base-url URL] [--serves a,b]');
   console.log('      Presence only — make THIS session routable without starting anything. Use it when a');
   console.log('      human, or the agent in this very tab, will work the tickets by hand. Runs from ANY');
   console.log('      directory — it registers for every account repo indexed on this machine that your');
@@ -9443,8 +10095,13 @@ async function main() {
     console.log('  - only which staged entries shadow them changes');
     console.log('');
     console.log('Typical setup, one worktree per agent, all on the same branch:');
-    console.log('  git worktree add ../ms-agent-a forked');
+    console.log('  git fetch origin');
+    console.log('  git switch forked');
+    console.log('  git pull --ff-only origin forked');
+    console.log('  git rev-list --left-right --count HEAD...origin/forked   # must print: 0  0');
+    console.log('  git worktree add --force ../ms-agent-a forked');
     console.log('  cd ../ms-agent-a && remits-cli workspace use --auto');
+    console.log('  remits-cli components status      # branch world + staging lane + other lanes');
     console.log('  remits-cli components stage          # isolated lane; nobody else sees it');
     console.log('  remits-cli test run --test 42        # resolves this lane over the forked variants');
     console.log('  remits-cli token --path /page/x      # its own browser token, in this lane');
@@ -9624,6 +10281,13 @@ async function main() {
 }
 
 main().catch((err) => {
+  // A REFUSAL is an answer, not a fault. The platform's sentence already says exactly what is wrong and
+  // what to do instead; wrapping it in "remits-cli error:" and a stack invites the caller to retry the
+  // identical call, which is the one thing a refused caller must not do.
+  if (err && err.refused) {
+    console.error('Refused: ' + err.message);
+    process.exit(1);
+  }
   if (process.env.REMITS_CLI_DEBUG_STACK === '1' && err && err.stack) {
     console.error(err.stack);
   }