create-pmos 0.42.0 → 0.44.0

package/payload/scripts/pmos-log.sh

@@ -3,18 +3,29 @@
 # Appends ONE validated JSON line to the right pmos/state/ file. Mirrors the hosted rules:
 # verdict enum (save_eval), pm_label enum (record_acceptance), disposition enum + the D57
 # evidence-required-for-terminal rule (record_outcome_check). Append-only by construction — this
-# script only ever `>>`s; a correction is a NEW record. No dependencies beyond POSIX + python3
+# script only ever appends; a correction is a NEW record. Parity with PMOS's own writers
+# (pmos-cockpit-mod, D81): an acceptance needs a note and a run that exists, and a ledger that is a
+# symlink or has another hard link is refused (the same rule as scripts/lib/sink.js, applied at the
+# moment of the write; it does not defend against a process racing the open). No dependencies beyond POSIX + python3
 # (used solely for safe JSON string escaping).
 #
 #   pmos-log.sh run      <run_id> <initiative_id> [human_corrections] [model]
 #   pmos-log.sh eval     <run_id> <initiative_id> <score 0..1> <PASS|PASS-WITH-FINDINGS|FAIL> <rubric_path> [evaluator_model]
-#   pmos-log.sh accept   <run_id> <initiative_id> <pass|fail> [note]
+#   pmos-log.sh accept   <run_id> <initiative_id> <pass|fail> <note>
 #   pmos-log.sh outcome  <initiative_id> <validated|refuted|inconclusive> [evidence]
 #   pmos-log.sh friction <note...>
+#   pmos-log.sh grant    <merge:<PR or branch>|publish:<artifact>> <pm> <instruction> [ttl_minutes]
+#   pmos-log.sh grant-use <grant_id> <action>
+#
+# `grant` and `grant-use` belong to the cockpit mod (D81). A grant is the PM's typed permission for
+# ONE action: single use, 120 minutes unless a shorter time is given (24 hours at most), one target. A
+# standing scope (docs-sync, outward:*) and any other scope is refused. The mod mints a grant only from
+# the PM's typed /pmos-grant or a press, and denies a model that runs either subcommand.
+# PMOS_STATE_DIR names the folder of the ledgers when it is not <kit>/state (PMOS's own repository).
 set -euo pipefail
 
 KIT="${KIT_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
-STATE="$KIT/state"
+STATE="${PMOS_STATE_DIR:-$KIT/state}"
 fail() { echo "pmos-log: ERROR — $*" >&2; exit 1; }
 [ -d "$STATE" ] || fail "state dir not found at $STATE (run from a vendored kit, or set KIT_ROOT)."
 
@@ -24,8 +35,54 @@ nonempty() { # nonempty <label> <value> — ids must not be blank (hosted tools
 }
 today="$(date -u +%Y-%m-%d)"
 
+# safe_append <file under state/> <line> — open with O_NOFOLLOW, then refuse anything that is not a
+# regular file with a single link, and write to the descriptor that was vetted (python3 is already a
+# dependency of this script). Nothing is written when it refuses.
+safe_append() {
+  python3 - "$STATE/$1" "$2" <<'PY' || exit 1
+import os, stat, sys
+path, line = sys.argv[1], sys.argv[2]
+flags = os.O_WRONLY | os.O_APPEND | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
+try:
+    fd = os.open(path, flags, 0o644)
+except OSError as e:
+    sys.stderr.write("pmos-log: ERROR — refusing to write %s: %s\n" % (path, e.strerror)); sys.exit(1)
+try:
+    st = os.fstat(fd)
+    if not stat.S_ISREG(st.st_mode) or st.st_nlink != 1:
+        sys.stderr.write("pmos-log: ERROR — refusing to write %s: it is not a regular file with a single link (a symlink, a hard link or a special file).\n" % path); sys.exit(1)
+    os.write(fd, (line + "\n").encode("utf-8"))
+finally:
+    os.close(fd)
+PY
+}
+
+# run_exists <run_id> — true when state/runs.jsonl holds a run with that id. Lines that are not JSON
+# are skipped; the checkers report them.
+run_exists() {
+  python3 - "$STATE/runs.jsonl" "$1" <<'PY'
+import json, sys
+path, rid = sys.argv[1], sys.argv[2]
+try:
+    lines = open(path, encoding="utf-8").read().splitlines()
+except OSError:
+    sys.exit(1)
+for l in lines:
+    l = l.strip()
+    if not l:
+        continue
+    try:
+        r = json.loads(l)
+    except ValueError:
+        continue
+    if isinstance(r, dict) and str(r.get("run_id", "")) == rid:
+        sys.exit(0)
+sys.exit(1)
+PY
+}
+
 append() { # append <file> <json-line>
-  printf '%s\n' "$2" >> "$STATE/$1"
+  safe_append "$1" "$2"
   echo "✅ appended to state/$1:"
   echo "   $2"
 }
@@ -86,9 +143,11 @@ case "$cmd" in
     append evals.jsonl "{\"run_id\":$(js "$1"),\"initiative_id\":$(js "$2"),\"score\":$score,\"verdict\":$(js "$4"),\"rubric_path\":$(js "$5"),\"date\":\"$today\"$emodel_field}"
     ;;
   accept)
