claude-code-session-manager 0.109.0 → 0.111.0

package/src/main/build-info.json

@@ -1,8 +1,8 @@
 {
-  "version": "0.109.0",
-  "gitSha": "14869c8ae8d91422ea84f5b1e1fb483349544a80",
-  "gitShortSha": "14869c8a",
+  "version": "0.111.0",
+  "gitSha": "ca0cbc30d2ee72698993f0f07f878a932843c758",
+  "gitShortSha": "ca0cbc30",
   "gitBranch": "HEAD",
-  "builtAt": "2026-10-10T21:41:36.398Z",
+  "builtAt": "2026-10-11T04:47:08.011Z",
   "dirty": false
 }

package/src/main/chatRunner.cjs

@@ -970,6 +970,12 @@ function enqueueExternalPrompt(tabId, prompt) {
   broadcast('chat:external-send', { tabId, prompt });
 }
 
+// Asks the renderer to start a new Session (same launchSession a macro press
+// uses) on behalf of the paired phone. Payload is pre-validated by the caller.
+function requestExternalNewSession(payload) {
+  broadcast('chat:external-new-session', payload);
+}
+
 /**
  * Registers the admin-HTTP entry point for enqueueExternalPrompt, mirroring
  * prdCreate.cjs's registerAdminRoute pattern (auth is the injected transport's
@@ -1050,5 +1056,6 @@ module.exports = {
   WARN_CEILING_MS,
   __setExecutor,
   enqueueExternalPrompt,
+  requestExternalNewSession,
   registerAdminRoute,
 };

package/src/main/index.cjs

@@ -130,6 +130,7 @@ const filesIpc = require('./files.cjs');
 const { registerDocEditHandlers, attachWindow: attachDocEditWindow } = require('./docEdit.cjs');
 const webRemote = require('./webRemote.cjs');
 const { registerRemoteClientHandlers } = require('./remoteClientIpc.cjs');
+const { registerUpdaterIpc } = require('./updaterIpc.cjs');
 const { listExchanges } = require('./exchanges.cjs');
 const { resolveClaudeBin } = require('./lib/claudeBin.cjs');
 const { checkInsideHome, assertInsideHome } = require('./lib/insideHome.cjs');
@@ -1100,6 +1101,11 @@ filesIpc.registerFilesHandlers();
 registerDocEditHandlers();
 webRemote.registerRemoteHandlers();
 registerRemoteClientHandlers(() => mainWindow);
+try {
+  registerUpdaterIpc({ ipcMain, getWindow: () => mainWindow, ptyManager });
+} catch (e) {
+  logs.writeLine({ scope: 'main', level: 'error', message: 'updater IPC registration failed', meta: { error: e?.message } });
+}
 chatRunner.registerChatHandlers();
 
 // Direct in-process PRD authoring for a queued PromptTicket classified

package/src/main/ipcSchemas.cjs

@@ -944,6 +944,19 @@ const chatExternalSend = z.object({
   ),
 });
 
+// Phone-initiated new Session. cwd/agentName are re-checked against the open
+// tabs / persona list in webRemote.cjs before anything touches the filesystem.
+const remoteSessionCreate = z.object({
+  cwd: z.string().min(1).max(4096),
+  agentName: z.string().regex(/^[A-Za-z0-9._-]{1,64}$/),
+  tag: EpicTagSchema,
+  title: z.string().min(1).max(120),
+  prompt: z.string().min(1).refine(
+    (s) => Buffer.byteLength(s, 'utf8') <= CHAT_PROMPT_MAX_BYTES,
+    `prompt must be ≤ ${CHAT_PROMPT_MAX_BYTES} bytes`,
+  ),
+});
+
 // ──────────────────────────────────────────── Web Remote
 // OTP is 8 uppercase alphanumeric chars (case-insensitive entry, normalised to upper in handler).
 const WEB_REMOTE_OTP_RE = /^[A-Z0-9]{8}$/i;
@@ -957,6 +970,11 @@ const webRemoteRevokeDevice = z.object({
   deviceId: z.string().regex(DEVICE_ID_RE),
 }).strict();
 
+// Optional payload: omit (undefined) to confirm the single pending client.
+const webRemoteConfirmSas = z.object({
+  clientKey: z.string().max(64).optional(),
+}).strict().optional();
+
 const webRemoteAuditTail = z.object({
   lines: z.number().int().min(1).max(500).optional(),
 }).strict();
@@ -1137,9 +1155,11 @@ function validated(schema, handler) {
 //
 // Ungated READ_COMMANDS (justify each):
 //   cmd:app:version      — exposes only the app semver string; no user data.
+//   cmd:app:info         — exposes only app semver + OS platform string; no user data.
 //   cmd:session:unsubscribe — teardown lifecycle; returns nothing sensitive.
 const READ_COMMANDS = new Set([
   'cmd:app:version',
+  'cmd:app:info',
   // v2 mobile: unsubscribe is a teardown lifecycle call with no data payload.
   'cmd:session:unsubscribe',
 ]);
@@ -1147,9 +1167,13 @@ const READ_COMMANDS = new Set([
 // Sensitive reads — return user data; require SAS confirmation same as MUTATE.
 const SAS_GATED_READS = new Set([
   'cmd:sessions:load',
+  // Same data as the event:session:list push (projects + their active Epics).
+  'cmd:sessions:list',
   'cmd:history:aggregate',
   // subscribe initiates a live stream of session state/summary — sensitive.
   'cmd:session:subscribe',
+  // Picker data (projects, personas, tags, macros) for the phone's New Session.
+  'cmd:session:options',
   // NOTE: cmd:exchanges:list is intentionally NOT allowlisted — webRemote.cjs has
   // no dispatch handler for it, so an allowlist entry would only fail closed with
   // an opaque reject. Re-add here together with the handler when remote exchanges
@@ -1175,6 +1199,8 @@ const MUTATE_COMMANDS = new Set([
   // Pushes a prompt into an open tab's chat queue — a real mutation of that
   // tab's session, same tier as pty:write.
   'cmd:chat:send',
+  // Starts a new Session on the desktop via the renderer's launchSession.
+  'cmd:session:create',
 ]);
 
 const ALLOWED_COMMANDS = new Set([...READ_COMMANDS, ...SAS_GATED_READS, ...MUTATE_COMMANDS]);
@@ -1193,6 +1219,7 @@ module.exports = {
     webRemotePair,
     webRemoteRevokeDevice,
     webRemoteAuditTail,
+    webRemoteConfirmSas,
     sessionSubscribe,
     ptySpawn,
     ptyTabId,
@@ -1284,6 +1311,7 @@ module.exports = {
     chatCancel,
     chatClassifyTicket,
     chatExternalSend,
+    remoteSessionCreate,
     exchangesList,
     agentsSavePersona,
     macrosSave,

package/src/main/lib/autoUpdater.cjs

@@ -0,0 +1,190 @@
+'use strict';
+
+/**
+ * autoUpdater.cjs — pure, dependency-injected state machine around electron-updater's autoUpdater.
+ *
+ * Requires neither electron nor electron-updater: the caller injects the updater instance. The feed is
+ * whatever app-update.yml electron-builder baked into the installer; this module never supplies a feed URL.
+ * Checks on start() and every 4h, downloads in the background, and installs ONLY after requestInstall() —
+ * deferring (polling isBusy every 60s) while scheduler jobs or terminals are busy.
+ */
+
+const CHECK_INTERVAL_MS = 4 * 60 * 60 * 1000;
+const BUSY_POLL_MS = 60 * 1000;
+
+/** Unsigned mac builds cannot use Squirrel.Mac, so darwin is always unsupported. */
+function isAutoUpdateSupported({ packaged, platform, env }) {
+  const e = env || {};
+  if (packaged !== true) return false;
+  if (e.SM_AUTO_UPDATE === '0' || e.SM_E2E === '1') return false;
+  if (platform === 'win32') return true;
+  return platform === 'linux' && typeof e.APPIMAGE === 'string' && e.APPIMAGE.length > 0;
+}
+
+function createAutoUpdater({
+  updater, supported, currentVersion, isBusy, getEnabled,
+  setInterval: setIntervalFn = setInterval, clearInterval: clearIntervalFn = clearInterval,
+  now = Date.now, log = () => {},
+}) {
+  let enabledOverride = null;
+  let started = false;
+  let listening = false;
+  let checkTimer = null;
+  let pollTimer = null;
+  const subscribers = new Set();
+
+  const isEnabled = () => {
+    if (enabledOverride !== null) return enabledOverride;
+    return typeof getEnabled === 'function' ? getEnabled() !== false : true;
+  };
+
+  let snapshot = {
+    state: supported ? 'idle' : 'unsupported',
+    current: currentVersion,
+    latest: null,
+    progress: null,
+    error: null,
+    busyReason: null,
+    lastCheckedAt: null,
+  };
+
+  function setState(patch) {
+    const next = { ...snapshot, ...patch };
+    if (Object.keys(next).every((k) => next[k] === snapshot[k])) return;
+    snapshot = next;
+    for (const fn of [...subscribers]) {
+      try { fn(snapshot); } catch (e) { log('autoUpdater subscriber threw', e); }
+    }
+  }
+
+  const holding = () => snapshot.state === 'ready' || snapshot.state === 'deferred';
+
+  function fail(e) {
+    const message = e && e.message ? e.message : String(e);
+    log('autoUpdater error', message);
+    setState({ state: 'error', error: message, progress: null });
+  }
+
+  function clearPoll() {
+    if (pollTimer !== null) { clearIntervalFn(pollTimer); pollTimer = null; }
+  }
+
+  function clearChecks() {
+    if (checkTimer !== null) { clearIntervalFn(checkTimer); checkTimer = null; }
+  }
+
+  function attach() {
+    if (listening) return;
+    listening = true;
+    updater.autoDownload = true;
+    updater.autoInstallOnAppQuit = true;
+    updater.allowPrerelease = false;
+    updater.allowDowngrade = false;
+    updater.on('checking-for-update', () => {
+      if (!holding()) setState({ state: 'checking', error: null });
+    });
+    updater.on('update-available', (info) => {
+      if (!holding()) setState({ state: 'downloading', latest: info && info.version ? info.version : null, progress: null, error: null });
+    });
+    updater.on('download-progress', (p) => {
+      if (!holding()) setState({ state: 'downloading', progress: p && typeof p.percent === 'number' ? p.percent : null });
+    });
+    updater.on('update-downloaded', (info) => {
+      setState({ state: 'ready', latest: info && info.version ? info.version : snapshot.latest, progress: 100, error: null, busyReason: null });
+    });
+    updater.on('update-not-available', () => {
+      if (!holding()) setState({ state: 'idle', latest: null, progress: null, error: null });
+    });
+    updater.on('error', (e) => {
+      if (!holding()) fail(e);
+    });
+  }
+
+  async function checkNow() {
+    if (!supported || !isEnabled()) return;
+    if (holding() || snapshot.state === 'checking' || snapshot.state === 'downloading') return;
+    attach();
+    setState({ state: 'checking', error: null, lastCheckedAt: now() });
+    try {
+      await updater.checkForUpdates();
+    } catch (e) {
+      fail(e);
+    }
+  }
+
+  function startChecks() {
+    clearChecks();
+    checkTimer = setIntervalFn(() => { checkNow(); }, CHECK_INTERVAL_MS);
+    if (checkTimer && typeof checkTimer.unref === 'function') checkTimer.unref();
+    checkNow();
+  }
+
+  function applyEnabled() {
+    if (!supported) return;
+    if (!isEnabled()) {
+      clearChecks();
+      clearPoll();
+      setState({ state: 'disabled', busyReason: null, progress: null, error: null });
+      return;
+    }
+    if (snapshot.state === 'disabled') setState({ state: 'idle' });
+    if (started) startChecks();
+  }
+
+  function start() {
+    if (!supported || started) return;
+    started = true;
+    applyEnabled();
+  }
+
+  function stop() {
+    started = false;
+    clearChecks();
+    clearPoll();
+  }
+
+  function setEnabled(value) {
+    enabledOverride = !!value;
+    applyEnabled();
+  }
+
+  function install() {
+    clearPoll();
+    try {
+      updater.quitAndInstall(false, true);
+    } catch (e) {
+      fail(e);
+    }
+  }
+
+  function requestInstall({ force } = {}) {
+    if (!supported || !holding()) return;
+    if (snapshot.state === 'deferred' && !force) return;
+    if (force) { install(); return; }
+    const b = isBusy ? isBusy() : { busy: false };
+    if (!b || !b.busy) { install(); return; }
+    setState({ state: 'deferred', busyReason: b.reason || null });
+    clearPoll();
+    pollTimer = setIntervalFn(() => {
+      const cur = isBusy ? isBusy() : { busy: false };
+      if (cur && cur.busy) { setState({ busyReason: cur.reason || null }); return; }
+      install();
+    }, BUSY_POLL_MS);
+    if (pollTimer && typeof pollTimer.unref === 'function') pollTimer.unref();
+  }
+
+  function cancelDeferred() {
+    if (snapshot.state !== 'deferred') return;
+    clearPoll();
+    setState({ state: 'ready', busyReason: null });
+  }
+
+  function subscribe(fn) {
+    subscribers.add(fn);
+    return () => { subscribers.delete(fn); };
+  }
+
+  return { start, stop, checkNow, requestInstall, cancelDeferred, setEnabled, status: () => snapshot, subscribe };
+}
+
+module.exports = { isAutoUpdateSupported, createAutoUpdater, CHECK_INTERVAL_MS, BUSY_POLL_MS };

