claude-code-session-manager 0.40.2 → 0.41.0

package/dist/index.html

@@ -7,10 +7,10 @@
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
     <link href="https://fonts.googleapis.com/css2?family=Newsreader:ital,opsz,wght@0,6..72,400;0,6..72,500;0,6..72,600;0,6..72,700;1,6..72,400&family=Geist:wght@300;400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
-    <script type="module" crossorigin src="./assets/index-bdqOSyxG.js"></script>
+    <script type="module" crossorigin src="./assets/index-H7rwsoKV.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/monaco-editor-BW5C4Iv1.js">
     <link rel="stylesheet" crossorigin href="./assets/monaco-editor-BTnBOi8r.css">
-    <link rel="stylesheet" crossorigin href="./assets/index-BxVBtmjA.css">
+    <link rel="stylesheet" crossorigin href="./assets/index-CKY3mHgV.css">
   </head>
   <body class="bg-bg text-fg font-sans antialiased">
     <div id="root"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-session-manager",
-  "version": "0.40.2",
+  "version": "0.41.0",
   "description": "Local cockpit for the Claude Code CLI — multi-tab terminal, full config surface, scheduler, voice dictation, and live observability.",
   "type": "module",
   "main": "src/main/index.cjs",
@@ -13,6 +13,8 @@
     "plugins/",
     "scripts/postinstall.cjs",
     "scripts/lib/",
+    "scripts/propose-epic.cjs",
+    "scripts/mint-epic.cjs",
     "src/main/",
     "src/preload/",
     "dist/index.html",

package/plugins/session-manager-dev/skills/develop/SKILL.md

@@ -20,7 +20,7 @@ description: >-
 **Role:** `/develop` owns the *pipeline*: it turns a development request into one or more
 self-contained PRDs, queues them, and tracks them to completion. It is the convergence point
 for both entry paths — an interactive human prompt comes straight here; an agent feedback file
-arrives via `/process-feedback`, which evaluates it and then calls this skill. Everything from
+arrives as an approved Epic proposal (`/propose-epic`), which the user approves and then calls this skill. Everything from
 here on is identical regardless of who asked.
 
 **Never** hand-implement the work inline in chat, and never restate rules that live elsewhere:
@@ -66,7 +66,7 @@ can't load skills.
 1. **Clarify scope first.** If the prompt has genuine ambiguity (acceptance criteria, target
    repo, framework, edge cases), ask 2–4 focused questions as plain text and wait. Don't use
    the AskUserQuestion tool. Don't guess on decisions that would cost real rework. (When the
-   caller is `/process-feedback`, scope is already established by its evaluation — don't
+   caller is an approved Epic proposal, scope is already established by its objective — don't
    re-ask; build from the brief it hands you.)
 
 2. **Explore the target repo — broadly, not just the obvious file.** Identify the absolute
@@ -186,7 +186,7 @@ can't load skills.
    (`title`, `cwd`, `estimateMinutes`, `goal`, `acceptanceCriteria[]`, `implementationNotes`,
    `outOfScope[]`) maps directly onto the sections below — pass them straight through. It
    allocates a strictly-unique `NN` atomically (no read-then-write race against another
-   concurrent `/develop`/`/process-feedback` invocation, never reused across the project — PRD
+   concurrent `/develop` invocation, never reused across the project — PRD
    832), derives and collision-checks the slug, and embeds the standards pointer for you.
    `parallelGroup` is DEPRECATED and ignored — express ordering with the `dependsOn` input
    (slugs that must complete first); independent PRDs simply omit it and may run in parallel.
@@ -334,7 +334,7 @@ can't load skills.
 ## Phase 2 — Track to completion (reusable tail)
 
 The queued PRDs run headlessly and can take a while. Don't fire-and-forget, and don't block —
-hand off to a recurring check. `/process-feedback` delegates to this exact phase, so it is the
+hand off to a recurring check. An approved proposal delegates to this exact phase, so it is the
 single definition of "tracked to done" for both entry paths.
 
 7. **Watch the scheduler every ~30 min.** Start a 30-minute monitoring loop (`/loop 30m` over
@@ -348,7 +348,7 @@ single definition of "tracked to done" for both entry paths.
      per `PRD_AUTHORING.md`). Don't silently retry forever. For `needs_review`, the scheduler
      auto-files a Root Cause Analysis into the target project's feedback inbox
      (`rcaFeedbackHook`, filename `<date>-rca-<slug>-<runId>.md`) — reference that file in
-     your report rather than re-deriving the analysis, and let `/process-feedback` fold its
+     your report rather than re-deriving the analysis, and let the approving user fold its
      prevention hint back into future PRD authoring. A `rateLimited` exit-1 is the
      scheduler's benign auto-pause (auto-resumes next window) — keep waiting, don't escalate.
    - **All PRDs completed successfully** — go to step 8.