-    [ $# -ge 3 ] || fail "usage: accept <run_id> <initiative_id> <pass|fail> [note]"
+    [ $# -ge 4 ] || fail "usage: accept <run_id> <initiative_id> <pass|fail> <note> — the note is required: an acceptance with no reasoning is the rubber stamp D12 exists to prevent."
     nonempty run_id "$1"; nonempty initiative_id "$2"
     case "$3" in pass|fail) ;; *) fail "pm_label must be pass | fail, got '$3'." ;; esac
+    nonempty note "$4"
+    run_exists "$1" || fail "run_id '$1' is not in state/runs.jsonl — log the run first (pmos-log.sh run ...), then accept it."
     acc=true; [ "$3" = fail ] && acc=false
     append acceptances.jsonl "{\"run_id\":$(js "$1"),\"initiative_id\":$(js "$2"),\"accepted\":$acc,\"pm_label\":$(js "$3"),\"note\":$(js "${4:-}"),\"date\":\"$today\"}"
     ;;
@@ -104,10 +163,63 @@ case "$cmd" in
     ;;
   friction)
     [ $# -ge 1 ] || fail "usage: friction <note...>"
-    printf -- '- %s %s #friction\n' "$today" "$*" >> "$STATE/discoveries.md"
+    safe_append discoveries.md "- $today $* #friction"
     echo "✅ appended to state/discoveries.md: - $today $* #friction"
     ;;
+  grant)
+    [ $# -ge 3 ] || fail "usage: grant <merge:<PR or branch>|publish:<artifact>> <pm> <instruction> [ttl_minutes]"
+    nonempty pm "$2"; nonempty instruction "$3"
+    row="$(python3 - "$1" "$2" "$3" "${4:-120}" <<'PY'
+import datetime, json, re, secrets, sys
+scope, pm, instruction, ttl = sys.argv[1:5]
+def die(m):
+    sys.stderr.write("pmos-log: ERROR — %s\n" % m); sys.exit(1)
+if re.match(r"^(docs-sync|outward)(:|$)", scope):
+    die('"%s" is a standing scope. Standing grants are not allowed in this release (D81). Mint one single-use grant per action.' % scope)
+kind, sep, target = scope.partition(":")
+if not sep or kind not in ("merge", "publish"):
+    die('unknown scope "%s". Use merge:<PR number or branch> or publish:<artifact>.' % scope)
+pat = r"^(?:[0-9]{1,9}|[A-Za-z0-9][A-Za-z0-9._/-]{0,79})$" if kind == "merge" else r"^[A-Za-z0-9@][A-Za-z0-9@._/-]{0,99}$"
+if not re.match(pat, target) or "*" in target or ".." in target:
+    die('"%s" is not a single %s. A grant names one target; a wildcard is refused.' % (target, "PR number or branch name" if kind == "merge" else "artifact name"))
+if not re.match(r"^[0-9]{1,4}$", ttl) or not (1 <= int(ttl) <= 1440):
+    die("ttl_minutes must be a whole number from 1 to 1440, got '%s'." % ttl)
+now = datetime.datetime.now(datetime.timezone.utc).replace(microsecond=0)
+fmt = lambda d: d.strftime("%Y-%m-%dT%H:%M:%SZ")
+print(json.dumps({"type": "grant", "id": "g-%d-%s" % (int(now.timestamp()), secrets.token_hex(3)), "scope": kind, "target": target,
+                  "pm": pm, "at": fmt(now), "expires_at": fmt(now + datetime.timedelta(minutes=int(ttl))), "uses": 1, "instruction": instruction}, separators=(",", ":")))
+PY
+)" || exit 1
+    append grants.jsonl "$row"
+    ;;
+  grant-use)
+    [ $# -ge 2 ] || fail "usage: grant-use <grant_id> <action>"
+    nonempty grant_id "$1"; nonempty action "$2"
+    python3 - "$STATE/grants.jsonl" "$1" <<'PY' || exit 1
+import json, sys
+path, gid = sys.argv[1], sys.argv[2]
+found = used = False
+try:
+    lines = open(path, encoding="utf-8").read().splitlines()
+except OSError:
+    lines = []
+for l in lines:
+    try:
+        r = json.loads(l)
+    except ValueError:
+        continue
+    if isinstance(r, dict) and r.get("type") == "grant" and r.get("id") == gid:
+        found = True
+    if isinstance(r, dict) and r.get("type") == "use" and r.get("grant_id") == gid:
+        used = True
+if not found:
+    sys.stderr.write("pmos-log: ERROR — grant_id '%s' is not in state/grants.jsonl.\n" % gid); sys.exit(1)
+if used:
+    sys.stderr.write("pmos-log: ERROR — grant '%s' was already used. A grant is single use.\n" % gid); sys.exit(1)
+PY
+    append grants.jsonl "{\"type\":\"use\",\"grant_id\":$(js "$1"),\"at\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"action\":$(js "$2")}"
+    ;;
   *)
-    fail "unknown command '${cmd:-}' — one of: run | eval | accept | outcome | friction (see AGENTS-HUMAN.md)."
+    fail "unknown command '${cmd:-}' — one of: run | eval | accept | outcome | friction | grant | grant-use (see AGENTS-HUMAN.md)."
     ;;
 esac

package/payload/skills/pmos-router.skill

@@ -26,7 +26,7 @@ router is the bug (fix it via the weekly harness scan).
 1. **Sharpness (the fog/ticket test):** *can the PM state the question or idea precisely now — not
    answer it, state it?* If not, it is **fog**: not ready for intake. Name what would sharpen it
    (a conversation, a datum, a spike) and stop — do not open an initiative to hold fog.
