create-pmos 0.126.0 → 0.127.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.126.0",
+  "version": "0.127.0",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@ef9256d
+kernel-source: pmos@ad6b0f4
 assembled: 2026-10-11
 mode: vendor

package/payload/planning/evals/eval-calibration.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Eval calibration log"
 description: "Append-only record of every PM override of an evaluator verdict."
-generated: {by: process:create-pmos, at: "2026-10-11T02:44:29Z"}
+generated: {by: process:create-pmos, at: "2026-10-11T02:52:51Z"}
 status: stable
 ---
 

package/payload/planning/okrs/health-budgets.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Health budgets"
 description: "Closed registry of health-budget anchors (D59), edited only by the PM."
-generated: {by: process:create-pmos, at: "2026-10-11T02:44:29Z"}
+generated: {by: process:create-pmos, at: "2026-10-11T02:52:51Z"}
 status: stable
 ---
 

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-11T02:44:29Z"}
+generated: {by: process:create-pmos, at: "2026-10-11T02:52:51Z"}
 status: stable
 ---
 

package/workspace/guide/layout.md

@@ -2,7 +2,7 @@
 type: Guide
 title: "Guide: layout"
 description: "The frame: one top bar, the place on screen, the detail and the agent dock; the phone tabs and lists; the keys; and the older layout."
-timestamp: 2026-10-08
+timestamp: 2026-10-11
 ---
 
 # Guide: layout
@@ -51,7 +51,7 @@ The dock holds your terminals, documents, conversations, skills and web pages. I
 
 - Press ⌘J (Ctrl-J), or the button on the rail, to open the dock. Press ⌘J again, or the fold button in the dock, to fold it to the rail.
 - The dock never opens by itself. A tab that opens while the dock is a rail waits in the dock until you open it.
