create-pmos 0.55.5 → 0.57.0

package/workspace/lib/docs-cli.js

@@ -0,0 +1,221 @@
+'use strict';
+/* docs-cli.js — `pmos docs`: the sync signal for documents linked to Google Docs and Confluence, from a terminal
+ * (initiative docs-three-way-sync).
+ *
+ *   pmos docs [list] [--attention] [--json]               each linked document and its signal per copy
+ *   pmos docs link <file> <google-or-confluence-link>     link a repository file to a copy
+ *   pmos docs unlink <file> google|confluence             remove that link (the copy is not touched)
+ *   pmos docs check-start [--json]                        open a check: what to read, with each file's hash
+ *   pmos docs record <check> --file <readings.json>       record what the session read
+ *   pmos docs check-finish <check> [--summary "…"]        close the check
+ *   pmos docs find [words]                                the repository's markdown files that match, with or without a copy
+ *   pmos docs sync-start <file> google|confluence --use pmos|copy [--json]   open a sync of one copy (the sync session)
+ *   pmos docs sync-finish <sync> --version <v> [--modified-at <t>] [--url <u>]   close it: both sides now the same
+ *   pmos docs sync-fail <sync> --reason "…"               close it: nothing was written, and why
+ *
+ * The same module the Docs place reads (lib/doc-sync-store.js), so a terminal line and a row cannot disagree.
+ * No command writes a document. A check reads; a sync (amended 2026-10-06: the PM presses Use … version for one copy) is
+ * written by the doc-sync session with the PM's connectors, and these commands only record that it started and ended.
+ * check-start, record and check-finish are the check session's commands; each must name who read, which is the
+ * session's PMOS_SESSION token, or `--by <profile>` when the session runs outside the workspace.
+ *
+ * Exit codes: 0 done, 1 refused, 2 usage.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const D = require('./doc-sync');
+const store = require('./doc-sync-store');
+const { parseArgs } = require('./schedule-cli');
+
+const COMMANDS = { docs: ['list', 'link', 'unlink', 'check-start', 'record', 'check-finish', 'find', 'sync-start', 'sync-finish', 'sync-fail'] };
+const USAGE = [
+  'usage: pmos docs [list|link|unlink|find|check-start|record|check-finish|sync-start|sync-finish|sync-fail] — is each linked document the same as its Google Docs and Confluence copy',
+  '  pmos docs [list] [--attention] [--json]            each linked document and its signal: same, ahead, behind, edited in both',
+  '  pmos docs link <file> <link>                       link a repository file to a Google Doc or a Confluence page',
+  '  pmos docs unlink <file> google|confluence          remove that link; the copy is not touched',
+  '  pmos docs check-start [--json]                     (check session) open a check and list what to read',
+  '  pmos docs record <check> --file <readings.json>    (check session) record what was read',
+  '  pmos docs check-finish <check> [--summary "…"]     (check session) close the check',
+  '  pmos docs find [words]                             the repository\'s markdown files that match',
+  '  pmos docs sync-start <file> google|confluence --use pmos|copy   (sync session) open a sync of one copy',
+  '  pmos docs sync-finish <sync> --version <v> [--modified-at <t>] [--url <u>]   (sync session) both sides are now the same',
+  '  pmos docs sync-fail <sync> --reason "…"            (sync session) nothing was written, and why',
+  'Nothing here writes a document. Press Check now, or Use … version on one copy, in Docs.',
+];
+const BOOL = new Set(['json', 'attention', 'help']);
+
+function parse(argv) {
+  const rest = []; const bools = {};
+  for (const a of argv) {
+    if (a.startsWith('--') && BOOL.has(a.slice(2))) bools[a.slice(2)] = true;
+    else if (a === '-h') bools.help = true;
+    else rest.push(a);
+  }
+  const { pos, flags } = parseArgs(rest);
+  return { pos, flags: { ...flags, ...bools } };
+}
+function repoRoot(cwd) {
+  try { return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || cwd; }
+  catch { return cwd; }
+}
+/** Who is reading: the workspace session's token names it; outside the workspace, the profile the PM names. */
+function whoOf(flags, env) {
+  const tok = String(env.PMOS_SESSION || '').trim();
+  if (tok) return 'session:' + tok.split('.')[0].slice(0, 60);
+  if (flags.by) return 'profile:' + String(flags.by).slice(0, 60);
+  return null;
+}
+const kindOf = (target) => {
+  if (D.remoteIdOf('confluence', target) && /atlassian|confluence|\/wiki\/|pageId=/i.test(target)) return 'confluence';
+  if (D.remoteIdOf('google', target) && /google|docs\.|drive\./i.test(target)) return 'google';
+  return null;
+};
+const ago = (iso, now) => {
+  if (!iso) return 'never';
+  const m = Math.round((now - Date.parse(iso)) / 60000);
+  if (m < 1) return 'just now';
+  if (m < 60) return `${m} min ago`;
+  if (m < 48 * 60) return `${Math.round(m / 60)} h ago`;
+  return `${Math.round(m / 1440)} days ago`;
+};
+
+async function run(argv, { say = console.log, cwd = process.cwd(), env = process.env, now = Date.now() } = {}) {
+  const { pos, flags } = parse(argv.slice(1));
+  const sub = pos[0] || 'list';
+  if (flags.help || sub === 'help') { USAGE.forEach((l) => say(l)); return 0; }
+  const json = !!flags.json;
+  const root = flags.root ? path.resolve(cwd, flags.root) : repoRoot(cwd);
+  const fail = (error, code = 1) => { if (json) say(JSON.stringify({ ok: false, error })); else say(`✗ ${error}`); return code; };
+  const rel = (p) => {
+    const abs = path.resolve(cwd, p);
+    const r = path.relative(root, abs).split(path.sep).join('/');
+    return r.startsWith('..') ? null : r;
+  };
+
+  if (sub === 'list') {
+    const v = store.view(root);
+    if (!v.ok) return fail(v.error);
+    const docs = flags.attention ? v.docs.filter((d) => d.attention) : v.docs;
+    if (json) { say(JSON.stringify({ ...v, docs })); return 0; }
+    if (!v.docs.length) { say('No document is linked to Google Docs or Confluence. Link one: pmos docs link <file> <link>'); return 0; }
+    const s = v.summary;
+    say(`Docs · ${s.documents} document${s.documents === 1 ? '' : 's'} · ${s.same} same · ${s.ahead} ahead · ${s.behind} behind · ${s.diverged} edited in both · ${s.unchecked} not checked`);
+    say(v.last ? `Last check ${ago(v.last.finished_at, now)}${v.last.summary ? ': ' + v.last.summary : ''}` : 'Never checked. Press Check now in Docs.');
+    if (v.open) say(`A check is running (started ${ago(v.open.started_at, now)}).`);
+    for (const d of docs) {
+      say(`${d.title}  (${d.path})`);
+      for (const l of d.links) say(`  ${l.label.padEnd(12)} ${l.words}${l.checked_at ? ' · checked ' + ago(l.checked_at, now) : ''}`);
+    }
+    return 0;
+  }
+
+  if (sub === 'link') {
+    const [file, target] = [pos[1], pos[2]];
+    if (!file || !target) return fail('usage: pmos docs link <file> <google-or-confluence-link>', 2);
+    const kind = flags.kind || kindOf(target);
+    if (!kind) return fail('that is not a Google Docs or Confluence link — paste the page\'s address');
+    const r = rel(file);
+    if (!r) return fail(`${file} is not inside this repository`);
+    const w = store.addLink(root, { path: r, kind, target });
+    if (!w.ok) return fail(w.error);
+    if (json) say(JSON.stringify({ ok: true, path: r, kind })); else say(`✓ ${r} is linked to ${D.KIND_LABEL[kind]}. Its signal shows after the next check.`);
+    return 0;
+  }
+
+  if (sub === 'unlink') {
+    const [file, kind] = [pos[1], pos[2]];
+    if (!file || !D.KINDS.includes(kind)) return fail('usage: pmos docs unlink <file> google|confluence', 2);
+    const r = rel(file);
+    if (!r) return fail(`${file} is not inside this repository`);
+    const w = store.removeLink(root, { path: r, kind });
+    if (!w.ok) return fail(w.error);
+    if (json) say(JSON.stringify({ ok: true })); else say(`✓ ${r} is no longer linked to ${D.KIND_LABEL[kind]}. The copy is not touched.`);
+    return 0;
+  }
+
+  if (sub === 'find') {
+    const found = store.findFiles(root, pos.slice(1).join(' '));
+    const v = store.view(root);
+    const linked = new Map((v.ok ? v.docs : []).map((d) => [d.path, d.links.map((l) => l.label)]));
+    const files = found.map((f) => ({ ...f, copies: linked.get(f.path) || [] }));
+    if (json) { say(JSON.stringify({ ok: true, files })); return 0; }
+    if (!files.length) { say('No markdown file matches.'); return 0; }
+    for (const f of files) say(`${f.title}  (${f.path})  ${f.copies.length ? f.copies.join(', ') : 'no copy'}`);
+    return 0;
+  }
+
+  const by = whoOf(flags, env);
+  if (sub === 'check-start') {
+    if (!by) return fail('a check must name who reads: run it in a workspace session, or add --by <profile>');
+    const s = store.checkStart(root, { by, now: new Date(now) });
+    if (!s.ok) return fail(s.error);
+    if (json) { say(JSON.stringify(s)); return 0; }
+    say(`Check ${s.run} · ${s.links.length} link${s.links.length === 1 ? '' : 's'} to read`);
+    for (const l of s.links) say(`  ${l.path}  ${D.KIND_LABEL[l.kind]}  ${l.target}  hash ${l.repo_hash || '(no file)'}`);
+    return 0;
+  }
+  if (sub === 'record') {
+    const runId = pos[1];
+    if (!runId || !flags.file) return fail('usage: pmos docs record <check> --file <readings.json>', 2);
+    if (!by) return fail('a reading must name who read: run it in a workspace session, or add --by <profile>');
+    let readings;
+    try {
+      const parsed = JSON.parse(fs.readFileSync(path.resolve(cwd, flags.file), 'utf8'));
+      readings = Array.isArray(parsed) ? parsed : parsed.readings;
+    } catch (e) { return fail(`could not read ${flags.file}: ${String((e && e.message) || e).slice(0, 160)}`); }
+    const r = store.record(root, { run: runId, by, readings, now: new Date(now) });
+    if (json) say(JSON.stringify(r));
+    else {
+      say(`${r.recorded ? r.recorded.length : 0} reading(s) recorded.`);
+      for (const x of r.refused || []) say(`✗ ${x.path} ${x.kind}: ${x.error}`);
+      if (!r.recorded && r.error) say(`✗ ${r.error}`);
+    }
+    return r.ok ? 0 : 1;
+  }
+  if (sub === 'check-finish') {
+    const runId = pos[1];
+    if (!runId) return fail('usage: pmos docs check-finish <check> [--summary "…"]', 2);
+    if (!by) return fail('a check must name who ran it: run it in a workspace session, or add --by <profile>');
+    const r = store.checkFinish(root, { run: runId, by, summary: flags.summary || null, now: new Date(now) });
+    if (!r.ok) return fail(r.error);
+    const v = store.view(root);
+    if (json) say(JSON.stringify({ ok: true, summary: v.ok ? v.summary : null }));
+    else say(v.ok ? `✓ Check closed · ${v.summary.same} same · ${v.summary.ahead} ahead · ${v.summary.behind} behind · ${v.summary.diverged} edited in both` : '✓ Check closed');
+    return 0;
+  }
+  if (sub === 'sync-start') {
+    const [file, kind] = [pos[1], pos[2]];
+    if (!file || !D.KINDS.includes(kind) || !D.USES.includes(flags.use)) return fail('usage: pmos docs sync-start <file> google|confluence --use pmos|copy', 2);
+    if (!by) return fail('a sync must name who writes: run it in a workspace session, or add --by <profile>');
+    const r = rel(file);
+    if (!r) return fail(`${file} is not inside this repository`);
+    const s = store.syncStart(root, { path: r, kind, use: flags.use, by, now: new Date(now) });
+    if (!s.ok) return fail(s.error);
+    if (json) { say(JSON.stringify(s)); return 0; }
+    say(`Sync ${s.run} · ${s.path} · ${s.use === 'pmos' ? 'write the PMOS version to ' + s.label : 'write the ' + s.label + ' version to PMOS'} · ${s.target}`);
+    return 0;
+  }
+  if (sub === 'sync-finish') {
+    const runId = pos[1];
+    if (!runId || !flags.version) return fail('usage: pmos docs sync-finish <sync> --version <v> [--modified-at <t>] [--url <u>]', 2);
+    if (!by) return fail('a sync must name who wrote: run it in a workspace session, or add --by <profile>');
+    const r = store.syncFinish(root, { run: runId, by, version: flags.version, modified_at: flags['modified-at'] || null,
+      modified_by: flags['modified-by'] || null, url: flags.url || null, now: new Date(now) });
+    if (!r.ok) return fail(r.error);
+    if (json) say(JSON.stringify({ ok: true })); else say('✓ Sync closed. Both sides are the same.');
+    return 0;
+  }
+  if (sub === 'sync-fail') {
+    const runId = pos[1];
+    if (!runId || !flags.reason) return fail('usage: pmos docs sync-fail <sync> --reason "…"', 2);
+    if (!by) return fail('a sync must name who ran it: run it in a workspace session, or add --by <profile>');
+    const r = store.syncFail(root, { run: runId, by, reason: String(flags.reason), now: new Date(now) });
+    if (!r.ok) return fail(r.error);
+    if (json) say(JSON.stringify({ ok: true })); else say('✓ Sync closed as failed. Nothing was written.');
+    return 0;
+  }
+  return fail(`pmos docs ${sub} is not a command. ${USAGE[0]}`, 2);
+}
+
+module.exports = { run, COMMANDS, USAGE };