package/plugins/session-manager-dev/skills/develop/standards.md

@@ -82,7 +82,7 @@ Data-driven from 400+ scheduler runs: long hangs (not bad code) are the dominant
 - **Verify before done.** Run the acceptance test command once before declaring success. If it's red, fix it or `exit 1` with the failure — never end the run on a failing test (that trips the verifier's `transcript_errors` downgrade).
 - **Fail loud, fail fast.** On any step failure, print one diagnostic line and `exit 1`; don't swallow with `|| true` or spin in a silent retry. A `rateLimited` exit-1 is the scheduler's benign auto-pause (auto-resumes next window) — not a failure to engineer around.
 - **Stay in the AC.** Do not add work past the acceptance checklist ("while we're here" generators/fixtures are the post-AC-overrun incident). Body must be clean UTF-8 — no NUL/control bytes.
-- **You ARE the executor — never re-queue or self-schedule.** A headless PRD run must perform its own acceptance criteria directly. Do NOT invoke `/develop`, `/process-feedback`, or any queue-authoring skill from inside a run — those are interactive main-loop skills that author a *new* PRD and return, so the run exits 0 having done nothing (no commit, no sentinel → `needs_review` with `no_verdict_sentinel`). Do NOT call `ScheduleWakeup`/set a tracking loop either — the process exits when the run ends and nothing re-invokes it. This applies just as much to spawning your own review agents and waiting on them: do NOT invoke `/code-review`, `/security-review`, `requesting-code-review`, or any other skill/subagent as a background/async step and then end your turn with something like "I'll wait for the review agents to complete" — a headless run has no next turn, so that line is the run's last output, no verdict sentinel prints, and the job parks in `needs_review` even though the actual work already landed. If a PRD's acceptance criteria call for a second review pass, run it **synchronously, inline, before the finish protocol** — call the reviewer and read its result in the same turn, don't fire-and-wait. If the PRD's work looks large, decompose and execute it inline within this run; never delegate it back to the queue. (Incidents: PRD 460 invoked `/develop`, spawned a duplicate PRD 461, and exited 0 with no work. PRD 479 landed its commit correctly but then backgrounded `/code-review --fix` + `/security-review` and called `ScheduleWakeup` to "wait" for them — same class of failure, different entry point.)
+- **You ARE the executor — never re-queue or self-schedule.** A headless PRD run must perform its own acceptance criteria directly. Do NOT invoke `/develop`, `/propose-epic`, or any queue-authoring skill from inside a run — those are interactive main-loop skills that author a *new* PRD and return, so the run exits 0 having done nothing (no commit, no sentinel → `needs_review` with `no_verdict_sentinel`). Do NOT call `ScheduleWakeup`/set a tracking loop either — the process exits when the run ends and nothing re-invokes it. This applies just as much to spawning your own review agents and waiting on them: do NOT invoke `/code-review`, `/security-review`, `requesting-code-review`, or any other skill/subagent as a background/async step and then end your turn with something like "I'll wait for the review agents to complete" — a headless run has no next turn, so that line is the run's last output, no verdict sentinel prints, and the job parks in `needs_review` even though the actual work already landed. If a PRD's acceptance criteria call for a second review pass, run it **synchronously, inline, before the finish protocol** — call the reviewer and read its result in the same turn, don't fire-and-wait. If the PRD's work looks large, decompose and execute it inline within this run; never delegate it back to the queue. (Incidents: PRD 460 invoked `/develop`, spawned a duplicate PRD 461, and exited 0 with no work. PRD 479 landed its commit correctly but then backgrounded `/code-review --fix` + `/security-review` and called `ScheduleWakeup` to "wait" for them — same class of failure, different entry point.)
 - **A shared-repo `cwd` can be occupied by a concurrent job — check before you touch shared state.** When a PRD's `cwd` is a repo other headless runs may also target (a shared team repo like sigma, not a private single-purpose project), a `git checkout`/`gh pr checkout` can land you in another job's live worktree with its own uncommitted WIP. Before running `git stash`, `git reset`, or any command that discards or hides working-tree state, check `git stash list` and `git status` first, and if you must set aside pre-existing uncommitted changes that aren't yours, **stash with a descriptive message** (`git stash push -m "pre-existing WIP found by PRD <NN>, not mine"`) and **restore it before your run ends** (or, if you can't safely restore because your own commit depends on that worktree state, leave it stashed with the message and say so explicitly in your finish output — never let the run end silently dropping someone else's stash). Never `git stash drop`/`git clean -fd` on state you didn't create. (Incident: PRD 477 stashed a concurrent job's rAF-throttle-revert WIP to get its own checkout, finished, and exited without restoring it — orphaning the other job's uncommitted work in `stash@{0}` with no record of whose it was.)
 - **`gh pr edit --body` can fail on repos with legacy GitHub Projects (classic) boards** — the underlying GraphQL query fetches `repository.pullRequest.projectCards`, a field GitHub is sunsetting, and errors with `GraphQL: Projects (classic) is being deprecated ... (repository.pullRequest.projectCards)` even though the edit itself would otherwise succeed. This is a known `gh` CLI quirk, not a defect in your work. Prefer `gh api -X PATCH repos/<owner>/<repo>/pulls/<n> -f body="$(cat body.md)"` for updating a PR description headlessly — it doesn't touch the deprecated field. If you do use `gh pr edit` and it fails this way, don't leave the bare GraphQL error as the last thing in that step (it reads as an unrecovered error in the final-20%-of-transcript verifier heuristic): immediately retry with the `gh api` form and print one line noting the known-bug fallback, so the recovery is adjacent to the error.
 - **`gh pr checks`/`gh run watch` exit non-zero while CI is merely *pending*, not failed — don't let that surface as a bare error.** Polling `gh pr checks <n>` before checks finish returns a non-zero exit (e.g. 8) with output like `check  pending  0  <url>` — this is normal, documented `gh` CLI behavior, not a failure. If you retry with a *differently-worded* command (e.g. dropping a `sleep N &&` prefix, or switching to `gh run watch <id> --exit-status`), the verifier's self-recovery detector pairs retries by exact command-description match and may not recognize the differently-worded retry as the same recovery, leaving the original pending-state error looking unrecovered in the transcript (incident: `745-pr188-ci-lint-docs-integrity`, a fully green, committed, pushed run flagged `needs_review` over exactly this). Prefer polling with the *same* command/description each time (e.g. loop `gh pr checks <n>` unchanged, or use `gh run watch <id> --exit-status` from the start rather than switching mid-poll) so a later success is recognized as recovering the earlier pending-state failure.

