spectoflow 0.23.5 → 0.27.0

package/lib/dashboard/meeting.js

@@ -0,0 +1,116 @@
+'use strict';
+/*
+ * Daily meeting — generates a dated standup-style note (.spectoflow/meetings/<date>.md) via the
+ * configured agent. Structurally parallel to summarize.js's runSummarize (read that first — this
+ * file mirrors its resolveRunnerCommand/spawn/emit shape exactly) but differs in two ways: what it
+ * feeds the agent (a digest of recent task activity + the chat log, not just the chat log alone) and
+ * where the result lands (a dated file under .spectoflow/meetings/, via files.js, never
+ * runtime.messages — a meeting note is a project artifact, not a chat message).
+ */
+const { spawn } = require('child_process');
+const store = require('../store');
+const files = require('./files');
+const { resolveRunnerCommand } = require('./runner');
+const { formatLog } = require('./summarize'); // reused as-is rather than reimplemented — see report
+
+const TASK_LIMIT = 20; // mirrors summarize.js's own DEFAULT_LIMIT philosophy (cap, most-recent-last)
+const LOG_LIMIT = 40; // same DEFAULT_LIMIT summarize.js uses for the chat log
+
+// YYYY-MM-DD in the machine running the dashboard's OWN local time zone. This is a deliberate,
+// explicit choice (see the project report for the full reasoning): a meeting note's filename must be
+// unambiguous, and this is a single-writer local tool — a viewer's own browser time zone must never
+// decide which file "today" resolves to (it could differ from the server's, or from another viewer's
+// browser, producing two different "today"s for the same project). The client reads this same value
+// back from GET /api/project (ops.js's 'project.read' → p.todayDate), so both halves of this feature
+// (manual edit and agent-generate) agree on exactly one "today".
+function todayLocal() {
+  const d = new Date();
+  const y = d.getFullYear(), m = String(d.getMonth() + 1).padStart(2, '0'), day = String(d.getDate()).padStart(2, '0');
+  return `${y}-${m}-${day}`;
+}
+
+// "id: title (status)" lines for tasks that are done or in_progress — a cheap, already-available
+// proxy for "what was built / is in flight" (no new aggregation invented), most-recent-last order
+// (readPlans' own file/task order), capped to TASK_LIMIT.
+function formatTasks(plans, limit = TASK_LIMIT) {
+  const tasks = [];
+  for (const pl of plans || []) {
+    for (const ph of pl.phases || []) {
+      for (const t of ph.tasks || []) {
+        if (t.status === 'done' || t.status === 'in_progress') tasks.push(t);
+      }
+    }
+  }
+  return tasks.slice(-limit).map((t) => `${t.id}: ${t.title} (${t.status})`).join('\n');
+}
+
+// Strict YYYY-MM-DD only. This is the security boundary for the meetings feature: meetingPath()
+// concatenates `date` straight into a file path, and files.writeFile()'s own safePath() guard only
+// rejects a path that resolves OUTSIDE the project root entirely — it does NOT confine a write to
+// .spectoflow/meetings/, so an unvalidated date like "../../important" would happily write to
+// <root>/important.md. Every caller of meetingPath()/runMeetingGenerate() with a date that did not
+// come from todayLocal() MUST go through this check first (see runMeetingGenerate below).
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+function isValidDate(date) {
+  return DATE_RE.test(date);
+}
+
+function meetingPath(date) {
+  return `.spectoflow/meetings/${date}.md`;
+}
+
+// Same "reply with the text only" instruction line runSummarize already uses (already well-tuned),
+// adapted for a daily-meeting-note framing instead of a chat-log-digest framing.
+function buildPrompt(plans, messages) {
+  const taskDigest = formatTasks(plans) || '(no done / in-progress tasks yet)';
+  const logDigest = formatLog(messages, LOG_LIMIT) || '(no recent chat activity)';
+  return 'Write a short daily meeting note for this project, standup-style: what was done, '
+    + 'what\'s in progress or blocked, and suggested next steps — 3-6 concise bullet points or short '
+    + 'paragraphs. Reply with the note text only: no preamble, no sentinel lines, and do not read, '
+    + 'search or edit any files — answer using only the digest below.'
+    + '\n\nRecent tasks:\n' + taskDigest
+    + '\n\nRecent chat log:\n' + logDigest;
+}
+
+// Generates a daily meeting note and WRITES it to .spectoflow/meetings/<date>.md (default: today —
+// see todayLocal()), OVERWRITING whatever is already there. Overwrite-SAFETY (not silently
+// destroying a real existing note) is the CLIENT's responsibility — see app.js's meeting-generate
+// confirm flow — this function trusts its caller the same way runSummarize trusts chat.summarize's
+// caller. Returns { child } on success or { error }, mirroring runSummarize's own shape exactly.
+function runMeetingGenerate(root, { agent, date } = {}, emit) {
+  const cfg = store.readConfig(root);
+  const which = agent || cfg.agent || 'claude';
+  const cmdStr = resolveRunnerCommand(root, cfg, which);
+  if (!cmdStr) return { error: `No runner configured for "${which}".` };
+
+  const day = date || todayLocal();
+  if (!isValidDate(day)) return { error: 'Invalid date.' };
+  const plans = store.readPlans(root);
+  const messages = store.readRuntime(root).messages || [];
+  const prompt = buildPrompt(plans, messages);
+
+  const parts = cmdStr.split(/\s+/).filter(Boolean);
+  const runId = 'meeting-' + Date.now().toString(36);
+  // Emitted before the spawn attempt (same order runner.js/summarize.js use) so the client's "agent
+  // running" indicator lights up immediately, and a spawn failure below still gets a matching run-end.
+  if (emit) emit({ type: 'run-start', run: { id: runId } });
+  let child;
+  // windowsHide: without it, spawning a .cmd-shimmed CLI on Windows pops up a real console window.
+  try { child = spawn(parts[0], [...parts.slice(1), prompt], { cwd: root, env: process.env, windowsHide: true }); }
+  catch (e) { if (emit) emit({ type: 'run-end', runId, code: 1 }); return { error: e.message }; }
+  try { child.stdin && child.stdin.end(); } catch {}
+
+  let out = '';
+  child.stdout && child.stdout.on('data', (d) => { out += d.toString(); });
+  child.stderr && child.stderr.on('data', (d) => { out += d.toString(); });
+  child.on('close', (code) => {
+    const text = out.trim() || (code === 0 ? '(no output)' : `meeting generate failed (exit ${code})`);
+    files.writeFile(root, meetingPath(day), text);
+    // run-end before change, same ordering summarize.js uses — the client must never see "running"
+    // linger past the point where the new content is actually ready to be re-fetched.
+    if (emit) { emit({ type: 'run-end', runId, code }); emit({ type: 'change' }); }
+  });
+  return { child };
+}
+
+module.exports = { runMeetingGenerate, formatTasks, todayLocal, meetingPath, buildPrompt, isValidDate };