package/src/main/lib/builtinMacros.cjs

@@ -30,9 +30,9 @@ const BUILTIN_MACROS = Object.freeze([
     tag: 'project-home-builder',
     surface: 'project-home',
     projects: ['*'],
-    builtinVersion: 3,
+    builtinVersion: 4,
     prompt:
-      'Generate a 30-second demo video for this project as one self-contained HTML/JavaScript animation that presents its main goals and key features, grounded only in what you read in the repository, with a matching on-device narration track: narrate with Kokoro (kokoro-onnx) using a natural female (af_heart) or male (am_michael) voice per the audio policy in the persona. Save it with a single project_demo_video_write call passing htmlPath.',
+      "Generate a character and cute animated JavaScript video: a 30-second demo of this project as one self-contained HTML/JavaScript animation. Ground everything in what you read in the repository — invent an original mascot character whose look, name and personality match the project's theme and purpose, and tell the project's real goals and key features through it. The character, story and visuals must match the project's theme and purpose as read from the repository. Write the narration script first (hook, problem, solution, three features, call to action), then build every scene to match its line, with fun dynamic elements per the persona. Use the style named on a 'Video style: <name>' line in the additional instructions — Professional, Fun, Animated whiteboard, or Kinetic typography — otherwise pick the one that best fits the project. Narrate with Kokoro (kokoro-onnx) using a natural female (af_heart) or male (am_michael) voice per the audio policy in the persona. Save it with a single project_demo_video_write call passing htmlPath.",
   }),
 ]);
 