-2. **Prior rejection:** check [planning/out-of-scope/](/README.md) for the
+2. **Prior rejection:** check [planning/out-of-scope/](/planning/out-of-scope/README.md) for the
    concept. If a file exists, **read it first** and surface it to the PM — the concept returns only
    if the PM overrides the recorded reasoning, and the file is updated either way.
 3. **The specimen test — ASK it, do not wait to be told** (D60 as amended 2026-07-24):

package/payload/skills/prototype.skill

@@ -131,7 +131,7 @@ system, a convention set, or a prototype to validate an idea.
      work has a surface, then runs inside that initiative's Build.
    - **iterate** → back to step 5 with the PM's reaction folded in.
    - **kill** → record one honest line on the initiative, **file the concept into
-     [planning/out-of-scope/](/README.md)** (decision, reasoning, what would
+     [planning/out-of-scope/](/planning/out-of-scope/README.md)** (decision, reasoning, what would
      reopen it) so it is not re-prototyped from scratch, and close. A cheap kill is this lane
      *succeeding*.
 8. **Log.** `log_agent_run` with the disposition; friction to discoveries.md (`#friction`).

package/payload/skills/strategic-brief.skill

@@ -49,7 +49,7 @@ volume where informal prioritization strains) are now met.
 
 - `planning/briefs/<initiative-id>-brief.md` — operational instance, never in the OKF bundle.
 - An accepted brief becomes the PRD's parent rationale (the PRD links it). A **no-go** files the
-  concept into [planning/out-of-scope/](/README.md) so it is not re-litigated.
+  concept into [planning/out-of-scope/](/planning/out-of-scope/README.md) so it is not re-litigated.
 
 ## Level 3 sub-cases
 

package/payload/skills-native/harness-refine/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: harness-refine
-description: >
+description: "Turn PMOS's own run evidence into concrete, evidence-cited edits to the harness. Read the eval defects, recurring friction, run transcripts, and the calibration log; cluster them into specific proposed edits \u2014 each mapped to ONE artifact (an MCP tool description, a skill body, an OKF concept, or an AGENTS.md heuristic) and citing the run/friction/eval that motivates it \u2014 including prunes of scaffolding the model now handles natively. Emit a proposals report and open a PR for the PM. Use on demand: when the PM invokes it, at the D23 quarterly harness review, or when v_friction_recurrence / recurring eval defects show a harness gap. Never merges, never self-approves, never auto-applies."
 license: MIT
 metadata:
   pmos-maturity_mode: active

package/payload/skills-native/pmos-router/SKILL.md

@@ -28,7 +28,7 @@ router is the bug (fix it via the weekly harness scan).
 1. **Sharpness (the fog/ticket test):** *can the PM state the question or idea precisely now — not
    answer it, state it?* If not, it is **fog**: not ready for intake. Name what would sharpen it
    (a conversation, a datum, a spike) and stop — do not open an initiative to hold fog.
-2. **Prior rejection:** check [planning/out-of-scope/](/README.md) for the
+2. **Prior rejection:** check [planning/out-of-scope/](/planning/out-of-scope/README.md) for the
    concept. If a file exists, **read it first** and surface it to the PM — the concept returns only
    if the PM overrides the recorded reasoning, and the file is updated either way.
 3. **The specimen test — ASK it, do not wait to be told** (D60 as amended 2026-07-24):

package/payload/skills-native/prototype/SKILL.md

@@ -133,7 +133,7 @@ system, a convention set, or a prototype to validate an idea.
      work has a surface, then runs inside that initiative's Build.
    - **iterate** → back to step 5 with the PM's reaction folded in.
    - **kill** → record one honest line on the initiative, **file the concept into
-     [planning/out-of-scope/](/README.md)** (decision, reasoning, what would
+     [planning/out-of-scope/](/planning/out-of-scope/README.md)** (decision, reasoning, what would
      reopen it) so it is not re-prototyped from scratch, and close. A cheap kill is this lane
      *succeeding*.
 8. **Log.** `log_agent_run` with the disposition; friction to discoveries.md (`#friction`).

package/payload/skills-native/strategic-brief/SKILL.md

@@ -51,7 +51,7 @@ volume where informal prioritization strains) are now met.
 
 - `planning/briefs/<initiative-id>-brief.md` — operational instance, never in the OKF bundle.
 - An accepted brief becomes the PRD's parent rationale (the PRD links it). A **no-go** files the
-  concept into [planning/out-of-scope/](/README.md) so it is not re-litigated.
+  concept into [planning/out-of-scope/](/planning/out-of-scope/README.md) so it is not re-litigated.
 
 ## Level 3 sub-cases
 

package/payload/state/discoveries.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Discoveries and friction log"
 description: "Append-only record of what runs discovered and where the process rubbed."
-generated: {by: process:create-pmos, at: "2026-10-04T01:33:06Z"}
+generated: {by: process:create-pmos, at: "2026-10-04T08:22:32Z"}
 status: stable
 ---
 

package/workspace/README.md

