create-pmos 0.168.0 → 0.170.0

package/workspace/guide/index.md

@@ -62,6 +62,7 @@ On a desktop the workspace is one frame. [Layout](layout.md) explains each part.
 - [Initiatives: the Roadmap, the List and the initiative sheet](initiatives-screen.md): how to read and order the initiatives of a repository, open the sheet, make a new initiative, and review the cycle.
 - [Initiatives and the Roadmap: Now, Next and Later](initiatives-roadmap.md): what day one shows, how an agent proposes a move, and `pmos initiative` and `pmos measure` from a terminal.
 - [The Initiative Driver: drafts the agent files for you](initiative-driver.md): when the driver runs, the unblock sweep, the limits, Keep, Send back and Drop, the board modes, and `pmos driver`.
+- [The Horizon scan: the agent looks outside your initiatives](horizon-scan.md): how often it runs, the watch list you keep, what a scan does, where findings land, what it cannot do, and `pmos scan`.
 - [PM-only acts: what only you can do](pm-only-acts.md): which acts are yours, how the workspace checks that a press comes from your page or your terminal, and what to do when one is refused.
 - [PM-only lines: how the workspace checks your acts](pm-only-lines.md): how each act is recorded, what the Today card "A PM-only line is not attested" means, and the grants for a bulk lifecycle change and a Release.
 - [Breakdown › Timeline](timeline.md): an initiative's items on a time axis, split by stage, with milestones, today, and the at-risk flag when an item starts before its predecessor ends.

package/workspace/guide/initiative-driver.md

@@ -50,6 +50,14 @@ The agent reads, and it files proposals with `pmos driver propose`. It has no Wr
 
 In Discover, the agent writes the problem statement, the evidence, the opportunity sizing, the riskiest assumption and the stakeholders. When you have kept the first three, it proposes the move to Plan. In the other stages, it names the blocker and proposes what would clear it.
 
+## Where you see the agent
+
+- **The Agent strip.** Open an initiative and stay on Overview. The Agent section is at the top. It shows the state of the agent (working, idle, waiting on you, paused or off), the last thing it did, and what stops it ("Stopped by: ..."). Each open proposal is one row with Keep, Send back and Drop. Press a row to read its text and its sources. A source that is a link opens in a new tab. Pause and Resume are in the header. The text "1 of 3 runs used today" opens the list of today's runs.
+- **Keep, Send back and Drop on a row.** A kept row stays in the strip, marked "Kept by you", until you leave the page. Send back asks for a one-line note. A kept stage move changes the stage on the page at once. These three acts cannot be undone: each adds one line to the ledger.
+- **One line in Work.** A Work task with an open proposal shows one line under its title, for example "Agent drafted a follow-up to Dana. Nothing is sent." Press Review to read the draft. Keep copies the text so you can send it yourself, and records your decision. If the browser does not allow copying, the text is selected and you press Ctrl+C. A suggested next step shows Keep and Drop in the line. Shadow and Off show no line.
+- **Needs you.** In Briefing, the agent has two kinds of row: "Agent has 3 drafts on ..." and "... is waiting on you". Press a row to open the initiative.
+- **The Agent setting.** Open the board, press Board settings, and find Agent. Choose Off, Shadow or Approve. The setting is saved when you press it.
+
 ## Keep, send back, drop
 
 Open proposals appear in Needs you as one row for each initiative or task: "Agent has 3 drafts on the initiative".
@@ -77,3 +85,7 @@ The agent uses `pmos driver propose` to file a proposal and `pmos driver status`
 - `pmos driver mode <off|shadow|approve> [--board <id>]` sets the board mode. Without `--board` it sets every board.
 
 The ledger is `driver.jsonl` in the state folder of the repository (`pmos/state`, `state` or `.pmos`). Each action adds one line. Nothing is changed or removed.
+
+## Related
+
+The [Horizon scan](horizon-scan.md) is the part of the agent that looks outside the initiatives: it files new opportunities as asks in Triage.

package/workspace/lib/engine/boards.js

@@ -27,7 +27,7 @@
  *   workflow     { stages: [{ name, cat, hint }], renamed: { old: new }, moved: [{ id, from, to }], sprints? }
  *   move         { id, from, to, why, warnings }
  *   assign       { id, to }                               (`board` is the board it left, or null)
- *   ask          { ask, line, source, draft }
+ *   ask          { ask, line, source, draft, found? }     found: what a Horizon scan filed with the ask { why, sources: [{ label, ref }], match, scan } (source 'scan')
  *   ask-accept   { ask, initiative, stage }
  *   ask-decline  { ask, why }
  *   ask-more     { ask, note }                            the asker is prompted for more detail; the ask stays open