-- The dock lists the sessions of the repository by initiative. A session is in the group of the initiative it is recorded on, or of its `initiative/<id>` branch. Then come **Not linked** (no initiative) and **Automatic** (anything you did not start yourself, for example a schedule, the day run, a note's summary or bullets, or a Jira push). **Automatic** is hidden until you press **Show automatic** at the foot of the list (or beside the group select in the strip). A session in front, or one held on a permission question, is always shown. An agent that has finished and reads "needs you" is hidden like the rest. Finished automatic sessions remove themselves a minute after a clean exit, and one with no output for 60 minutes is ended and removed. A failed one stays. When a session has been removed, its terminal tab closes too, also when the workspace was stopped for an update, so the tab does not come back as a row under **Open**. The setting is in `state/session-policy.json`: `finish` (true or false) and `idleMinutes` (5 or more, or 0 for off). Then **Open** lists the tabs that are not sessions, for example documents and skills. Each one shows its title, what it is (for example PRD, Document or Web page) and its branch when it is not main. **✕** on an Open row closes the tab only. A terminal keeps running.
+- The dock lists the sessions of the repository by initiative. A session is in the group of the initiative it is recorded on, or of its `initiative/<id>` branch. Then come **Not linked** (no initiative) and **Automatic** (anything you did not start yourself, for example a schedule, the day run, a note's summary or bullets, or a Jira push). **Automatic** is hidden until you press **Show automatic** at the foot of the list (or beside the group select in the strip). A session in front, or one held on a permission question, is always shown. An agent that has finished and reads "needs you" is hidden like the rest. Finished automatic sessions remove themselves a minute after a clean exit, and one with no output for 60 minutes is ended and removed. A failed one stays for a day. When a schedule starts a new run, it ends its previous run first, unless that run is still working or waits for your answer. Any session that has ended, also one you started, is removed after 7 days. Its conversation is kept when it ends. A session you started is never ended for you. When a session has been removed, its terminal tab closes too, also when the workspace was stopped for an update, so the tab does not come back as a row under **Open**. The setting is in `state/session-policy.json`: `finish` (true or false), `idleMinutes` (5 or more, or 0 for off) and `keepExitedDays` (1 to 365, or 0 to keep ended sessions). Then **Open** lists the tabs that are not sessions, for example documents and skills. Each one shows its title, what it is (for example PRD, Document or Web page) and its branch when it is not main. **✕** on an Open row closes the tab only. A terminal keeps running.
 - Each session row starts with a mark for its state: ● working, ◼ quiet, ◆ needs you, ◇ maybe blocked, ○ ended. Under the name, the row shows the state when the session is not working, the type of work when one is set, and the branch when it is not main and not the initiative's own branch. Running sessions come first and ended sessions last. Press the row to bring the session to the front.
 - Press the name of a group to fold it or open it. The number beside it counts its sessions. **Automatic** is folded while none of its sessions is running, because each run leaves an ended session. The group of the session in front always stays open, and the workspace keeps your choice for each group.
 - **⋯** and **✕** show on the row in front, on the row under the pointer and on the row with the keyboard focus. On a touch screen they always show.

package/workspace/lib/git-info.js

@@ -251,6 +251,24 @@ function removeWorktree(root, dir) {
   return { ok: true, dir: target.dir, branch: target.branch, pruned: false };
 }
 
+// { ok, current, detached } — only the HEAD half of branchInfo, with the same failure codes. The
+// workspace list and the session heartbeat need the branch name and nothing else; branchInfo also
+// lists every branch, runs `git status --porcelain` and lists the worktrees, which on a large repo
+// is most of the cost and was paid for every workspace every 15 seconds. `top` may be passed when
+// the caller already resolved the repo root, saving one more shell-out.
+function headInfo(root, top) {
+  const t = top === undefined ? repoRoot(root) : top;
+  if (!t) {
+    if (!isRepo(root)) return { ok: false, code: 'no-git', error: 'not a git repository' };
+    return { ok: false, code: 'git-error', error: 'git not available' };
+  }
+  const head = git(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  if (head.failed) return { ok: false, code: 'git-error', error: 'git not available' };
+  if (head.code !== 0) return { ok: false, code: 'git-error', error: head.err || 'could not read HEAD' };
+  const detached = head.out === 'HEAD';
+  return { ok: true, current: detached ? null : head.out, detached };
+}
+
 // { ok, current, branches[], detached, dirty, repoRoot, subdir, linked, worktrees[] }. A non-repo
 // or a failed git returns ok:false with a reason — NEVER a fabricated branch (a wrong branch chip
 // is worse than none; anti-drift). `subdir` is the workspace's path INSIDE the repo ('' at the
@@ -284,5 +302,5 @@ function branchInfo(root) {
   };
 }
 
-module.exports = { isRepo, repoRoot, validBranchName, branchInfo, checkout, worktrees, worktreePath,
+module.exports = { isRepo, repoRoot, validBranchName, branchInfo, headInfo, checkout, worktrees, worktreePath,
   addWorktree, worktreeSafety, removeWorktree, originUrl, isGithubRemote };

package/workspace/lib/session-origin.js

@@ -7,6 +7,10 @@
  *
  * Next step, Hand to agent, a skill draft and an alignment are NOT automatic: the PM pressed those, and often talks on.
  * Any other origin is automatic.
+ *
+ * A live session the PM started is never ended here. Once ANY session has ended, it expires after the policy's
+ * keepExitedDays (default 7): its conversation was recorded when it exited, and a list that only grows costs memory,
+ * disk, a bigger push every 2 seconds, and blocks forgetting a workspace (workspace-session-lifecycle).
  */
 'use strict';
 
@@ -24,8 +28,12 @@ function isAutomatic(origin) {
   return !(MANUAL_EXACT.includes(o) || MANUAL_PREFIX.some((p) => o.startsWith(p)));
 }
 
-const DEFAULT_POLICY = Object.freeze({ finish: true, idleMinutes: 60 });
+const DEFAULT_POLICY = Object.freeze({ finish: true, idleMinutes: 60, keepExitedDays: 7 });
 const FINISH_GRACE_MS = 60 * 1000;   // a finished job stays this long, so a PM watching it sees it end
+// A job that FAILED stays long enough for the PM to see it on the next look at the workspace, then goes. Kept for ever,
+// a schedule firing at a moved repo added one dead row per fire, each with its scrollback in memory and on disk.
+const FAILED_KEEP_MS = 24 * 3600 * 1000;
+const KEEP_DAYS_MAX = 365;
 const IDLE_MIN = 5;
 const IDLE_MAX = 7 * 24 * 60;
 
@@ -38,7 +46,14 @@ function normalizePolicy(raw) {
   else if (typeof r.idleMinutes === 'number' && Number.isFinite(r.idleMinutes)) {
     idle = Math.min(IDLE_MAX, Math.max(IDLE_MIN, Math.round(r.idleMinutes)));
   }
-  return { finish, idleMinutes: idle };
+  // keepExitedDays: how long ANY ended session (the PM's too) stays in the list. Its conversation is recorded when it
+  // exits, so removing the row loses no work. 0 or null = keep for ever.
+  let keep = DEFAULT_POLICY.keepExitedDays;
+  if (r.keepExitedDays === null || r.keepExitedDays === 0) keep = null;
+  else if (typeof r.keepExitedDays === 'number' && Number.isFinite(r.keepExitedDays)) {
+    keep = Math.min(KEEP_DAYS_MAX, Math.max(1, Math.round(r.keepExitedDays)));
+  }
+  return { finish, idleMinutes: idle, keepExitedDays: keep };
 }
 
 /** Did the session end cleanly? The note the server writes on exit reads "exited (code 0)". Anything else is kept. */
@@ -49,23 +64,33 @@ function endedCleanly(s) {
 /**
  * What the sweep should do with one session row: 'remove' (it has ended and may go), 'end' (it is idle: stop it, and
  * it is removed on a later sweep), or null (leave it).
- * Row fields read: origin, state, shown, note, lastOutputAt, autoDelete ('never' opts one job out), autoEnded.
+ * Row fields read: origin, state, shown, note, lastOutputAt, exitedAt, autoDelete ('never' opts one out), autoEnded.
+ * `shown` is only read for a live automatic session past its idle limit; the caller may pass a function for it so the
+ * transcript lookup behind it runs only then (see needsShown).
  */
 function decide(s, policy, now) {
-  if (!s || !isAutomatic(s.origin) || s.autoDelete === 'never') return null;
+  if (!s || s.autoDelete === 'never') return null;
+  const exitedAt = Date.parse(s.exitedAt || '') || 0;
+  // Every ended session, whoever started it, expires after keepExitedDays. A live session the PM started is never ended.
+  if (s.state === 'exited' && policy.keepExitedDays && exitedAt && now - exitedAt >= policy.keepExitedDays * 86400000) return 'remove';
+  if (!isAutomatic(s.origin)) return null;
   const last = Number(s.lastOutputAt) || 0;
-  if (!last) return null;   // no clock for it (restored from disk): never guess an age
-  const age = now - last;
   if (s.state === 'exited') {
+    // The exit time is the better clock for an ended job; the output clock is the fallback for a row from before it.
+    const age = now - (exitedAt || last);
+    if (!exitedAt && !last) return null;   // no clock for it: never guess an age
     if (!policy.finish && !s.autoEnded) return null;
-    if (!s.autoEnded && !endedCleanly(s)) return null;   // a failed job needs the PM's eye
+    if (!s.autoEnded && !endedCleanly(s)) return age >= FAILED_KEEP_MS ? 'remove' : null;   // a failed job: the PM's eye first
     return age >= FINISH_GRACE_MS ? 'remove' : null;
   }
+  if (!last) return null;   // no clock for it (restored from disk): never guess an age
   if (!policy.idleMinutes) return null;
+  if (now - last < policy.idleMinutes * 60 * 1000) return null;
   // A call waiting for permission is a real ask. 'needs' (the agent's turn is over) is NOT: a finished agent always reads
   // 'needs you', so exempting it would keep every finished job for ever. The idle clock still gives a late question time.
-  if (s.shown === 'blocked') return null;
-  return age >= policy.idleMinutes * 60 * 1000 ? 'end' : null;
+  const shown = typeof s.shown === 'function' ? s.shown() : s.shown;
+  if (shown === 'blocked') return null;
+  return 'end';
 }
 
-module.exports = { isAutomatic, normalizePolicy, decide, endedCleanly, DEFAULT_POLICY, FINISH_GRACE_MS, MANUAL_EXACT, MANUAL_PREFIX };
+module.exports = { isAutomatic, normalizePolicy, decide, endedCleanly, DEFAULT_POLICY, FINISH_GRACE_MS, FAILED_KEEP_MS, MANUAL_EXACT, MANUAL_PREFIX };

package/workspace/lib/transcript-read.js

@@ -66,13 +66,21 @@ function slugFor(cwd) {
  * Default descendant lister: ONE `ps` snapshot → a ppid→children map → the direct children of
  * `pid`. Injected in tests so the walk is exercised without real processes. Returns [] on any
  * failure — a resolver miss must degrade to the refusal, never throw.
+ *
+ * The snapshot is shared for PS_SNAPSHOT_MS. The walk asks for the children of every pid it visits,
+ * and the server resolves every shell pane on each 2s heartbeat, so an uncached lister ran one
+ * synchronous `ps` per visited pid per pane per push: 10 `ps` runs per push with six shell panes,
+ * each one blocking the thread that carries keystrokes. One snapshot answers all of them.
  */
-function defaultChildren(pid) {
+const PS_SNAPSHOT_MS = 1000;
+let psSnap = null;   // { at, kids: Map<ppid, pid[]> }
+function psChildrenMap(now = Date.now()) {
+  if (psSnap && now - psSnap.at < PS_SNAPSHOT_MS) return psSnap.kids;
   let out;
   try {
     out = cp.execFileSync('ps', ['-Ao', 'pid=,ppid='], { encoding: 'utf8', timeout: 2000 });
   } catch {
-    return [];
+    return null;   // not cached: tmux or ps can be transiently busy, and the next call tries again
   }
   const kids = new Map();
   for (const line of out.split('\n')) {
@@ -83,7 +91,12 @@ function defaultChildren(pid) {
     if (!kids.has(pp)) kids.set(pp, []);
     kids.get(pp).push(p);
   }
-  return kids.get(Number(pid)) || [];
+  psSnap = { at: now, kids };
+  return kids;
+}
+function defaultChildren(pid) {
+  const kids = psChildrenMap();
+  return (kids && kids.get(Number(pid))) || [];
 }
 
 /** Breadth-first descendants of `pid`, bounded to `maxDepth` levels. `listChildren(pid)->pids`. */
@@ -303,4 +316,4 @@ function readHarness(file, clean = (x) => x) {
 }
 
 module.exports = { findTranscript, readHarness, prettyTool, slugFor, resolvePid, descendants,
-  MAX_BYTES, MAX_WALK_DEPTH };
+  MAX_BYTES, MAX_WALK_DEPTH, PS_SNAPSHOT_MS, defaultChildren };

package/workspace/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmos-workspace",
-  "version": "0.126.0",
+  "version": "0.127.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.126.0",
+      "version": "0.127.0",
       "license": "MIT",
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.126.0",
+  "version": "0.127.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",

package/workspace/server.js

@@ -639,7 +639,9 @@ function repoIdentity(root) {
   // a fault: a folder registered by path legitimately has no origin, and null is the honest answer.
   try { remote = gitInfo.originUrl(root); } catch { remote = null; }
   try {
-    const bi = gitInfo.branchInfo(root);
+    // headInfo, not branchInfo: only the branch name is used here, and branchInfo's branch list,
+    // `git status` and worktree list cost ~5 more shell-outs per workspace per TTL (session lifecycle).
+    const bi = gitInfo.headInfo(root, tree || null);
     if (bi.ok) branch = bi.detached ? null : bi.current;
     // R1/A2 — carry the CODE and the MESSAGE, not a boolean. branchInfo already separates the two
     // failures and says so in its own comment: `no-git` is an ordinary folder and "deserves no
@@ -2387,6 +2389,23 @@ function reportToMarkdown(surface) {
 }
 // Fire one schedule: run its skill → contract → deliverable → stamp → file to needs-you. Same path
 // for a scheduled tick and for run-now (R7). Pure of PTYs in v1 (deterministic report skill).
+// A schedule that fires again while its previous run is still open ends that run first, unless it is still producing
+// output or holds a call waiting for the PM. Before, every fire added a session beside the last one, and each stayed
+// up to the idle limit (workspace-session-lifecycle). Only automatic origins are ever touched.
+function endSupersededRuns(origin, now = Date.now()) {
+  const ended = [];
+  if (!sessionOrigin.isAutomatic(origin)) return ended;
+  for (const s of sessions.values()) {
+    if (s.origin !== origin || !s.pty || s.autoDelete === 'never') continue;
+    if (harness.deriveState(s.state, s.lastOutputAt, now).state === 'working') continue;
+    if (sessionShown(s, now) === 'blocked') continue;
+    s.autoEnded = true; s.note = 'ended: the schedule started a new run';
+    if (s.tmux) tmuxKillSession(s.tmux);
+    try { s.pty.kill(); } catch {}
+    ended.push(s.id);
+  }
+  return ended;
+}
 function fireSchedule(sched) {
   const w = workspaces.get(sched.ws) || homeWorkspace();
   const root = w ? w.root : SELF_ROOT;
@@ -2412,6 +2431,7 @@ function fireSchedule(sched) {
     // The schedule's recorded profile travels with the process it creates (profiles R8.3). Only an
     // AGENT-kind task has a PTY, which is why `profile_applies` is false for the skill-kind rows
     // below rather than the control simply being hidden.
+    endSupersededRuns('schedule:' + sched.id);
     const s = spawnSession({ name: sched.name, agent: task.agent || 'claude', ws: sched.ws,
       origin: 'schedule:' + sched.id, initialInput: prompt ? prompt + '\r' : null,
       profile: sched.profile == null ? null : sched.profile,
@@ -2502,6 +2522,8 @@ function recordConversation(s) {
 }
 function persist(s) {
   if (s.state === 'exited' && !s._txSaved) { s._txSaved = true; try { recordConversation(s); } catch {} }
+  // When it ended: the clock the sweep's keepExitedDays reads. A live session has none (a respawn clears it).
+  if (s.state === 'exited') { if (!s.exitedAt) s.exitedAt = nowISO(); } else if (s.exitedAt) delete s.exitedAt;
   else if (s.state !== 'exited') s._txSaved = false;
   // note IS persisted — a restored session must still say why it exited. `root` is persisted
   // so a session survives even if the workspace registry is lost (it re-registers its root).
@@ -2509,6 +2531,7 @@ function persist(s) {
     state: s.state, note: s.note || '', created: s.created, tmux: s.tmux || null, origin: s.origin || null };
   if (s.autoDelete) meta.autoDelete = s.autoDelete;
   if (s.autoEnded) meta.autoEnded = true;
+  if (s.exitedAt) meta.exitedAt = s.exitedAt;
   // The breakdown item a Hand to agent session is bound to, so a restart keeps the binding (pm-os-absorb Run 1).
   if (s.plan_item) meta.plan_item = s.plan_item;
   // pm-os-absorb Run 2 (R25): the SHA-256 of the agent's PMOS_SESSION token, never the token (D08). A restored session
@@ -2601,6 +2624,8 @@ function restorePersisted() {
       } else {
         s.state = 'exited';
         s.note = meta.note || 'restored after server restart — scrollback preserved; ↻ respawn to start a new process';
+        // A record from before exitedAt existed: its last write is when it last changed, the closest truthful clock.
+        if (!s.exitedAt) { try { s.exitedAt = new Date(fs.statSync(path.join(SESS_DIR, f)).mtimeMs).toISOString(); } catch {} }
       }
       const n = Number(String(meta.id).split('-')[1]); if (Number.isFinite(n) && n >= seq) seq = n + 1;
     } catch {}
@@ -2897,7 +2922,9 @@ function sweepAutomaticSessions(now = Date.now()) {
   const policy = readSessionPolicy();
   const done = { ended: [], removed: [] };
   for (const s of [...sessions.values()]) {
-    const act = sessionOrigin.decide({ ...s, shown: sessionShown(s, now) }, policy, now);
+    // `shown` is a function: decide() asks for it only for a live automatic session past its idle limit, so the sweep no
+    // longer resolves a transcript (a `ps` walk for a shell pane) for every session every 30 seconds.
+    const act = sessionOrigin.decide({ ...s, shown: () => sessionShown(s, now) }, policy, now);
     if (act === 'end' && s.pty) {
       s.autoEnded = true; s.note = 'ended: idle too long (automatic session)';
       if (s.tmux) tmuxKillSession(s.tmux);
@@ -8986,7 +9013,7 @@ if (require.main === module) {
     });
   });
 }
-module.exports = { server, online: { ONLINE, applyOnline, tunnel, publicHost }, spawnSession, removeSession, renameSession, sessions, libraryTree, readTextDoc,
+module.exports = { server, online: { ONLINE, applyOnline, tunnel, publicHost }, spawnSession, removeSession, sweepAutomaticSessions, endSupersededRuns, renameSession, sessions, libraryTree, readTextDoc,
   registerWorkspace, forgetWorkspace, workspaces, library, initiativeIndex, fsList,
   // R1 — exported so the suite can assert the CARRY-THROUGH: branchInfo separates an ordinary
   // non-repo folder from a real git fault, and the whole legibility defect was that distinction

package/workspace/test-files.json

@@ -53,6 +53,7 @@
     "learn.test.js",
     "session-flag.test.js",
     "session-origin.test.js",
+    "session-lifecycle.test.js",
     "tab-gone.test.js",
     "live-notes.test.js",
     "plan-items.test.js",
@@ -172,6 +173,7 @@
     "learn.test.js": 3,
     "session-flag.test.js": 1,
     "session-origin.test.js": 1,
+    "session-lifecycle.test.js": 2,
     "tab-gone.test.js": 1,
     "live-notes.test.js": 3,
     "pm-shell-test.js": 6,