ticlawk 0.1.16-dev.9 → 0.1.17-dev.1

package/src/core/agent-home.mjs

@@ -7,9 +7,10 @@
  * lives in cwd, agent reads it via `cat MEMORY.md`.
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readFileSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { AF_HOME } from './config.mjs';
+import { buildAgentHandbookFiles, LEGACY_HANDBOOK_FILE_NAMES } from '../runtimes/_shared/agent-handbook.mjs';
 
 export const AF_AGENTS_DIR = join(AF_HOME, 'agents');
 
@@ -37,9 +38,88 @@ export function ensureAgentHome(agentId, { displayName } = {}) {
   if (!existsSync(memoryPath)) {
     writeFileSync(memoryPath, buildInitialMemoryMd({ displayName, home }), 'utf8');
   }
+  writeManagedHandbookFiles(home);
+  ensureSkillSymlinks(home);
   return home;
 }
 
+function writeManagedHandbookFiles(home) {
+  removeLegacyManagedHandbookFiles(home);
+  for (const { name, content } of buildAgentHandbookFiles()) {
+    const path = join(home, name);
+    try {
+      let stat = null;
+      try { stat = lstatSync(path); } catch { /* not present */ }
+      if (stat && !stat.isFile()) continue;
+      const next = `${content.trim()}\n`;
+      if (stat) {
+        const current = readFileSync(path, 'utf8');
+        if (current === next) continue;
+      }
+      writeFileSync(path, next, { encoding: 'utf8', mode: 0o600 });
+    } catch (err) {
+      console.warn(`[agent-home] failed to write ${path}: ${err?.message || err}`);
+    }
+  }
+}
+
+function removeLegacyManagedHandbookFiles(home) {
+  for (const name of LEGACY_HANDBOOK_FILE_NAMES) {
+    const path = join(home, name);
+    try {
+      const stat = lstatSync(path);
+      if (!stat.isFile()) continue;
+      unlinkSync(path);
+    } catch (err) {
+      if (err?.code === 'ENOENT') continue;
+      console.warn(`[agent-home] failed to remove legacy handbook ${path}: ${err?.message || err}`);
+    }
+  }
+}
+
+/**
+ * Cross-runtime skill discovery: every runtime (Claude Code, Codex,
+ * opencode, pi, openclaw) auto-discovers SKILL.md under at least one of
+ * .claude/skills/, .codex/skills/, .opencode/skills/, .pi/skills/, or
+ * .agents/skills/. We pin everything to a single source-of-truth
+ * directory (.agents/skills/) and symlink the rest so a skill written
+ * once is visible to every runtime without sync machinery.
+ *
+ * .pi and .opencode skip the symlink — both natively scan
+ * .agents/skills/ in addition to their own folder.
+ *
+ * No migration / no recovery: if the target path already exists as a
+ * real dir or wrong-target symlink, we leave it alone. The user (or a
+ * future agent) resolves it manually. See cos_impl.md §一.不为错误兜底.
+ */
+function ensureSkillSymlinks(home) {
+  const realRoot = join(home, '.agents', 'skills');
+  mkdirSync(realRoot, { recursive: true });
+
+  const links = [
+    { dir: join(home, '.claude'), name: 'skills', target: '../.agents/skills' },
+    { dir: join(home, '.codex'), name: 'skills', target: '../.agents/skills' },
+    // openclaw expects skills/ at the home root
+    { dir: home, name: 'skills', target: '.agents/skills' },
+  ];
+
+  for (const { dir, name, target } of links) {
+    mkdirSync(dir, { recursive: true });
+    const linkPath = join(dir, name);
+    let stat = null;
+    try { stat = lstatSync(linkPath); } catch { /* not present */ }
+    if (stat) continue; // path already exists — do not touch
+    try {
+      symlinkSync(target, linkPath, 'dir');
+    } catch (err) {
+      // Best-effort: an EEXIST race or platform that disallows symlinks
+      // gets logged but doesn't fail spawn. Skills just won't be visible
+      // for that runtime via this folder.
+      console.warn(`[agent-home] failed to symlink ${linkPath} -> ${target}: ${err?.message || err}`);
+    }
+  }
+}
+
 function buildInitialMemoryMd({ displayName, home }) {
   const lines = [
     `# ${displayName || 'Agent'}`,

package/src/core/argv.mjs

@@ -29,7 +29,17 @@ export function parseOptionArgs(argv = []) {
       const value = inlineValue !== undefined
         ? inlineValue
         : argv[i + 1] && !argv[i + 1].startsWith('-') ? argv[++i] : true;
-      args[rawKey] = value;
+      // Repeated flags collect into an array so `--attach a --attach b`
+      // surfaces as ['a','b'] to callers that expect repeatable input
+      // (--attach on message send, --member on group create, etc).
+      // First occurrence stays scalar so single-value callers don't
+      // have to learn array-or-string.
+      if (Object.prototype.hasOwnProperty.call(args, rawKey)) {
+        const existing = args[rawKey];
+        args[rawKey] = Array.isArray(existing) ? [...existing, value] : [existing, value];
+      } else {
+        args[rawKey] = value;
+      }
       continue;
     }
     args._.push(arg);

package/src/core/events/worker-events.mjs

@@ -1,22 +1,9 @@
-import { createHash } from 'node:crypto';
-
 const workerEventSeq = new Map();
-const DELTA_LOG_PREVIEW_CHARS = 48;
 
 function shortId(value) {
   return value ? String(value).slice(0, 8) : null;
 }
 
-function hashText(text) {
-  return createHash('sha1').update(String(text)).digest('hex').slice(0, 12);
-}
-
-function previewDelta(text) {
-  const normalized = String(text).replace(/\n/g, '\\n');
-  if (normalized.length <= DELTA_LOG_PREVIEW_CHARS) return normalized;
-  return normalized.slice(0, DELTA_LOG_PREVIEW_CHARS) + '…';
-}
-
 function nextWorkerEventMeta({ agent, sessionId, turnId }) {
   const key = `${agent}:${sessionId || ''}:${turnId || 'session'}`;
   const seq = (workerEventSeq.get(key) || 0) + 1;
@@ -37,6 +24,16 @@ export async function emitWorkerEvent({ adapter, binding, agent, sessionId, cwd
   if (!sessionId || typeof adapter.emitEvent !== 'function') return;
   const eventName = event?.worker_event_name || event?.hook_event_name || 'unknown';
   const logicalTurnId = replyToMessageId || turnId || event?.turn_id || null;
+  if (eventName === 'worker.message.delta') {
+    logger?.debugLog?.('events', 'delta.drop', {
+      bindingId: binding.id,
+      agent,
+      sessionId: shortId(sessionId),
+      turnId: shortId(logicalTurnId),
+      chars: typeof event?.delta === 'string' ? event.delta.length : null,
+    });
+    return;
+  }
   const { key, seq, originTs } = nextWorkerEventMeta({ agent, sessionId, turnId: logicalTurnId });
   const enrichedEvent = {
     ...event,
@@ -45,29 +42,14 @@ export async function emitWorkerEvent({ adapter, binding, agent, sessionId, cwd
     event_seq: seq,
     origin_ts: originTs,
   };
-  if (typeof event?.delta === 'string' && event.delta) {
-    enrichedEvent.delta_chars = event.delta.length;
-    enrichedEvent.delta_hash = hashText(event.delta);
-    logger?.debugLog?.('events', 'delta.recv', {
-      bindingId: binding.id,
-      agent,
-      sessionId: shortId(sessionId),
-      turnId: shortId(logicalTurnId),
-      seq,
-      chars: event.delta.length,
-      hash: enrichedEvent.delta_hash,
-      preview: previewDelta(event.delta),
-    });
-  } else {
-    logger?.debugLog?.('events', 'event.recv', {
-      bindingId: binding.id,
-      agent,
-      sessionId: shortId(sessionId),
-      turnId: shortId(logicalTurnId),
-      seq,
-      eventName,
-    });
-  }
+  logger?.debugLog?.('events', 'event.recv', {
+    bindingId: binding.id,
+    agent,
+    sessionId: shortId(sessionId),
+    turnId: shortId(logicalTurnId),
+    seq,
+    eventName,
+  });
   await adapter.emitEvent(binding, {
     agent,
     sessionId,
@@ -78,3 +60,17 @@ export async function emitWorkerEvent({ adapter, binding, agent, sessionId, cwd
     clearWorkerEventMeta(key);
   }
 }
+
+export function emitWorkerEventBestEffort(args) {
+  void emitWorkerEvent(args).catch((err) => {
+    const event = args?.event || {};
+    const eventName = event.worker_event_name || event.hook_event_name || 'unknown';
+    args?.logger?.debugError?.('events', 'event.best-effort-failed', {
+      bindingId: args?.binding?.id || null,
+      agent: args?.agent || null,
+      sessionId: shortId(args?.sessionId),
+      eventName,
+      error: err?.message || 'unknown error',
+    });
+  });
+}

package/src/core/http.mjs

@@ -3,6 +3,25 @@ import {
   handleAttachmentUpload,
   handleAttachmentView,
   handleGroupCreate,
+  handleWorkstreamCharterGet,
+  handleWorkstreamCharterSet,
+  handleWorkstreamCreate,
+  handleWorkstreamDelete,
+  handleWorkstreamList,
+  handleAgentList,
+  handleAgentCreate,
+  handleAgentDelete,
+  handleWorkstreamDashboardSet,
+  handleWorkstreamDashboardGet,
+  handleCredentialRequest,
+  handleBriefingPublish,
+  handleBriefingGet,
+  handleServiceCreate,
+  handleServiceUpdate,
+  handleServiceDelete,
+  handleServiceList,
+  handleServiceInfo,
+  handleServiceCall,
   handleGroupMembers,
   handleGroupMembersAdd,
   handleGroupMembersRemove,
@@ -20,6 +39,11 @@ import {
   handleReminderSchedule,
   handleReminderSnooze,
   handleReminderUpdate,
+  handleGoalChanged,
+  handleGoalReport,
+  handleApprovalRequest,
+  handleApprovalResolve,
+  handleApprovalList,
   handleServerInfo,
   handleTaskClaim,
   handleTaskCreate,
@@ -125,6 +149,34 @@ export function startLocalHttpServer({ port, adapter, ctx }) {
         const r = await handleTaskList(req, parseQuery(req.url || ''), cliCtx);
         return writeJson(res, r.status, r.body);
       }
+      if (urlNoQuery === '/agent/goal/report' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleGoalReport(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/goal/changed' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleGoalChanged(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/approval/request' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleApprovalRequest(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/approval/resolve' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleApprovalResolve(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/approval/list' && method === 'GET') {
+        const r = await handleApprovalList(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
       if (urlNoQuery === '/agent/message/react' && method === 'POST') {
         const body = await readJsonBody(req);
         if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
@@ -223,6 +275,106 @@ export function startLocalHttpServer({ port, adapter, ctx }) {
         const r = await handleServerInfo(req, parseQuery(req.url || ''), cliCtx);
         return writeJson(res, r.status, r.body);
       }
+      if (urlNoQuery === '/agent/workstream/charter/get' && method === 'GET') {
+        const r = await handleWorkstreamCharterGet(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/workstream/charter/set' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleWorkstreamCharterSet(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/workstream/create' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleWorkstreamCreate(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/workstream/delete' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleWorkstreamDelete(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/workstream/list' && method === 'GET') {
+        const r = await handleWorkstreamList(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/agent/list' && method === 'GET') {
+        const r = await handleAgentList(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/agent/create' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleAgentCreate(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/agent/delete' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleAgentDelete(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/dashboard/set' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleWorkstreamDashboardSet(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/dashboard/get' && method === 'GET') {
+        const r = await handleWorkstreamDashboardGet(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/briefing/publish' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleBriefingPublish(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/briefing/get' && method === 'GET') {
+        const r = await handleBriefingGet(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/credential/request' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleCredentialRequest(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/service/create' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleServiceCreate(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/service/update' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleServiceUpdate(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/service/delete' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleServiceDelete(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/service/list' && method === 'GET') {
+        const r = await handleServiceList(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/service/info' && method === 'GET') {
+        const r = await handleServiceInfo(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/service/call' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleServiceCall(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
 
       writeJson(res, 404, { error: 'not found' });
     } catch (err) {

package/src/core/runtime-contract.mjs

@@ -55,7 +55,6 @@ import { normalizeServiceType } from './runtime-registry.mjs';
  * @property {(inbound: any, ctx: RuntimeDeliveryContext) => Promise<boolean>} deliverTurn
  * @property {(binding: any, ctx: { adapter: any, logger: any }) => (Promise<void>|void)} [onBindingUpdated]
  * @property {(ctx: { adapter: any, getBinding: (bindingId: string) => any }) => (Promise<number>|number)} [recoverInFlight]
- * @property {(binding: any, ctx: { adapter: any, logger: any }) => (Promise<number>|number)} [reconcileAfterRestart]
  */
 
 /**

package/src/core/runtime-env.mjs

@@ -15,6 +15,7 @@
 const STRIPPED_KEYS = new Set([
   'TICLAWK_CONNECTOR_API_KEY',
   'TICLAWK_CONNECTOR_WS_URL',
+  'TICLAWK_CREDENTIAL_NAMES',
   'TICLAWK_SETUP_CODE',
 ]);
 
@@ -35,11 +36,17 @@ export function buildAgentRuntimeEnv({
   sessionId,
   hostId,
   daemonUrl,
+  conversationId,
+  messageId,
+  target,
 } = {}) {
   const out = {};
   if (agentId) out.TICLAWK_RUNTIME_AGENT_ID = String(agentId);
   if (sessionId) out.TICLAWK_RUNTIME_SESSION_ID = String(sessionId);
   if (hostId) out.TICLAWK_RUNTIME_HOST_ID = String(hostId);
+  if (conversationId) out.TICLAWK_RUNTIME_CONVERSATION_ID = String(conversationId);
+  if (messageId) out.TICLAWK_RUNTIME_MESSAGE_ID = String(messageId);
+  if (target) out.TICLAWK_RUNTIME_TARGET = String(target);
   out.TICLAWK_RUNTIME_DAEMON_URL = daemonUrl || 'http://127.0.0.1:8741';
   return out;
 }

package/src/core/runtime-support.mjs

@@ -1,8 +1,8 @@
 import { getStreamingMode } from './config.mjs';
 import { getAgentHome } from './agent-home.mjs';
+import { debugError } from './logger.mjs';
 const ERROR_MAX_CHARS = 500;
-const DEFAULT_DELTA_FLUSH_MS = 250;
-const DEFAULT_DELTA_FLUSH_CHARS = 64;
+const MAX_SCOPED_RUNTIME_SESSIONS = 50;
 
 function truncateError(text) {
   if (!text) return null;
@@ -74,12 +74,21 @@ export async function reportSubprocessFailure({ adapter, binding, inbound, runti
   // skips fan-out to member-role agents, breaking what would otherwise
   // be a failure→fan-out→failure cascade when several agents share a
   // broken runtime.
-  await adapter.postAgentReply(binding, {
-    conversationId: inbound?.conversationId || null,
-    text,
-    replyToMessageId: inbound?.messageId || null,
-    visibility: 'admin',
-  });
+  try {
+    await adapter.postAgentReply(binding, {
+      conversationId: inbound?.conversationId || null,
+      text,
+      replyToMessageId: inbound?.messageId || null,
+      visibility: 'admin',
+    });
+  } catch (err) {
+    debugError('runtime', 'failure-notice.failed', {
+      agentId: binding?.id || null,
+      runtimeName,
+      messageId: inbound?.messageId || null,
+      error: err?.message || 'unknown error',
+    });
+  }
 }
 
 export function terminalRuntimeFailure(reason = 'runtime failure') {
@@ -105,80 +114,123 @@ export async function updateBindingRuntimeMeta(ctx, binding, runtimeMetaPatch, e
   });
 }
 
-export function createDeltaAggregator({
-  flushDelta,
-  flushMs = DEFAULT_DELTA_FLUSH_MS,
-  flushChars = DEFAULT_DELTA_FLUSH_CHARS,
-}) {
-  let buffer = '';
-  let pendingMeta = null;
-  let timer = null;
-  let flushChain = Promise.resolve();
-
-  const clearTimer = () => {
-    if (!timer) return;
-    clearTimeout(timer);
-    timer = null;
-  };
+function readScopedSessionKey(inbound = {}) {
+  const conversationId = String(inbound?.conversationId || '').trim();
+  if (!conversationId) return '';
+  const threadRoot = String(inbound?.raw?.thread_root_message_id || '').trim();
+  return threadRoot ? `${conversationId}:thread:${threadRoot}` : conversationId;
+}
 
-  const startFlush = () => {
-    if (!buffer || typeof flushDelta !== 'function') return flushChain;
-    const text = buffer;
-    const meta = pendingMeta || {};
-    buffer = '';
-    pendingMeta = null;
-    clearTimer();
-    flushChain = flushChain
-      .catch(() => {})
-      .then(() => flushDelta({ text, ...meta }));
-    return flushChain;
-  };
+function normalizeScopedRuntimeSessions(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  const out = {};
+  for (const [key, session] of Object.entries(value)) {
+    if (!key || !session || typeof session !== 'object' || Array.isArray(session)) continue;
+    const sessionId = typeof session.sessionId === 'string' ? session.sessionId.trim() : '';
+    if (!sessionId) continue;
+    out[key] = {
+      sessionId,
+      path: typeof session.path === 'string' ? session.path : null,
+      lastRotatedAt: typeof session.lastRotatedAt === 'string' ? session.lastRotatedAt : null,
+      updatedAt: typeof session.updatedAt === 'string' ? session.updatedAt : null,
+    };
+  }
+  return out;
+}
 
-  const scheduleFlush = () => {
-    if (!buffer || timer) return;
-    timer = setTimeout(() => {
-      timer = null;
-      void startFlush();
-    }, flushMs);
-    timer.unref?.();
-  };
+function pruneScopedRuntimeSessions(sessions) {
+  const entries = Object.entries(sessions);
+  if (entries.length <= MAX_SCOPED_RUNTIME_SESSIONS) return sessions;
+  return Object.fromEntries(entries
+    .sort(([, a], [, b]) => {
+      const aTs = Date.parse(a?.updatedAt || a?.lastRotatedAt || '') || 0;
+      const bTs = Date.parse(b?.updatedAt || b?.lastRotatedAt || '') || 0;
+      return bTs - aTs;
+    })
+    .slice(0, MAX_SCOPED_RUNTIME_SESSIONS));
+}
 
+// The chat lane and the goal-FSM lane keep separate scoped session maps so a
+// transition turn never resumes a user-chat runtime session (their per-step
+// prompts and context differ). Lane is carried on the inbound; default chat.
+function laneSessionsField(lane) {
+  return lane === 'goal' ? 'goalSessions' : 'chatSessions';
+}
+
+export function resolveRuntimeSessionScope(meta = {}, inbound = {}) {
+  const lane = inbound?.lane === 'goal' ? 'goal' : 'chat';
+  const field = laneSessionsField(lane);
+  const key = readScopedSessionKey(inbound);
+  if (!key) {
+    return {
+      key: '',
+      lane,
+      field,
+      sessions: {},
+      sessionId: meta.sessionId || null,
+      path: meta.path || null,
+      lastRotatedAt: meta.lastRotatedAt || null,
+      shouldRotate: !meta.sessionId || Boolean(meta.rotatePending),
+    };
+  }
+
+  const sessions = meta.rotatePending ? {} : normalizeScopedRuntimeSessions(meta[field]);
+  const scoped = sessions[key] || {};
   return {
-    push(text, meta = {}) {
-      const normalized = typeof text === 'string' ? text : '';
-      if (!normalized) return;
-
-      const nextMeta = {
-        sessionId: meta.sessionId || null,
-        turnId: meta.turnId || null,
-        cwd: meta.cwd || '',
-      };
-
-      const sameContext = !pendingMeta
-        || (
-          pendingMeta.sessionId === nextMeta.sessionId
-          && pendingMeta.turnId === nextMeta.turnId
-          && pendingMeta.cwd === nextMeta.cwd
-        );
-
-      if (!sameContext && buffer) {
-        void startFlush();
-      }
-
-      pendingMeta = nextMeta;
-      buffer += normalized;
-
-      if (buffer.length >= flushChars) {
-        void startFlush();
-        return;
-      }
-
-      scheduleFlush();
-    },
+    key,
+    lane,
+    field,
+    sessions,
+    sessionId: scoped.sessionId || null,
+    path: scoped.path || null,
+    lastRotatedAt: scoped.lastRotatedAt || null,
+    shouldRotate: !scoped.sessionId || Boolean(meta.rotatePending),
+  };
+}
 
-    async flush() {
-      clearTimer();
-      await startFlush();
-    },
+export function buildRuntimeSessionMetaPatch(meta = {}, scope = {}, result = {}) {
+  const now = new Date().toISOString();
+  const scoped = Boolean(scope.key);
+  const lane = scope.lane === 'goal' ? 'goal' : 'chat';
+  const field = scope.field || laneSessionsField(lane);
+  const sessionId = result?.sessionId || scope.sessionId || (scoped ? null : meta.sessionId || null);
+  const path = result?.path || scope.path || (scoped ? null : meta.path || null);
+  const lastRotatedAt = scope.shouldRotate
+    ? now
+    : (scope.lastRotatedAt || meta.lastRotatedAt || now);
+
+  if (!scoped) {
+    return {
+      sessionId,
+      ...(path !== undefined ? { path } : {}),
+      rotatePending: false,
+      lastRotatedAt,
+    };
+  }
+
+  const sessions = {
+    ...(scope.sessions || {}),
   };
+  if (sessionId) {
+    sessions[scope.key] = {
+      sessionId,
+      path,
+      lastRotatedAt,
+      updatedAt: now,
+    };
+  }
+
+  const patch = {
+    [field]: pruneScopedRuntimeSessions(sessions),
+    rotatePending: false,
+    lastRotatedAt,
+  };
+  // The flat sessionId/path is the chat lane's "last used" mirror, read only
+  // by non-scoped resolution and display. The goal lane owns its own map and
+  // must not clobber that mirror.
+  if (lane === 'chat') {
+    patch.sessionId = sessionId;
+    patch.path = path;
+  }
+  return patch;
 }