package/src/main/lib/crossProjectFeedback.cjs

@@ -83,6 +83,14 @@ const DEFAULT_FEEDBACK_AGENT = 'architect';
 const MAX_TITLE_CHARS = 200;
 const MAX_BODY_CHARS = 20000;
 const MAX_REFERENCES = 20;
+const MAX_MOTIVATION_CHARS = 2000;
+const MAX_LIST_ITEMS = 20;
+const MAX_LIST_ITEM_CHARS = 500;
+const MAX_SERIES_KEY_CHARS = 60;
+const MAX_SERIES_TITLE_CHARS = 120;
+const MAX_SERIES_TOTAL = 50;
+const MAX_ORIGIN_ASK_CHARS = 300;
+const KEBAB_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
 /** Bound on how many `~/.claude/projects/` folders listFeedbackTargets will
  *  resolve. That directory accumulates one folder per path the CLI was ever
@@ -127,6 +135,29 @@ function isSessionManagerProject(cwd) {
   return isDirectory(path.join(cwd, OPS_ROOT_DIR));
 }
 
+/**
+ * resolveOriginAsk(fromCwd, fromEpicId) → string | null
+ *
+ * The sending Epic's own human goal (single line, ≤ 300 chars), read from the
+ * sender project's active-index.json. Never throws: a missing Epic or an
+ * unreadable file is just "no origin known".
+ */
+function resolveOriginAsk(fromCwd, fromEpicId) {
+  if (!fromCwd || !fromEpicId) return null;
+  try {
+    const sessions = readActiveIndex(fromCwd).sessions;
+    if (!Object.prototype.hasOwnProperty.call(sessions, fromEpicId)) return null;
+    const goal = singleLine(sessions[fromEpicId] && sessions[fromEpicId].goalText);
+    return goal ? goal.slice(0, MAX_ORIGIN_ASK_CHARS) : null;
+  } catch {
+    return null;
+  }
+}
+
+function seriesLine(series) {
+  return series ? `Part ${series.index} of ${series.total} — ${singleLine(series.title)}` : '';
+}
+
 /**
  * composeFeedbackIntake({ fromCwd, fromEpicId, title, body, referencePaths })
  *   → { goalText, openingPrompt, sections }
@@ -160,6 +191,12 @@ function composeFeedbackIntake({
   agentName = DEFAULT_FEEDBACK_AGENT,
   agentDescription = null,
   referencePaths = [],
+  originAsk = null,
+  motivation = '',
+  plan = [],
+  acceptanceCriteria = [],
+  outOfScope = [],
+  series = null,
 } = {}) {
   const trimmedTitle = singleLine(title);
   const trimmedBody = String(body ?? '').trim();
@@ -174,21 +211,36 @@ function composeFeedbackIntake({
     });
   }
 
+  const fromPath = singleLine(fromCwd);
+  const fromName = path.basename(fromPath) || fromPath;
   const origin = fromEpicId
-    ? `${singleLine(fromCwd)} (session ${singleLine(fromEpicId)})`
-    : singleLine(fromCwd);
+    ? `${fromName} (${fromPath}, session ${singleLine(fromEpicId)})`
+    : `${fromName} (${fromPath})`;
+  const askClause = originAsk ? ` It was raised while working on: ${singleLine(originAsk)}.` : '';
   sections.push({
     kind: 'input',
     label: 'Input',
     text:
-      `This session is INBOUND FEEDBACK from another project: ${origin}. `
+      `This session is INBOUND FEEDBACK from another project: ${origin}.${askClause} `
       + 'Nobody in this project wrote the report below — an agent working in that project did, and it '
       + 'may be wrong about this codebase. Verify the claim against the code here before acting on it, '
       + 'and if it does not hold, say so and close the session rather than building against it.',
     source: fromCwd,
   });
 
-  const goalBody = trimmedTitle ? `Goal: ${trimmedTitle}\n\n${trimmedBody}` : trimmedBody;
+  const trimmedMotivation = String(motivation ?? '').trim();
+  const blocks = [];
+  if (series) blocks.push(seriesLine(series));
+  if (trimmedMotivation) blocks.push(`## Why\n${trimmedMotivation}`);
+  if (plan.length) blocks.push(`## Proposed plan\n${plan.map((x, i) => `${i + 1}. ${singleLine(x)}`).join('\n')}`);
+  if (acceptanceCriteria.length) {
+    blocks.push(`## Acceptance criteria\n${acceptanceCriteria.map((x) => `- [ ] ${singleLine(x)}`).join('\n')}`);
+  }
+  if (outOfScope.length) blocks.push(`## Out of scope\n${outOfScope.map((x) => `- ${singleLine(x)}`).join('\n')}`);
+  blocks.push(`## Details\n${trimmedBody}`);
+  const structured = blocks.join('\n\n');
+
+  const goalBody = trimmedTitle ? `Goal: ${trimmedTitle}\n\n${structured}` : structured;
   sections.push({ kind: 'goal', label: 'Goal', text: goalBody });
 
   for (const p of referencePaths) {
@@ -203,7 +255,7 @@ function composeFeedbackIntake({
     return out + sep + s.text;
   }, '');
 
-  const bodyText = trimmedTitle ? `${trimmedTitle}\n\n${trimmedBody}` : trimmedBody;
+  const bodyText = trimmedTitle ? `${trimmedTitle}\n\n${structured}` : structured;
   const refLines = referencePaths.map((p) => `Reference: ${singleLine(p)}`);
   const goalText = refLines.length ? `${bodyText}\n\n${refLines.join('\n')}` : bodyText;
 
@@ -237,6 +289,66 @@ function validateFeedbackInput(input = {}) {
     return bad(400, `tag must be one of ${FEEDBACK_TAGS.join(' | ')} (got ${JSON.stringify(tag)})`);
   }
 
+  const motivation = typeof input.motivation === 'string' ? input.motivation.trim() : '';
+  if (!motivation) {
+    return bad(400, 'motivation is required — WHY this is needed, in the sending human\'s terms, so the receiving human can judge it');
+  }
+  if (motivation.length > MAX_MOTIVATION_CHARS) {
+    return bad(400, `motivation is ${motivation.length} chars; cap is ${MAX_MOTIVATION_CHARS}`);
+  }
+
+  const listPurpose = {
+    plan: 'the ordered steps you propose the receiving project take',
+    acceptanceCriteria: 'the checkable conditions that mean this is done',
+    outOfScope: 'what this proposal deliberately does not cover',
+  };
+  const lists = {};
+  for (const field of ['plan', 'acceptanceCriteria', 'outOfScope']) {
+    const raw = input[field];
+    if (raw === undefined || raw === null) { lists[field] = []; continue; }
+    if (!Array.isArray(raw)) return bad(400, `${field} must be an array of strings (${listPurpose[field]})`);
+    if (raw.length > MAX_LIST_ITEMS) {
+      return bad(400, `${field} has ${raw.length} items; cap is ${MAX_LIST_ITEMS} (${listPurpose[field]})`);
+    }
+    const items = [];
+    for (const item of raw) {
+      const t = typeof item === 'string' ? item.trim() : '';
+      if (!t) return bad(400, `${field} items must be non-blank strings (${listPurpose[field]})`);
+      if (t.length > MAX_LIST_ITEM_CHARS) {
+        return bad(400, `a ${field} item is ${t.length} chars; cap is ${MAX_LIST_ITEM_CHARS}`);
+      }
+      items.push(t);
+    }
+    lists[field] = items;
+  }
+  if (lists.acceptanceCriteria.length === 0) {
+    return bad(400, `acceptanceCriteria is required with at least one item — ${listPurpose.acceptanceCriteria}`);
+  }
+  if (tag === 'feature' && lists.plan.length === 0) {
+    return bad(400, `plan is required with at least one item when tag is 'feature' — ${listPurpose.plan}`);
+  }
+
+  let series = null;
+  if (input.series !== undefined && input.series !== null) {
+    const sr = input.series;
+    const sbad = (why) => bad(400, `series ${why} (series groups one request split across several proposals: { key, title, index, total })`);
+    if (typeof sr !== 'object' || Array.isArray(sr)) return sbad('must be an object');
+    const key = typeof sr.key === 'string' ? sr.key : '';
+    if (!key || key.length > MAX_SERIES_KEY_CHARS || !KEBAB_RE.test(key)) {
+      return sbad(`key must be kebab-case, ≤ ${MAX_SERIES_KEY_CHARS} chars`);
+    }
+    const stitle = typeof sr.title === 'string' ? sr.title.trim() : '';
+    if (!stitle || stitle.length > MAX_SERIES_TITLE_CHARS) {
+      return sbad(`title must be non-blank, ≤ ${MAX_SERIES_TITLE_CHARS} chars`);
+    }
+    if (!Number.isInteger(sr.index) || sr.index < 1) return sbad('index must be an integer ≥ 1');
+    if (!Number.isInteger(sr.total) || sr.total < 2 || sr.total > MAX_SERIES_TOTAL) {
+      return sbad(`total must be an integer 2..${MAX_SERIES_TOTAL}`);
+    }
+    if (sr.index > sr.total) return sbad('index must be ≤ total');
+    series = { key, title: stitle, index: sr.index, total: sr.total };
+  }
+
   const referencePaths = Array.isArray(input.referencePaths) ? input.referencePaths : [];
   if (referencePaths.length > MAX_REFERENCES) {
     return bad(400, `too many referencePaths (${referencePaths.length}); cap is ${MAX_REFERENCES}`);
@@ -293,6 +405,11 @@ function validateFeedbackInput(input = {}) {
       title,
       body,
       tag,
+      motivation,
+      plan: lists.plan,
+      acceptanceCriteria: lists.acceptanceCriteria,
+      outOfScope: lists.outOfScope,
+      series,
       referencePaths: referencePaths.map((p) => String(p)),
       fromEpicId: input.fromEpicId ? String(input.fromEpicId) : null,
       agentType: input.agentType ? String(input.agentType) : DEFAULT_FEEDBACK_AGENT,
@@ -337,6 +454,8 @@ async function openFeedbackSession(input, deps = {}) {
     } catch { /* unresolvable — the proposal still delivers, just without a receipt */ }
   }
 