@@ -86,6 +86,10 @@ The top of Today is a brief: a greeting, the day's calendar, ranked priorities a
 
 `pmos kg find|card|neighbors|section|why|stats` builds a map of the repository's tracked Markdown files from relations they already write down (links, frontmatter paths, `D<nn>` citations, `initiative_id`, `parent_kr`) and answers from it, so an agent reads one card or one section and not a 130 KB file. `lib/kg.js` is pure; `lib/kg-cli.js` reads the files, keeps the map in the runtime state directory (rebuilt when HEAD or an uncommitted `.md` changes) and writes nothing in the repository. A link to a missing file is listed as dangling and is never an edge; `lib/kg-dangling-rules.json` says which dangling links are history by design. It does not guess, use embeddings, or call a model or the network. `node scripts/kg-bench.js` replays two written strategies over the fixed questions in `planning/evals/knowledge-graph-questions.md`; it is a simulation, and says "NOT REPORTABLE" until three of the questions are the PM's. Guide page: `guide/knowledge-graph.md`. Tests: `kg.test.js`.
 
+## Background prepare (`proactive-engine`, slice D3)
+
+From a Today item that names an initiative the PM can approve **one plan hash**: the step an agent may do now, with the exact first input. The server queues that approval (`prepare-queue.jsonl` in the runtime state directory) and a 60-second tick starts it through the same `startWork` path as the C1 "go" button — origin `next-step`, the same propose-only rules, the same session budget — only when the switch is on (default off), it is not quiet hours, the budget allows, and the plan hash has not changed. An approval expires after 24 hours, at most 5 can be queued, and a changed plan is skipped, never run. `lib/prepare-queue.js` holds the pure rules (`fold`, `checkRequest`, `canQueue`, `decide`); the routes are `/api/proactive/prepare/{plan,queue,cancel,run}` and `GET /api/proactive/prepare`; `pmos proactive prepare plan|queue|status|cancel|run` is the terminal face. "Run now" ignores quiet hours only. The C1 run record carries `via: 'background'`. Guide page: `guide/proactive-engine.md`. Tests: `proactive-prepare.test.js` (server, CLI, boundary) and `pm-r25-test.js` (browser). Not verified here: a real `claude` session doing the work; the suites use a stand-in agent that records what it was typed.
+
 ## Scheduled tasks from the terminal (`schedule-cli`)
 
 `pmos schedule` and `pmos skill` talk to the running workspace server, so the terminal and the workspace share one schedule store and one validator. Every change is saved the moment the command succeeds. A refused value names what is allowed and changes nothing. With no server running the command says so and exits 1.

package/workspace/guide/proactive-engine.md

@@ -22,6 +22,23 @@ The top of Today is the morning brief: a greeting, the day's calendar, the prior
 - A brief is refused, with the reason and with nothing stored, when it has a wrong shape, an unknown source, a confidence outside 0 to 1, more than 12 items or 20 events, or a text field that is too long.
 - The brief is stored in the workspace state folder on this computer. It is not committed.
 
+## Background preparation
+
+From a Today item that names an initiative, you can ask for the plan and approve it. The workspace then starts that session itself, later. It uses the same path as the next-step go button, so the plan, the prompt, the propose-only rules and the session budget are the same.
+
+- Press **prepare in the background** on an item. Today shows the step an agent session may work on now, where the work would happen, the budget and the exact first input. Press **queue it** to approve that plan.
+- Background prepare is off by default. Turn it on in the settings. When it is off, nothing can be queued and nothing queued is started. A queued entry waits while it is off. It is not dropped.
+- The approval is for one plan. If the plan has changed when the workspace is ready to start, the entry is skipped and the reason is shown. Queue it again to approve the new plan.
+- An approval expires after 24 hours. An expired entry is never started.
+- The workspace starts an entry only when the switch is on, it is not quiet hours, the session budget allows it, and the plan is the one you approved. If the budget is full, the entry waits. Entries start oldest first. At most 5 entries wait at once.
+- **run the queue now** looks at the queue immediately. It ignores quiet hours and nothing else.
+- A queued entry can be cancelled. A cancelled entry is never started.
+- The session starts with no profile, so it names no outside source, and with typed scoring off. It commits only to a local initiative branch or writes drafts. It does not push, open a pull request, send, post, accept, approve a contract or merge. The contract, acceptance and open items are your steps and cannot be queued.
+- A started session counts in the same session budget as a next-step go. Switch to it from Today, and review it from the initiative as for any prepared step.
+- It runs only while the workspace server runs. The queue is stored in the workspace state folder on this computer.
+
+The states of an entry are queued, started, skipped, expired and cancelled.
+
 ## What it shows
 
 Today scans for five conditions. Each one becomes one item with the reason and the evidence.
@@ -52,6 +69,7 @@ A verdict never changes a status, a lifecycle record or an acceptance. In this r
 | engine on | Off stops automatic scans. The scan now button still works. |
 | watch: needs, returned, review, schedule, stalled | Turn one trigger off. |
 | brief sources | One switch for each of calendar, wispr, mail, jira and confluence. |
+| background prepare | Off by default. On lets the workspace start a session for a plan you approved. |
 | typed scoring | Off by default. On lets the skill send titles and metadata to the Typesafe service. |
 | name | Used in the greeting. |
 | stalled after N days | The stalled threshold, from 1 to 90 days. |
@@ -62,14 +80,15 @@ A verdict never changes a status, a lifecycle record or an acceptance. In this r
 
 - `pmos proactive today` lists the items.
 - `pmos proactive scan` scans now.
