create-pmos 0.96.0 → 0.97.0

package/workspace/server.js

@@ -130,6 +130,7 @@ const sessionState = require('./lib/session-state');   // the cadence×turn join
 // none of their logic is re-derived here, because a second implementation of "what does this
 // record declare" is how two surfaces come to disagree about the same file.
 const repoScan = require('./lib/repo-scan');           // scanRepo(root) — pure, cannot write (ingest R3)
+const claudeFlags = require('./lib/claude-flags');     // list() / resolve(requested, agent) — the launch-flag allow-list
 const profilesLib = require('./lib/profiles');         // readProfiles(homeDir) / profileLine(profile, read)
 const focus = require('./lib/focus');                  // buildFocus(input) → FocusView (cross-product)
 const handoff = require('./lib/handoff');              // readLinks(parsedFrontmatterObject) — never a path
@@ -712,6 +713,10 @@ function announceModel(s) {
   if (!s.model || s.model.state === 'not-asked') return;
   appendBuf(s, `\x1b[38;5;244mpmos: ${modelLib.line(s.model)}\x1b[0m\r\n`);
 }
+function announceLaunchFlags(s) {
+  if (!Array.isArray(s.launchFlags) || !s.launchFlags.length) return;
+  appendBuf(s, `\x1b[38;5;244mpmos: ${claudeFlags.line(s.launchFlags)}\x1b[0m\r\n`);
+}
 function announceStateHealth(s) {
   const h = stateHealthNow();
   if (h.ok) return;
@@ -2507,6 +2512,7 @@ function persist(s) {
   // D75 — what model was asked for and what was APPLIED. Same `in`-guard as the profile: a record from before
   // routing existed restores as 'not recorded', and writing a key for the past would be a lie about it.
   if ('model' in s) { meta.model = s.model; meta.modelAsk = s.modelAsk || null; }
+  if ('launchFlags' in s) meta.launchFlags = s.launchFlags;
   // WHAT THIS SESSION IS FOR, and where that came from. Same `in`-guard as `profile` above and for
   // the same reason: every session running before this field existed has no attribution, and
   // writing a key for it would turn "we were never told" into "it belongs to nothing". Both keys
@@ -3290,7 +3296,7 @@ function sendToSession(id, text) {
   try { firstInput.deliver(s, safeFirstInput(t) + '\r'); return true; } catch { return false; }
 }
 
-function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile, initiative, modelAsk, planItem, workType, autoDelete }) {
+function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile, initiative, modelAsk, planItem, workType, autoDelete, launchFlags }) {
   const id = nextSessionId();
   /* pm-os-absorb Run 1 — every AGENT session gets a token, `<id>.<8 hex>`, in its environment as PMOS_SESSION, and
    * PMOS_BIN, this workspace's own bin/pmos.js. `pmos item` run inside it is then attributed `agent:<token>` (the token
@@ -3355,7 +3361,14 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile, ini
   base.model = { state: mres.state, tier: mres.tier || null, model: mres.model || null, effort: mres.effort || null,
     decidedBy: mres.decidedBy || null, why: mres.why || null };
   base.modelAsk = modelAsk || null;
-  const launchArgs = mres.state === 'applied' ? mres.args : [];
+  /* LAUNCH FLAGS (workspace-launch-flags). Checked against the generated claude flag list, and refused like a model
+   * choice: a flag that cannot be honoured starts nothing. The tokens go AFTER the model's, and a flag the model
+   * chips already own is refused by the list itself, so the two never both speak. */
+  const fres = claudeFlags.resolve(launchFlags, agent);
+  if (!fres.ok) return exitedSession(base, workdir, `launch flag refused — ${fres.error}`);
+  if (launchFlags !== undefined) base.launchFlags = fres.applied;
+  const argv = [...(mres.state === 'applied' ? mres.args : []), ...fres.args];
+  const launchArgs = argv;
   if (mres.tier) {
     const mc = modelLib.core();
     if (mc.ok) mc.core.logDecision(root, { kind: 'spawn', session: id, agent, tier: mres.tier, model: mres.model, effort: mres.effort,
@@ -3396,6 +3409,8 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile, ini
     // the OVERLAY, not the merged env — the merged env is for the direct-PTY path below, which
     // really does spawn the process itself. See createTmuxSession for why the two differ.
     // The launch args are plain tokens by construction (pmos-model's strict pattern), so joining them is safe.
+    // tmux hands the command to a shell, so every token is quoted; the direct PTY below passes the raw argv
+    const launchArgs = argv.map(claudeFlags.shellQuote);
     if (!createTmuxSession(tname, launchArgs.length ? [cmd, ...launchArgs].join(' ') : cmd, workdir, 80, 24, itemEnv, sessionFlag.tmuxOverlay(profileOverlay(pres.profile)))) {
       const why = `could not start a tmux session for '${cmd}'. Run \`npm run doctor\` in workspace/.`;
       s.state = 'exited'; s.tmux = null; s.note = why;
@@ -3405,6 +3420,7 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile, ini
     announceStateHealth(s);   // the unmigrated notice comes FIRST — it explains an empty skills list
     announceTree(s);   // before attach, so the advisory is the first line of the pane's record
     announceModel(s);
+    announceLaunchFlags(s);
     attachPty(s);
     feed(s);
     persist(s); pushSessions(); pushWorkspaces(); return s;
@@ -3460,7 +3476,7 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile, ini
 // A FAILED git operation in a real repo must never spawn a session on the wrong branch (rubric
 // hard floor): we return {ok:false} and spawn nothing. Kept as its own function so the
 // git-then-maybe-spawn contract is unit-testable without a WS client.
-function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch, isolate, profile, initiative, modelAsk, origin, initialInput, planItem, workType }) {
+function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch, isolate, profile, initiative, modelAsk, origin, initialInput, planItem, workType, launchFlags }) {
   const w = getWs(ws);
   if (!w) return { ok: false, error: 'no workspace' };
   // The profile is checked BEFORE any git operation. A composer that picked a profile PMOS cannot
@@ -3471,6 +3487,9 @@ function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch, isolate,
   // The model choice is checked on the same terms (D75): a refused choice starts nothing, and leaves no branch moved.
   const mchk = modelLib.resolveForSpawn(w.root, agent || 'shell', modelAsk);
   if (!mchk.ok) return { ok: false, error: `model choice refused — ${mchk.error}` };
+  // …and so is a launch flag the list does not accept (workspace-launch-flags): before any branch moves.
+  const fchk = claudeFlags.resolve(launchFlags, agent || 'shell');
+  if (!fchk.ok) return { ok: false, error: `launch flag refused — ${fchk.error}` };
   let targetWs = w.id;
   let notice = null;
   // Isolation exists to protect OTHER sessions. Alone in the working TREE there are none to
@@ -3507,7 +3526,7 @@ function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch, isolate,
       broadcast({ t: 'branch', ws: w.id, ...gitInfo.branchInfo(w.root) });   // let every client refresh the chip
     }
   }
-  const s = spawnSession({ name, agent: agent || 'shell', cwd, ws: targetWs, profile: pres.id, initiative, modelAsk, origin, initialInput, planItem, workType });
+  const s = spawnSession({ name, agent: agent || 'shell', cwd, ws: targetWs, profile: pres.id, initiative, modelAsk, origin, initialInput, planItem, workType, launchFlags });
   // The co-tenancy fact, on the ordinary path too. Note where this sits: OUTSIDE the `if (branch)`
   // block above. The isolate default already computes that other sessions would be disturbed — and
   // then the whole git block is skipped when no branch was picked, which is the common path and the
@@ -3610,7 +3629,7 @@ function startPreview({ initiative, repoKey, ws }) {
 // One click. Resolves the policy, then hands the SAME seam spawnWithBranch already exposes the
 // branch/isolate decision it made — so the inherited hard floor (a failed git operation spawns
 // nothing) is enforced in exactly one place and is not re-implemented here.
-function startWork({ initiative, repoKey, ws, agent, name, profile, origin, initialInput, planItem, workType, modelAsk }) {
+function startWork({ initiative, repoKey, ws, agent, name, profile, origin, initialInput, planItem, workType, modelAsk, launchFlags }) {
   const key = repoKeyFor({ repoKey, ws });
   if (!key) return { ok: false, error: 'no repository selected' };
   const trees = treesOfRepo(key);
@@ -3639,7 +3658,7 @@ function startWork({ initiative, repoKey, ws, agent, name, profile, origin, init
     // Hand to agent (pm-os-absorb Run 1): only /api/plan-items/handoff/go passes it.
     planItem,
     // 0.55.1 — the dock's new-session sheet: the type of work, and a skill's model ask.
-    workType, modelAsk: modelAsk || null,
+    workType, modelAsk: modelAsk || null, launchFlags,
   });
   if (!r.ok) return r;
   return { ok: true, session: r.session, notice: r.notice || plan.why, plan: plan.plan };
@@ -6091,6 +6110,55 @@ async function handleRequest(req, res) {
       error: read.error || null,
     });
   }
+  // Every flag `claude --help` lists, with whether the form may offer it (workspace-launch-flags). A static file.
+  if (p === '/api/claude-flags' && req.method === 'GET') return json(res, claudeFlags.list());
+  /* Create one descriptor from the Settings form (workspace-launch-flags). It writes ONE file, ~/.claude/profiles/<id>.json,
+   * and only when none by that name exists: PMOS never overwrites a descriptor the PM keeps. The file is read back through
+   * the same reader every other surface uses, so a descriptor this route wrote that the reader would refuse is removed
+   * again and the refusal is returned. The answer is profileWire(): the variable NAMES, never the values. */
+  if (p === '/api/profiles/create' && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const bad = (error) => json(res, { ok: false, error }, 400);
+    const id = typeof body.id === 'string' ? body.id.trim() : '';
+    if (!/^[a-z0-9][a-z0-9._-]{0,63}$/.test(id)) return bad('the id must be lowercase letters, digits, dots, dashes or underscores, and at most 64 characters — it is the file name');
+    const desc = { id };
+    if (body.label != null && String(body.label).trim()) desc.label = String(body.label).trim().slice(0, 80);
+    if (body.account != null && String(body.account).trim()) desc.account = String(body.account).trim().slice(0, 200);
+    if (body.mcp != null) {
+      if (!Array.isArray(body.mcp) || body.mcp.some((x) => typeof x !== 'string' || !/^[A-Za-z0-9][\w.-]{0,63}$/.test(x))) return bad('mcp must be a list of server names (letters, digits, dots, dashes, underscores)');
+      if (body.mcp.length) desc.mcp = body.mcp.slice(0, 50);
+    }
+    if (body.env != null) {
+      if (!body.env || typeof body.env !== 'object' || Array.isArray(body.env)) return bad('env must be an object of variable names and values');
+      const env = {};
+      for (const [k, v] of Object.entries(body.env)) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(k)) return bad(`“${k.slice(0, 40)}” is not a valid environment variable name`);
+        if (k === sessionFlag.FLAG) return bad(`${k} is set by the workspace itself and cannot come from a profile`);
+        if (typeof v !== 'string' || v.length > 4000 || /\0/.test(v)) return bad(`the value for ${k} must be text of at most 4000 characters`);
+        env[k] = v;
+      }
+      if (Object.keys(env).length) desc.env = env;
+    }
+    const dir = profilesLib.profilesDir(os.homedir());
+    const file = path.join(dir, id + '.json');
+    try {
+      fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+      fs.writeFileSync(file, JSON.stringify(desc, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+    } catch (e) {
+      if (e && e.code === 'EEXIST') return bad(`a profile named “${id}” already exists — PMOS does not overwrite one`);
+      return json(res, { ok: false, error: `the profile could not be written — ${String((e && e.code) || (e && e.message) || 'write failed').slice(0, 120)}` }, 500);
+    }
+    const read = readProfilesNow();
+    const made = (read.profiles || []).find((x) => x.id === id);
+    if (!made) {
+      try { fs.unlinkSync(file); } catch { /* nothing more to do */ }
+      const why = (read.broken || []).find((b) => b.file === id + '.json');
+      return bad(`the profile was refused when read back — ${why ? why.error : 'it could not be read'}; nothing was kept`);
+    }
+    return json(res, { ok: true, profile: profileWire(made, read), path: file });
+  }
   if (p === '/api/profiles/prefer' && req.method === 'POST') {
     let body = {};
     try { body = JSON.parse((await readBody(req)) || '{}'); }
@@ -8761,13 +8829,13 @@ wss.on('connection', (ws) => {
       // 0.55.1 — a session started FROM a skill: the skill's agent, prompt and tier, resolved here and never sent.
       const sk = m.skill ? skillLaunch(m.ws, m.skill) : null;
       if (sk && !sk.ok) { ws.send(JSON.stringify({ t: 'error', error: 'skill: ' + sk.error })); return; }
-      const r = spawnWithBranch({ name: m.name, agent: sk ? sk.agent : m.agent, cwd: m.cwd, ws: m.ws, branch: m.branch, createBranch: m.createBranch, isolate: m.isolate, profile: m.profile, initiative: wsBindable(ws, m.initiative),
+      const r = spawnWithBranch({ name: m.name, agent: sk ? sk.agent : m.agent, cwd: m.cwd, ws: m.ws, branch: m.branch, createBranch: m.createBranch, isolate: m.isolate, profile: m.profile, initiative: wsBindable(ws, m.initiative), launchFlags: m.flags,
         // D75 — what the composer chose (a tier, or a model), carried like the profile. Absent = not asked.
         modelAsk: sk ? sk.modelAsk : ((m.tier || m.model) ? { explicit: { tier: m.tier, model: m.model, effort: m.effort } } : null),
         initialInput: sk ? sk.initialInput : null, workType: m.workType });
       // A refused profile is its own sentence, not "branch: …" — the composer's error line names
       // what PMOS could not read, and nothing was started.
-      if (!r.ok) { ws.send(JSON.stringify({ t: 'error', error: (/^(profile|model choice) /.test(r.error || '') ? '' : 'branch: ') + r.error })); return; }
+      if (!r.ok) { ws.send(JSON.stringify({ t: 'error', error: (/^(profile|model choice|launch flag) /.test(r.error || '') ? '' : 'branch: ') + r.error })); return; }
       // a non-fatal truth about what just happened (a worktree's path, a branch ignored on a
       // non-repo) — said out loud, never swallowed
       if (r.notice) ws.send(JSON.stringify({ t: 'notice', notice: r.notice }));
@@ -8779,11 +8847,11 @@ wss.on('connection', (ws) => {
       const sk = m.skill ? skillLaunch(m.ws, m.skill) : null;
       if (sk && !sk.ok) { ws.send(JSON.stringify({ t: 'error', error: 'skill: ' + sk.error })); return; }
       const r = startWork({ initiative: wsBindable(ws, m.initiative), repoKey: m.repoKey, ws: m.ws,
-        agent: sk ? sk.agent : m.agent, name: m.name, profile: m.profile,
+        agent: sk ? sk.agent : m.agent, name: m.name, profile: m.profile, launchFlags: m.flags,
         initialInput: sk ? sk.initialInput : null, workType: m.workType,
         // a blank session from the dock carries the Settings tier (D75); a skill's own tier wins
         modelAsk: sk ? sk.modelAsk : (m.tier ? { explicit: { tier: m.tier } } : null) });
-      if (!r.ok) { ws.send(JSON.stringify({ t: 'error', error: (/^profile /.test(r.error || '') ? '' : 'start: ') + r.error })); return; }
+      if (!r.ok) { ws.send(JSON.stringify({ t: 'error', error: (/^(profile|launch flag) /.test(r.error || '') ? '' : 'start: ') + r.error })); return; }
       if (r.notice) ws.send(JSON.stringify({ t: 'notice', notice: r.notice }));
       ws.send(JSON.stringify({ t: 'created', id: r.session.id }));
     } else if (m.t === 'respawn') {
@@ -8792,7 +8860,7 @@ wss.on('connection', (ws) => {
       // server already holds, not re-sent by the client — a client that forgot it would otherwise
       // silently restart the pane on a different environment, and the pane would look identical.
       const carried = 'profile' in old ? old.profile : null;
-      const s = spawnSession({ name: old.name, agent: old.agent, cwd: path.relative(old.root, old.cwd), ws: old.ws, profile: carried, modelAsk: old.modelAsk || null, planItem: old.plan_item || null });
+      const s = spawnSession({ name: old.name, agent: old.agent, cwd: path.relative(old.root, old.cwd), ws: old.ws, profile: carried, modelAsk: old.modelAsk || null, planItem: old.plan_item || null, launchFlags: Array.isArray(old.launchFlags) ? old.launchFlags.map((a) => ({ flag: a.flag, value: a.value })) : undefined });
       // A descriptor deleted since the original spawn does NOT get substituted. The respawn goes
       // ahead with no profile — the pane line already says so — and the reason is said out loud
       // rather than left for the PM to notice.

package/workspace/test-lists/workspace-launch-flags.json

@@ -0,0 +1,15 @@
+{
+  "_comment": "workspace-launch-flags: lib/claude-flags.js and the generated list it reads.",
+  "modules": [
+    "claude-flags.test.js",
+    "launch-flags.test.js"
+  ],
+  "seconds": {
+    "claude-flags.test.js": 1,
+    "launch-flags.test.js": 25,
+    "pm-launch-flags-test.js": 20
+  },
+  "panels": [
+    "pm-launch-flags-test.js"
+  ]
+}