+  const originAsk = resolveOriginAsk(v.fromCwd, v.fromEpicId);
+
   const { goalText, openingPrompt, sections } = composeFeedbackIntake({
     fromCwd: v.fromCwd,
     fromEpicId: v.fromEpicId,
@@ -345,6 +464,12 @@ async function openFeedbackSession(input, deps = {}) {
     agentName: v.agentType,
     agentDescription: v.agentDescription,
     referencePaths: v.referencePaths,
+    originAsk,
+    motivation: v.motivation,
+    plan: v.plan,
+    acceptanceCriteria: v.acceptanceCriteria,
+    outOfScope: v.outOfScope,
+    series: v.series,
   });
 
   // The Epic's stored identity is the one-line title, not the whole report —
@@ -363,6 +488,14 @@ async function openFeedbackSession(input, deps = {}) {
         producer: 'cross-project-feedback',
         fromCwd: v.fromCwd,
         ...(v.fromEpicId ? { fromEpicId: v.fromEpicId } : {}),
+        proposal: {
+          motivation: v.motivation,
+          originAsk,
+          plan: v.plan,
+          acceptanceCriteria: v.acceptanceCriteria,
+          outOfScope: v.outOfScope,
+          series: v.series,
+        },
       },
       mintAuthority: MINT_AUTHORITY_CROSS_PROJECT_FEEDBACK,
     });