-- `pmos proactive settings` shows the settings. Add `--enabled`, `--trigger NAME=on|off`, `--stalled-days`, `--quiet HH:MM-HH:MM|none`, `--pause-learning`, `--brief-source NAME=on|off`, `--brief-scoring on|off` or `--name` to change one.
+- `pmos proactive settings` shows the settings. Add `--enabled`, `--trigger NAME=on|off`, `--stalled-days`, `--quiet HH:MM-HH:MM|none`, `--pause-learning`, `--background-prepare on|off`, `--brief-source NAME=on|off`, `--brief-scoring on|off` or `--name` to change one.
 - `pmos proactive brief` shows today's brief. `pmos proactive brief submit --file PATH` submits one. `pmos proactive brief schedule` makes the 06:45 schedule for the current repository.
+- `pmos proactive prepare` shows the queue. `pmos proactive prepare plan --initiative ID` shows a plan and its hash. `pmos proactive prepare queue --initiative ID --item ITEM --sha HASH` approves it. `pmos proactive prepare cancel ID` cancels an entry. `pmos proactive prepare run` looks at the queue now.
 - `pmos proactive feedback <id> useful|not-useful|wrong-priority|opened|dismissed` records feedback. Use `--missed "text"` for a missed item.
 
 ## Limits
 
 - It runs only while the workspace server runs. It does not catch up for time the server was off. A sleeping computer gets no scan.
 - The items from the records come from this computer. The workspace itself does not read your mail or your calendar. Only the morning-brief session does, and only the sources you switched on.
-- It does not start a session, push, send, post, accept or merge. It only shows items and records your feedback.
+- It does not start a session, push, send, post, accept or merge. It only shows items and records your feedback. The one exception is background preparation, which starts a session only for a plan you approved, as described above.
 - An unreadable repository is listed as not read. An empty list is not proof that nothing waits there.
 - The records stay in the workspace state folder on this computer. They are not committed.

package/workspace/lib/prepare-queue.js

@@ -0,0 +1,76 @@
+'use strict';
+/* prepare-queue.js — the rules for background preparation: what may be queued, and when a queued entry may start.
+ *
+ * Pure: no I/O, no clock, no model. The server passes what is true now (the settings, the entries read from the ledger, a
+ * fresh prepare of the same step, the session budget) and this module decides. An approval is ONE plan hash, never a
+ * standing permission: a plan that changed is skipped, an approval older than 24 hours expires, and nothing is caught up.
+ *
+ *   fold(events)                         → the entries, each with its latest status
+ *   checkRequest(body)                   → the shape of a queue request, or why it is refused
+ *   canQueue({settings, entries, req})   → null, or the reason a request is refused
+ *   decide({entry, now, settings, quiet, manual, fresh, budget}) → {action, reason}
+ *
+ * Statuses: queued · started · skipped · expired · cancelled. Only `queued` can change; the other four are final.
+ */
+const MAX_QUEUED = 5;
+const EXPIRE_MS = 24 * 60 * 60 * 1000;
+const FINAL = ['started', 'skipped', 'expired', 'cancelled'];
+const HASH = /^[0-9a-f]{16}$/;
+const ID = /^[a-z0-9][a-z0-9._-]*$/i;
+const ITEM = /^[\w.:-]{1,120}$/;
+const CAND = /^[0-9a-f]{12}$/;
+
+/** The latest status of every entry, oldest first. A line that names no entry is ignored. */
+function fold(events) {
+  const by = new Map();
+  for (const e of Array.isArray(events) ? events : []) {
+    if (!e || typeof e.id !== 'string') continue;
+    if (e.event === 'queued') { if (!by.has(e.id)) by.set(e.id, { id: e.id, status: 'queued', queued_at: e.at, ws: e.ws, initiative_id: e.initiative_id, item_id: e.item_id, key: e.key, candidate_id: e.candidate_id || null, prompt_sha: e.prompt_sha, branch: e.branch || null, reason: null, session_id: null, at: e.at }); continue; }
+    const cur = by.get(e.id);
+    if (!cur || FINAL.includes(cur.status) || !FINAL.includes(e.event)) continue;
+    cur.status = e.event; cur.reason = e.reason || null; cur.session_id = e.session_id || null; cur.at = e.at;
+  }
+  return [...by.values()];
+}
+
+/** @returns {{ok:true, req:object}|{ok:false, error:string}} */
+function checkRequest(body) {
+  const b = body && typeof body === 'object' ? body : {};
+  if (b.confirm !== true) return { ok: false, error: 'confirm is required: this lets the workspace start a session later' };
+  if (typeof b.ws !== 'string' || !b.ws) return { ok: false, error: 'ws is required' };
+  if (typeof b.initiative_id !== 'string' || !ID.test(b.initiative_id)) return { ok: false, error: 'initiative_id is required' };
+  if (typeof b.item_id !== 'string' || !ITEM.test(b.item_id)) return { ok: false, error: 'item_id is required' };
+  if (typeof b.prompt_sha !== 'string' || !HASH.test(b.prompt_sha)) return { ok: false, error: 'prompt_sha is required: queue the plan you were shown' };
+  if (b.candidate_id !== undefined && b.candidate_id !== null && b.candidate_id !== '' && !CAND.test(String(b.candidate_id))) return { ok: false, error: 'candidate_id is not a candidate id' };
+  return { ok: true, req: { ws: b.ws, initiative_id: b.initiative_id, item_id: b.item_id, prompt_sha: b.prompt_sha, candidate_id: b.candidate_id || null } };
+}
+
+/** @returns {string|null} the reason a request is refused, or null */
+function canQueue({ settings, entries, req }) {
+  if (!settings || settings.backgroundPrepare !== true) return 'background prepare is off. Turn it on in the Today settings first.';
+  const queued = (entries || []).filter((e) => e.status === 'queued');
+  if (queued.some((e) => e.ws === req.ws && e.initiative_id === req.initiative_id && e.item_id === req.item_id)) return 'this step is already queued';
+  if (queued.length >= MAX_QUEUED) return `${queued.length} entries are already waiting (the limit is ${MAX_QUEUED}). Cancel one or wait for it to start.`;
+  return null;
+}
+
+/**
+ * What the runner does with one queued entry right now.
+ * @param {{entry:object, now:number, settings:object, quiet:boolean, manual:boolean, fresh:object, budget:object}} s
+ * @returns {{action:'start'|'wait'|'skip'|'expire', reason:string|null}}
+ */
+function decide(s) {
+  const e = s.entry;
+  const age = s.now - Date.parse(e.queued_at);
+  if (!Number.isFinite(age) || age > EXPIRE_MS) return { action: 'expire', reason: 'the approval is older than 24 hours — queue it again if you still want it' };
+  if (!s.settings || s.settings.backgroundPrepare !== true) return { action: 'wait', reason: 'background prepare is off' };
+  if (s.quiet && !s.manual) return { action: 'wait', reason: 'quiet hours' };
+  const f = s.fresh || {};
+  if (!f.ok) return { action: 'skip', reason: f.error || 'the step could not be prepared again' };
+  if (f.refused) return { action: 'skip', reason: f.refused.why };
+  if (f.prompt_sha !== e.prompt_sha) return { action: 'skip', reason: 'the plan changed since you approved it — queue it again to approve the new one' };
+  if (!s.budget || !s.budget.allowed) return { action: 'wait', reason: (s.budget && s.budget.reason) || 'no session budget' };
+  return { action: 'start', reason: null };
+}
+
+module.exports = { MAX_QUEUED, EXPIRE_MS, FINAL, fold, checkRequest, canQueue, decide };

