claude-code-session-manager 0.40.3 → 0.41.0

package/src/main/scheduler.cjs

@@ -63,6 +63,7 @@ const prdParser = require('./scheduler/prdParser.cjs');
 const sessionsStore = require('./sessionsStore.cjs');
 const { enqueueExternalPrompt } = require('./chatRunner.cjs');
 const { appendResponseEventIfKnown } = require('./promptSessionEvents.cjs');
+const promptSessionTranscript = require('./promptSessionTranscript.cjs');
 const { verifyRun } = require('./runVerify.cjs');
 const { latestTerminalOutcomeForSlug, COMPLETED_EQUIVALENT_VERDICTS } = require('./lib/terminalRunOutcome.cjs');
 const logs = require('./logs.cjs');
@@ -84,9 +85,8 @@ const queueOps = require('./queueOps.cjs');
 // Plain Node module, no Electron dependency; queuePath/prdsDir defaults already
 // match ROOT/QUEUE_PATH below since both resolve the same ~/.claude/session-manager
 // home-dir layout.
-const { sweep: sweepFeedback } = require('../../scripts/lib/watchdogHelpers.cjs');
-const { resolvePrdsDirs, resolvePrdWriteDir, listEpicPrdDirs } = require('./lib/prdLocations.cjs');
-const { ensureEpic, appendPrdCreatedEvent, readActiveIndex } = require('./lib/epicMint.cjs');
+const { resolvePrdsDirs, resolvePrdWriteDir, listEpicPrdDirs, listArchivedPrdDirs } = require('./lib/prdLocations.cjs');
+const { ensureEpic, appendPrdCreatedEvent, removeEpic, readActiveIndex } = require('./lib/epicMint.cjs');
 
 // ---------- origin session resolution (PRD 832) ----------
 // An Epic IS a tagged claude session — job rows carry the originating
@@ -144,6 +144,10 @@ const POST_RESULT_GRACE_MS = 90_000;
 const POST_RESULT_KILL_MS = 30_000;
 const RESULT_TAIL_POLL_MS = 5_000;
 const RESULT_TAIL_BYTES = 8 * 1024;
+// Wider than RESULT_TAIL_BYTES (which only needs the subtype near the
+// boundary) — a real `result` string can be a full paragraph, so
+// extractResultTextFromLog scans more of the tail to find it whole.
+const RESULT_TEXT_TAIL_BYTES = 64 * 1024;
 
 // Idle-output watchdog: if the log file mtime stops advancing for this long
 // while the process is still alive, the agent is hung mid-work (network
@@ -492,23 +496,43 @@ function prdPathForJob(job) {
   return path.join(prdDirForCwd(job && job.cwd), `${job && job.slug}.md`);
 }
 
