create-pmos 0.38.6 → 0.38.8

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 };

package/workspace/lib/schedule-logic.js

@@ -86,10 +86,25 @@ function nextSlot(schedule, now) {
 }
 function addDays(d, n) { const x = new Date(d); x.setDate(x.getDate() + n); return x; }
 
+// R5 — an optional end. A schedule ends when it has run `max_runs` times or when the day after `until` begins
+// (the `until` day itself still runs). No `until` and no `max_runs` means it never ends on its own.
+function endOfDay(dateStr) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(String(dateStr || ''));
+  return m ? new Date(+m[1], +m[2] - 1, +m[3] + 1, 0, 0, 0, 0) : null;
+}
+function finishReason(schedule, now = new Date()) {
+  if (!schedule) return null;
+  const max = +schedule.max_runs;
+  if (max > 0 && (+schedule.runs || 0) >= max) return `max_runs reached (${max} run${max === 1 ? '' : 's'})`;
+  const end = endOfDay(schedule.until);
+  if (end && now >= end) return `until ${schedule.until} has passed`;
+  return null;
+}
 // Is the schedule due to fire at `now`? Enabled + a slot in (lastRun, now]. For bi-weekly, also
 // require ≥ 13 days since lastRun (weekly slots, fired every other week).
 function isDue(schedule, now = new Date()) {
   if (!schedule || !schedule.enabled) return false;
+  if (finishReason(schedule, now)) return false;
   const slot = lastSlot(schedule, now);
   if (!slot) return false;
   const last = schedule.lastRun ? new Date(schedule.lastRun) : null;
@@ -130,6 +145,11 @@ function normalizeSchedule(input) {
   if (!s.name || !String(s.name).trim()) return { ok: false, error: 'name is required' };
   if (!CADENCES.includes(s.cadence)) return { ok: false, error: 'invalid cadence' };
   if (!s.skill || !String(s.skill).trim()) return { ok: false, error: 'a skill-backed task is required' };
+  if (s.until != null && s.until !== '') {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(String(s.until)) || !endOfDay(s.until) || Number.isNaN(endOfDay(s.until).getTime())) return { ok: false, error: 'until must be a date, YYYY-MM-DD' };
+    if (endOfDay(s.until) <= new Date()) return { ok: false, error: 'until is already in the past — the schedule would never run' };
+  }
+  if (s.max_runs != null && s.max_runs !== '' && !(Number.isInteger(+s.max_runs) && +s.max_runs >= 1 && +s.max_runs <= 10000)) return { ok: false, error: 'max_runs must be a whole number from 1 to 10000' };
   if (s.cadence === 'once') {
     if (!/^\d{4}-\d{2}-\d{2}$/.test(String(s.date || ''))) return { ok: false, error: 'a one-off needs a date (YYYY-MM-DD)' };
     const slot = onceSlot({ date: s.date, time: s.time });
@@ -153,9 +173,11 @@ function normalizeSchedule(input) {
       task: s.task || s.skill,
       skill: String(s.skill).trim(),
       enabled: s.enabled !== false,
+      ...(s.until ? { until: String(s.until) } : {}),
+      ...(s.max_runs ? { max_runs: Math.floor(+s.max_runs) } : {}),
     },
   };
 }
 function parseTimeStr(t) { const { h, m } = parseTime(t); return `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}`; }
 
-module.exports = { CADENCES, isMissed, ONCE_GRACE_MS, isDue, nextRun, humanCadence, normalizeSchedule, lastSlot, nextSlot };
+module.exports = { finishReason, endOfDay, CADENCES, isMissed, ONCE_GRACE_MS, isDue, nextRun, humanCadence, normalizeSchedule, lastSlot, nextSlot };

package/workspace/lib/skill-store.js

@@ -266,7 +266,7 @@ function retargetFiling(text, filing) {
 // Scaffold a well-formed user skill file from the New Skill flow's fields. Returns { ok, slug, content }
 // or { ok:false, error }. User skills default to run:agent — a user-authored skill reasons through a
 // claude session (the existing agent path); the deterministic fast-path is reserved for the built-ins.
-function scaffoldSkill({ name, description, output, body, filing } = {}) {
+function scaffoldSkill({ name, description, output, body, filing, work } = {}) {
   const slug = slugify(name);
   if (!NAME_RE.test(slug)) return { ok: false, error: 'name must be a short slug (letters, digits, hyphens)' };
   const label = titleCase(name) || slug;
@@ -276,7 +276,7 @@ function scaffoldSkill({ name, description, output, body, filing } = {}) {
   if (!out.length) out = ['Summary', 'Findings', 'Next steps'];   // always a valid contract
   // A hand-written body is retargeted too: a PM pasting the old contract text in gets a skill that
   // files where the console reads, not one that quietly writes into a directory nobody opens.
-  const proc = retargetFiling(String(body || '').trim(), filing) || defaultBody(label, desc, out, slug, filing);
+  const proc = retargetFiling(String(body || '').trim(), filing) || defaultBody(label, desc, out, slug, filing, work ? String(work).slice(0, 8000) : null);
   const content = [
     '---',
     `name: ${slug}`,
@@ -306,7 +306,7 @@ function scaffoldSkill({ name, description, output, body, filing } = {}) {
 // suite could not reach it. A scaffold that still said "workspace/state/deliverables/" would send
 // every scheduled agent's report to a directory the console never reads: a silent, permanent
 // no-show in the needs-you queue. The defaults keep this module usable standalone.
-function defaultBody(label, desc, out, slug, filing) {
+function defaultBody(label, desc, out, slug, filing, work) {
   const id = slug || slugify(label) || 'run';
   const deliverables = (filing && filing.deliverables) || 'workspace/state/deliverables';
   const needs = (filing && filing.needs) || 'workspace/state/needs.json';
@@ -318,9 +318,17 @@ function defaultBody(label, desc, out, slug, filing) {
     '',
     'Procedure — run the numbered steps in order; each ends on a checkable done-condition:',
     '',
+    ...(work ? [
+      '1. Repeat the work below. It was captured from an earlier terminal session by the PM: do the same job again,',
+      "   with today's dates and this repository's current files. Do not repeat one-off details (old names, old dates, old errors).",
+      '   Done when: the same kind of result exists for today, each statement traceable to a real source.',
+      '   Captured work:',
+      ...String(work).split('\n').map((l) => '   | ' + l),
+    ] : [
     "1. Gather inputs from this repo's own local sources — name the exact commands/paths the run",
     '   depends on (e.g. `git log`, `gh pr view <n> --json title,body`, a file under `planning/`).',
     '   Done when: every input the sections below need is in hand, each traceable to a real source.',
+    ]),
     '2. Produce each required section from those inputs, in the exact order of the output contract.',
     '   An empty section is the literal line "None this period." — never a dropped heading, never invented content.',
     '   Done when: every contract section is filled or explicitly "None this period.".',