package/plugins/session-manager-dev/skills/explain-to-me/SKILL.md

@@ -67,9 +67,9 @@ If you can't state it in the present tense without a date or a PRD, cut it.
 - **The Skill Map** — `session-manager-operations/HUMAN_LEARN/SKILL_MAP.html`, a
   **separate, dedicated** page (NOT a section of index.html) that visualizes the
   *local-development skill chain*: the two intakes (interactive human prompt;
-  agent feedback via `/process-feedback`) converging on `/develop`, which owns
+  agent proposals via `/propose-epic`, approved by the user) converging on `/develop`, which owns
   PRD authoring + reads `standards.md`, queues onto the scheduler, and gates with
-  review/verify — plus `/my-feedback` outbound. It is the "how I build on this
+  review/verify. It is the "how I build on this
   project" companion to index.html's "how this project works." index.html links
   to it from the nav; it links back.
 

package/plugins/session-manager-dev/skills/find-opportunity/SKILL.md

@@ -74,7 +74,7 @@ blocking PR number — never a silent omission.
 
 - This skill only *reads* the tracker (issues/PRs) and git state — it makes no commits,
   opens nothing, and files nothing. If the loop surfaces a genuine follow-up that can't be
-  picked now, note it in the report; do not auto-file a new issue or `/my-feedback` item
+  picked now, note it in the report; do not auto-file a new issue or `/propose-epic` item
   for it. Filing anything public/outward is a human decision, not this skill's default.
 - Don't rank an item you couldn't verify is actually unclaimed and non-conflicting — when
   in doubt, put it in the skip list with the uncertainty stated, rather than ranking a

package/plugins/session-manager-dev/skills/project-status/SKILL.md

@@ -134,51 +134,37 @@ A status check shouldn't dead-end at a report. Once the four dimensions are in,
 self-contained *bootstrap → evaluate → improve* loop, usable even on a brand-new
 project.
 