-/** Absolute path to the sibling `prds-archived/<slug>.md` twin of a job's PRD. */
+/**
+ * Absolute path to a job's archived-twin `<slug>.md`. Resolves to the first
+ * archive dir (across the flat legacy layout and every Epic's own sibling
+ * archive — see listArchivedPrdDirs) that actually contains the slug, falling
+ * back to the flat `prds-archived/<slug>.md` path when none do (this fallback
+ * is only ever used for its string value — logging/note text in
+ * prdArchivedSkipResult — never as an existence check).
+ */
 function archivedPrdPathForJob(job) {
-  return path.join(prdDirForCwd(job && job.cwd), '..', 'prds-archived', `${job && job.slug}.md`);
+  const slug = job && job.slug;
+  const flatPath = path.join(prdDirForCwd(job && job.cwd), '..', 'prds-archived', `${slug}.md`);
+  for (const dir of listArchivedPrdDirs((job && job.cwd) || DEFAULT_PROJECT_CWD)) {
+    const candidate = safeSlugPathIn(dir, slug);
+    if (candidate && fs.existsSync(candidate)) return candidate;
+  }
+  return flatPath;
 }
 
 /**
- * True if a job's PRD has already been archived (sibling `prds-archived/<slug>.md`
- * exists). A queue entry whose PRD moved there is stale — the work already shipped
- * — not a genuine missing-PRD failure.
+ * True if a job's PRD has already been archived — in the flat legacy
+ * `prds-archived/` dir OR in the Epic-scoped sibling archive dir every new
+ * PRD actually lands in (archiveCompletedPrd archives into the source PRD's
+ * OWN parent's prds-archived/, which for an Epic PRD is inside that Epic).
+ * A queue entry whose PRD moved to either is stale — the work already
+ * shipped — not a genuine missing-PRD failure.
  */
 async function archivedTwinExists(job) {
-  try {
-    await fsp.access(archivedPrdPathForJob(job));
-    return true;
-  } catch {
-    return false;
+  const slug = job && job.slug;
+  for (const dir of listArchivedPrdDirs((job && job.cwd) || DEFAULT_PROJECT_CWD)) {
+    const candidate = safeSlugPathIn(dir, slug);
+    if (!candidate) continue;
+    try {
+      await fsp.access(candidate);
+      return true;
+    } catch { /* not here — try the next archive dir */ }
   }
+  return false;
 }
 
 /**
@@ -1106,9 +1130,13 @@ async function reconcile(state) {
       estimateMinutes: p.estimateMinutes,
       sourcePromptId: reconcileSourcePromptId(job, p.sourcePromptId),
       sourceTabId: p.sourceTabId,
+      // Unlike sourcePromptId (frozen once a row leaves 'pending'), epicId is
+      // refreshed from disk every pass: the PRD's directory IS its Epic
+      // membership, so moving the file between Epic dirs must re-point the row.
+      epicId: p.epicId ?? job.epicId ?? null,
       dependsOn: p.dependsOn,
       originSessionId: job.originSessionId
-        ?? resolveOriginSessionId(p.cwd, reconcileSourcePromptId(job, p.sourcePromptId)),
+        ?? resolveOriginSessionId(p.cwd, p.epicId ?? reconcileSourcePromptId(job, p.sourcePromptId)),
       bodyPreview: p.body.split('\n').slice(0, 6).join('\n'),
     });
   }
@@ -1167,8 +1195,9 @@ async function reconcile(state) {
       estimateMinutes: p.estimateMinutes,
       sourcePromptId: p.sourcePromptId,
       sourceTabId: p.sourceTabId,
+      epicId: p.epicId ?? null,
       dependsOn: p.dependsOn,
-      originSessionId: resolveOriginSessionId(p.cwd, p.sourcePromptId),
+      originSessionId: resolveOriginSessionId(p.cwd, p.epicId ?? p.sourcePromptId),
       bodyPreview: p.body.split('\n').slice(0, 6).join('\n'),
       status: 'pending',
       runId: null,
@@ -1267,17 +1296,11 @@ let resumeTimer = null;
 let pollLoopTimer = null;
 let rescheduleInterval = null;
 let heartbeatInterval = null;
-// Feedback sweep piggybacks on the 60s heartbeat tick but runs far less often —
-// every Nth tick — since it's a readdir-per-active-project scan, not free.
-// 5 ticks = 5 minutes; well inside sweep()/activeProjectCwds()'s 90-minute
-// active-session window, so no active project can be missed between sweeps.
-const FEEDBACK_SWEEP_TICK_INTERVAL = 5;
-let feedbackSweepTickCount = 0;
-/** Pure gate for the tick counter above — exported so the wiring is testable
- *  without waiting on real setInterval timers. */
-function feedbackSweepDue(tickCount, interval = FEEDBACK_SWEEP_TICK_INTERVAL) {
-  return tickCount >= interval;
-}
+// (The 5-minute feedback sweep that used to piggyback on this heartbeat is
+// gone: it scanned each active project's session-manager-operations/feedback/
+// and auto-queued a /process-feedback PRD. Both the folder and that skill are
+// retired — agents now file a `proposed` Epic that waits for human approval,
+// so there is nothing to sweep for. See lib/rcaFeedbackHook.cjs.)
 // In-memory set of slugs currently spawned in this process. Prevents
 // double-spawn when runDueJobs() is called while jobs are in flight.
 const runningSet = new Set();
@@ -1623,6 +1646,34 @@ function isNotifiableTerminalStatus(effectiveStatus) {
   return effectiveStatus === 'completed' || effectiveStatus === 'failed';
 }
 
+/**
+ * Scans a run log's tail for the last `{"type":"result",...}` JSONL event
+ * (the claude harness's final message) and returns its `result` string, or
+ * null if the log is missing, unreadable, or has no parseable result line.
+ * Never throws — a missing/torn log must not break notifyOriginatingTab.
+ */
+function extractResultTextFromLog(logPath) {
+  if (!logPath) return null;
+  try {
+    const tail = readTail(logPath, RESULT_TEXT_TAIL_BYTES);
+    if (!tail) return null;
+    const lines = tail.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i].trim();
+      if (!line || !line.includes('"type":"result"')) continue;
+      try {
+        const parsed = JSON.parse(line);
+        if (parsed && typeof parsed.result === 'string') return parsed.result;
+      } catch {
+        // torn/partial line — keep scanning backward
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * notifyOriginatingTab(job) → void
  *
@@ -1630,31 +1681,62 @@ function isNotifiableTerminalStatus(effectiveStatus) {
  * rateLimited auto-pause, which resets the job to pending instead), publish
  * a short status notification for the PRD that queued this job.
  *
- * Resolution order (PRD 814): (1) if the PRD's `sourcePromptId` resolves to
- * a known, still-active PromptSession (minted for a dev-work dispatch, PRD
- * 813) under the job's cwd, append a 'response' PromptSessionEvent to THAT
- * session's own event chain — its own scoped PromptSessionConversation, not
- * whatever tab happens to be active — and stop; (2) otherwise, fall back to
- * today's behavior: push a short status prompt into the chat tab that queued
- * this PRD via enqueueExternalPrompt (PRD 753), resolved via the PRD's own
- * `sourceTabId` frontmatter, then the first open tab (per sessionsStore's
- * persisted tabs.json) whose cwd matches the job's cwd — first match only,
- * no fan-out to multiple matching tabs; (3) no-op. Never throws to the
- * caller (fire-and-forget from spawnJob). Deps are injectable (mirrors
- * partitionBootOrphans's isAlive param) so unit tests can exercise the
- * resolution logic without touching disk/electron.
+ * Resolution order (PRD 814, extended by PRD 854): (1) if the PRD's
+ * `sourcePromptId` resolves to a known, still-active PromptSession (minted
+ * for a dev-work dispatch, PRD 813) under the job's cwd, append a 'response'
+ * PromptSessionEvent to THAT session's own event chain — its own scoped Epic
+ * conversation (EpicDetail.tsx), not whatever tab happens to be active — and
+ * stop; (2) otherwise, fall back to pushing a short status prompt via
+ * enqueueExternalPrompt (PRD 753) at a target id resolved from, in order,
+ * the PRD's own `sourceTabId` frontmatter, then `sourcePromptId` again (a PRD
+ * dispatched straight from an Epic's composer, dispatchPromptSessionToPrd,
+ * never sets sourceTabId — sourcePromptId IS the Epic id and is a valid
+ * chat:external-send target too, which the renderer now resolves against
+ * both open tabs and known Epics, refusing a completed one), then the first
+ * open tab (per sessionsStore's persisted tabs.json) whose cwd matches the
+ * job's cwd — first match only, no fan-out to multiple matching tabs; (3)
+ * no-op. The cwd-match step only runs when NEITHER sourceTabId nor
+ * sourcePromptId is present in frontmatter at all — `sendPrompt` (
+ * enqueueExternalPrompt) is fire-and-forget IPC with no ack, so once step
+ * (2) picks either id it is not retried even if the renderer can't resolve
+ * it either (e.g. a stale/garbage id) — same non-guaranteed-delivery
+ * tradeoff this function already accepted for sourceTabId pre-PRD-854.
+ * Never throws to the caller (fire-and-forget from spawnJob). Deps are
+ * injectable (mirrors partitionBootOrphans's isAlive param) so unit tests
+ * can exercise the resolution logic without touching disk/electron.
  */
 async function notifyOriginatingTab(job, {
   parsePrdRaw = prdParser.parsePrdRaw,
   loadSessions = sessionsStore.load,
   sendPrompt = enqueueExternalPrompt,
   appendResponseEvent = appendResponseEventIfKnown,
+  appendTranscriptTurn = promptSessionTranscript.appendTurn,
+  readResultFromLog = extractResultTextFromLog,
 } = {}) {
   try {
     const prdPath = prdPathForJob(job);
     const prd = await parsePrdRaw(prdPath).catch(() => null);
     const message = `PRD ${job.slug} finished: ${job.status}. Check Scheduler for details.`;
 
+    // Persist the job's real result text (not just the short status chip
+    // above) to the durable per-Epic transcript, keyed off whichever id
+    // notifyOriginatingTab would otherwise notify. Best-effort: a missing
+    // cwd/epic id, an unreadable run log, or an IPC error here must never
+    // block the notification below.
+    const epicIdForTranscript = prd?.sourcePromptId || prd?.sourceTabId || null;
+    if (epicIdForTranscript && job.cwd) {
+      try {
+        const logPath = job.runId ? path.join(RUNS_DIR, job.runId, `${job.slug}.log`) : null;
+        const resultText = readResultFromLog(logPath);
+        await appendTranscriptTurn(job.cwd, epicIdForTranscript, {
+          role: 'assistant',
+          text: resultText || message,
+        });
+      } catch (e) {
+        console.error('[scheduler] notifyOriginatingTab transcript append error', job?.slug, e);
+      }
+    }
+
     if (prd?.sourcePromptId) {
       const routed = await appendResponseEvent(job.cwd || null, prd.sourcePromptId, message).catch((e) => {
         console.error('[scheduler] notifyOriginatingTab appendResponseEvent error', job?.slug, e);
@@ -1663,7 +1745,13 @@ async function notifyOriginatingTab(job, {
       if (routed) return;
     }
 
-    let targetTabId = prd?.sourceTabId || null;
+    // appendResponseEvent already refused above (unknown id, completed
+    // Epic, or disk error) — the sourcePromptId fallback below re-sends to
+    // the SAME id via chat:external-send, which the renderer independently
+    // re-checks against its own live PromptSession store. Deliberate
+    // defense-in-depth (main's disk-backed check vs. the renderer's
+    // in-memory one can disagree/race), not a redundant duplicate to prune.
+    let targetTabId = prd?.sourceTabId || prd?.sourcePromptId || null;
     if (!targetTabId) {
       const jobCwd = job.cwd || null;
       if (jobCwd) {
@@ -1673,7 +1761,7 @@ async function notifyOriginatingTab(job, {
       }
     }
     if (!targetTabId) {
-      console.log(`[scheduler] notifyOriginatingTab: no target tab for ${job.slug}, skipping`);
+      console.log(`[scheduler] notifyOriginatingTab: no open tab and no Epic for ${job.slug}, skipping`);
       return;
     }
 
@@ -1838,8 +1926,13 @@ async function executeJob(job, runDir, defaultCwd, onPid) {
   }
 
   // Read full PRD body fresh from disk (queue stored only the preview).
+  // Resolve through findPrdDir's full candidate search (legacy flat dir +
+  // every project's Epic-scoped dirs) first, so the common case — a live
+  // Epic-scoped PRD — is a first-try hit instead of probing the retired flat
+  // dir and only then falling back.
   let prompt;
-  let prdPath = prdPathForJob(job);
+  const resolvedDir = await findPrdDir(job.slug);
+  let prdPath = resolvedDir ? path.join(resolvedDir, `${job.slug}.md`) : prdPathForJob(job);
   try {
     const parsed = await parsePrd(prdPath);
     // Centrally enforce the review → security-review → verify → commit finish
@@ -3757,7 +3850,7 @@ function registerScheduleHandlers() {
     const resolved = safeSlugPathIn(dir, data.slug);
     if (!resolved) return { ok: false, error: 'invalid slug' };
     try {
-      await config.writeTextAtomic(resolved, data.body);
+      await config.writeTextAtomic(resolved, data.body, { writer: 'scheduler' });
     } catch (e) {
       return { ok: false, error: e?.message ?? 'write failed' };
     }
@@ -3795,6 +3888,7 @@ function registerScheduleHandlers() {
             cwd: parsed.cwd || '',
             estimateMinutes: parsed.estimateMinutes,
             sourcePromptId: parsed.sourcePromptId,
+            epicId: parsed.epicId ?? null,
             mtimeMs: stat.mtimeMs,
           });
         } catch (e) {
@@ -4006,16 +4100,6 @@ async function init() {
       utilization: cachedUtilization,
       consecutiveFailures,
     });
-
-    feedbackSweepTickCount++;
-    if (feedbackSweepDue(feedbackSweepTickCount, FEEDBACK_SWEEP_TICK_INTERVAL)) {
-      feedbackSweepTickCount = 0;
-      try {
-        sweepFeedback();
-      } catch (e) {
-        console.warn('[scheduler] feedback sweep failed', e?.message);
-      }
-    }
   }, 60_000);
   if (heartbeatInterval.unref) heartbeatInterval.unref();
 
@@ -4125,10 +4209,16 @@ const remote = {
       if (!dir) {
         try {
           const { fm } = splitFrontmatter(body);
-          const epic = ensureEpic(cwd, {
+          const epic = await ensureEpic(cwd, {
             goalText: fm.title || slug,
             tag: fm.tag,
             // An Epic-conversation dispatch already has its Epic — join it.
+            // fm.sourcePromptId must be an existing Epic's promptSessionId
+            // (== its active-index.json sessions key), NOT a
+            // PromptTicket.id — epicMint.cjs's ensureEpic looks it up via
+            // `index.sessions[explicitEpicId]` (see epicMint.cjs ~line 73),
+            // a literal-equality join. Any other id (e.g. a PromptTicket.id)
+            // simply won't match and mints a sibling Epic instead of joining.
             epicId: fm.sourcePromptId,
           });
           dir = epic.prdDir;
@@ -4151,16 +4241,22 @@ const remote = {
     // PRD 825: if this call minted a brand-new Epic (ensureEpic's `created`)
     // and the write below never lands, don't strand an empty Epic dir —
     // best-effort remove `<epic>/prds` then `<epic>` itself, only when empty.
+    // PRD 851: also drop the Epic's active-index.json entry (sessions/events)
+    // so an orphaned seed-prompt-only Epic doesn't linger in the Epics nav.
+    // Gated on epicCreated (never fires when ensureEpic joined an existing
+    // Epic) so a pre-existing Epic's history is never touched.
     const cleanupEmptyMintedEpic = async () => {
       if (!epicCreated || !epicId) return;
       try {
         const entries = await fsp.readdir(dir);
-        if (entries.length > 0) return;
-        await fsp.rmdir(dir);
-        const epicRootDir = path.dirname(dir);
-        const epicRootEntries = await fsp.readdir(epicRootDir);
-        if (epicRootEntries.length === 0) await fsp.rmdir(epicRootDir);
+        if (entries.length === 0) {
+          await fsp.rmdir(dir);
+          const epicRootDir = path.dirname(dir);
+          const epicRootEntries = await fsp.readdir(epicRootDir);
+          if (epicRootEntries.length === 0) await fsp.rmdir(epicRootDir);
+        }
       } catch { /* best-effort only */ }
+      try { removeEpic(cwd, epicId); } catch { /* best-effort only */ }
     };
 
     const resolved = safeSlugPathIn(dir, slug);
@@ -4185,11 +4281,11 @@ const remote = {
         await cleanupEmptyMintedEpic();
         return { ok: false, error: 'invalid slug' };
       }
-      await config.writeTextAtomic(resolved, body);
+      await config.writeTextAtomic(resolved, body, { writer: 'scheduler' });
       const stat = await fsp.stat(resolved);
       if (epicTrace) {
         // Best-effort: record the dispatch on the minted Epic's event chain.
-        try { appendPrdCreatedEvent(cwd, epicTrace, slug); } catch { /* trace only */ }
+        try { await appendPrdCreatedEvent(cwd, epicTrace, slug); } catch { /* trace only */ }
       }
       return { ok: true, bytesWritten: stat.size };
     } catch (e) {
@@ -4288,4 +4384,4 @@ function registerAdminRoutes(adminHttp, remoteObj = remote) {
   });
 }
 
-module.exports = { registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR, writeQueue, reconcile, reconcileSourcePromptId, allocateParallelGroup, selectHistoryJobs, parsePorcelain, FINISH_PROTOCOL, remote, pickNextBatch, pickForProject, reapDeadRunningJobs, pollRecoveryClearSource, memoryLimitedBatchSize, availableForJobs, reverifyNeedsReview, isRescanCandidate, isPromotableOriginal, selectAutoFixTargets, isEligibleForImmediateAutoFix, resolveRunId, isUnresolvableNeedsReview, healTargetForFix, buildInvestigationPrompt, committedInWindow, computeCommittedDuringRun, classifySigtermWithCommit, isFixPlanSlug, isFixPlanBeyondDepthCap, MAX_INVESTIGATION_DEPTH, forceTickOutcome, applyPauseCleared, detectNetworkErrorInLog, detectRateLimitInLog, classifyFailureOutcome, commitGuardVerdict, TRANSIENT_RETRY_CAP, buildScheduleStatePayload, partitionBootOrphans, applyOrphanOutcome, BOOT_ORPHAN_KILL_GRACE_MS, feedbackSweepDue, FEEDBACK_SWEEP_TICK_INTERVAL, sweepFeedback, registerAdminRoutes, notifyOriginatingTab, isNotifiableTerminalStatus, candidatePrdsDirs, prdDirForCwd, prdPathForJob, archivedPrdPathForJob, archivedTwinExists, findPrdDir, runPrdMigration, shouldSkipInvestigationForCleanRun, archiveCompletedPrd, retireCompletedSlugs, SCHEDULER_BOOTED_AT, SCHEDULER_CODE_SHA, resetJobFields };
+module.exports = { registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR, writeQueue, reconcile, reconcileSourcePromptId, allocateParallelGroup, selectHistoryJobs, parsePorcelain, FINISH_PROTOCOL, remote, pickNextBatch, pickForProject, reapDeadRunningJobs, pollRecoveryClearSource, memoryLimitedBatchSize, availableForJobs, reverifyNeedsReview, isRescanCandidate, isPromotableOriginal, selectAutoFixTargets, isEligibleForImmediateAutoFix, resolveRunId, isUnresolvableNeedsReview, healTargetForFix, buildInvestigationPrompt, committedInWindow, computeCommittedDuringRun, classifySigtermWithCommit, isFixPlanSlug, isFixPlanBeyondDepthCap, MAX_INVESTIGATION_DEPTH, forceTickOutcome, applyPauseCleared, detectNetworkErrorInLog, detectRateLimitInLog, classifyFailureOutcome, commitGuardVerdict, TRANSIENT_RETRY_CAP, buildScheduleStatePayload, partitionBootOrphans, applyOrphanOutcome, BOOT_ORPHAN_KILL_GRACE_MS, registerAdminRoutes, notifyOriginatingTab, isNotifiableTerminalStatus, extractResultTextFromLog, candidatePrdsDirs, prdDirForCwd, prdPathForJob, archivedPrdPathForJob, archivedTwinExists, findPrdDir, runPrdMigration, shouldSkipInvestigationForCleanRun, archiveCompletedPrd, retireCompletedSlugs, SCHEDULER_BOOTED_AT, SCHEDULER_CODE_SHA, resetJobFields };

package/src/main/templates/PRD_AUTHORING.md

@@ -437,7 +437,7 @@ not be re-proposed:
 
 ### Reference implementation of this exact loop
 
-`/process-feedback`'s step 0b (source → triage → `/develop` → queue) is a working example of this
+The proposal → approve → `/develop` → queue path is a working example of this
 shape, landed 2026-07-14 (`feat(process-feedback): sync open GitHub issues into the feedback
 intake`, commit `352b89c`). It syncs open GitHub issues into `session-manager-operations/feedback/`
 (deduped on a `gh-issue-<N>` token), then processes each item through the same triage → `/develop`

package/src/preload/api.d.ts

@@ -122,6 +122,11 @@ export interface ImportRef {
   ok: boolean;
 }
 
+/** Declared owner ids for the single-writer law over a project's
+ *  session-manager-operations/ root. Mirrors OWNERS in
+ *  src/main/lib/opsOwnership.cjs — one writer per namespace; everyone reads. */
+export type OpsWriter = 'epics' | 'scheduler' | 'project-home' | 'feedback' | 'browser';
+
 export interface WriteResult {
   ok: boolean;
   mtimeMs: number;
@@ -415,6 +420,11 @@ export interface ScheduleJob {
    *  `sourceTabId` for referential tracing even when the tab/session no
    *  longer resolves. */
   sourcePromptId?: string | null;
+  /** The Epic this job's PRD belongs to, derived from the PRD's directory
+   *  (`scheduler/epics/<epicId>/prds/`) — fact on disk, unlike the
+   *  intent-carrying `sourcePromptId`/`sourceTabId`, which can disagree.
+   *  Authoritative source for "which Epic is this from" in every UI. */
+  epicId?: string | null;
 }
 
 export interface SchedulePaths {
@@ -459,6 +469,8 @@ export interface PrdListItem {
   /** PRD frontmatter `sourcePromptId` — the PromptSession (Epic) id this PRD
    *  was dispatched from, if any. */
   sourcePromptId?: string | null;
+  /** Owning Epic id, derived from the PRD's directory. See ScheduleJob.epicId. */
+  epicId?: string | null;
 }
 
 export interface SupervisorConfig {
@@ -874,6 +886,8 @@ export interface ProjectBriefScopeEntry {
 export interface ProjectBrief {
   version: number;
   synthesizedAt: string;
+  /** ISO timestamp of the last hand-edit through `projectBrief.update`, or null. */
+  editedAt: string | null;
   model: string;
   purpose: string;
   what: string[];
@@ -884,6 +898,15 @@ export interface ProjectBrief {
   pinned: { what: string[] | null; conventions: string[] | null };
 }
 
+export interface PromptSessionTranscriptTurn {
+  v: 1;
+  epicId: string;
+  eventId: string | null;
+  role: 'user' | 'assistant';
+  at: string;
+  text: string;
+}
+
 export interface ProjectBriefSource {
   label: string;
   detail: string;
@@ -904,6 +927,19 @@ export type ProjectBriefSetPinResult =
   | { ok: true; brief: ProjectBrief }
   | { ok: false; error: string };
 
+/** Hand-edit patch over brief.json. Editing `what`/`conventions` auto-pins them. */
+export interface ProjectBriefPatch {
+  purpose?: string;
+  what?: string[];
+  conventions?: string[];
+  areas?: ProjectBriefArea[];
+  scope?: ProjectBriefScopeEntry[];
+}
+
+export type ProjectBriefUpdateResult =
+  | { ok: true; brief: ProjectBrief }
+  | { ok: false; error: string };
+
 // ────────────────────────────────────────────── Per-subagent memory
 // Stored at ~/.claude/session-manager/agent-memory/<agentId>.json. Keyed by
 // agent name (the .md filename in ~/.claude/agents/), not by workspace cwd.
@@ -1184,7 +1220,7 @@ export interface SessionManagerAPI {
       | { ok: true; url: string; title: string; dataUrl: string }
       | { ok: false; error: string }
     >;
-    saveBinary: (path: string, base64: string) => Promise<{ ok: boolean; error?: string }>;
+    saveBinary: (path: string, base64: string, writer?: OpsWriter) => Promise<{ ok: boolean; error?: string }>;
     /** Opens a native "Save As" dialog and writes `text` to the chosen path directly
      *  (bypasses config.cjs's write-boundary check — the path is user-chosen via OS dialog). */
     saveRecording: (payload: { defaultName: string; text: string }) => Promise<
@@ -1253,8 +1289,10 @@ export interface SessionManagerAPI {
   config: {
     readJson: (path: string) => Promise<ReadJsonResult>;
     readText: (path: string) => Promise<ReadTextResult>;
-    writeJson: (path: string, data: unknown) => Promise<WriteResult>;
-    writeText: (path: string, text: string) => Promise<WriteResult>;
+    /** `writer` declares the owning surface for the single-writer law — required
+     *  when `path` is inside a project's session-manager-operations/ root. */
+    writeJson: (path: string, data: unknown, writer?: OpsWriter) => Promise<WriteResult>;
+    writeText: (path: string, text: string, writer?: OpsWriter) => Promise<WriteResult>;
     listDir: (path: string, opts?: { filesOnly?: boolean; dirsOnly?: boolean; includeHidden?: boolean }) => Promise<ListDirResult>;
     exists: (path: string) => Promise<boolean>;
     watch: (paths: string[]) => void;
@@ -1439,6 +1477,18 @@ export interface SessionManagerAPI {
     refresh: (cwd: string) => Promise<ProjectBriefRefreshResult>;
     /** Pin/unpin a synthesized block ('what' | 'conventions'), freezing or clearing its frozen copy. */
     setPin: (cwd: string, block: ProjectBriefPinnableBlock, pinned: boolean) => Promise<ProjectBriefSetPinResult>;
+    /** Hand-edit brief.json in place — no LLM cost. Edited pinnable blocks are auto-pinned so the next refresh preserves them. */
+    update: (cwd: string, patch: ProjectBriefPatch) => Promise<ProjectBriefUpdateResult>;
+  };
+  promptSessionTranscript: {
+    /** Append one full-text turn to an Epic's durable JSONL transcript. Best-effort — resolves `{ok:false}` rather than throwing on failure. */
+    append: (
+      cwd: string,
+      epicId: string,
+      turn: { role: 'user' | 'assistant'; text: string; at?: string; eventId?: string },
+    ) => Promise<{ ok: boolean }>;
+    /** Read back an Epic's full-text turns (optionally capped to the last `limit`). Skips corrupt lines rather than throwing. */
+    read: (cwd: string, epicId: string, limit?: number) => Promise<{ turns: PromptSessionTranscriptTurn[] }>;
   };
   agentMemory: {
     /** List all memory entries for one subagent. Sorted newest first. */
@@ -1522,6 +1572,29 @@ export interface SessionManagerAPI {
       offset?: number;
     }) => Promise<Exchange[]>;
   };
+  promptSessions: {
+    /** Fires when the main process appends an event to a PromptSession's
+     *  chain on disk (currently only the scheduler's response-event append
+     *  from notifyOriginatingTab) — lets an already-hydrated Epic pick it up
+     *  live instead of waiting for a restart. */
+    onEventAppended: (handler: (e: PromptSessionEventAppendedPayload) => void) => () => void;
+  };
+}
+
+// ─────────────────────────────────── PromptSession event-appended broadcast
+
+export interface PromptSessionEventAppendedPayload {
+  cwd: string;
+  promptSessionId: string;
+  event: {
+    id: string;
+    promptSessionId: string;
+    kind: 'prompt' | 'prd_created' | 'response' | 'closed';
+    causedByEventId: string | null;
+    at: string;
+    prdSlug?: string;
+    text?: string;
+  };
 }
 
 // ────────────────────────────────────────────── Exchanges (PRD 324 read path)

package/src/preload/index.cjs

@@ -82,7 +82,7 @@ contextBridge.exposeInMainWorld('api', {
     },
     captureDom: (payload) => ipcRenderer.invoke('browser:capture-dom', payload),
     captureShot: (viewId) => ipcRenderer.invoke('browser:capture-shot', { viewId }),
-    saveBinary: (path, base64) => ipcRenderer.invoke('browser:save-binary', { path, base64 }),
+    saveBinary: (path, base64, writer) => ipcRenderer.invoke('browser:save-binary', { path, base64, writer }),
     saveRecording: (payload) => ipcRenderer.invoke('browser:save-recording', payload),
     replay: (payload) => ipcRenderer.invoke('browser:replay', payload),
     onReplayStep: (viewId, handler) => {
@@ -153,8 +153,8 @@ contextBridge.exposeInMainWorld('api', {
   config: {
     readJson: (path) => ipcRenderer.invoke('config:read-json', { path }),
     readText: (path) => ipcRenderer.invoke('config:read-text', { path }),
-    writeJson: (path, data) => ipcRenderer.invoke('config:write-json', { path, data }),
-    writeText: (path, text) => ipcRenderer.invoke('config:write-text', { path, text }),
+    writeJson: (path, data, writer) => ipcRenderer.invoke('config:write-json', { path, data, writer }),
+    writeText: (path, text, writer) => ipcRenderer.invoke('config:write-text', { path, text, writer }),
     listDir: (path, opts) => ipcRenderer.invoke('config:list-dir', { path, opts }),
     exists: (path) => ipcRenderer.invoke('config:exists', { path }),
     watch: (paths) => ipcRenderer.send('config:watch', { paths }),
@@ -320,6 +320,13 @@ contextBridge.exposeInMainWorld('api', {
     get: (cwd) => ipcRenderer.invoke('project-brief:get', { cwd }),
     refresh: (cwd) => ipcRenderer.invoke('project-brief:refresh', { cwd }),
     setPin: (cwd, block, pinned) => ipcRenderer.invoke('project-brief:set-pin', { cwd, block, pinned }),
+    update: (cwd, patch) => ipcRenderer.invoke('project-brief:update', { cwd, patch }),
+  },
+  promptSessionTranscript: {
+    append: (cwd, epicId, turn) =>
+      ipcRenderer.invoke('promptSessionTranscript:append', { cwd, epicId, ...turn }),
+    read: (cwd, epicId, limit) =>
+      ipcRenderer.invoke('promptSessionTranscript:read', { cwd, epicId, ...(limit ? { limit } : {}) }),
   },
   agentMemory: {
     list: (agentId) => ipcRenderer.invoke('agent-memory:list', { agentId }),
@@ -440,4 +447,15 @@ contextBridge.exposeInMainWorld('api', {
      *  `sessionId` filters to one session; `limit`/`offset` for pagination. */
     list: (payload) => ipcRenderer.invoke('exchanges:list', payload),
   },
+  promptSessions: {
+    /** Fires when the main process (currently only the scheduler's
+     *  response-event append) appends an event to a PromptSession's chain on
+     *  disk — lets an already-hydrated Epic pick it up live instead of
+     *  waiting for a restart. */
+    onEventAppended: (handler) => {
+      const listener = (_e, payload) => handler(payload);
+      ipcRenderer.on('promptSession:event-appended', listener);
+      return () => ipcRenderer.removeListener('promptSession:event-appended', listener);
+    },
+  },
 });