package/workspace/lib/online-mode.js

@@ -0,0 +1,158 @@
+'use strict';
+/* online-mode.js — the Online switch: its settings record and the tunnel it runs (workspace-online-mode, PRD O1, O2).
+ *
+ * THE RECORD. `<runtime state>/online.json`, in the per-user runtime directory lib/state-root.js keeps outside every
+ * repository, written with mode 0600 through a temporary file and a rename (the typesafe-settings.js pattern):
+ *   { on, host, tunnel, team, audience, email }
+ *   host      the public hostname, validated by remote-access.parsePublicHost (pmos.pm-os.app)
+ *   tunnel    the Cloudflare tunnel name or id that `cloudflared tunnel run` takes (pmos)
+ *   team      the Cloudflare team domain, <team>.cloudflareaccess.com
+ *   audience  the Access application's audience tag, 64 hex characters
+ *   email     the one address allowed in
+ * A field that fails its check is refused with the reason, and nothing is written.
+ *
+ * THE TUNNEL. createTunnel() runs `cloudflared tunnel --no-autoupdate run <tunnel>` as a child of the server, with its
+ * output appended to `<runtime state>/online-tunnel.log`. stop() ends it. If it exits while Online is on, it is started
+ * again after 5 seconds. cloudflared is the PM's own installed program; it is found on PATH or in the two Homebrew
+ * folders, because a workspace started at login has a short PATH.
+ */
+const fs = require('fs');
+const path = require('path');
+const childProcess = require('child_process');
+const remoteAccess = require('./remote-access');
+const accessKeys = require('./access-keys');
+
+const FILE = 'online.json';
+const LOG = 'online-tunnel.log';
+const FIELDS = ['host', 'tunnel', 'team', 'audience', 'email'];
+const RESTART_MS = 5000;
+
+function file(stateDir) { return path.join(stateDir, FILE); }
+
+const CHECKS = {
+  host: (v) => {
+    if (!v) return 'give the public hostname, such as pmos.pm-os.app';
+    const r = remoteAccess.parsePublicHost(v);
+    return r.refused ? 'the hostname must be a bare DNS name, such as pmos.pm-os.app (no https://, port or path)' : null;
+  },
+  tunnel: (v) => (/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(v) ? null : 'give the tunnel name you created with cloudflared, such as pmos'),
+  team: (v) => (accessKeys.validTeamDomain(v) ? null : 'give your Cloudflare team domain, such as myteam.cloudflareaccess.com'),
+  audience: (v) => (/^[a-f0-9]{64}$/.test(v) ? null : "give the Access application's Audience (AUD) tag: 64 letters and digits from the application's Overview"),
+  email: (v) => (/^[^\s@]{1,64}@[^\s@]+\.[^\s@]{2,}$/.test(v) && v.length <= 254 ? null : 'give the email address you sign in with'),
+};
+function norm(field, v) {
+  const s = String(v == null ? '' : v).trim();
+  return field === 'tunnel' ? s : s.toLowerCase();
+}
+
+function read(stateDir) {
+  const out = { on: false, host: '', tunnel: '', team: '', audience: '', email: '' };
+  try {
+    const st = fs.lstatSync(file(stateDir));
+    if (!st.isFile()) return out;
+    const o = JSON.parse(fs.readFileSync(file(stateDir), 'utf8')) || {};
+    for (const f of FIELDS) if (typeof o[f] === 'string' && !CHECKS[f](o[f])) out[f] = o[f];
+    out.on = o.on === true && complete(out);
+  } catch { /* none yet */ }
+  return out;
+}
+
+function complete(s) { return FIELDS.every((f) => s[f] && !CHECKS[f](s[f])); }
+
+/** The first field that is missing or invalid, as { field, error }, or null when all five are good. */
+function firstProblem(s) {
+  for (const f of FIELDS) { const e = CHECKS[f](s[f] || ''); if (e) return { field: f, error: e }; }
+  return null;
+}
+
+function write(stateDir, data) {
+  const target = file(stateDir);
+  try { if (fs.lstatSync(target).isSymbolicLink()) return { ok: false, error: 'the settings file is a symlink and was not written' }; }
+  catch { /* not there yet */ }
+  const tmp = target + '.' + process.pid + '.tmp';
+  try {
+    fs.mkdirSync(stateDir, { recursive: true });
+    fs.writeFileSync(tmp, JSON.stringify(data), { mode: 0o600 });
+    fs.chmodSync(tmp, 0o600);
+    fs.renameSync(tmp, target);
+    return { ok: true };
+  } catch (e) {
+    try { fs.unlinkSync(tmp); } catch { /* nothing to clean */ }
+    return { ok: false, error: 'the online settings could not be saved (' + String((e && e.code) || 'write failed') + ')' };
+  }
+}
+
+/**
+ * save(stateDir, patch) → { ok, settings } | { ok: false, field?, error }
+ * patch may carry any of the five fields and `on`. Fields are validated first; `on: true` then needs all five.
+ * Whether cloudflared is installed is the caller's check, because it is not a property of the record.
+ */
+function save(stateDir, patch = {}) {
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) return { ok: false, error: 'the body must be an object' };
+  const next = read(stateDir);
+  for (const f of FIELDS) {
+    if (!(f in patch)) continue;
+    const v = norm(f, patch[f]);
+    const e = CHECKS[f](v);
+    if (e) return { ok: false, field: f, error: e };
+    next[f] = v;
+  }
+  if ('on' in patch) {
+    if (typeof patch.on !== 'boolean') return { ok: false, field: 'on', error: 'on must be true or false' };
+    if (patch.on) { const p = firstProblem(next); if (p) return { ok: false, ...p }; }
+    next.on = patch.on;
+  }
+  const w = write(stateDir, next);
+  return w.ok ? { ok: true, settings: next } : { ok: false, error: w.error };
+}
+
+/** The cloudflared binary: PATH first, then the two Homebrew folders. null when absent. */
+function findCloudflared({ env = process.env, exists = (p) => { try { fs.accessSync(p, fs.constants.X_OK); return fs.statSync(p).isFile(); } catch { return false; } } } = {}) {
+  const dirs = String(env.PATH || '').split(path.delimiter).filter(Boolean).concat(['/opt/homebrew/bin', '/usr/local/bin']);
+  const name = process.platform === 'win32' ? 'cloudflared.exe' : 'cloudflared';
+  for (const d of dirs) { const p = path.join(d, name); if (exists(p)) return p; }
+  return null;
+}
+
+/**
+ * createTunnel({ stateDir, spawn, find, setTimer }) → { start(name), stop(), status() }
+ * status() → { running, pid, since, lastExit } — lastExit is { code, at } of the last exit, or null.
+ */
+function createTunnel({ stateDir, spawn = childProcess.spawn, find = findCloudflared, setTimer = setTimeout } = {}) {
+  let child = null; let want = null; let since = null; let lastExit = null; let timer = null;
+  function launch() {
+    timer = null;
+    if (!want || child) return;
+    const bin = find();
+    if (!bin) { lastExit = { code: null, at: new Date().toISOString(), error: 'cloudflared is not installed' }; return; }
+    let fd = 'ignore';
+    try { fs.mkdirSync(stateDir, { recursive: true }); fd = fs.openSync(path.join(stateDir, LOG), 'a', 0o600); } catch { fd = 'ignore'; }
+    try {
+      child = spawn(bin, ['tunnel', '--no-autoupdate', 'run', want], { stdio: ['ignore', fd, fd], detached: false });
+    } catch (e) {
+      child = null; lastExit = { code: null, at: new Date().toISOString(), error: 'cloudflared could not start' };
+    }
+    if (typeof fd === 'number') { try { fs.closeSync(fd); } catch { /* ignore */ } }
+    if (!child) return;
+    since = new Date().toISOString();
+    const mine = child;
+    mine.on('error', () => {});
+    mine.on('exit', (code) => {
+      if (child !== mine) return;
+      child = null; since = null; lastExit = { code, at: new Date().toISOString() };
+      if (want && !timer) timer = setTimer(launch, RESTART_MS);
+    });
+  }
+  return {
+    start(name) { want = name; if (!child && !timer) launch(); },
+    stop() {
+      want = null;
+      if (timer) { clearTimeout(timer); timer = null; }
+      const c = child; child = null; since = null;
+      if (c) { try { c.kill('SIGTERM'); } catch { /* already gone */ } }
+    },
+    status: () => ({ running: !!child, pid: child ? child.pid : null, since, lastExit }),
+  };
+}
+
+module.exports = { read, save, complete, firstProblem, findCloudflared, createTunnel, FIELDS, FILE, LOG };