package/lib/dashboard/ops.js

@@ -0,0 +1,257 @@
+'use strict';
+/*
+ * The dashboard's operations — one pure function per action, (root, args, ctx) → result, with no
+ * HTTP in sight. handlers.js maps HTTP routes onto this table; the online dashboard (sub-project C)
+ * will map WebSocket messages onto the very same table. ctx.emit broadcasts SSE events to every
+ * client of this project; ops call it themselves after a successful mutation so any caller gets
+ * the same live behaviour. Errors are OpError(status, message) — the transport turns status into
+ * its own vocabulary (HTTP status code today).
+ */
+const fs = require('fs');
+const path = require('path');
+const store = require('../store');
+const files = require('./files');
+const { startRun } = require('./runner');
+const { runSummarize } = require('./summarize');
+const { runMeetingGenerate, todayLocal } = require('./meeting');
+const orchestrator = require('./orchestrator');
+const adapters = require('../adapters');
+const detect = require('../detect');
+
+const PKG_VERSION = require('../../package.json').version;
+
+class OpError extends Error {
+  constructor(status, message) { super(message); this.status = status; }
+}
+const bad = (msg) => { throw new OpError(400, msg); };
+const notFound = (msg) => { throw new OpError(404, msg); };
+const text = (v, msg) => { if (!v || !String(v).trim()) bad(msg); return String(v).trim(); };
+
+function frameworkVersion(root) {
+  try { return JSON.parse(fs.readFileSync(path.join(root, '.spectoflow', '.manifest.json'), 'utf8')).version || PKG_VERSION; } catch { return PKG_VERSION; }
+}
+function findPlanFileForTask(root, id) {
+  for (const pl of store.readPlans(root)) for (const ph of pl.phases) if (ph.tasks.find((t) => t.id === id)) return pl.file;
+  return null;
+}
+function readAgentFile(root, rel) {
+  const base = path.join(root, '.spectoflow');
+  const aDir = path.join(base, 'agents'), sDir = path.join(base, 'skills');
+  const abs = path.resolve(base, rel || '');
+  const okDir = abs.startsWith(aDir + path.sep) || abs.startsWith(sDir + path.sep);
+  if (!okDir || !abs.endsWith('.md') || !fs.existsSync(abs) || fs.statSync(abs).isDirectory()) bad('not an agent/skill file');
+  let real; try { real = fs.realpathSync(abs); } catch { real = null; }
+  const realA = (() => { try { return fs.realpathSync(aDir); } catch { return aDir; } })();
+  const realS = (() => { try { return fs.realpathSync(sDir); } catch { return sDir; } })();
+  const okReal = real && (real.startsWith(realA + path.sep) || real.startsWith(realS + path.sep));
+  if (!okReal || !real.endsWith('.md') || fs.statSync(real).isDirectory()) bad('not an agent/skill file');
+  return { content: fs.readFileSync(real, 'utf8') };
+}
+// The 6 Kanban column ids, mirroring app.js's STATUS keys exactly (order doesn't matter here — the
+// client always re-derives display order from its own STATUS object). Kept as the one server-side
+// source of truth for "what's a real column id" — never trust the client's array blindly.
+const KANBAN_STATUSES = ['todo', 'in_progress', 'to_validate', 'to_analyze', 'done', 'blocked'];
+// The 13 native nav tab ids (Sous-projet C: Task 1 built the mechanism with the original 11; Task 2
+// registered 'notes'; Task 3 registers 'meeting' — the Daily meeting tab — into it), mirroring
+// app.js's ROUTES array exactly — the one server-side source of truth for "what's a real native tab
+// id".
+const NATIVE_TABS = ['board', 'chat', 'requests', 'attention', 'backlog', 'workflow', 'team', 'files', 'notes', 'meeting', 'info', 'docs', 'personalize'];
+function writeConfig(root, patch, detectOpts) {
+  const cp = path.join(root, '.spectoflow', 'config.json');
+  const cfg = JSON.parse(fs.readFileSync(cp, 'utf8'));
+  if (patch.mode && ['autopilot', 'semi', 'manual'].includes(patch.mode)) cfg.mode = patch.mode;
+  if (typeof patch.language === 'string' && patch.language.trim()) cfg.language = patch.language.trim();
+  if (typeof patch.design === 'string' && /^[a-z0-9-]{1,40}$/.test(patch.design)) cfg.design = patch.design;
+  if (typeof patch.theme === 'string' && ['light', 'dark'].includes(patch.theme)) cfg.theme = patch.theme;
+  if (typeof patch.boardView === 'string' && ['list', 'kanban'].includes(patch.boardView)) cfg.boardView = patch.boardView;
+  if (typeof patch.sideHidden === 'boolean') cfg.sideHidden = patch.sideHidden;
+  if (Array.isArray(patch.expandedPhases)) cfg.expandedPhases = patch.expandedPhases.filter((v) => typeof v === 'string');
+  if (typeof patch.activeTab === 'string' && patch.activeTab.trim()) cfg.activeTab = patch.activeTab.trim();
+  if (typeof patch.chatOpen === 'boolean') cfg.chatOpen = patch.chatOpen;
+  // kanbanColumns: reject the whole patch (leave the current value untouched) rather than silently
+  // filtering out bad entries — an invalid/unknown status id here means the client sent something it
+  // shouldn't have, and a real product-safety rule (never persist zero visible columns) applies too.
+  if (Array.isArray(patch.kanbanColumns)) {
+    const allKnown = patch.kanbanColumns.every((v) => typeof v === 'string' && KANBAN_STATUSES.includes(v));
+    const uniq = [...new Set(patch.kanbanColumns)];
+    if (allKnown && uniq.length) cfg.kanbanColumns = uniq;
+  }
+  if (patch.kanbanPageSize === 10 || patch.kanbanPageSize === 20) cfg.kanbanPageSize = patch.kanbanPageSize;
+  // navTabs: same "reject the whole patch" philosophy as kanbanColumns above — plus a stricter safety
+  // rule than Kanban's "can't disable the last column": the stored list must always be a COMPLETE
+  // reordering/enable-state of the full native tab set (every known id exactly once, never a partial
+  // filter), and 'personalize' must always stay enabled — it's the only place the user can ever turn
+  // a tab back on, so letting it be disabled would permanently lock them out (short of hand-editing
+  // config.json on disk).
+  if (patch.navTabs !== undefined) {
+    const arr = patch.navTabs;
+    const valid = Array.isArray(arr)
+      && arr.every((v) => v && typeof v === 'object' && typeof v.id === 'string' && typeof v.enabled === 'boolean')
+      && arr.length === NATIVE_TABS.length
+      && new Set(arr.map((v) => v.id)).size === NATIVE_TABS.length
+      && arr.every((v) => NATIVE_TABS.includes(v.id));
+    const personalizeOk = valid && arr.find((v) => v.id === 'personalize').enabled === true;
+    if (personalizeOk) cfg.navTabs = arr.map((v) => ({ id: v.id, enabled: v.enabled }));
+  }
+  // commands: the dashboard's slash-command macros. Same "reject the whole patch" safety as
+  // kanbanColumns/navTabs above — if it isn't an array, or ANY entry is structurally malformed (a
+  // trigger that fails the format, or an empty instruction), the stored list is left untouched rather
+  // than partially applied. A valid array (including an empty one) replaces it: triggers are deduped
+  // case-insensitively (first wins), description/instruction are trimmed and clamped, enabled coerced.
+  if (patch.commands !== undefined) {
+    const arr = patch.commands;
+    // The format regex has no /i flag (the client is expected to normalize to lowercase before
+    // sending), but it is tested against the lowercased trigger here rather than the raw one: this
+    // still enforces the exact charset/length rule while letting an occasional mixed-case trigger
+    // (e.g. a client that didn't normalize) validate and dedupe correctly instead of taking down the
+    // whole patch over casing alone. The stored trigger is always the canonical lowercase form.
+    const okShape = Array.isArray(arr) && arr.every((c) => c && typeof c === 'object'
+      && typeof c.trigger === 'string' && /^[a-z0-9][a-z0-9_-]{0,39}$/.test(c.trigger.toLowerCase())
+      && typeof c.instruction === 'string' && c.instruction.trim().length > 0);
+    if (okShape) {
+      const seen = new Set(); const out = [];
+      for (const c of arr) {
+        const lc = c.trigger.toLowerCase();
+        if (seen.has(lc)) continue;
+        seen.add(lc);
+        out.push({
+          trigger: lc,
+          description: (typeof c.description === 'string' ? c.description.trim() : '').slice(0, 120),
+          instruction: c.instruction.trim().slice(0, 4000),
+          enabled: c.enabled !== false,
+        });
+      }
+      cfg.commands = out;
+    }
+  }
+  if (typeof patch.agent === 'string' && patch.agent.trim()) {
+    const id = patch.agent.trim();
+    const known = adapters.knownAgents().find((a) => a.id === id);
+    // Never activate an agent whose CLI isn't actually there — it would just fail silently later.
+    if (!detect.isAgentInstalled(id, root, detectOpts)) bad(`${known ? known.label : id} isn't installed here (its command wasn't found on PATH). Install it, then try again.`);
+    cfg.agent = id;
+    if (known && known.runner) { cfg.runners = cfg.runners || {}; if (!cfg.runners[id]) cfg.runners[id] = known.runner; }
+  }
+  fs.writeFileSync(cp, JSON.stringify(cfg, null, 2) + '\n');
+  return cfg;
+}
+const filesResult = (r) => { if (r.error) bad(r.error); return r; };
+const changed = (ctx, result) => { ctx.emit({ type: 'change' }); return result; };
+
+const ops = {
+  'project.read': async (root) => {
+    const p = store.readProject(root);
+    p.version = frameworkVersion(root);
+    p.projectName = path.basename(root);
+    p.knownAgents = adapters.knownAgents().map((a) => ({ id: a.id, label: a.label, headless: a.headless, docsUrl: a.docsUrl }));
+    p.installedAgents = detect.installedAgents(root);
+    // Daily meeting (Sous-projet C, Task 3): the SERVER's own local date — see meeting.js's
+    // todayLocal() header comment for why this, not the browser's date, is the one source of truth
+    // for which .spectoflow/meetings/<date>.md "today" resolves to.
+    p.todayDate = todayLocal();
+    return p;
+  },
+  'agentfile.read': async (root, { path: rel }) => readAgentFile(root, rel),
+
+  'files.tree': async (root) => ({ tree: files.tree(root) }),
+  'files.read': async (root, { path: rel }) => filesResult(files.readFile(root, rel || '')),
+  'files.write': async (root, { path: rel, content }, ctx) => changed(ctx, filesResult(files.writeFile(root, rel, content))),
+  'files.mkdir': async (root, { path: rel }, ctx) => changed(ctx, filesResult(files.mkdir(root, rel))),
+
+  'task.add': async (root, { title, phase, file, owner, level }, ctx) => {
+    const t = store.addTask(root, { title: text(title, 'A title is required.'), phase, file, owner, level });
+    return changed(ctx, { task: t });
+  },
+  'task.update': async (root, { id, patch }, ctx) => {
+    const file = findPlanFileForTask(root, id); if (!file) notFound(`Task ${id} not found.`);
+    store.updateTaskLine(root, file, id, patch || {});
+    return changed(ctx, { ok: true });
+  },
+  'task.comment': async (root, { id, text: body, action }, ctx) => {
+    const msg = text(body, 'Empty comment.');
+    const file = findPlanFileForTask(root, id); if (!file) notFound(`Task ${id} not found.`);
+    store.addTaskComment(root, file, id, msg, 'me');
+    if (action === 'analyze') store.updateTaskLine(root, file, id, { status: 'to_analyze' });
+    return changed(ctx, { ok: true });
+  },
+  'workflow.toggle': async (root, { name }, ctx) => {
+    const wf = path.join(root, '.spectoflow', 'workflow.md');
+    const lines = fs.readFileSync(wf, 'utf8').split('\n');
+    // Strip the trailing {cap:... skill:... policy} annotation BEFORE "(optional)" — the same order as
+    // store.readWorkflow(), which is what the client's step names come from (D60).
+    const stepName = (rest) => { const ann = rest.match(/\{([^}]*)\}\s*$/); if (ann) rest = rest.slice(0, ann.index).trim(); return rest.replace(/\s*\(optional\)\s*$/i, '').trim(); };
+    for (let i = 0; i < lines.length; i++) {
+      const m = lines[i].match(/^(\s*- \[)( |x|X)(\]\s+)(.*)$/);
+      if (m && stepName(m[4]) === name) lines[i] = m[1] + (m[2].trim() ? ' ' : 'x') + m[3] + m[4];
+    }
+    fs.writeFileSync(wf, lines.join('\n'));
+    return changed(ctx, { ok: true });
+  },
+
+  'run.start': async (root, { prompt, agent, display }, ctx) => {
+    text(prompt, 'Empty request.');
+    const r = startRun(root, { prompt, agent, display }, ctx.emit);
+    if (r.error) bad(r.error);
+    return { runId: r.runId };
+  },
+  'chat.summarize': async (root, { agent }, ctx) => {
+    const r = runSummarize(root, { agent }, ctx.emit);
+    if (r.error) bad(r.error);
+    return { ok: true };
+  },
+  'meeting.generate': async (root, { agent, date }, ctx) => {
+    const r = runMeetingGenerate(root, { agent, date }, ctx.emit);
+    if (r.error) bad(r.error);
+    return { ok: true };
+  },
+  'chat.clear': async (root, _args, ctx) => {
+    const rt = store.readRuntime(root); rt.messages = []; store.writeRuntime(root, rt);
+    return changed(ctx, { ok: true });
+  },
+  'orchestrate.start': async (root, { request }, ctx) => {
+    const req = text(request, 'Empty request.');
+    const active = store.readRuntime(root).orchestration;
+    if (active && ['running', 'awaiting_approval'].includes(active.status)) throw new OpError(409, 'An orchestration is already active.');
+    const mode = store.readConfig(root).mode || 'semi';
+    orchestrator.runOrchestration({ root, request: req, mode, runStep: orchestrator.defaultRunStep, confirm: orchestrator.defaultConfirm }, ctx.emit)
+      .catch((e) => ctx.emit({ type: 'message', message: { role: 'orchestrator', kind: 'status', text: 'orchestration error: ' + e.message } }));
+    const o = store.readRuntime(root).orchestration;
+    return { orchestrationId: o && o.id };
+  },
+  'orchestrate.approve': async (root, { decision, note }) => {
+    if (!orchestrator.submitDecision(decision, note, root)) throw new OpError(409, 'No pending approval.');
+    return { ok: true };
+  },
+
+  'settings.save': async (root, patch, ctx) => changed(ctx, { config: writeConfig(root, patch || {}, ctx.env ? { env: ctx.env } : undefined) }),
+
+  'attention.add': async (root, { text: body }, ctx) => {
+    const msg = text(body, 'Empty note.');
+    const rt = store.readRuntime(root); rt.attention = rt.attention || [];
+    const item = { id: 'att' + Date.now().toString(36), at: new Date().toISOString(), by: 'me', source: 'user', status: 'open', text: msg };
+    rt.attention.unshift(item); store.writeRuntime(root, rt);
+    return changed(ctx, { item });
+  },
+  'attention.promote': async (root, { id }, ctx) => {
+    const rt = store.readRuntime(root); const it = (rt.attention || []).find((x) => x.id === id);
+    if (!it) notFound('Note not found.');
+    const t = store.addTask(root, { phase: 'Attention', title: it.text, owner: 'user' });
+    it.status = 'resolved'; it.promotedTo = t.id; store.writeRuntime(root, rt);
+    return changed(ctx, { task: t });
+  },
+  'attention.update': async (root, { id, patch }, ctx) => {
+    const rt = store.readRuntime(root); const it = (rt.attention || []).find((x) => x.id === id);
+    if (!it) notFound('Note not found.');
+    const p = patch || {};
+    if (typeof p.text === 'string' && p.text.trim()) it.text = p.text.trim();
+    if (p.status && ['open', 'resolved'].includes(p.status)) it.status = p.status;
+    store.writeRuntime(root, rt);
+    return changed(ctx, { item: it });
+  },
+  'attention.remove': async (root, { id }, ctx) => {
+    const rt = store.readRuntime(root); rt.attention = (rt.attention || []).filter((x) => x.id !== id); store.writeRuntime(root, rt);
+    return changed(ctx, { ok: true });
+  },
+};
+
+module.exports = { ops, OpError };