-**First, work the inbox — triage before generating new work.** Right after the
-audit, clear the inbound queue via **`/process-feedback`**: it evaluates any
-pending feedback (cross-project asks others filed to us, plus the prior cycle's
-`/optimize-kpi` item) and routes each — ours-do-it → `/develop`, theirs →
-`/my-feedback`, decline-with-reason. Don't generate new levers on top of an
-unprocessed backlog. (If the inbox is empty, say so and move on.)
-
-**Reconcile queued feedback — this audit owns it, because `/process-feedback`
-hands off at queue time.** Under the resilience contract, `/process-feedback` is
-done the moment an item is queued as a PRD and archived to `processed/` — it does
-NOT wait for the PRD to land. So the ongoing tracking is **this skill's job**: as
-part of the chores/scheduler audit, cross-reference the feedback status-log
-against `queue.json` and (a) flip any **🛠** row whose PRD now shows `completed`
-to **✅** with the landing evidence, and (b) surface any `failed` / `needs_review`
-/ stuck Burrow PRD behind a still-🛠 row as a finding to route. The file is
-already in `processed/`; only the row's status is reconciled here. A `-local` may
-supply the exact cross-reference command (grep 🛠 rows → look up their PRD id in
-the queue); if it doesn't, do it inline. Never expect `/process-feedback` to have
-delivery-gated the archive — that's the anti-pattern this split removes.
+**First, work the pending proposals — decide before generating new work.** Right
+after the audit, look at the project's **proposed Epics** (status `proposed` in
+`session-manager-operations/prompt-sessions/active-index.json`): these are the
+items agents filed for a human decision. Report them so the user can approve
+or discard; do not
+approve them yourself, and do not stack new levers on top of an undecided
+backlog. (If there are none, say so and move on.)
+
+There is no inbox to reconcile and no archive convention to keep in step: an
+approved proposal becomes an active Epic whose PRDs and runs are already visible
+in the Scheduler, so its status is read from the queue directly rather than
+tracked in a parallel status log.
 
 Then route **this audit's own findings**, by ownership:
 
 1. **A finding that belongs to another project** (an upstream/downstream service
    in the stack — e.g. the data source is stale, a contract drifted): do NOT
-   reach across the boundary. File it with **`/my-feedback <project>`** into that
-   project's intake, and note it in the report. (Same rule as everywhere: service
-   boundaries outrank convenience.)
+   reach across the boundary. File it with **`/propose-epic <that project's cwd>`**,
+   and note it in the report. (Same rule as everywhere: service boundaries
+   outrank convenience.)
 2. **A finding that belongs to THIS project** (a real bug, a missing guard, an
    enhancement the audit revealed — a cold sold-surface, a recurring error in the
    logs, a usage gap): queue it as a scheduled PRD via **`/develop`** — never
    implement it inline here. Record the queued PRD id in the report.
 3. **Nothing actionable** — just report.
 
-Then, the improvement gate: **if and only if the full health verdict is GREEN**
-(every check passing — not degraded, not down) **and** the KPI/crons are clean,
-invoke **`/optimize-kpi`** to drive the next North-Star improvement. The green gate
-is load-bearing: optimizing the KPI on a broken or degraded base is wasted
-motion — *fix health first* (via routes 1/2 above), and let a later run, once
-green, trigger the optimizer. State explicitly in the report whether the gate
-opened (green → optimize queued) or stayed shut (degraded/down → health findings
-routed first).
-
-This sequence — audit → route findings (my-feedback / develop) → optimize-when-green
-— is enough to bootstrap, evaluate, and continuously improve a project from a
-single `/project-status` invocation. The `-local` owns the *specifics* of each
+Then stop. There is no automatic improvement gate: findings are routed as
+proposals and PRDs above, and the user decides what gets worked on next.
+
+This sequence — audit → route findings (propose-epic / develop) — is enough to
+bootstrap and evaluate a project from a single `/project-status` invocation. The `-local` owns the *specifics* of each
 step; this framework owns the *loop*.
 
 ## Model expectation (every local must mirror this)