package/workspace/lib/pmos-verbs.js

@@ -35,6 +35,9 @@ const VERBS = Object.freeze({
   report: Object.freeze({ module: 'report-cli.js', run: 5, guide: 'reports.md',
     help: 'pmos report draft|issue|list … — draft and issue reports (pmos report help)' }),
   // Not a pm-os-absorb verb (run: null): the workspace-launcher initiative added it through the same table.
+  // Not a pm-os-absorb verb (run: null): docs-three-way-sync added it through the same table.
+  docs: Object.freeze({ module: 'docs-cli.js', run: null, guide: 'docs.md',
+    help: 'pmos docs [list|link|unlink|find] … — is each linked document the same as, ahead of or behind its Google Docs and Confluence copy, and record a sync (pmos docs help)' }),
   launcher: Object.freeze({ module: 'launcher-cli.js', run: null, guide: 'launcher.md',
     help: 'pmos launcher on|off|status — a PMOS app and a login item, so the workspace starts without a terminal' }),
 });

package/workspace/lib/remote-access.js

@@ -373,9 +373,11 @@ function stripTokenParam(url) {
 // The cookie a valid token seeds. HttpOnly (no script needs it) + SameSite=Strict + the Origin/Host
 // allowlist keep a foreign site from riding it. No Secure flag on the tailnet: it speaks plain HTTP
 // inside WireGuard. On the public host the browser is on HTTPS (TLS ends at the edge), so the cookie
-// is Secure there and is never sent over plain HTTP. 7 days, unchanged from workspace-mobile-remote-access.
+// is Secure there and is never sent over plain HTTP. 30 days (workspace-remember-device; was 7), so a
+// device signs in about once a month: the PM's own phone, behind Cloudflare Access or the tailnet.
+const SESSION_MAX_AGE = 30 * 24 * 60 * 60;
 function sessionCookie(token, { secure = false } = {}) {
-  return `${COOKIE_NAME}=${encodeURIComponent(token)}; HttpOnly; ${secure ? 'Secure; ' : ''}SameSite=Strict; Path=/; Max-Age=604800`;
+  return `${COOKIE_NAME}=${encodeURIComponent(token)}; HttpOnly; ${secure ? 'Secure; ' : ''}SameSite=Strict; Path=/; Max-Age=${SESSION_MAX_AGE}`;
 }
 
 // The sign-in form posts application/x-www-form-urlencoded `token=<t>` to /auth.
@@ -425,7 +427,7 @@ module.exports = {
   LOOPBACK, isLoopbackAddr, isTailnetIp, detectTailnetIp, remoteRequested,
   resolveBinds, extractHttpToken, extractWsToken, tokenMatches, authorize, startupLines,
   checkHostOrigin, isAllowedOrigin, hostnameAllowed,
-  parsePublicHost, PROXY_HEADERS, ACCESS_HEADER, isProxied, edgeAllowed,
+  parsePublicHost, PROXY_HEADERS, ACCESS_HEADER, isProxied, edgeAllowed, hostnameOf,
   COOKIE_NAME, extractCookieToken, presentedToken,
   phoneUrl, isPageNavigation, stripTokenParam, sessionCookie, AUTH_PATH, parseAuthForm, signInPage,
 };

package/workspace/package-lock.json

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

package/workspace/package.json

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

package/workspace/public/pm/app.js

@@ -406,7 +406,7 @@ function render() {
 
 const FRAME = !FIXTURE && !LEGACY_LAYOUT_FLAG;
 const FRAME_KEY = 'pmos.workspace.pm.frame';
-const FRAME_DESTS = Object.freeze(['today', 'initiatives', 'board', 'reports', 'settings']);
+const FRAME_DESTS = Object.freeze(['today', 'initiatives', 'board', 'reports', 'docs', 'settings']);
 
 function readFrame() {
   if (!FRAME) return {};
@@ -637,7 +637,7 @@ function pressIn(r, key) {
   if (b && !b.disabled) { b.click(); return true; }
   return false;
 }
-const G_KEYS = { t: 'today', i: 'initiatives', b: 'board', r: 'reports' };
+const G_KEYS = { t: 'today', i: 'initiatives', b: 'board', r: 'reports', d: 'docs' };
 
 function frameKey(e) {
   const mod = e.metaKey || e.ctrlKey;

package/workspace/public/pm/components.css

@@ -4067,6 +4067,152 @@
   }
 }
 
+/* Docs (docs-three-way-sync): one line per copy — a status dot, the title over the copy's link, one sentence, one action. */
+.rp-docs {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+.rp-docs-top {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 12px;
+}
+.rp-docs-top > .rp-head__title {
+  margin-right: auto;
+}
+.rp-docs-find {
+  flex: 1 1 260px;
+  max-width: 420px;
+}
+.rp-docs-body {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+.rp-docs-views {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 12px;
+  border-bottom: 1px solid var(--border);
+}
+.rp-docs-when {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  margin-left: auto;
+  font-size: 12px;
+  color: var(--muted-foreground);
+}
+.rp-docs-group__title {
+  margin: 0;
+  padding: 8px 0;
+  font-size: 12px;
+  font-weight: 500;
+  color: var(--muted-foreground);
+}
+.rp-docs-row {
+  border-top: 1px solid var(--border);
+}
+.rp-docs-row:last-child {
+  border-bottom: 1px solid var(--border);
+}
+.rp-docs-dot {
+  display: inline-block;
+  width: 8px;
+  height: 8px;
+  background: var(--muted-foreground);
+}
+.rp-docs-dot--ok {
+  background: var(--muted-foreground);
+}
+.rp-docs-dot--warn {
+  background: var(--warning);
+}
+.rp-docs-dot--bad {
+  background: var(--destructive);
+}
+.rp-docs-dot--none {
+  background: transparent;
+  border: 1px solid var(--muted-foreground);
+}
+.rp-docs-open {
+  font-size: 12px;
+  color: var(--muted-foreground);
+  white-space: nowrap;
+  text-underline-offset: 2px;
+}
+.rp-docs-detail {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 12px;
+  padding: 4px 0 16px 24px;
+}
+.rp-docs-side {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 4px;
+  min-width: 0;
+  padding: 12px;
+  border: 1px solid var(--border);
+}
+.rp-docs-side--new {
+  border-color: var(--foreground);
+}
+.rp-docs-side__label {
+  font-size: 12px;
+  color: var(--muted-foreground);
+}
+.rp-docs-side__where {
+  max-width: 100%;
+  font-family: var(--mono);
+  font-size: 12px;
+  overflow-wrap: anywhere;
+}
+.rp-docs-side__edit {
+  margin-bottom: 8px;
+  font-size: 14px;
+}
+.rp-docs-diff {
+  grid-column: 1 / -1;
+  margin: 0;
+  padding: 8px 10px;
+  border: 1px solid var(--border);
+  font-family: var(--mono);
+  font-size: 12px;
+  overflow-wrap: anywhere;
+}
+.rp-docs-more {
+  grid-column: 1 / -1;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+.rp-docs-add {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 0 12px 24px;
+}
+.rp-docs-add__input {
+  flex: 1 1 240px;
+}
+.rp-docs-add__err {
+  flex-basis: 100%;
+  font-size: 12px;
+  color: var(--destructive);
+}
+@media (max-width: 640px) {
+  .rp-docs-detail {
+    grid-template-columns: 1fr;
+    padding-left: 0;
+  }
+}
+
 /* -- layouts · .lg- the legacy and fixture shells (Run 3, slice 3D) -- */
 /* The legacy and fixture cockpit's two columns: the list head (a stack) and the rail's tile column. */
 .lg-stack {