create-pmos 0.38.7 → 0.38.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.38.7",
+  "version": "0.38.8",
   "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@8c38e46
+kernel-source: pmos@6e5901f
 assembled: 2026-10-03
 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-03T01:20:42Z"}
+generated: {by: process:create-pmos, at: "2026-10-03T03:25:22Z"}
 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-03T01:20:42Z"}
+generated: {by: process:create-pmos, at: "2026-10-03T03:25:22Z"}
 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-03T01:20:42Z"}
+generated: {by: process:create-pmos, at: "2026-10-03T03:25:22Z"}
 status: stable
 ---
 

package/workspace/README.md

@@ -46,6 +46,41 @@ npm run test:ui      # browser checks: terminal geometry, reader scroll, markdow
 ```
 </details>
 
+## 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.
+
+```
+pmos schedule add --skill gather-requirements --cadence daily --time 07:30 --max-runs 20 --until 2026-12-31
+pmos schedule add --from-session <session-id> --skill-name my-check --output "Summary,Risks" --cadence weekly --day Fri --time 16:00
+pmos schedule add --from-file notes.txt --skill-name my-check --cadence daily      # same, from a text file
+pmos schedule list [--all] · show <id|name> · run · enable · disable · rm
+pmos schedule edit <id|name> --time 08:00 --args "focus on billing" --tier deep --until none
+pmos skill list · show <name> · new --name N --description T [--body-file F] · edit <name> --file F · copy <name>
+```
+
+| To change | Use |
+|---|---|
+| Period | `--cadence daily\|weekly\|bi-weekly\|monthly\|once` with `--time HH:MM`, `--day`, `--day-of-month` or `--date` |
+| Duration | `--until YYYY-MM-DD` (that day still runs) and `--max-runs N`. When either is reached the schedule turns itself off and records why. `none` clears one. |
+| Details and input | `--name`, `--args` (up to 2000 characters, added to each run) |
+| How it runs | `--skill`, `--tier fast\|balanced\|deep`, `--profile` |
+| Structure and output | The skill: `pmos skill edit`. Its `output:` list is the contract. Built-in skills are read-only; `pmos skill copy` makes an editable one. |
+
+`--from-session` and `--from-file` write a new **user** skill from the captured work (the last 6000 characters of a session's terminal text, escape codes removed) and schedule it. Read the skill before its first run: `pmos skill show <name>`. A session's text can hold anything you typed or printed. The command never overwrites a skill and never uses a built-in's name.
+
+**A schedule fires only while the workspace server is running.** A slot missed while it is stopped is skipped, never caught up. A one-off gets a 15-minute grace window. A skill's text is never typed into a session starting with `/`, because Claude Code would read that as a slash command.
+
+## The initiative list and detail: status groups, next steps, conversations, files (`initiative-surface-batch`)
+
+**Group by status.** Above the initiative list, `group by objective | status` switches the grouping, and `active only` (in status mode) shows only live work. The groups, in this order: **Needs you** (returned at acceptance, or open items in the needs queue) · **In progress** (runs logged, nothing merged) · **Planning** (recorded, no run yet) · **Awaiting acceptance** (delivered, not accepted) · **Accepted** · **On hold** · **Closed** · **Cancelled** · **Unknown** (the history could not be read, so the status cannot be derived). "Active" is the first four. The status is **derived** from the ledgers and git, never typed into a record. On hold, closed and cancelled are the PM's: the `on hold` / `close` / `cancel` buttons in the initiative detail append one line to `lifecycle.jsonl`, and `reopen` appends another. An active search shows every match whatever its status.
+
+**Next steps to done.** The initiative detail lists everything between where it is and accepted, in order: the remaining workflow steps (blocked first), open needs items, a returned acceptance, the sessions running on it, then the PM acceptance (D12). The first is marked `next`. Every item names the fact it came from. It is read from the workflow ladder and the ledgers, not written by a model, so it never names a step the engine does not require. A stopped initiative says so and leads with `reopen`; an accepted one says nothing remains.
+
+**Conversations and files in the artifacts.** A session that belongs to an initiative — one you bound, one started on it, or one on its `initiative/<id>` branch — is listed under its artifacts as a conversation. It opens a read-only transcript tab. The transcript is saved when the session ends or is removed, so ending a session no longer erases it. It is kept in this machine's **runtime state directory** (`transcripts/`), not in the repository, and is never sent anywhere; a transcript can contain anything you typed or an agent printed, including a secret. A session on no initiative is not recorded. Below the documents, **files from git** lists what was changed for the initiative: commits on its `initiative/<id>` branch and commits whose subject names it, grouped as code, tests, documents or other, once each, only files that still exist. A failed git read is stated, never shown as an empty list.
+
+**Ending a session from the repository navigation** closes its tab. A refused end, or "asked it to end, not exited yet", leaves the tab open.
+
 ## Layout — four panels (PM-directed design, built by `workspace-four-panel`)
 The three-column layout is retired. The surface is now **four collapsible panels** under a 44px top bar and a 26px status bar, on the oklch token layer, in both themes:
 

package/workspace/bin/pmos.js

@@ -389,6 +389,13 @@ function doctor() {
   else if (cmd === 'ls' || cmd === 'list') code = await ls();
   else if (cmd === 'stop') code = await stop();
   else if (cmd === 'doctor') code = doctor();
+  else if (cmd === 'schedule' || cmd === 'skill') {
+    // Thin client of the running server's own routes (lib/schedule-cli.js): one store, one validator.
+    const live = await discover();
+    const port = live.length ? live[0].port : null;
+    code = await require('../lib/schedule-cli').run(process.argv.slice(2), {
+      say, call: async (m, p, b) => (port ? api(port, m, p, b) : null) });
+  }
   else if (cmd === 'upgrade') {
     // Escape hatch: pull the latest bundled app and force-reinstall over this global copy. Delegates
     // to the scaffolder (which owns the install path) rather than reinstalling itself in place.
@@ -400,9 +407,11 @@ function doctor() {
     if (r.error) { say('✗ could not run ' + npx + ' — ' + r.error.message); code = 1; }
     else code = r.status === null ? 1 : r.status;
   } else if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
-    say('usage: pmos [<path>|status|ls|stop|doctor|upgrade]');
+    say('usage: pmos [<path>|status|ls|stop|doctor|upgrade|schedule|skill]');
     say('  pmos          open the current repo as a workspace (starts the server if needed)');
     say('  pmos <path>   open another repo as a workspace');
+    say('  pmos schedule …  create, edit and run scheduled tasks (pmos schedule --help)');
+    say('  pmos skill …     list, read, create and edit skills');
     say('  pmos upgrade  reinstall the workspace app from the latest published create-pmos');
     code = 0;
   } else if (cmd === 'up' || cmd === 'start' || cmd === 'open') {

package/workspace/lib/initiative-files.js

@@ -0,0 +1,111 @@
+'use strict';
+/* initiative-files.js — the files changed FOR an initiative, read from git.
+ *
+ * The artifact index lists only documents that carry the initiative's name in their header or filename.
+ * A source file, a test or an unlabelled note created for the work is therefore invisible there. Git
+ * already knows: the commits on the initiative's `initiative/<id>` branch, and trunk commits whose
+ * subject names the initiative (PMOS's `type(scope): subject (<id>)` convention). This reads both.
+ *
+ * It lists a file once, only if it still exists, skips what the document index already shows, and says
+ * so when git could not be read — a failed read is never an empty list. Local git only; no network.
+ */
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const MAX_FILES = 200;
+const cache = new Map();   // root|id → {head, at, result}
+const TTL_MS = 30000;
+
+function git(root, args) {
+  const r = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8', maxBuffer: 32 * 1024 * 1024, timeout: 20000 });
+  if (r.error || r.status !== 0) return { ok: false, error: String((r.error && r.error.message) || r.stderr || 'git failed').trim().slice(0, 160) };
+  return { ok: true, out: r.stdout };
+}
+
+// An id must match as a whole token, so `overhaul-r1` does not claim `overhaul-r12`.
+function namesId(subject, id) {
+  const esc = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp('(?<![\\w.-])' + esc + '(?![\\w.-])').test(subject);
+}
+
+function groupOf(p) {
+  if (/(^|\/)(tests?|__tests__|spec)(\/|$)|\.(test|spec)\.[a-z]+$|(^|\/)[\w-]*-test\.[a-z]+$/i.test(p)) return 'tests';
+  if (/\.(md|mdx|txt|rst|html)$/i.test(p)) return 'documents';
+  if (/\.(js|mjs|cjs|ts|tsx|jsx|py|sh|rb|go|rs|java|css|sql|ya?ml|json)$/i.test(p)) return 'code';
+  return 'other';
+}
+
+function parseLog(out, keep) {
+  // records: \x1e<sha>\x1f<subject>\n<name-status lines>
+  const commits = [];
+  for (const rec of out.split('\x1e')) {
+    if (!rec.trim()) continue;
+    const nl = rec.indexOf('\n');
+    const head = nl < 0 ? rec : rec.slice(0, nl);
+    const [sha, subject] = head.split('\x1f');
+    if (!keep(subject || '')) continue;
+    const files = [];
+    for (const line of (nl < 0 ? '' : rec.slice(nl + 1)).split('\n')) {
+      const m = /^([AMRC]\d*)\t(?:.+\t)?(.+)$/.exec(line.trim());
+      if (m) files.push(m[2]);
+    }
+    commits.push({ sha, subject, files });
+  }
+  return commits;
+}
+
+/**
+ * @param {string} root      repository root
+ * @param {string} id        initiative id
+ * @param {{exclude?:Set<string>}} opts  repo-relative paths the document index already lists
+ * @returns {{ok:true, items:Array, total:number, truncated:boolean, via:string[]}|{ok:false, reason:string}}
+ */
+function filesFor(root, id, opts) {
+  const exclude = (opts && opts.exclude) || new Set();
+  if (!/^[A-Za-z0-9][\w.-]*$/.test(String(id || ''))) return { ok: false, reason: 'not an initiative id' };
+  const headR = git(root, ['rev-parse', 'HEAD']);
+  if (!headR.ok) return { ok: false, reason: 'git could not be read here — ' + headR.error };
+  const head = headR.out.trim();
+  const key = root + '|' + id;
+  const hit = cache.get(key);
+  let base = hit && hit.head === head && Date.now() - hit.at < TTL_MS ? hit.result : null;
+  if (!base) {
+    const commits = []; const via = [];
+    // 1. trunk and every other ref: commits whose subject names the initiative
+    const named = git(root, ['log', '--all', '-F', '--grep=' + id, '-n', '2000', '--no-merges', '--name-status', '--format=%x1e%H%x1f%s']);
+    if (!named.ok) return { ok: false, reason: 'git history could not be read — ' + named.error };
+    const byName = parseLog(named.out, (s) => namesId(s, id));
+    if (byName.length) { via.push('commits naming it'); commits.push(...byName); }
+    // 2. the initiative's own branch, local or remote, relative to the trunk
+    const branch = ['initiative/' + id, 'origin/initiative/' + id].find((b) => git(root, ['rev-parse', '--verify', '--quiet', b]).ok);
+    const trunk = ['origin/main', 'main', 'origin/master', 'master'].find((b) => git(root, ['rev-parse', '--verify', '--quiet', b]).ok);
+    if (branch && trunk) {
+      const own = git(root, ['log', trunk + '..' + branch, '--no-merges', '--name-status', '--format=%x1e%H%x1f%s']);
+      if (own.ok) { const rows = parseLog(own.out, () => true); if (rows.length) { via.push('its branch ' + branch); commits.push(...rows); } }
+    }
+    // What still exists: the checked-out tree plus the initiative's own branch tip, so a file that lives only on an
+    // unmerged branch is listed, and a file deleted since is not. `ls-tree` once per ref, never one spawn per file.
+    const present = new Set();
+    let treeOk = false;
+    for (const ref of ['HEAD', branch].filter(Boolean)) {
+      const t = git(root, ['ls-tree', '-r', '--name-only', '-z', ref]);
+      if (t.ok) { treeOk = true; for (const f of t.out.split('\0')) if (f) present.add(f); }
+    }
+    base = { commits, via, present: treeOk ? present : null };
+    cache.set(key, { head, at: Date.now(), result: base });
+  }
+  const seen = new Map();
+  for (const c of base.commits) for (const f of c.files) {
+    if (exclude.has(f)) continue;
+    const prev = seen.get(f);
+    if (prev) { if (!prev.shas.includes(c.sha)) prev.shas.push(c.sha); } else seen.set(f, { path: f, shas: [c.sha] });
+  }
+  const exists = (f) => { if (base.present) return base.present.has(f); try { return fs.existsSync(path.join(root, f)); } catch { return false; } };
+  const items = [...seen.values()].filter((x) => exists(x.path))
+    .map((x) => ({ path: x.path, group: groupOf(x.path), commits: x.shas.length, last: x.shas[0].slice(0, 7) }))
+    .sort((a, b) => (a.group + a.path).localeCompare(b.group + b.path));
+  return { ok: true, total: items.length, truncated: items.length > MAX_FILES, items: items.slice(0, MAX_FILES), via: base.via };
+}
+
+module.exports = { filesFor, groupOf, namesId };

package/workspace/lib/next-steps.js

@@ -0,0 +1,113 @@
+'use strict';
+/* next-steps.js — what is left between an initiative's present position and "accepted".
+ *
+ * The workflow engine already derives a ladder: each step is done, current, blocked, pending, na or
+ * unknown, and carries the action that would move it. The detail view used to show the one `next`
+ * action. This module lists the WHOLE remaining path, in order, from the facts the repository already
+ * holds — and invents nothing: every item names the fact it was read from, and a step the engine does
+ * not require never appears. Pure: no I/O, no clock, no model. A list a person can check against the
+ * ladder is the point; generated advice would be a second opinion about a derived fact.
+ *
+ * Order (PRD R4): the remaining ladder steps, then open needs items, a returned acceptance, the
+ * running sessions, and the PM acceptance. The item the engine names as `next` is marked `first`;
+ * with none named, the first item is.
+ *
+ * Input: { id, status, lifecycle:{state,reason,at}|null, accepted, returned, ladder:{ok,row}|null,
+ *          needs:[{question,kind}], sessions:[{id,name,state}] }
+ * Output: { state: 'accepted'|'stopped'|'open'|'unreadable', summary, items:[…] }
+ */
+
+const REMAINING = new Set(['blocked', 'current', 'pending', 'unknown']);
+
+const clip = (s, n = 200) => String(s == null ? '' : s).replace(/\s+/g, ' ').trim().slice(0, n);
+
+function stepItem(s) {
+  const unread = s.status === 'unknown';
+  return {
+    kind: 'step', key: s.key, status: s.status,
+    text: unread ? `${s.key} could not be read` : s.key,
+    action: clip(s.next || s.evidence || (unread ? 'the workflow engine could not decide this step' : 'no action recorded for this step')),
+    why: clip(s.evidence),
+    blocking: !!s.blocking,
+    source: 'workflow ladder' + (s.rule ? ` — ${clip(s.rule, 120)}` : ''),
+  };
+}
+
+function deriveNextSteps(input) {
+  const i = input || {};
+  const row = i.ladder && i.ladder.ok && i.ladder.row ? i.ladder.row : null;
+  const steps = row && Array.isArray(row.steps) ? row.steps : [];
+  const remaining = steps.filter((s) => REMAINING.has(s.status));
+  // blocked first (the engine's own choice of `next`), the rest in ladder order
+  const ordered = [...remaining.filter((s) => s.status === 'blocked'), ...remaining.filter((s) => s.status !== 'blocked')];
+  const live = (i.sessions || []).filter((s) => s && s.state !== 'exited');
+
+  if (i.accepted) {
+    return { state: 'accepted', summary: 'Accepted by the PM — nothing remains.', items: [] };
+  }
+
+  const stopped = i.lifecycle && i.lifecycle.state && i.lifecycle.state !== 'active' ? i.lifecycle : null;
+  if (stopped) {
+    const items = [{
+      kind: 'reopen', key: 'reopen', status: 'pending',
+      text: `Reopen — it is ${stopped.state}`,
+      action: 'Reopen it to put it back on the board and have its steps gate again. Nothing below is required while it is stopped.',
+      why: clip(stopped.reason), source: 'lifecycle.jsonl (D70)',
+    }, ...ordered.map((s) => ({ ...stepItem(s), held: true }))];
+    items.forEach((it, n) => { it.n = n + 1; it.first = n === 0; });
+    return {
+      state: 'stopped',
+      summary: `Stopped (${stopped.state})${stopped.reason ? ' — ' + clip(stopped.reason, 120) : ''}. It is off the board and not gating. Reopen to continue; the steps it would then owe are listed after.`,
+      items,
+    };
+  }
+
+  if (!row) {
+    const why = i.ladder && i.ladder.error ? clip(i.ladder.error, 160) : 'no initiative record, so no loop position can be derived';
+    return { state: 'unreadable', summary: `No next steps can be listed — ${why}.`, items: [] };
+  }
+
+  // The ladder's own `accept` step is the acceptance: it goes last, after everything the PM would want settled first.
+  const acceptStep = ordered.find((s) => s.key === 'accept') || null;
+  const items = ordered.filter((s) => s.key !== 'accept').map(stepItem);
+  const hasAcceptStep = steps.some((s) => s.key === 'accept');
+  for (const n of (i.needs || [])) {
+    items.push({
+      kind: 'needs', key: 'needs', status: 'pending', text: clip(n.question || '(unstated)', 160),
+      action: 'Answer or clear this open item.', why: '', source: 'needs queue',
+    });
+  }
+  if (i.returned) {
+    items.push({
+      kind: 'returned', key: 'returned', status: 'blocked', text: 'The PM returned this at the Acceptance Gate',
+      action: 'Address the return, then request acceptance again.', why: '', source: 'acceptances.jsonl',
+    });
+  }
+  for (const s of live) {
+    items.push({
+      kind: 'session', key: 'session', status: 'current', text: `Session “${clip(s.name, 60)}” is running on it`,
+      action: 'Let it finish, or end it before accepting.', why: '', source: 'live sessions',
+    });
+  }
+  if (acceptStep) items.push({ ...stepItem(acceptStep), kind: 'accept', text: 'PM Acceptance' });
+  else if (!hasAcceptStep) {
+    items.push({
+      kind: 'accept', key: 'accept', status: 'pending', text: 'PM Acceptance',
+      action: 'The PM names one thing verified by hand, then records the acceptance (D12). It is the PM’s and cannot be delegated.',
+      why: '', source: 'Acceptance Gate (D12)',
+    });
+  }
+
+  const engineNext = row.next && row.next.step ? row.next.step : null;
+  const firstIdx = engineNext ? Math.max(0, items.findIndex((x) => x.kind === 'step' && x.key === engineNext)) : 0;
+  items.forEach((it, n) => { it.n = n + 1; it.first = n === firstIdx; });
+  if (!items.length) return { state: 'open', summary: 'No step is outstanding — the ladder shows every required step done. Acceptance is the PM’s.', items: [] };
+  const blockedN = items.filter((x) => x.status === 'blocked').length;
+  return {
+    state: 'open',
+    summary: `${items.length} thing${items.length === 1 ? '' : 's'} left to reach acceptance${blockedN ? `, ${blockedN} blocked` : ''}. Start with step ${firstIdx + 1}.`,
+    items,
+  };
+}
+
+module.exports = { deriveNextSteps };

package/workspace/lib/prompt-input.js

@@ -0,0 +1,18 @@
+'use strict';
+/* prompt-input.js — what the workspace types into an agent session as its first input.
+ *
+ * Claude Code reads input that begins with `/` as a slash command. Every agent skill body opens
+ * `/<skill-name> — …`, so a scheduled run of `skill-discover` was answered "Unknown command:
+ * /skill-discover" and the session did no work, while the schedule recorded `started`. The skill
+ * files keep their wording; the fix is here, at the one point where a body becomes typed input.
+ * A text that does not begin with `/` is returned unchanged. Pure: no I/O.
+ */
+const LEADING_SLASH = /^\s*\//;
+const PREFIX = 'Follow this skill: ';
+
+function safeFirstInput(text) {
+  const s = String(text == null ? '' : text);
+  return LEADING_SLASH.test(s) ? PREFIX + s.replace(/^\s+/, '') : s;
+}
+
+module.exports = { safeFirstInput, PREFIX };

package/workspace/lib/schedule-cli.js

@@ -0,0 +1,256 @@
+'use strict';
+/* schedule-cli.js — `pmos schedule …` and `pmos skill …`: the terminal face of the scheduler.
+ *
+ * Every command is a thin client of the running workspace server's own routes, so the terminal and the
+ * workspace can never disagree about a schedule: one store, one validator, one fire path. Nothing here
+ * writes a file itself. A refused value is reported with the allowed values and nothing is changed,
+ * because the server checks before it writes. With no server running the command says so and exits 1.
+ *
+ *   pmos schedule list [--all]
+ *   pmos schedule show <id|name>
+ *   pmos schedule add --skill S --cadence C [fields]       fields: --name --day --day-of-month --time --date
+ *   pmos schedule add --from-session ID|--from-file PATH --skill-name N [--output "A,B"] [--description T] [fields]
+ *   pmos schedule edit <id|name> [fields] [--skill S]      fields also: --until --max-runs  ('none' clears one)
+ *   pmos schedule run|enable|disable|rm <id|name>
+ *   pmos skill list | show <name> | new --name N --description T [--output "A,B"] [--body-file F]
+ *   pmos skill edit <name> --file F | copy <name>
+ *
+ * Pure of sockets: the caller passes `call` (an HTTP client) and `say`, so the whole thing is testable.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const FLAG_FIELDS = {
+  name: 'name', skill: 'skill', cadence: 'cadence', day: 'day', 'day-of-month': 'dayOfMonth', time: 'time',
+  date: 'date', args: 'args', tier: 'tier', profile: 'profile', until: 'until', 'max-runs': 'max_runs',
+};
+const BOOLEAN_FLAGS = new Set(['all', 'help']);
+
+function parseArgs(argv) {
+  const pos = []; const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      const key = eq > 0 ? a.slice(2, eq) : a.slice(2);
+      if (BOOLEAN_FLAGS.has(key)) { flags[key] = true; continue; }
+      if (eq > 0) { flags[key] = a.slice(eq + 1); continue; }
+      const next = argv[i + 1];
+      if (next === undefined || (next.startsWith('--') && next.length > 2)) { flags[key] = ''; continue; }
+      flags[key] = next; i++;
+    } else pos.push(a);
+  }
+  return { pos, flags };
+}
+
+// The fields a command sets, as the server names them. 'none' clears until/max_runs/tier/profile/args.
+function fieldsFrom(flags) {
+  const out = {};
+  for (const [flag, key] of Object.entries(FLAG_FIELDS)) {
+    if (!(flag in flags)) continue;
+    const v = flags[flag];
+    const clearable = ['until', 'max_runs', 'tier', 'profile', 'args'].includes(key);
+    out[key] = clearable && (v === 'none' || v === '') ? null : v;
+  }
+  if (out.max_runs != null && /^\d+$/.test(String(out.max_runs))) out.max_runs = +out.max_runs;
+  if (out.dayOfMonth != null && /^\d+$/.test(String(out.dayOfMonth))) out.dayOfMonth = +out.dayOfMonth;
+  return out;
+}
+
+function gitRoot(dir) {
+  try { return execFileSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); }
+  catch { return path.resolve(dir); }
+}
+
+function describe(s) {
+  const when = s.cadence === 'once' ? `once, ${s.date || '?'} at ${s.time || '09:00'}`
+    : s.cadence === 'weekly' ? `every ${s.day || 'Mon'} at ${s.time}`
+      : s.cadence === 'bi-weekly' ? `every other ${s.day || 'Mon'} at ${s.time}`
+        : s.cadence === 'monthly' ? `monthly on day ${s.dayOfMonth || 1} at ${s.time}`
+          : `every day at ${s.time}`;
+  return when;
+}
+
+function showLines(s) {
+  const lines = [
+    `${s.name}  (${s.id})`,
+    `  skill     ${s.skill}`,
+    `  when      ${describe(s)}  ·  ${s.enabled ? 'enabled' : 'disabled'}${s.endedReason ? ' — ended: ' + s.endedReason : ''}`,
+    `  next run  ${s.enabled && s.next ? new Date(s.next).toLocaleString() : '—'}`,
+    `  last run  ${s.lastRun ? new Date(s.lastRun).toLocaleString() + '  [' + (s.lastStatus || '?') + ']' : 'never'}`,
+    `  runs      ${+s.runs || 0}${s.max_runs ? ' of ' + s.max_runs : ''}${s.until ? '  ·  until ' + s.until + ' (that day included)' : ''}`,
+  ];
+  if (s.args) lines.push(`  args      ${s.args}`);
+  if (s.tier) lines.push(`  tier      ${s.tier}`);
+  if (s.profile) lines.push(`  profile   ${s.profile}`);
+  lines.push('  note      this schedule fires only while the workspace server is running; a slot missed while it is stopped is skipped, not caught up.');
+  return lines;
+}
+
+async function run(argv, { call, say, cwd = process.cwd() }) {
+  const [group, verb, ...rest] = argv;
+  const { pos, flags } = parseArgs(rest);
+  if (!group || flags.help || group === 'help') { usage(say); return group ? 0 : 1; }
+  if (!['schedule', 'skill'].includes(group)) { say(`✗ unknown command "${group}" — use schedule or skill`); return 1; }
+
+  // The server first: with none running, every command is the same one honest sentence.
+  const probe = await call('GET', '/api/schedules?all=1');
+  if (!probe) { say('✗ the workspace server is not running — start it with: pmos'); return 1; }
+
+  const fail = (msg) => { say('✗ ' + msg); return 1; };
+  const refused = (r, what) => fail(`${what} refused — ${(r && r.error) || 'the server did not answer'}. Nothing was changed.`);
+
+  async function repoWs() {
+    const root = gitRoot(flags.repo ? path.resolve(flags.repo) : cwd);
+    const wl = await call('GET', '/api/workspaces');
+    const hit = ((wl && wl.workspaces) || []).find((w) => path.resolve(w.root) === root);
+    return hit ? { id: hit.id, name: hit.name, root } : { missing: root };
+  }
+  async function pick(ref) {
+    if (!ref) return { err: 'say which schedule: its id or its name (pmos schedule list)' };
+    const all = ((await call('GET', '/api/schedules?all=1')) || {}).schedules || [];
+    const byId = all.filter((s) => s.id === ref || s.id.startsWith(ref));
+    const hits = byId.length ? byId : all.filter((s) => s.name.toLowerCase() === ref.toLowerCase());
+    if (hits.length === 1) return { s: hits[0] };
+    return { err: hits.length ? `"${ref}" matches ${hits.length} schedules — use the id` : `no schedule "${ref}" (pmos schedule list)` };
+  }
+
+  if (group === 'schedule') {
+    if (verb === 'list' || !verb) {
+      let list = probe.schedules || [];
+      if (!flags.all) {
+        const w = await repoWs();
+        if (!w.missing) list = list.filter((s) => s.ws === w.id);
+      }
+      if (!list.length) { say('no scheduled tasks here (pmos schedule add …, or --all for every repository)'); return 0; }
+      for (const s of list) say(`${s.enabled ? '●' : '○'} ${s.id}  ${s.name}  ·  ${s.skill}  ·  ${describe(s)}${s.endedReason ? '  ·  ended: ' + s.endedReason : ''}`);
+      return 0;
+    }
+    if (verb === 'show') {
+      const { s, err } = await pick(pos[0]); if (err) return fail(err);
+      showLines(s).forEach((l) => say(l)); return 0;
+    }
+    if (verb === 'add') {
+      const w = await repoWs();
+      if (w.missing) return fail(`${w.missing} is not a registered workspace — run \`pmos\` in it once, or pass --repo of one that is`);
+      const f = fieldsFrom(flags);
+      let created = null;
+      if (flags['from-session'] || flags['from-file']) {
+        const skillName = flags['skill-name'];
+        if (!skillName) return fail('--from-session and --from-file need --skill-name, the name for the new skill');
+        let work = '';
+        if (flags['from-file']) { try { work = fs.readFileSync(path.resolve(cwd, flags['from-file']), 'utf8'); } catch { return fail(`cannot read ${flags['from-file']}`); } }
+        else {
+          const t = await call('GET', '/api/sessions/transcript?id=' + encodeURIComponent(flags['from-session']) + '&max=6000');
+          if (!t || !t.ok) return refused(t, 'reading the session');
+          work = t.text;
+        }
+        if (!work.trim()) return fail('the source is empty — there is nothing to turn into a skill');
+        const out = flags.output || '';
+        const sk = await call('POST', '/api/skills', { name: skillName, description: flags.description || `Repeat: ${skillName}`, output: out, work, ws: w.id });
+        if (!sk || !sk.ok) return refused(sk, 'creating the skill');
+        created = sk.skill.id;
+        f.skill = created;
+        say(`✓ skill "${created}" written (user skill). Review it: pmos skill show ${created}`);
+      }
+      if (!f.skill) return fail('say which skill: --skill <name> (pmos skill list), or --from-session / --from-file');
+      if (!f.cadence) return fail('say when: --cadence daily|weekly|bi-weekly|monthly|once (with --time HH:MM, --day, --day-of-month or --date)');
+      f.name = f.name || (created ? `${created}` : f.skill);
+      f.task = f.skill;
+      const r = await call('POST', '/api/schedules', { ...f, ws: w.id });
+      if (!r || !r.ok) return refused(r, 'adding the schedule');
+      const s = r.schedule;
+      say(`✓ scheduled "${s.name}" (${s.id}) in ${w.name}: ${describe(s)}`);
+      say(`  next run ${s.nextRun ? new Date(s.nextRun).toLocaleString() : '—'} — fires only while the workspace server is running`);
+      return 0;
+    }
+    if (verb === 'edit') {
+      const { s, err } = await pick(pos[0]); if (err) return fail(err);
+      const f = fieldsFrom(flags);
+      if (f.skill) f.task = f.skill;
+      if (!Object.keys(f).length) return fail('nothing to change — pass a field, e.g. --time 08:00 or --max-runs 10');
+      const r = await call('POST', '/api/schedules/update', { id: s.id, ...f });
+      if (!r || !r.ok) return refused(r, 'the edit');
+      say(`✓ saved "${r.schedule.name}": ${describe(r.schedule)}`);
+      return 0;
+    }
+    if (verb === 'enable' || verb === 'disable') {
+      const { s, err } = await pick(pos[0]); if (err) return fail(err);
+      const r = await call('POST', '/api/schedules/update', { id: s.id, enabled: verb === 'enable' });
+      if (!r || !r.ok) return refused(r, verb);
+      say(`✓ "${r.schedule.name}" is ${r.schedule.enabled ? 'enabled' : 'disabled'}`);
+      return 0;
+    }
+    if (verb === 'run') {
+      const { s, err } = await pick(pos[0]); if (err) return fail(err);
+      const r = await call('POST', '/api/schedules/run', { id: s.id });
+      const res = r && r.result;
+      if (!r || !r.ok || !res || res.ok === false) return fail(`"${s.name}" did not start — ${(res && res.reason) || (r && r.error) || 'no answer'}`);
+      say(res.sessionId ? `✓ started session ${res.sessionId} for "${s.name}"` : `✓ ran "${s.name}"`);
+      return 0;
+    }
+    if (verb === 'rm' || verb === 'remove' || verb === 'delete') {
+      const { s, err } = await pick(pos[0]); if (err) return fail(err);
+      const r = await call('POST', '/api/schedules/delete', { id: s.id });
+      if (!r || !r.ok) return refused(r, 'removing');
+      say(`✓ removed "${s.name}"`);
+      return 0;
+    }
+    return fail(`unknown schedule command "${verb}" — list, show, add, edit, run, enable, disable, rm`);
+  }
+
+  // skill
+  const w = await repoWs();
+  const wsq = w.missing ? '' : '&ws=' + encodeURIComponent(w.id);
+  if (verb === 'list' || !verb) {
+    const r = await call('GET', '/api/skills' + (wsq ? '?' + wsq.slice(1) : ''));
+    for (const k of (r && r.skills) || []) say(`${k.source === 'user' ? '✎' : '·'} ${k.id}  [${k.source}]  ${k.description}`);
+    return 0;
+  }
+  if (verb === 'show') {
+    if (!pos[0]) return fail('say which skill: pmos skill show <name>');
+    const r = await call('GET', '/api/skills/read?id=' + encodeURIComponent(pos[0]) + wsq);
+    if (!r || !r.ok) return refused(r, 'reading the skill');
+    say(`# ${r.id} — ${r.source}${r.editable ? ' (yours — edit with: pmos skill edit ' + r.id + ' --file <path>)' : ' (read-only — pmos skill copy ' + r.id + ')'}`);
+    say(r.text);
+    return 0;
+  }
+  if (verb === 'new') {
+    if (!flags.name) return fail('--name is required');
+    let body = '';
+    if (flags['body-file']) { try { body = fs.readFileSync(path.resolve(cwd, flags['body-file']), 'utf8'); } catch { return fail(`cannot read ${flags['body-file']}`); } }
+    const r = await call('POST', '/api/skills', { name: flags.name, description: flags.description || '', output: flags.output || '', body, ws: w.missing ? undefined : w.id });
+    if (!r || !r.ok) return refused(r, 'creating the skill');
+    say(`✓ skill "${r.skill.id}" written. Edit it: pmos skill edit ${r.skill.id} --file <path>`);
+    return 0;
+  }
+  if (verb === 'edit') {
+    if (!pos[0] || !flags.file) return fail('usage: pmos skill edit <name> --file <path>   (the whole new skill text; "-" reads stdin)');
+    let text;
+    try { text = flags.file === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(path.resolve(cwd, flags.file), 'utf8'); } catch { return fail(`cannot read ${flags.file}`); }
+    const r = await call('POST', '/api/skills/save', { id: pos[0], text });
+    if (!r || !r.ok) return refused(r, 'saving the skill');
+    say(`✓ saved "${r.id}"`);
+    return 0;
+  }
+  if (verb === 'copy') {
+    if (!pos[0]) return fail('say which skill: pmos skill copy <name>');
+    const r = await call('POST', '/api/skills/copy', { id: pos[0], ws: w.missing ? undefined : w.id });
+    if (!r || !r.ok) return refused(r, 'copying');
+    say(`✓ copied as "${r.id}" — yours to edit`);
+    return 0;
+  }
+  return fail(`unknown skill command "${verb}" — list, show, new, edit, copy`);
+}
+
+function usage(say) {
+  say('usage: pmos schedule <list|show|add|edit|run|enable|disable|rm> …   |   pmos skill <list|show|new|edit|copy> …');
+  say('  pmos schedule add --skill gather-requirements --cadence daily --time 07:30 [--until 2026-12-31] [--max-runs 20]');
+  say('  pmos schedule add --from-session <id> --skill-name my-check --cadence weekly --day Fri --time 16:00');
+  say('  pmos schedule edit <id|name> --time 08:00 --args "focus on the billing initiative" --tier deep --until none');
+  say('  fields: --name --skill --cadence --day --day-of-month --time --date --args --tier --profile --until --max-runs --repo');
+  say('  schedules fire only while the workspace server is running.');
+}
+
+module.exports = { run, parseArgs, fieldsFrom };