@@ -377,6 +510,7 @@ async function openFeedbackSession(input, deps = {}) {
     fromEpicId: v.fromEpicId,
     tag: v.tag,
     title: v.title,
+    series: v.series,
   });
 
   let receiptOnOriginEpic = false;
@@ -385,7 +519,9 @@ async function openFeedbackSession(input, deps = {}) {
       receiptOnOriginEpic = await appendReceipt(
         v.fromCwd,
         v.fromEpicId,
-        `Feedback delivered to ${v.toCwd} as a proposed session (${minted.epicId}): "${v.title}". `
+        `Feedback delivered to ${v.toCwd} as a proposed session (${minted.epicId}): "${v.title}"`
+        + (v.series ? ` [${seriesLine(v.series)}]` : '')
+        + '. '
         + 'It will not run until a human in that project approves it.',
       );
     } catch {
@@ -545,6 +681,7 @@ module.exports = {
   resolveProjectsDir,
   isSessionManagerProject,
   composeFeedbackIntake,
+  resolveOriginAsk,
   validateFeedbackInput,
   openFeedbackSession,
   listFeedbackTargets,

package/src/main/lib/mcpToolCatalog.cjs

@@ -238,15 +238,24 @@ const MCP_TOOL_CATALOG = [
       + 'opening prompt and stamped with where it came from. Session Manager performs the cross-folder '
       + 'write; you never write another project\'s files yourself.',
     whenToUse: 'Use when work in this project surfaces something that is genuinely another project\'s to fix. '
-      + 'Write the report for a reader who has never seen your project: state the symptom, where you '
-      + 'observed it, what you expected, and (if you know) the file in THEIR repo that looks responsible. '
-      + 'Never assume they can see your code.',
+      + 'Write for a human who must approve it and has never seen your project. Lead with WHY: `motivation` '
+      + 'in the originating human\'s terms. Then give the full `plan` (required for tag "feature") and '
+      + '`acceptanceCriteria`; put evidence, symptom and references in `body`. Name the file in THEIR repo '
+      + 'that looks responsible if you know it. When one request is split into several proposals, send '
+      + 'them ALL with one shared `series` {key, title, total} (plus each one\'s `index`) and summarise '
+      + 'the overall plan in each motivation.',
     whenNotToUse: 'WHEN NOT TO USE IT: for work in the project you are ALREADY in, run /develop inside the Epic you '
       + 'are already in — this tool refuses toCwd === fromCwd outright.',
     exampleArgs: {
       toCwd: '/home/bilko/Projects/other-project',
       fromCwd: '/home/bilko/Projects/session-manager',
       title: 'Cross-project contract mismatch in the shared admin API',
+      tag: 'feature',
+      motivation: 'The human wants X to work across both projects; today Y breaks because Z, so the shared admin API needs W.',
+      plan: ['Add field F to the admin API response', 'Update the validator to accept F', 'Cover F with a contract test'],
+      acceptanceCriteria: ['Admin API returns F', 'Contract test for F passes'],
+      outOfScope: ['Migrating existing records'],
+      series: { key: 'shared-admin-api-f', title: 'Shared admin API field F', index: 1, total: 2 },
       body: 'Symptom: X. Observed while doing Y in session-manager. Expected: Z. Suspected file: <path in their repo>.',
     },
     notes: 'WHAT THIS DOES NOT DO: it does not start anything, queue a PRD, or spend a token. The session '

package/src/main/lib/reaperHelpers.cjs

@@ -339,6 +339,14 @@ const ORPHAN_REQUEUE_CAP = 5;
  *    diverted into `recovered` exactly like a `findLiveProcess` hit.
  * Both default to a no-op when omitted, so existing callers/tests are
  * unaffected.
+ *
+ * `finalizeOwned` (optional, `(job) → boolean`) covers the dead-PID shape:
+ * a claude child exits BEFORE its spawnJob() has integrated the worktree
+ * branch and written the terminal row, so for that whole window the row is
+ * 'running' with a dead pid. Reaping it then races the fast-forward merge and
+ * parks landed work as reaped_without_integration (family-frame 137,
+ * 2026-10-10: park + merge in the same second). A true return skips the row
+ * with a warning; the caller bounds how long it may keep answering true.
  */
 /**
  * Pure, never-throws formatter for the dispatch-phase breadcrumb appended to
@@ -400,7 +408,7 @@ function resolvePidlessFailureOverride(job) {
 }
 
 function selectReapableJobs(jobs, now, {
-  pidAlive, grace, findLiveProcess, getLogMtimeMs, getLogPid, logFreshWindowMs,
+  pidAlive, grace, findLiveProcess, getLogMtimeMs, getLogPid, logFreshWindowMs, finalizeOwned,
 } = {}) {
   const reapable = [];
   const warnings = [];
@@ -410,6 +418,10 @@ function selectReapableJobs(jobs, now, {
     const pid = j.runtime?.pid;
     if (pid) {
       if (pidAlive(pid)) continue;
+      if (typeof finalizeOwned === 'function' && finalizeOwned(j)) {
+        warnings.push({ slug: j.slug, reason: `pid ${pid} exited but its spawnJob is still finalizing (integration in flight)` });
+        continue;
+      }
       reapable.push({ slug: j.slug, pid, pidless: false });
       continue;
     }