@@ -146,6 +146,12 @@ const TOOLS = Object.freeze({
 
 const STATUSES = Object.freeze(['on track', 'at risk', 'late', 'done']);
 const VIEWS = Object.freeze(['now', 'mine', 'risk', 'noowner', 'all']);
+/** What a Horizon scan filed with an ask (initiative horizon-scan), cut to its shape; null for any other ask. */
+function foundOf(f) {
+  if (!f || typeof f !== 'object' || Array.isArray(f)) return null;
+  const sources = Array.isArray(f.sources) ? f.sources.filter((x) => x && typeof x.ref === 'string').slice(0, 8).map((x) => ({ label: String(x.label || ''), ref: x.ref })) : [];
+  return { why: typeof f.why === 'string' ? f.why : '', sources, match: typeof f.match === 'string' && f.match ? f.match : null, scan: typeof f.scan === 'string' ? f.scan : null, run: typeof f.run === 'string' ? f.run : null };
+}
 const KINDS = new Set(['board', 'workflow', 'move', 'assign', 'ask', 'ask-accept', 'ask-decline', 'ask-more', 'ini-workflow', 'task', 'task-update', 'ini-epics']);
 const TASK_STATES = Object.freeze(['To do', 'In progress', 'In review', 'Done']);
 
@@ -206,7 +212,7 @@ function fold(events) {
     } else if (e.kind === 'assign' && typeof e.id === 'string' && typeof e.to === 'string') {
       assigns.set(e.id, e.to);
     } else if (e.kind === 'ask' && b && typeof e.ask === 'string' && !asks.has(e.ask)) {
-      asks.set(e.ask, { id: e.ask, board: b, line: String(e.line || ''), source: e.source || null, draft: e.draft || null, at: e.at || null, by: e.by || null, state: 'open', initiative: null, stage: null, why: null, closedAt: null });
+      asks.set(e.ask, { id: e.ask, board: b, line: String(e.line || ''), source: e.source || null, draft: e.draft || null, ...(foundOf(e.found) ? { found: foundOf(e.found) } : {}), at: e.at || null, by: e.by || null, state: 'open', initiative: null, stage: null, why: null, closedAt: null });
     } else if (e.kind === 'ask-accept' && typeof e.ask === 'string' && asks.has(e.ask)) {
       const a = asks.get(e.ask);
       if (a.state !== 'open') continue;

package/workspace/lib/headless.js

@@ -3,7 +3,7 @@
  * (initiative workspace-headless-jobs; PM decision 2026-10-11: keep Jev, no direct Claude API, background
  * jobs that need no human run headless).
  *
- *   kindFor({ agent, origin, skill, env })        → 'notes' | 'skill' | 'ask' | 'drive' | null   (null: open a pane, as before)
+ *   kindFor({ agent, origin, skill, env })        → 'notes' | 'skill' | 'ask' | 'drive' | 'scan-web' | 'scan-repo' | null   (null: open a pane, as before)
  *   argsFor(kind, { modelArgs, addDirs })          → the argv after `claude`
  *   parseResult(stdout)                            → { ok, text, isError, turns, durationMs, costUsd, denied[] }
  *   logLines(result, exitCode)                     → the lines the read-only log pane shows at the end
@@ -20,6 +20,11 @@
  * connector tool is named in its list, so a connector read runs only where the PM's own Claude Code settings already allow it,
  * and a connector write is denied and reported like any other tool outside the list. The PM-only `pmos driver` verbs refuse an
  * agent session by themselves. The driver never runs in a pane (server.js refuses to start it when PMOS_HEADLESS=off).
+ *
+ * The `scan-web` and `scan-repo` kinds are the Horizon scan (initiative horizon-scan). `scan-web` has WebSearch, WebFetch and
+ * `pmos scan file`, and nothing else: it reads untrusted pages, so it holds no private data (no Read, Glob or Grep, no repository
+ * path in its prompt, no --add-dir). `scan-repo` reads the repository and the findings the web run filed, so it has no web tool and
+ * nothing that sends. Neither kind ever runs in a pane.
  */
 
 // The skills whose every start runs headless: they read, file a result for PMOS, and send nothing out.
@@ -33,6 +38,11 @@ const HEADLESS_ORIGINS = Object.freeze(['notes-bullets:', 'notes-summary:']);
 const ASK_ORIGINS = Object.freeze(['doc-ask:', 'focus-companion:']);   // focus-companion: the Meeting focus page's quiet companion and its private questions (read-only, nothing sent)
 // initiative-driver: one short run for one initiative or one Work task. Its origin is `drive:<kind>:<id>`.
 const DRIVE_ORIGINS = Object.freeze(['drive:']);
+// horizon-scan: a scan is two runs. The web run (origin `scan-web:<board>:<scan>`) reads the public web for the kept watch list and sees nothing of
+// the repository. The repository run (origin `scan-repo:<board>:<scan>`, and `scan-suggest:<board>` for the one that suggests a watch list) reads
+// the repository and fetches nothing. Neither has both untrusted input and a way out (PRD: trust boundary).
+const SCAN_WEB_ORIGINS = Object.freeze(['scan-web:']);
+const SCAN_REPO_ORIGINS = Object.freeze(['scan-repo:', 'scan-suggest:']);
 
 // What each kind may use. Read-only search is always allowed. The notes passes write their JSON (and rename the .tmp
 // file) in their notes folder, which --add-dir opens to them; the skills also run `pmos` verbs and repository scripts.
@@ -41,6 +51,11 @@ const TOOLS = Object.freeze({
   ask: Object.freeze(['Read', 'Glob', 'Grep']),
   drive: Object.freeze(['Read', 'Glob', 'Grep', 'Bash(pmos driver *)', 'Bash(pmos initiative list *)', 'Bash(pmos initiative export *)',
     'Bash(git log *)', 'Bash(ls *)', 'Bash(date *)']),
+  // The web run: WebSearch, WebFetch and the one verb that files a finding. No Read, no Glob, no Grep, no repository path in its prompt or its add-dirs.
+  'scan-web': Object.freeze(['WebSearch', 'WebFetch', 'Bash(pmos scan file *)']),
+  // The repository run: read and search the repository, `pmos scan` (its PM-only verbs refuse an agent session), the initiative list and git log.
+  // No WebSearch, no WebFetch, no curl, no git push: it reads the web run's findings, which are untrusted text, so it has nothing that sends or fetches.
+  'scan-repo': Object.freeze(['Read', 'Glob', 'Grep', 'Bash(pmos scan *)', 'Bash(pmos initiative list *)', 'Bash(git log *)']),
   skill: Object.freeze(['Read', 'Write', 'Edit', 'Glob', 'Grep', 'Bash(pmos *)', 'Bash(node *)',
     'Bash(git log *)', 'Bash(git status *)', 'Bash(git diff *)', 'Bash(ls *)', 'Bash(date *)']),
 });
@@ -57,6 +72,8 @@ function kindFor({ agent, origin, skill, env } = {}) {
   if (HEADLESS_ORIGINS.some((p) => o.startsWith(p))) return 'notes';
   if (ASK_ORIGINS.some((p) => o.startsWith(p))) return 'ask';
   if (DRIVE_ORIGINS.some((p) => o.startsWith(p))) return 'drive';
+  if (SCAN_WEB_ORIGINS.some((p) => o.startsWith(p))) return 'scan-web';
+  if (SCAN_REPO_ORIGINS.some((p) => o.startsWith(p))) return 'scan-repo';
   if (skill && HEADLESS_SKILLS.includes(String(skill))) return 'skill';
   return null;
 }
@@ -65,7 +82,8 @@ function argsFor(kind, { modelArgs = [], addDirs = [] } = {}) {
   const tools = TOOLS[kind];
   if (!tools) throw new Error('unknown headless kind: ' + kind);
   const argv = ['-p', '--output-format', 'json', '--no-session-persistence', ...modelArgs, '--allowedTools', tools.join(',')];
-  for (const d of addDirs) if (d) argv.push('--add-dir', String(d));
+  // The web run gets no directory at all, whatever the caller passes: it must not be able to read the repository.
+  if (kind !== 'scan-web') for (const d of addDirs) if (d) argv.push('--add-dir', String(d));
   return argv;
 }
 
@@ -107,4 +125,4 @@ function logLines(r, exitCode) {
   return out;
 }
 
-module.exports = { HEADLESS_SKILLS, HEADLESS_ORIGINS, ASK_ORIGINS, DRIVE_ORIGINS, TOOLS, DEFAULT_TIMEOUT_MS, kindFor, argsFor, timeoutMs, parseResult, logLines, switchedOff };
+module.exports = { HEADLESS_SKILLS, HEADLESS_ORIGINS, ASK_ORIGINS, DRIVE_ORIGINS, SCAN_WEB_ORIGINS, SCAN_REPO_ORIGINS, TOOLS, DEFAULT_TIMEOUT_MS, kindFor, argsFor, timeoutMs, parseResult, logLines, switchedOff };

package/workspace/lib/pmos-verbs.js

@@ -59,6 +59,9 @@ const VERBS = Object.freeze({
   // Not a pm-os-absorb verb (run: null): initiative initiative-driver added it through the same table.
   driver: Object.freeze({ module: 'driver-cli.js', run: null, guide: 'initiative-driver.md',
     help: 'pmos driver propose|status|keep|return|drop|pause|resume|mode … — the Initiative Driver: drafts for you to keep, send back or drop (pmos driver help)' }),
+  // Not a pm-os-absorb verb (run: null): initiative horizon-scan added it through the same table.
+  scan: Object.freeze({ module: 'scan-cli.js', run: null, guide: 'horizon-scan.md',
+    help: 'pmos scan file|list|match|suggest|status|cadence|watch … — the Horizon scan: what the agent found outside the initiatives, and the watch list (pmos scan help)' }),
   launcher: Object.freeze({ module: 'launcher-cli.js', run: null, guide: 'launcher.md',
     help: 'pmos launcher on|off|status — a PMOS app and a login item, so the workspace starts without a terminal' }),
 });

package/workspace/lib/route-modules.js

@@ -69,6 +69,7 @@ const MODULES = Object.freeze([
   'routes-meeting-focus', // console3 Meeting focus: the meeting, its note's talk, the companion's notes (GET); topic corrections and Ask PMOS quietly (page press)
   'routes-stage-tools',   // stage-tools-records: the records the PM edits per stage, what PMOS holds per stage, the sprint burndown
   'routes-driver',        // initiative-driver: the Agent strip's data, Keep, Send back, Drop, Pause and the board mode (driver.jsonl)
+  'routes-scan',          // horizon-scan: a board's watch list, cadence and last scan, the day's scan for the Briefing, the PM's watch and cadence presses (scan.jsonl)
 ]);
 const PM_DIR = path.join(__dirname, '..', 'public', 'pm');
 const MODULE_NAME = /^[a-z0-9][a-z0-9-]*\.js$/;

package/workspace/lib/routes-boards.js

@@ -94,6 +94,33 @@ function append(file, actor, ev) {
   return line;
 }
 
+/** A Horizon scan ask that the PM declines counts as a correction (initiative horizon-scan, PRD section 5): one line in corrections.jsonl, as the driver writes. */
+function scanDeclineSignal(ctx, a) {
+  if (!ctx.runtimeDir) return;
+  try {
+    const f = path.join(ctx.runtimeDir, 'corrections.jsonl');
+    const reason = 'scan:decline';
+    fs.mkdirSync(path.dirname(f), { recursive: true });
+    fs.appendFileSync(f, JSON.stringify({ type: 'correction', kind: 'reject', reason, run: (a.found && (a.found.run || a.found.scan)) || null, counted: true, at: new Date().toISOString(),
+      record: { kind: 'correction', run: (a.found && (a.found.run || a.found.scan)) || null, reason, by: 'pm' } }) + '\n');
+  } catch { /* the declined ask in the boards ledger is still the record */ }
+}
+
+/** The Triage ask of one Horizon scan finding (initiative horizon-scan, PRD section 4). The same ledger line as POST /api/boards/asks/add, with
+ * source 'scan', `found` and the agent as `by`. The ask id comes from the finding id, so writing it twice makes one ask. A scan never creates an
+ * initiative: the PM accepts or declines. → { ok, ask, existing } | { ok: false, error } */
+function appendScanAsk(ctx, w, boardId, f, by) {
+  const file = ledgerFile(ctx, w);
+  if (!file) return { ok: false, error: NO_STATE };
+  const id = 'ask-' + String(f.id).replace(/^f-/, '');
+  if (B.fold(readLedger(ctx, w)).asks.has(id)) return { ok: true, existing: true, id };
+  let draft = null;
+  try { draft = intake.intakeDraft({ line: f.title, root: w.root }); } catch { draft = null; }
+  append(file, { by }, { kind: 'ask', board: boardId, ask: id, line: f.title, source: 'scan', draft,
+    found: { why: f.why, sources: f.sources, match: f.match || null, scan: f.scan, run: f.run || null } });
+  return { ok: true, existing: false, id };
+}
+
 // ── boards of a workspace ─────────────────────────────────────────────────────────────────────────
 const isSelf = (ctx, w) => !!(ctx.selfRoot && w && path.resolve(w.root) === path.resolve(ctx.selfRoot));
 
@@ -750,6 +777,8 @@ const WRITES = {
     if (!ONE_LINE(body.why, 500)) return fail(ctx, res, 400, 'a decline needs a reason (why) of 1 to 500 characters');
     if (!p.file) return fail(ctx, res, 409, NO_STATE);
     append(p.file, g.actor, { kind: 'ask-decline', board: p.board.id, ask: a.id, why: body.why.trim() });
+    // initiative horizon-scan: a declined scan finding is a correction signal, as a dropped driver proposal is.
+    if (a.source === 'scan') scanDeclineSignal(ctx, a);
     ctx.json(res, { ok: true });
   },
 };
@@ -846,4 +875,4 @@ function meetingBoards(ctx) {
   return { list, detail };
 }
 
-module.exports = { prefixes: ['/api/boards'], handle, move, boardIndex, frameFor, boardIdOf, meetingBoards, boardsOf, baseRows, boardRow, portfolio, SELF_REFUSAL, NO_STATE };
+module.exports = { prefixes: ['/api/boards'], handle, move, boardIndex, appendScanAsk, frameFor, boardIdOf, meetingBoards, boardsOf, baseRows, boardRow, portfolio, SELF_REFUSAL, NO_STATE };

package/workspace/lib/routes-driver.js

@@ -1,13 +1,16 @@
 'use strict';
 /* routes-driver.js — the Initiative Driver's routes (initiative initiative-driver, PRD sections 4 and 5).
  *
- *   GET  /api/driver/strip?ws&target_kind&id       → { ok, ws, target, mode, board, paused, budget, running, last, blocker, proposals }
+ *   GET  /api/driver/strip?ws&target_kind&id[&board] → { ok, ws, target, mode, board, paused, budget, today: [runs of today], running, last, blocker, proposals }
  *   POST /api/driver/keep    { ws, proposal }                     → { ok, proposal, wrote, warnings }
  *   POST /api/driver/return  { ws, proposal, note }               → { ok, proposal }       the note is required; it wakes a run
  *   POST /api/driver/drop    { ws, proposal, note? }              → { ok, proposal }
  *   POST /api/driver/pause   { ws, target_kind, id }              → { ok, paused: true, target }
  *   POST /api/driver/resume  { ws, target_kind, id }              → { ok, paused: false, target }
  *   POST /api/driver/mode    { ws, board?, mode }                 → { ok, board, mode }    board omitted: every board
+ *   GET  /api/driver/mode?ws&board                                → { ok, ws, board, mode }  the mode a board runs in (Approve when none is set)
+ *   GET  /api/driver/open?ws&target_kind                          → { ok, ws, kind, mode, targets: { <id>: [proposal] } }  every open proposal of
+ *                                                                    one kind, by target: the Work list draws one agent line per task from this
  *
  * The strip is the data of the Agent strip on an initiative's Overview and of the one-line version on a Work task. Its
  * `proposals` are the open ones; `by` is the page name (`agent:sess-<n>`), never the session token. `running` is a run that has
@@ -28,6 +31,8 @@ const stageTools = require('./stage-tools.js');
 const text = (v) => (typeof v === 'string' ? v : '');
 const bad = (status, error) => ({ status, body: { ok: false, error } });
 const POSTS = ['keep', 'return', 'drop', 'pause', 'resume', 'mode'];
+const GETS = ['strip', 'mode', 'open'];
+const proposalOut = (p) => ({ id: p.id, what: p.what, data: p.data, why: p.why, sources: p.sources, run: p.run, by: actorLib.pageName(p.by), at: p.at });
 
 function wsOf(ctx, id) {
   const w = ctx.getWs(id || '');
@@ -46,22 +51,23 @@ function boardOfTarget(state, target) {
   return runs.length ? runs[runs.length - 1].board : null;
 }
 
-function stripOf(state, target, { now = Date.now() } = {}) {
+function stripOf(state, target, { now = Date.now(), board: asked = null } = {}) {
   const key = D.targetKey(target);
   const runs = [...state.runs.values()].filter((r) => D.targetKey(r.target) === key);
   const running = runs.filter((r) => !r.end).pop() || null;
   const ended = runs.filter((r) => r.end).pop() || null;
-  const board = boardOfTarget(state, target);
+  const board = boardOfTarget(state, target) || asked || null;
   const day = D.localDay(now);
   const blocker = state.blockers.filter((b) => b.target && D.targetKey(b.target) === key && b.day === day).pop() || null;
   const open = D.openProposals(state, target);
   return {
     target, board, mode: D.modeOf(state, board), paused: D.isPaused(state, target),
     budget: { used: D.runsOnDay(state, target, day), limit: target.kind === 'work' ? D.BUDGET.workPerDay : D.BUDGET.initiativePerDay, concurrent: D.BUDGET.concurrent },
+    today: runs.filter((r) => r.start && D.localDay(Date.parse(r.start)) === day).map((r) => ({ run: r.run, start: r.start, end: r.end, ok: r.ok, reason: r.reason, proposals: [...state.proposals.values()].filter((p) => p.run === r.run).length })),
     running: running ? { run: running.run, since: running.start } : null,
     last: ended ? { run: ended.run, at: ended.end, ok: ended.ok, reason: ended.reason, proposals: [...state.proposals.values()].filter((p) => p.run === ended.run).length } : null,
     blocker: blocker ? { code: blocker.code, text: blocker.text, owner: blocker.owner, day: blocker.day } : null,
-    proposals: open.map((p) => ({ id: p.id, what: p.what, data: p.data, why: p.why, sources: p.sources, run: p.run, by: actorLib.pageName(p.by), at: p.at })),
+    proposals: open.map(proposalOut),
   };
 }
 
@@ -69,7 +75,33 @@ async function handle(req, res, url, ctx) {
   const p = url.pathname;
   const send = (r) => { ctx.json(res, r.body, r.status); return true; };
   const sub = p.replace(/^\/api\/driver\/?/, '');
-  if (sub !== 'strip' && !POSTS.includes(sub)) return send(bad(404, 'no such driver route'));
+  if (!GETS.includes(sub) && !POSTS.includes(sub)) return send(bad(404, 'no such driver route'));
+
+  if (sub === 'mode' && req.method === 'GET') {
+    const w = wsOf(ctx, url.searchParams.get('ws'));
+    if (!w) return send(bad(404, 'no such workspace'));
+    const board = text(url.searchParams.get('board'));
+    if (!board || !D.ID_RE.test(board)) return send(bad(400, 'board must be a board id'));
+    const file = ledgerOf(ctx, w);
+    const state = D.fold(file ? D.readLines(file) : []);
+    return send({ status: 200, body: { ok: true, ws: w.id, ledger: !!file, board, mode: D.modeOf(state, board) } });
+  }
+
+  if (sub === 'open') {
+    if (req.method !== 'GET') return send(bad(405, 'GET only'));
+    const w = wsOf(ctx, url.searchParams.get('ws'));
+    if (!w) return send(bad(404, 'no such workspace'));
+    const kind = text(url.searchParams.get('target_kind'));
+    if (!D.KINDS.includes(kind)) return send(bad(400, `target_kind must be one of ${D.KINDS.join(', ')}`));
+    const file = ledgerOf(ctx, w);
+    const state = D.fold(file ? D.readLines(file) : []);
+    const targets = {};
+    for (const pr of D.openProposals(state)) {
+      if (pr.target.kind !== kind || pr.target.ws !== w.id) continue;
+      (targets[pr.target.id] = targets[pr.target.id] || []).push(proposalOut(pr));
+    }
+    return send({ status: 200, body: { ok: true, ws: w.id, ledger: !!file, kind, mode: D.modeOf(state, kind === 'work' ? 'work' : null), targets } });
+  }
 
   if (sub === 'strip') {
     if (req.method !== 'GET') return send(bad(405, 'GET only'));
@@ -79,7 +111,7 @@ async function handle(req, res, url, ctx) {
     if (!t.ok) return send(bad(400, t.error));
     const file = ledgerOf(ctx, w);
     const state = D.fold(file ? D.readLines(file) : []);
-    return send({ status: 200, body: { ok: true, ws: w.id, ledger: !!file, ...stripOf(state, t.target) } });
+    return send({ status: 200, body: { ok: true, ws: w.id, ledger: !!file, ...stripOf(state, t.target, { board: text(url.searchParams.get('board')) || null }) } });
   }
 
   if (req.method !== 'POST') return send(bad(405, 'POST only'));

package/workspace/lib/routes-scan.js

@@ -0,0 +1,130 @@
+'use strict';
+/* routes-scan.js — the Horizon scan's routes (initiative horizon-scan, PRD section 6).
+ *
+ *   GET  /api/scan/board?ws&board   → { ok, ws, board, ledger, cadence, schedule, items: [item], suggested: [item], kept: [item], suggesting, suggest_failed, running, last, next, switched_off }
+ *   GET  /api/scan/today?ws         → { ok, ws, ledger, scan: null | { day, at, boards: [{ id, name }], found, matches, fresh, pages, skipped, findings: [finding], failed: [{ board, reason }] } }
+ *   POST /api/scan/watch   { ws, board, op: keep | edit | remove | add, id?, name?, kind?, why?, restore? }   → { ok, id, item? }
+ *   POST /api/scan/cadence { ws, board, cadence: daily | weekly | off }                                       → { ok, board, cadence }
+ *
+ * An item is { id, kind, name, why, ini, added, state: suggested | kept }; `ini` is the initiative a suggestion came from (null for one the PM added). A finding is
+ * { id, ask, board, title, match, origin, state } where `state` is the Triage ask's state (open, accepted or declined). `next` is an ISO time or null.
+ * `scan` of today is the day's scans across the boards of the workspace read as one: the time of the latest, the boards scanned, the counts and the findings.
+ *
+ * WHO WRITES. Both POSTs pass pm-guard requirePagePress, and a request that carries an agent session header is refused first (403), as the driver routes
+ * do. `by` of every line is the guard's actor; the page sends none. The agent writes through `pmos scan` (lib/scan-cli.js) and the scan run, never here.
+ * State: <state folder>/scan.jsonl, one per repository (lib/scan.js). Nothing here sends anything outward.
+ */
+const guard = require('./pm-guard.js');
+const D = require('./driver.js');
+const S = require('./scan.js');
+const scanRun = require('./scan-run.js');
+
+const text = (v) => (typeof v === 'string' ? v : '');
+const bad = (status, error) => ({ status, body: { ok: false, error } });
+const GETS = ['board', 'today'];
+const POSTS = ['watch', 'cadence'];
+const itemOut = (i) => ({ id: i.id, kind: i.kind, name: i.name, why: i.why, ini: i.ini, added: !!i.added, state: i.state });
+
+function wsOf(ctx, id) {
+  const w = ctx.getWs(id || '');
+  return w && (!id || w.id === id) ? w : null;
+}
+function ledgerOf(ctx, w) {
+  const d = ctx.stateDirFor ? ctx.stateDirFor(w) : null;
+  return S.ledgerFile(d);
+}
+const boardsOf = (ctx, w) => { try { return require('./routes-boards.js').frameFor(ctx, w); } catch { return null; } };
+const settingsOf = (ctx) => { try { return ctx.proSettings ? ctx.proSettings() : null; } catch { return null; } };
+
+function boardAnswer(ctx, w, file, board, now) {
+  const state = S.fold(file ? S.readLines(file) : []);
+  const wl = S.watchOf(state, board);
+  const last = S.lastScan(state, board);
+  const cadence = S.cadenceOf(state, board);
+  const dc = (settingsOf(ctx) || {}).dayCheck || {};
+  const next = file ? S.nextScan(state, board, now, { dayEnd: dc.end || '18:00' }) : null;
+  const sug = S.scansOf(state, board, 'suggest');
+  const openSug = sug.find((x) => !x.end);
+  const lastSug = sug.filter((x) => x.end).pop() || null;
+  return {
+    cadence, schedule: S.scheduleText(cadence), items: S.itemsOf(state, board).map(itemOut), suggested: wl.suggested.map(itemOut), kept: wl.kept.map(itemOut),
+    suggesting: !!openSug, suggest_failed: !!(lastSug && lastSug.ok === false && !wl.suggested.length && !wl.kept.length),
+    running: S.openScans(state).some((x) => x.board === board && x.mode === 'scan'),
+    last: last ? { scan: last.scan, at: last.start, end: last.end, ok: last.ok, reason: last.reason, found: last.found, skipped: last.skipped, pages: last.pages } : null,
+    next: next == null ? null : new Date(next).toISOString(), switched_off: !!scanRun.off(process.env),
+  };
+}
+
+function todayAnswer(ctx, w, file, now) {
+  const state = S.fold(file ? S.readLines(file) : []);
+  const day = D.localDay(now);
+  const done = state.scanOrder.map((id) => state.scans.get(id)).filter((x) => x.mode === 'scan' && x.end && x.start && D.localDay(Date.parse(x.start)) === day);
+  if (!done.length) return null;
+  const fr = boardsOf(ctx, w);
+  const names = new Map(((fr && fr.boards) || []).map((b) => [b.id, b.name]));
+  let asks = new Map();
+  try { asks = fr ? fr.folded.asks : new Map(); } catch { asks = new Map(); }
+  const boards = []; const findings = []; const failed = [];
+  let pages = 0; let skipped = 0; let latest = done[0];
+  for (const sc of done) {
+    if (Date.parse(sc.start) >= Date.parse(latest.start)) latest = sc;
+    if (!boards.some((b) => b.id === sc.board)) boards.push({ id: sc.board, name: names.get(sc.board) || sc.board });
+    pages += sc.pages || 0; skipped += sc.skipped || 0;
+    if (sc.ok === false && sc.reason) failed.push({ board: sc.board, reason: sc.reason });
+    for (const fid of sc.findings) {
+      const f = state.findings.get(fid);
+      const ask = asks.get('ask-' + fid.replace(/^f-/, ''));
+      findings.push({ id: f.id, ask: ask ? ask.id : null, board: f.board, title: f.title, match: f.match, origin: f.origin, state: ask ? ask.state : null });
+    }
+  }
+  const matches = findings.filter((f) => f.match).length;
+  return { day, at: latest.start, boards, found: findings.length, matches, fresh: findings.length - matches, pages, skipped, findings, failed };
+}
+
+async function handle(req, res, url, ctx) {
+  const p = url.pathname;
+  const send = (r) => { ctx.json(res, r.body, r.status); return true; };
+  const sub = p.replace(/^\/api\/scan\/?/, '');
+  if (!GETS.includes(sub) && !POSTS.includes(sub)) return send(bad(404, 'no such scan route'));
+
+  if (GETS.includes(sub)) {
+    if (req.method !== 'GET') return send(bad(405, 'GET only'));
+    const w = wsOf(ctx, url.searchParams.get('ws'));
+    if (!w) return send(bad(404, 'no such workspace'));
+    const file = ledgerOf(ctx, w);
+    const now = Date.now();
+    if (sub === 'today') return send({ status: 200, body: { ok: true, ws: w.id, ledger: !!file, scan: todayAnswer(ctx, w, file, now) } });
+    const board = text(url.searchParams.get('board')) || w.id;
+    if (!S.ID_RE.test(board)) return send(bad(400, 'board must be a board id'));
+    const fr = boardsOf(ctx, w);
+    if (fr && !fr.boards.some((b) => b.id === board)) return send(bad(404, `no board ${board.slice(0, 40)} in this workspace`));
+    return send({ status: 200, body: { ok: true, ws: w.id, board, ledger: !!file, ...boardAnswer(ctx, w, file, board, now) } });
+  }
+
+  if (req.method !== 'POST') return send(bad(405, 'POST only'));
+  const read = await ctx.readJson(req);
+  if (!read.ok) return send(bad(400, 'the body is not JSON'));
+  const body = read.body;
+  if (req.headers && req.headers['x-pmos-session']) return send(bad(403, 'an agent session cannot change the watch list or the scan cadence'));
+  const g = guard.requirePagePress(req, body);
+  if (!g.ok) return send(bad(g.status, g.error));
+  const w = wsOf(ctx, text(body.ws));
+  if (!w) return send(bad(404, 'no such workspace'));
+  const file = ledgerOf(ctx, w);
+  if (!file) return send(bad(409, 'this repository has no state folder (pmos/state, state or .pmos), so the scan has nowhere to keep its ledger'));
+  const board = text(body.board);
+  if (!board || !S.ID_RE.test(board)) return send(bad(400, 'board must be a board id'));
+  const fr = boardsOf(ctx, w);
+  if (fr && !fr.boards.some((b) => b.id === board)) return send(bad(404, `no board ${board.slice(0, 40)} in this workspace`));
+
+  if (sub === 'cadence') {
+    const r = S.setCadence(file, board, text(body.cadence), g.actor);
+    if (!r.ok) return send(bad(r.status, r.error));
+    return send({ status: 200, body: { ok: true, board: r.board, cadence: r.cadence, schedule: S.scheduleText(r.cadence) } });
+  }
+  const r = S.watchOp(file, text(body.op), board, { id: body.id, name: body.name, kind: body.kind, why: body.why, restore: body.restore === true }, g.actor);
+  if (!r.ok) return send(bad(r.status, r.error));
+  return send({ status: 200, body: { ok: true, id: r.id, ...(r.item ? { item: r.item } : {}) } });
+}
+
+module.exports = { prefixes: ['/api/scan'], handle, boardAnswer, todayAnswer };