package/plugins/session-manager-dev/skills/propose-epic/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: propose-epic
+description: >-
+  File work you think should happen as a PROPOSED Epic — an Epic that does not
+  start until a human presses Approve. Replaces the retired /process-feedback
+  and /my-feedback intake pipeline: there is no feedback folder, no triage
+  pass, and no archiving convention, because the proposal IS the work item.
+  Use whenever you would previously have written a feedback file — for this
+  project or another one — or whenever the user says "/propose-epic",
+  "propose this", "file this for later", "suggest we do X", "send feedback to
+  X". Keywords: propose, proposal, feedback, enhancement request, file for
+  approval, cross-project request, backlog.
+---
+
+# propose-epic
+
+**Role:** the one way an agent asks for work to happen that it is not doing right now.
+
+You do not implement, and you do not queue anything that runs. You file a **proposed
+Epic** and stop. A human approves it in the Epics workspace, at which point its objective
+becomes the first prompt of its own claude session — the same start path every hand-created
+Epic takes.
+
+## Why this replaced the feedback folder
+
+The old flow was: write a markdown file into `session-manager-operations/feedback/` →
+`/process-feedback` later reads it, evaluates it, dedupes it, queues PRDs via `/develop`,
+archives the file to `processed/`, and updates a README with lessons. Four moving parts and
+~400 lines of instructions existed to move an idea from "written down" to "being worked on".
+
+An Epic already is that thing. It has a goal, an intent tag, its own session, its own PRD
+directory, and a place in the UI. The only piece it was missing was "don't start yet" —
+that is the `proposed` status. So the intake pipeline collapses into one command.
+
+## How to file one
+
+```bash
+node "$SM_ROOT/scripts/propose-epic.cjs" <project-cwd> "<one-line title>" [feature|bug|discussion] <<'BODY'
+<the full objective — this is sent verbatim as the first prompt on approval>
+BODY
+```
+
+`$SM_ROOT` is session-manager's own package root. Resolve it once, in this order:
+1. You are working inside the session-manager repo → `.` (use `scripts/propose-epic.cjs`).
+2. Otherwise the installed package — this skill file lives at
+   `<SM_ROOT>/plugins/session-manager-dev/skills/propose-epic/SKILL.md`, so
+   `SM_ROOT` is four directories up from this file's own path.
+
+- **`<project-cwd>`** — the project the work belongs to. Cross-project requests are just a
+  proposal filed into *that* project's cwd; there is no separate outbound skill.
+- **title** — one line. It is what the Epics list shows. Keep it specific: `Scheduler rows
+  don't show their Epic`, not `Scheduler bug`.
+- **body** — write it as an instruction to the agent that will pick it up, not as a report
+  to a human. Include what you observed, where in the code it lives (file:line if you know
+  it), and what done looks like. It is the first prompt, so it should be enough to act on.
+- Re-proposing the same title into the same project **joins** the existing proposal and
+  enriches it rather than duplicating it. Say more in the body and re-run; that is the
+  update mechanism.
+
+Report back the Epic id and the title you filed. Do not queue PRDs, do not edit code, and
+do not ask whether you should file it — filing is the default action, and the approval gate
+is the user's control, not your prompt.
+
+## When NOT to propose
+
+- The user asked you to do the work now → do it (or `/develop` it), don't propose it.
+- It is a one-line fix you are already in the file for → just fix it.
+- Nothing actionable → say so plainly and file nothing.

package/scripts/lib/watchdogHelpers.cjs