package/workspace/lib/proactive-cli.js

@@ -13,13 +13,16 @@
  *   pmos proactive brief [show]
  *   pmos proactive brief submit --file PATH
  *   pmos proactive brief schedule [--repo PATH]
+ *   pmos proactive prepare plan --initiative ID [--repo PATH]
+ *   pmos proactive prepare queue --initiative ID --item ITEM --sha HASH [--repo PATH]
+ *   pmos proactive prepare status | cancel ID | run
  */
 const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
 const { parseArgs } = require('./schedule-cli');
 
-const COMMANDS = { proactive: ['today', 'scan', 'settings', 'feedback', 'brief'] };
+const COMMANDS = { proactive: ['today', 'scan', 'settings', 'feedback', 'brief', 'prepare'] };
 const BRIEF_SOURCES = ['calendar', 'wispr', 'mail', 'jira', 'confluence'];
 const onOff = (v, what) => (v === 'on' || v === 'true' ? true : v === 'off' || v === 'false' ? false : { err: `${what} takes on or off` });
 
@@ -63,6 +66,7 @@ async function run(argv, { call, say, cwd = process.cwd() }) {
       patch.triggers = { [m[1]]: m[2] === 'on' };
     }
     if ('name' in flags) patch.name = flags.name;
+    if ('background-prepare' in flags) { const v = onOff(flags['background-prepare'], '--background-prepare'); if (v.err) return fail(v.err); patch.backgroundPrepare = v; }
     if ('brief-scoring' in flags) { const v = onOff(flags['brief-scoring'], '--brief-scoring'); if (v.err) return fail(v.err); patch.briefScoring = v; }
     if ('brief-source' in flags) {
       const m = /^([a-z]+)=(on|off)$/.exec(flags['brief-source']);
@@ -82,9 +86,61 @@ async function run(argv, { call, say, cwd = process.cwd() }) {
     }
     say(`engine ${s.enabled ? 'on' : 'off'} · stalled after ${s.stalledDays} days · quiet ${s.quiet ? s.quiet.start + '-' + s.quiet.end : 'none'} · learning ${s.pauseLearning ? 'paused' : 'on'}`);
     say('brief sources: ' + BRIEF_SOURCES.map((k) => `${k} ${s.briefSources && s.briefSources[k] ? 'on' : 'off'}`).join(', ') + ' · scoring ' + (s.briefScoring ? 'on' : 'off') + (s.name ? ' · name ' + s.name : ''));
+    say('background prepare ' + (s.backgroundPrepare ? 'on' : 'off'));
     say('watching: ' + Object.entries(s.triggers).map(([k, v]) => `${k} ${v ? 'on' : 'off'}`).join(', '));
     return 0;
   }