package/{templates → lib}/dashboard/orchestrator.js

@@ -1,7 +1,7 @@
 'use strict';
 const fs = require('fs');
 const path = require('path');
-const store = require('../lib/store');
+const store = require('../store');
 const { startRun } = require('./runner');
 
 // step (from store.readWorkflow) -> { agent, skill } or { error }
@@ -54,7 +54,7 @@ async function runOrchestration({ root, request, mode, runStep, confirm, resume
     if (needConfirm) {
       st.status = 'awaiting_approval'; o.status = 'awaiting_approval'; saveState(root, o, emit);
       post(root, 'orchestrator', 'question', `Approve step "${step.name}" (${r.agent})${policyGated ? ' — policy gate' : ''}?`, emit);
-      const dec = await confirm(step, { policy: policyGated });
+      const dec = await confirm(step, { policy: policyGated, root });
       post(root, 'orchestrator', 'status', `decision: ${dec.decision}${dec.note ? ' — ' + dec.note : ''}`, emit);
       if (dec.decision === 'cancel') { st.status = 'skipped'; o.status = 'cancelled'; saveState(root, o, emit); return o; }
       o.status = 'running'; saveState(root, o, emit);
@@ -94,12 +94,21 @@ function defaultRunStep({ root, step, agent, skill, request }, emit) {
   });
 }
 
-let pending = null;
-function defaultConfirm(step, reason) { return new Promise((resolve) => { pending = { resolve }; }); }
-function submitDecision(decision, note) {
-  if (!pending) return false;
-  const p = pending; pending = null; p.resolve({ decision, note }); return true;
+// Keyed by project root — before this hub shared one orchestrator.js instance across every project
+// (D64), a single module-level `pending` here was a real cross-project leak: approving in one
+// project could resolve (or silently overwrite) another project's pending gate.
+const pending = new Map(); // root -> { resolve }
+function defaultConfirm(step, reason) { return new Promise((resolve) => { pending.set(reason && reason.root, { resolve }); }); }
+function submitDecision(decision, note, root) {
+  const p = pending.get(root);
+  if (!p) return false;
+  pending.delete(root);
+  p.resolve({ decision, note });
+  return true;
 }
+// Drops any pending approval for `root` — called when a project is reloaded (its whole in-flight
+// session is considered gone) so a stale resolver can never be sitting around after the fact.
+function clearPending(root) { pending.delete(root); }
 
 // Boot-time reconcile: a process restart loses any in-flight orchestration (the runOrchestration
 // call stack, and the in-memory `pending` approval) even though runtime.json still records it as
@@ -116,4 +125,4 @@ function reconcileOnBoot(root) {
   return true;
 }
 
-module.exports = { resolveStep, runOrchestration, defaultRunStep, defaultConfirm, submitDecision, reconcileOnBoot };
+module.exports = { resolveStep, runOrchestration, defaultRunStep, defaultConfirm, submitDecision, clearPending, reconcileOnBoot };