@@ -294,7 +294,7 @@ function hasOpenFeedback(cwd) {
  *
  * Complexity: O(P) over PRD files in prdsDir + O(J) over queue jobs.
  */
-function emitFeedbackPRD(cwd, {
+async function emitFeedbackPRD(cwd, {
   prdsDir,
   queuePath,
   skillPath,
@@ -313,7 +313,7 @@ function emitFeedbackPRD(cwd, {
     // Every PRD belongs to an Epic (CLAUDE.md domain model). The sweep joins
     // one standing "Inbound feedback" Epic per project (reuseByGoal) so
     // recurring ticks chain into a single Epic rather than minting one each.
-    const epic = ensureEpic(cwd, {
+    const epic = await ensureEpic(cwd, {
       goalText: 'Inbound feedback processing',
       tag: 'discussion',
       reuseByGoal: true,
@@ -474,7 +474,7 @@ function emitFeedbackPRD(cwd, {
     if (epicId !== null) {
       // Trace the dispatch on the Epic's event chain (prompt → prd_created →
       // ...) so the Epic conversation shows the PRD it spawned.
-      try { appendPrdCreatedEvent(cwd, epicId, slug, `Feedback sweep emitted ${slug}`); } catch { /* trace is best-effort */ }
+      try { await appendPrdCreatedEvent(cwd, epicId, slug, `Feedback sweep emitted ${slug}`); } catch { /* trace is best-effort */ }
     }
   } catch (e) {
     try { fs.unlinkSync(tmpPath); } catch { /* best-effort cleanup */ }
@@ -655,7 +655,7 @@ function maybeRelaunchApp({
  *   projectsDir  — forwarded to activeProjectCwds for testing
  *   prdsDir, queuePath, skillPath, standardsPath — forwarded to emitFeedbackPRD
  */
-function sweep({
+async function sweep({
   projectsDir,
   prdsDir,
   queuePath,
@@ -679,7 +679,7 @@ function sweep({
     // dir); an explicit override (tests) is forwarded verbatim to every cwd.
     let result;
     try {
-      result = emitFeedbackPRD(cwd, { prdsDir, queuePath, skillPath, standardsPath });
+      result = await emitFeedbackPRD(cwd, { prdsDir, queuePath, skillPath, standardsPath });
     } catch (e) {
       process.stderr.write(`[sweep] error emitting PRD for ${cwd}: ${e?.message}\n`);
       continue;

package/scripts/mint-epic.cjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * mint-epic.cjs — CLI wrapper over lib/epicMint.cjs for PRD authors working
+ * without the app's admin API (the /develop skill's manual-write fallback).
+ *
+ * Usage:
+ *   node scripts/mint-epic.cjs <cwd> "<goal text>" [feature|bug|discussion]
+ *
+ * Prints the Epic's prds/ write directory on stdout (last line), minting the
+ * Epic (and registering it in prompt-sessions/active-index.json) if no active
+ * Epic with the same goal text exists — reuse-by-goal, so re-running for the
+ * same goal is idempotent and returns the same directory.
+ */
+'use strict';
+
+const { ensureEpic } = require('../src/main/lib/epicMint.cjs');
+
+const [cwd, goalText, tag] = process.argv.slice(2);
+if (!cwd || !goalText) {
+  process.stderr.write('usage: mint-epic.cjs <cwd> "<goal text>" [feature|bug|discussion]\n');
+  process.exit(1);
+}
+
+(async () => {
+  const { epicId, prdDir, created } = await ensureEpic(cwd, { goalText, tag, reuseByGoal: true });
+  process.stderr.write(`${created ? 'minted' : 'joined'} epic ${epicId}\n`);
+  process.stdout.write(`${prdDir}\n`);
+})();

package/scripts/propose-epic.cjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * propose-epic.cjs — file an Epic that does NOT start.
+ *
+ * This is the replacement for the feedback-folder intake. Instead of writing
+ * a markdown file into `session-manager-operations/feedback/` for a separate
+ * skill to later parse, triage, dedupe and re-queue, an agent files a
+ * `proposed` Epic: it appears in the Epics workspace with an Approve & start
+ * gate, and nothing runs or is spent until a human presses it.
+ *
+ * One mechanism replaces the whole intake pipeline — the proposal IS the
+ * work item, already in the place work is done, already carrying its own
+ * session and PRD directory.
+ *
+ * Usage:
+ *   node scripts/propose-epic.cjs <cwd> "<one-line title>" [feature|bug|discussion]
+ *     # full body (the first prompt sent on approval) is read from stdin;
+ *     # when stdin is empty the title is used as the body.
+ *
+ * Prints the Epic id on stdout. Reuse-by-title: re-proposing the same title
+ * into the same project joins the existing proposal instead of duplicating it.
+ */
+'use strict';
+
+const { ensureEpic } = require('../src/main/lib/epicMint.cjs');
+
+const [cwd, title, tag] = process.argv.slice(2);
+if (!cwd || !title) {
+  process.stderr.write('usage: propose-epic.cjs <cwd> "<title>" [feature|bug|discussion]  (body on stdin)\n');
+  process.exit(1);
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) { resolve(''); return; }
+    let buf = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (d) => { buf += d; });
+    process.stdin.on('end', () => resolve(buf));
+    process.stdin.on('error', () => resolve(''));
+  });
+}
+
+(async () => {
+  const body = (await readStdin()).trim();
+  const { epicId, created } = await ensureEpic(cwd, {
+    goalText: title,
+    tag: tag || 'feature',
+    status: 'proposed',
+    reuseByGoal: true,
+    openingPrompt: body || title,
+  });
+  process.stderr.write(`${created ? 'proposed' : 'joined existing proposal'} epic ${epicId}\n`);
+  process.stdout.write(`${epicId}\n`);
+})();

package/src/main/__tests__/epicMint.test.cjs

@@ -0,0 +1,85 @@
+/**
+ * epicMint.test.cjs — unit tests for ensureEpic's sourcePromptId join
+ * semantics (see PRD authoring notes: sourcePromptId must be an existing
+ * Epic's promptSessionId, i.e. its active-index.json sessions key — NOT a
+ * PromptTicket.id).
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/epicMint.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, afterEach } from 'vitest';
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const { ensureEpic, removeEpic, readActiveIndex } = require('../lib/epicMint.cjs');
+
+const tmpDirs = [];
+afterEach(async () => {
+  while (tmpDirs.length) {
+    const d = tmpDirs.pop();
+    await fsp.rm(d, { recursive: true, force: true });
+  }
+});
+
+async function mkCwd() {
+  const cwd = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-epicmint-cwd-'));
+  tmpDirs.push(cwd);
+  return cwd;
+}
+
+test('ensureEpic mints a new Epic when explicit epicId matches no existing Epic (documents current behavior for a stray PromptTicket.id)', async () => {
+  const cwd = await mkCwd();
+  const notAPromptSessionId = 'ticket-abc123';
+
+  const result = await ensureEpic(cwd, { goalText: 'do the thing', epicId: notAPromptSessionId });
+
+  expect(result.created).toBe(true);
+  expect(result.epicId).not.toBe(notAPromptSessionId);
+
+  const index = readActiveIndex(cwd);
+  expect(index.sessions[notAPromptSessionId]).toBeUndefined();
+  expect(index.sessions[result.epicId]).toBeDefined();
+  expect(Object.keys(index.sessions)).toHaveLength(1);
+});
+
+test('ensureEpic joins the existing Epic when explicit epicId equals its promptSessionId', async () => {
+  const cwd = await mkCwd();
+
+  const first = await ensureEpic(cwd, { goalText: 'initial epic goal' });
+  expect(first.created).toBe(true);
+
+  const second = await ensureEpic(cwd, { goalText: 'a different PRD title', epicId: first.epicId });
+
+  expect(second.created).toBe(false);
+  expect(second.epicId).toBe(first.epicId);
+  expect(second.prdDir).toBe(first.prdDir);
+
+  const index = readActiveIndex(cwd);
+  expect(Object.keys(index.sessions)).toHaveLength(1);
+});
+
+test('removeEpic deletes a minted Epic from both sessions and events maps', async () => {
+  const cwd = await mkCwd();
+  const minted = await ensureEpic(cwd, { goalText: 'to be rolled back' });
+  expect(readActiveIndex(cwd).sessions[minted.epicId]).toBeDefined();
+
+  const removed = removeEpic(cwd, minted.epicId);
+
+  expect(removed).toBe(true);
+  const index = readActiveIndex(cwd);
+  expect(index.sessions[minted.epicId]).toBeUndefined();
+  expect(index.events[minted.epicId]).toBeUndefined();
+});
+
+test('removeEpic is a no-op (returns false) for an unknown epicId', async () => {
+  const cwd = await mkCwd();
+  await ensureEpic(cwd, { goalText: 'unrelated epic' });
+
+  const removed = removeEpic(cwd, 'nonexistent-epic-id');
+
+  expect(removed).toBe(false);
+  expect(Object.keys(readActiveIndex(cwd).sessions)).toHaveLength(1);
+});

package/src/main/__tests__/prdCreate.test.cjs

@@ -171,7 +171,7 @@ function makeFakeRemoteWithPrdsDir(prdsDir) {
     async writePrd(slug, body) {
       try {
         const filePath = path.join(prdsDir, `${slug}.md`);
-        await config.writeTextAtomic(filePath, body);
+        await config.writeTextAtomic(filePath, body, { writer: 'scheduler' });
         return { ok: true };
       } catch (e) {
         return { ok: false, error: e?.message };
@@ -413,7 +413,8 @@ test('validateWrite allows writes under <root>/session-manager-operations/schedu
   await fsp.mkdir(prdsDir, { recursive: true });
   const filePath = path.join(prdsDir, '1-do-thing.md');
 
-  await config.writeTextAtomic(filePath, 'PRD body\n');
+  // Writes into scheduler/ must declare the owning surface (single-writer law).
+  await config.writeTextAtomic(filePath, 'PRD body\n', { writer: 'scheduler' });
 
   expect(fs.existsSync(filePath)).toBeTruthy();
   expect(await fsp.readFile(filePath, 'utf8')).toBe('PRD body\n');
@@ -437,6 +438,57 @@ test('createPrd normalizes a `~`-prefixed cwd via expandHome before calling remo
   }
 });
 
+// ──────────────────────────────────────────── PRD 862: register cwd as an
+// allowed write root at createPrd() time, not only at pty.spawn() time
+//
+// Before this fix, config.cjs's allowedRoots (the write-boundary allowlist)
+// only ever grew via pty.cjs's addAllowedRoot call inside pty.spawn(). A
+// chat-only Epic (headless `claude -p --resume`, no Terminal PTY ever
+// spawned for its project cwd) reached createPrd() -> remote.writePrd() ->
+// config.writeTextAtomic() -> config.validateWrite() and failed with "Write
+// outside allowed write boundaries", purely because no PTY had registered
+// that cwd yet in this process's lifetime. This test reproduces that exact
+// scenario: a brand-new project root that has NEVER had config.addAllowedRoot
+// called for it (mirroring pty.spawn() never having run), writing through the
+// real config.writeTextAtomic into the real session-manager-operations/
+// scheduler/ subtree (not the mocked-remote temp dirs the other tests here
+// use, which pre-register their root via addAllowedRoot in mkTmpPrdsDir).
+test('createPrd registers cwd as an allowed write root itself, so a chat-only Epic (no Terminal PTY ever spawned for this cwd) can still write its PRD', async () => {
+  // Must live under $HOME: validatePath's read boundary is home-dir-wide
+  // regardless of allowedRoots registration (matching every real project
+  // cwd, which checkInsideHome forces inside $HOME) — the bug this test
+  // reproduces is specifically about the *write* boundary (validateWrite),
+  // not the read one.
+  const root = await fsp.mkdtemp(path.join(os.homedir(), '.sm-chat-only-epic-'));
+  // Deliberately do NOT call config.addAllowedRoot(root) here — pty.spawn()
+  // is the only other caller of addAllowedRoot, and it never runs for a
+  // chat-only Epic. createPrd() itself must perform this registration.
+  const prdsEpicDir = path.join(root, 'session-manager-operations', 'scheduler', 'epics', 'chat-only-epic', 'prds');
+
+  try {
+    const remote = {
+      async allocateParallelGroup() { return 1; },
+      async readPrd() { return { ok: false }; },
+      async writePrd(slug, body) {
+        await fsp.mkdir(prdsEpicDir, { recursive: true });
+        const filePath = path.join(prdsEpicDir, `${slug}.md`);
+        // Real config.cjs write path — this is what threw
+        // "Write outside allowed write boundaries" before the fix.
+        await config.writeTextAtomic(filePath, body, { writer: 'scheduler' });
+        return { ok: true };
+      },
+    };
+
+    const result = await createPrd(validCreateBody({ cwd: root }), remote);
+
+    expect(result.ok).toBe(true);
+    const written = await fsp.readFile(path.join(prdsEpicDir, result.filename), 'utf8');
+    expect(written).toMatch(/title: Add widget frobnication/);
+  } finally {
+    await fsp.rm(root, { recursive: true, force: true });
+  }
+});
+
 test('POST /admin/scheduler/create-prd with sourcePromptId writes it into the created PRD frontmatter', async () => {
   const prdsDir = await mkTmpPrdsDir();
   const remote = makeFakeRemoteWithPrdsDir(prdsDir);

package/src/main/__tests__/promptSessionEvents.test.cjs

@@ -9,13 +9,18 @@
 
 'use strict';
 
-import { test, expect, beforeEach } from 'vitest';
+import { test, expect, beforeEach, vi } from 'vitest';
 const fs = require('node:fs');
 const fsp = require('node:fs/promises');
 const os = require('node:os');
 const path = require('node:path');
 const config = require('../config.cjs');
-const { appendResponseEventIfKnown, promptSessionActiveIndexPath } = require('../promptSessionEvents.cjs');
+const {
+  appendResponseEventIfKnown,
+  promptSessionActiveIndexPath,
+  attachWindow,
+  EVENT_APPENDED_CHANNEL,
+} = require('../promptSessionEvents.cjs');
 
 let cwd;
 
@@ -104,3 +109,52 @@ test('returns false (never throws) when cwd or sourcePromptId is missing', async
   await expect(appendResponseEventIfKnown(null, 'psess-1', 'hi')).resolves.toBe(false);
   await expect(appendResponseEventIfKnown(cwd, null, 'hi')).resolves.toBe(false);
 });
+
+test('broadcasts EVENT_APPENDED_CHANNEL to the attached window on a successful append', async () => {
+  await writeIndex({
+    sessions: { 'psess-1': { id: 'psess-1', cwd, status: 'active' } },
+    events: {
+      'psess-1': [
+        { id: 'pevt-1', promptSessionId: 'psess-1', kind: 'prompt', causedByEventId: null, at: '2026-01-01T00:00:00.000Z' },
+      ],
+    },
+  });
+
+  const send = vi.fn();
+  const fakeWindow = { isDestroyed: () => false, webContents: { isDestroyed: () => false, send } };
+  attachWindow(fakeWindow);
+  try {
+    const routed = await appendResponseEventIfKnown(cwd, 'psess-1', 'PRD finished');
+    expect(routed).toBe(true);
+    expect(send).toHaveBeenCalledTimes(1);
+    const [channel, payload] = send.mock.calls[0];
+    expect(channel).toBe(EVENT_APPENDED_CHANNEL);
+    expect(payload.cwd).toBe(cwd);
+    expect(payload.promptSessionId).toBe('psess-1');
+    expect(payload.event.kind).toBe('response');
+    expect(payload.event.text).toBe('PRD finished');
+    expect(payload.event.causedByEventId).toBe('pevt-1');
+  } finally {
+    attachWindow(null);
+  }
+});
+
+test('does not throw broadcasting before a window is attached, or after it is destroyed', async () => {
+  await writeIndex({
+    sessions: { 'psess-1': { id: 'psess-1', cwd, status: 'active' } },
+    events: {
+      'psess-1': [
+        { id: 'pevt-1', promptSessionId: 'psess-1', kind: 'prompt', causedByEventId: null, at: '2026-01-01T00:00:00.000Z' },
+      ],
+    },
+  });
+
+  attachWindow(null);
+  await expect(appendResponseEventIfKnown(cwd, 'psess-1', 'no window yet')).resolves.toBe(true);
+
+  const destroyedWindow = { isDestroyed: () => true, webContents: { isDestroyed: () => false, send: vi.fn() } };
+  attachWindow(destroyedWindow);
+  await expect(appendResponseEventIfKnown(cwd, 'psess-1', 'window destroyed')).resolves.toBe(true);
+  expect(destroyedWindow.webContents.send).not.toHaveBeenCalled();
+  attachWindow(null);
+});