+  if (verb === 'prepare') {
+    const sub = pos[0] || 'status';
+    const wsOf = async () => {
+      let root; try { root = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: flags.repo ? path.resolve(cwd, flags.repo) : cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return { err: 'this is not inside a git repository — use --repo PATH' }; }
+      const wl = await call('GET', '/api/workspaces');
+      const hit = ((wl && wl.workspaces) || []).find((w) => path.resolve(w.root) === path.resolve(root));
+      return hit ? { ws: hit.id } : { err: `${root} is not a registered workspace — open it with pmos first` };
+    };
+    if (sub === 'plan' || sub === 'queue') {
+      if (!flags.initiative) return fail(`usage: pmos proactive prepare ${sub} --initiative ID${sub === 'queue' ? ' --item ITEM --sha HASH' : ''}`);
+      const w = await wsOf(); if (w.err) return fail(w.err);
+      if (sub === 'plan') {
+        const r = await call('POST', '/api/proactive/prepare/plan', { ws: w.ws, initiative_id: flags.initiative });
+        if (!r || r.ok === false) return fail((r && r.error) || 'the server did not answer');
+        say(`step: ${r.item.key} — ${r.item.text}  (item ${r.item.id})`);
+        if (r.refused) { say('refused: ' + r.refused.why); return 1; }
+        say(r.plan.why || r.plan.plan);
+        say(`budget: ${r.budget.running} of ${r.budget.limits.concurrent} running · ${r.budget.startedToday} of ${r.budget.limits.perDay} started today`);
+        say('background prepare is ' + (r.background.enabled ? 'on' : 'off. Turn it on with: pmos proactive settings --background-prepare on'));
+        say('plan ' + r.prompt_sha + ' — the exact first input:');
+        say(r.prompt);
+        say(`queue it with: pmos proactive prepare queue --initiative ${r.initiative_id} --item ${r.item.id} --sha ${r.prompt_sha}`);
+        return 0;
+      }
+      if (!flags.item || !flags.sha) return fail('usage: pmos proactive prepare queue --initiative ID --item ITEM --sha HASH');
+      const r = await call('POST', '/api/proactive/prepare/queue', { ws: w.ws, initiative_id: flags.initiative, item_id: flags.item, prompt_sha: flags.sha, confirm: true });
+      if (!r || r.ok === false) return fail(`refused — ${(r && r.error) || 'the server did not answer'}. Nothing was queued.`);
+      say(`queued ${r.entry.id} — the workspace starts it when the budget allows. It expires in 24 hours.`);
+      return 0;
+    }
+    if (sub === 'cancel') {
+      if (!pos[1]) return fail('usage: pmos proactive prepare cancel ID');
+      const r = await call('POST', '/api/proactive/prepare/cancel', { id: pos[1] });
+      if (!r || r.ok === false) return fail((r && r.error) || 'the server did not answer');
+      say('cancelled'); return 0;
+    }
+    if (sub === 'run') {
+      const r = await call('POST', '/api/proactive/prepare/run', {});
+      if (!r || r.ok === false) return fail((r && r.error) || 'the server did not answer');
+      if (!r.results.length) say('nothing is queued');
+      for (const x of r.results) say(`${x.id}  ${x.action}${x.reason ? ' — ' + x.reason : ''}${x.session_id ? ' (session ' + x.session_id + ')' : ''}`);
+      return 0;
+    }
+    if (sub !== 'status') return fail('usage: pmos proactive prepare [status|plan|queue|cancel ID|run]');
+    const r = await call('GET', '/api/proactive/prepare');
+    if (!r || r.ok === false) return fail((r && r.error) || 'the server did not answer');
+    say(`background prepare ${r.enabled ? 'on' : 'off'}${r.quiet ? ' · quiet hours now' : ''} · ${r.budget.running} of ${r.budget.limits.concurrent} running · ${r.budget.startedToday} of ${r.budget.limits.perDay} started today`);
+    if (!r.entries.length) say('nothing has been queued');
+    for (const e of r.entries) say(`${e.id}  ${e.status}  ${e.label}${e.reason ? ' — ' + e.reason : ''}`);
+    return 0;
+  }
   if (verb === 'brief') {
     const sub = pos[0] || 'show';
     if (sub === 'submit') {

package/workspace/lib/proactive.js

@@ -32,7 +32,7 @@ const OWNER = { needs: 'pm', returned: 'pm', review: 'pm', schedule: 'pm', stall
 const BRIEF_SOURCES = ['calendar', 'wispr', 'mail', 'jira', 'confluence'];
 // Mail is off by default: a brief reads titles and metadata of the other sources, and the PM turns mail on.
 const BRIEF_DEFAULT = Object.freeze({ calendar: true, wispr: true, mail: false, jira: true, confluence: true });
-const DEFAULTS = Object.freeze({ name: '', briefSources: BRIEF_DEFAULT, briefScoring: false, enabled: true, triggers: Object.freeze(Object.fromEntries(TRIGGERS.map((t) => [t, true]))), stalledDays: 5, quiet: null, pauseLearning: false });
+const DEFAULTS = Object.freeze({ name: '', briefSources: BRIEF_DEFAULT, briefScoring: false, backgroundPrepare: false, enabled: true, triggers: Object.freeze(Object.fromEntries(TRIGGERS.map((t) => [t, true]))), stalledDays: 5, quiet: null, pauseLearning: false });
 
 const idOf = (key) => crypto.createHash('sha1').update(String(key)).digest('hex').slice(0, 12);
 const clip = (s, n) => String(s == null ? '' : s).replace(/\s+/g, ' ').trim().slice(0, n);
@@ -161,10 +161,11 @@ const HHMM = /^([01]\d|2[0-3]):([0-5]\d)$/;
 /** @returns {{ok:true, settings:object}|{ok:false, error:string}} — `raw` is merged over the defaults; nothing is partly applied. */
 function normalizeSettings(raw) {
   const r = raw && typeof raw === 'object' ? raw : {};
-  const s = { name: DEFAULTS.name, briefSources: { ...BRIEF_DEFAULT }, briefScoring: DEFAULTS.briefScoring, enabled: DEFAULTS.enabled, triggers: { ...DEFAULTS.triggers }, stalledDays: DEFAULTS.stalledDays, quiet: DEFAULTS.quiet, pauseLearning: DEFAULTS.pauseLearning };
+  const s = { name: DEFAULTS.name, briefSources: { ...BRIEF_DEFAULT }, briefScoring: DEFAULTS.briefScoring, backgroundPrepare: DEFAULTS.backgroundPrepare, enabled: DEFAULTS.enabled, triggers: { ...DEFAULTS.triggers }, stalledDays: DEFAULTS.stalledDays, quiet: DEFAULTS.quiet, pauseLearning: DEFAULTS.pauseLearning };
   if (r.enabled !== undefined) { if (typeof r.enabled !== 'boolean') return { ok: false, error: 'enabled must be true or false' }; s.enabled = r.enabled; }
   if (r.name !== undefined) { if (typeof r.name !== 'string' || r.name.length > 40) return { ok: false, error: 'name must be text of at most 40 characters' }; s.name = r.name.replace(/\s+/g, ' ').trim(); }
   if (r.briefScoring !== undefined) { if (typeof r.briefScoring !== 'boolean') return { ok: false, error: 'briefScoring must be true or false' }; s.briefScoring = r.briefScoring; }
+  if (r.backgroundPrepare !== undefined) { if (typeof r.backgroundPrepare !== 'boolean') return { ok: false, error: 'backgroundPrepare must be true or false' }; s.backgroundPrepare = r.backgroundPrepare; }
   if (r.briefSources !== undefined) {
     if (!r.briefSources || typeof r.briefSources !== 'object' || Array.isArray(r.briefSources)) return { ok: false, error: `briefSources must be an object of ${BRIEF_SOURCES.join(', ')} → true or false` };
     for (const [k, v] of Object.entries(r.briefSources)) {

package/workspace/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",
@@ -10,12 +10,12 @@
   "scripts": {
     "start": "node server.js",
     "test": "node test.js && npm run test:modules",
-    "test:modules": "node proactive.test.js && node focus.test.js && node handoff.test.js && node repo-scan.test.js && node profiles.test.js && node external-linking.test.js && node story-artifacts.test.js && node no-network.test.js && node typesafe-validation.test.js && node claims.test.js && node jev-claims.test.js && node repo-watch.test.js && node fixture-parity.test.mjs && node markdown.test.mjs && node start-policy.test.js && node state-isolation.test.js && node sync.test.js && node schedule-cli.test.js && node initiative-surface.test.js && node guide.test.js && node next-step-actions.test.js && node kg.test.js",
+    "test:modules": "node proactive.test.js && node focus.test.js && node handoff.test.js && node repo-scan.test.js && node profiles.test.js && node external-linking.test.js && node story-artifacts.test.js && node no-network.test.js && node typesafe-validation.test.js && node claims.test.js && node jev-claims.test.js && node repo-watch.test.js && node fixture-parity.test.mjs && node markdown.test.mjs && node start-policy.test.js && node state-isolation.test.js && node sync.test.js && node schedule-cli.test.js && node initiative-surface.test.js && node guide.test.js && node next-step-actions.test.js && node kg.test.js && node proactive-prepare.test.js",
     "test:ui": "node ui-test.js",
     "test:parity": "node design-parity.js --states",
     "test:all": "npm test && npm run test:panels && npm run test:ui && npm run test:parity && npm run test:offline",
     "doctor": "node doctor.js",
-    "test:panels": "node pm-shell-test.js && node pm-repos-test.js && node pm-initiatives-test.js && node pm-detail-test.js && node pm-tabs-test.js && node pm-term-test.js && node pm-modes-test.js && node pm-r1-test.js && node pm-r2-test.js && node pm-r3-test.js && node pm-r4-test.js && node pm-r5-test.js && node pm-r6-test.js && node pm-r7-test.js && node pm-r8-test.js && node pm-r9-test.js && node pm-r10-test.js && node pm-r11-test.js && node pm-r12-test.js && node pm-r13-test.js && node pm-r14-test.js && node pm-r15-test.js && node pm-r16-test.js && node pm-r17-test.js && node pm-r16-test.js && node pm-r18-test.js && node pm-r19-test.js && node pm-r20-test.js && node pm-r21-test.js && node pm-r22-test.js && node pm-r23-test.js && node pm-r24-test.js",
+    "test:panels": "node pm-shell-test.js && node pm-repos-test.js && node pm-initiatives-test.js && node pm-detail-test.js && node pm-tabs-test.js && node pm-term-test.js && node pm-modes-test.js && node pm-r1-test.js && node pm-r2-test.js && node pm-r3-test.js && node pm-r4-test.js && node pm-r5-test.js && node pm-r6-test.js && node pm-r7-test.js && node pm-r8-test.js && node pm-r9-test.js && node pm-r10-test.js && node pm-r11-test.js && node pm-r12-test.js && node pm-r13-test.js && node pm-r14-test.js && node pm-r15-test.js && node pm-r16-test.js && node pm-r17-test.js && node pm-r16-test.js && node pm-r18-test.js && node pm-r19-test.js && node pm-r20-test.js && node pm-r21-test.js && node pm-r22-test.js && node pm-r23-test.js && node pm-r24-test.js && node pm-r25-test.js",
     "test:offline": "node offline-tarball.test.js"
   },
   "engines": {