phronesis 1.0.0 → 1.1.0

package/src/cli.js

@@ -4,7 +4,6 @@ import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { resolve } from 'node:path';
 import { realpathSync } from 'node:fs';
-import { DEFAULT_DOMAIN } from './layout.js';
 import { COVERAGE_FLOOR_RANGE, MAX_K, QUALITY_FLOOR_RANGE } from './skills-bump.js';
 
 const nodeMajor = parseInt(process.versions.node.split('.')[0], 10);
@@ -21,6 +20,8 @@ function parseArgs(argv = process.argv.slice(2)) {
   if (!cmd || cmd === '--help' || cmd === '-h') return { command: 'help' };
   if (cmd === '--version' || cmd === '-v') return { command: 'version' };
   if (cmd === 'init') return parseInitArgs(rest);
+  if (cmd === 'launcher') return parseLauncherArgs(rest);
+  if (cmd === 'profile') return parseProfileArgs(rest);
   if (cmd === 'export') return parseExportArgs(rest);
   if (cmd === 'validate') return parseValidateArgs(rest);
   if (cmd === 'links') return parseLinksArgs(rest);
@@ -32,6 +33,7 @@ function parseArgs(argv = process.argv.slice(2)) {
   if (cmd === 'active-context') return parseActiveContextArgs(rest);
   if (cmd === 'registry') return parseRegistryArgs(rest);
   if (cmd === 'skills') return parseSkillsArgs(rest);
+  if (cmd === 'hook') return parseHookArgs(rest);
   if (cmd === 'hooks') return parseHooksArgs(rest);
   if (cmd === 'adapter') return parseAdapterArgs(rest);
   if (cmd === 'guard') return parseGuardArgs(rest);
@@ -48,6 +50,7 @@ function parseArgs(argv = process.argv.slice(2)) {
 function parseInitArgs(args) {
   let dir;
   let force = false;
+  let persist;
   // domain + the minimal-profile value flags (core-0039). Each accepts `--flag value` and `--flag=value`.
   const VALUE_FLAGS = ['domain', 'name', 'role', 'company', 'working-style'];
   const values = {};
@@ -59,6 +62,14 @@ function parseInitArgs(args) {
       force = true;
       continue;
     }
+    if (a === '--persist' || a === '--no-persist') {
+      const requested = a === '--persist';
+      if (persist !== undefined && persist !== requested) {
+        return { command: 'invalid', error: 'init: --persist and --no-persist are mutually exclusive.' };
+      }
+      persist = requested;
+      continue;
+    }
     let matched = false;
     for (const f of VALUE_FLAGS) {
       if (a === `--${f}`) {
@@ -92,6 +103,168 @@ function parseInitArgs(args) {
     role: values.role,
     company: values.company,
     workingStyle: values['working-style'],
+    persist,
+  };
+}
+
+function parseLauncherArgs(args) {
+  const [sub, ...rest] = args;
+  if (sub === undefined || sub === '--help' || sub === '-h') return { command: 'launcher-help' };
+  if (sub === 'install') {
+    const parsed = parseOptions(rest, {
+      values: ['backend', 'app-target', 'app-runtime', 'app-version', 'expect-owner', 'expect-version'],
+      flags: ['force-launcher', 'if-owned', 'no-path-offer', 'expect-absent'],
+    });
+    if (parsed.help) return { command: 'launcher-help' };
+    if (parsed.error) return { command: 'invalid', error: `${parsed.error} for launcher install.` };
+    if (parsed.positionals.length) {
+      return { command: 'invalid', error: 'launcher install takes no positional arguments.' };
+    }
+    const backend = parsed.values.backend || 'self-copy';
+    if (!['app', 'self-copy'].includes(backend)) {
+      return { command: 'invalid', error: `launcher install: --backend must be app | self-copy (got ${JSON.stringify(backend)}).` };
+    }
+    const appValues = ['app-target', 'app-runtime', 'app-version'];
+    if (backend === 'app') {
+      const missing = ['app-target', 'app-runtime'].filter((name) => !parsed.values[name]);
+      if (missing.length) {
+        return { command: 'invalid', error: `launcher install --backend app requires ${missing.map((name) => `--${name}`).join(', ')}.` };
+      }
+    } else if (appValues.some((name) => parsed.values[name] !== undefined) || parsed.flags['if-owned']) {
+      return { command: 'invalid', error: 'launcher install: app target/runtime/version and --if-owned require --backend app.' };
+    }
+    const expectOwner = parsed.values['expect-owner'];
+    const expectVersion = parsed.values['expect-version'];
+    const expectAbsent = Boolean(parsed.flags['expect-absent']);
+    if (parsed.flags['if-owned'] && (expectAbsent || expectOwner !== undefined || expectVersion !== undefined)) {
+      return { command: 'invalid', error: 'launcher install: --if-owned cannot be combined with --expect-absent/--expect-owner/--expect-version.' };
+    }
+    if (expectAbsent && (expectOwner !== undefined || expectVersion !== undefined)) {
+      return { command: 'invalid', error: 'launcher install: --expect-absent cannot be combined with --expect-owner/--expect-version.' };
+    }
+    if ((expectOwner === undefined) !== (expectVersion === undefined)) {
+      return { command: 'invalid', error: 'launcher install: --expect-owner and --expect-version must be passed together.' };
+    }
+    if (expectOwner !== undefined && !['app', 'self-copy'].includes(expectOwner)) {
+      return { command: 'invalid', error: `launcher install: --expect-owner must be app | self-copy (got ${JSON.stringify(expectOwner)}).` };
+    }
+    return {
+      command: 'launcher-install',
+      forceLauncher: Boolean(parsed.flags['force-launcher']),
+      backend,
+      appTarget: parsed.values['app-target'],
+      appRuntime: parsed.values['app-runtime'],
+      appVersion: parsed.values['app-version'],
+      ifOwned: Boolean(parsed.flags['if-owned']),
+      offerPath: !parsed.flags['no-path-offer'],
+      expectedPrior: expectAbsent
+        ? { absent: true }
+        : expectOwner === undefined
+          ? null
+          : { owner: expectOwner, version: expectVersion },
+    };
+  }
+  if (sub === 'remove') {
+    const parsed = parseOptions(rest, { values: ['backend'], flags: ['force-launcher'] });
+    if (parsed.help) return { command: 'launcher-help' };
+    if (parsed.error) return { command: 'invalid', error: `${parsed.error} for launcher remove.` };
+    if (parsed.positionals.length) {
+      return { command: 'invalid', error: 'launcher remove takes no positional arguments.' };
+    }
+    const backend = parsed.values.backend || 'self-copy';
+    if (!['app', 'self-copy'].includes(backend)) {
+      return { command: 'invalid', error: `launcher remove: --backend must be app | self-copy (got ${JSON.stringify(backend)}).` };
+    }
+    return {
+      command: 'launcher-remove',
+      forceLauncher: Boolean(parsed.flags['force-launcher']),
+      backend,
+    };
+  }
+  if (sub === 'path') {
+    const parsed = parseOptions(rest, { flags: ['append', 'append-consented-by-surface', 'json'] });
+    if (parsed.help) return { command: 'launcher-help' };
+    if (parsed.error) return { command: 'invalid', error: `${parsed.error} for launcher path.` };
+    if (parsed.positionals.length) {
+      return { command: 'invalid', error: 'launcher path takes no positional arguments.' };
+    }
+    if (parsed.flags['append-consented-by-surface'] && !parsed.flags.append) {
+      return { command: 'invalid', error: 'launcher path: --append-consented-by-surface requires --append.' };
+    }
+    return {
+      command: 'launcher-path',
+      append: Boolean(parsed.flags.append),
+      surfaceConsented: Boolean(parsed.flags['append-consented-by-surface']),
+      json: Boolean(parsed.flags.json),
+    };
+  }
+  if (sub === 'status') {
+    const parsed = parseOptions(rest, { flags: ['json'] });
+    if (parsed.help) return { command: 'launcher-help' };
+    if (parsed.error) return { command: 'invalid', error: `${parsed.error} for launcher status.` };
+    if (parsed.positionals.length) {
+      return { command: 'invalid', error: 'launcher status takes no positional arguments.' };
+    }
+    return { command: 'launcher-status', json: Boolean(parsed.flags.json) };
+  }
+  return { command: 'invalid', error: `Unknown launcher subcommand: ${sub} (expected: install | remove | path | status).` };
+}
+
+// `phronesis profile set` (core-0062 D1) — the non-destructive repair verb for the stamped
+// operator profile. Same value-flag grammar as init (--flag value / --flag=value); no --force.
+function parseProfileArgs(args) {
+  const [sub, ...rest] = args;
+  if (sub === undefined || sub === '--help' || sub === '-h') return { command: 'profile-help' };
+  if (sub !== 'set') return { command: 'invalid', error: `Unknown profile subcommand: ${sub} (expected: set).` };
+
+  let dir;
+  const VALUE_FLAGS = ['domain', 'name', 'role', 'company', 'working-style'];
+  const values = {};
+  for (let i = 0; i < rest.length; i += 1) {
+    const a = rest[i];
+    if (a === '--help' || a === '-h') return { command: 'profile-help' };
+    let matched = false;
+    for (const f of VALUE_FLAGS) {
+      if (a === `--${f}`) {
+        const v = rest[i + 1];
+        if (v === undefined || v.startsWith('--')) return { command: 'invalid', error: `Missing value for --${f}` };
+        values[f] = v;
+        i += 1;
+        matched = true;
+        break;
+      }
+      if (a.startsWith(`--${f}=`)) {
+        values[f] = a.slice(`--${f}=`.length);
+        matched = true;
+        break;
+      }
+    }
+    if (matched) continue;
+    if (a === '--dir') {
+      const v = rest[i + 1];
+      if (v === undefined || v.startsWith('--')) return { command: 'invalid', error: 'Missing value for --dir' };
+      dir = v;
+      i += 1;
+      continue;
+    }
+    if (a.startsWith('--dir=')) {
+      dir = a.slice('--dir='.length);
+      continue;
+    }
+    if (a.startsWith('-')) return { command: 'invalid', error: `Unknown option for profile set: ${a}` };
+    return { command: 'invalid', error: 'profile set takes no positional arguments (use --name, --role, --company, --working-style).' };
+  }
+  if (values.name === undefined && values.role === undefined && values.company === undefined && values['working-style'] === undefined) {
+    return { command: 'invalid', error: 'profile set: pass at least one of --name, --role, --company, --working-style.' };
+  }
+  return {
+    command: 'profile-set',
+    dir,
+    domain: values.domain,
+    name: values.name,
+    role: values.role,
+    company: values.company,
+    workingStyle: values['working-style'],
   };
 }
 
@@ -197,8 +370,9 @@ function parseLinksArgs(args) {
 // Compact option parser shared by the event commands (`--name value` / `--name=value` for
 // `values`, presence flags for `flags`, the rest positional). The older parsers above predate
 // it and stay hand-rolled; new multi-option commands use this to avoid the per-flag boilerplate.
-function parseOptions(args, { values = [], flags = [] } = {}) {
+function parseOptions(args, { values = [], multiValues = [], flags = [] } = {}) {
   const valueSet = new Set(values);
+  const multiValueSet = new Set(multiValues);
   const flagSet = new Set(flags);
   const out = { values: {}, flags: {}, positionals: [] };
   for (let i = 0; i < args.length; i += 1) {
@@ -208,10 +382,11 @@ function parseOptions(args, { values = [], flags = [] } = {}) {
       const eq = a.indexOf('=');
       const name = eq === -1 ? a.slice(2) : a.slice(2, eq);
       if (flagSet.has(name)) {
+        if (eq !== -1) return { error: `Presence flag --${name} does not accept a value` };
         out.flags[name] = true;
         continue;
       }
-      if (valueSet.has(name)) {
+      if (valueSet.has(name) || multiValueSet.has(name)) {
         if (eq === -1) {
           // A bare `--name` at the end, or one followed by another `--option`, is a missing
           // value — not "consume the next token". Swallowing it silently mislabels the next
@@ -220,10 +395,17 @@ function parseOptions(args, { values = [], flags = [] } = {}) {
           if (next === undefined || next.startsWith('--')) {
             return { error: `Missing value for --${name}` };
           }
-          out.values[name] = next;
+          if (multiValueSet.has(name)) {
+            if (!Array.isArray(out.values[name])) out.values[name] = [];
+            out.values[name].push(next);
+          } else out.values[name] = next;
           i += 1;
         } else {
-          out.values[name] = a.slice(eq + 1);
+          const value = a.slice(eq + 1);
+          if (multiValueSet.has(name)) {
+            if (!Array.isArray(out.values[name])) out.values[name] = [];
+            out.values[name].push(value);
+          } else out.values[name] = value;
         }
         continue;
       }
@@ -278,12 +460,26 @@ function parseEventArgs(args) {
 // and is rejected); flags carry execution context only. The approval signal is env
 // (PHRONESIS_APPROVAL_SOURCE), set by an approving adapter — deliberately not a flag.
 function parseActArgs(args) {
-  const p = parseOptions(args, { values: ['json', 'session', 'domain', 'actor', 'surface', 'dir', 'invocation-id'] });
+  const p = parseOptions(args, {
+    values: ['json', 'session', 'domain', 'actor', 'surface', 'dir', 'invocation-id'],
+    flags: ['schema'],
+  });
   if (p.help) return { command: 'act-help' };
   if (p.error) return { command: 'invalid', error: `${p.error} for act.` };
   if (p.positionals.length > 1) {
     return { command: 'invalid', error: 'act takes one <type> argument (semantic inputs go inside --json).' };
   }
+  // `--schema` is a read-only introspection of the effective payload schema — it does not
+  // run the action, so it is mutually exclusive with `--json` (describe vs execute).
+  if (p.flags.schema) {
+    if (p.values.json !== undefined) {
+      return {
+        command: 'invalid',
+        error: 'act --schema and --json are mutually exclusive: --schema prints the payload contract, --json executes against it.',
+      };
+    }
+    return { command: 'act-schema', type: p.positionals[0], dir: p.values.dir };
+  }
   const parsed = {
     command: 'act',
     type: p.positionals[0],
@@ -334,7 +530,7 @@ function parseCompileArgs(args) {
   // accept/reject are operator-driven by contract — no --actor (the events are always
   // actor: operator; the approval signal rides env PHRONESIS_APPROVAL_SOURCE, like act).
   if (sub === 'accept') {
-    const p = parseOptions(rest, { values: ['session', 'surface', 'dir'] });
+    const p = parseOptions(rest, { values: ['session', 'surface', 'dir', 'reviewed-digest'] });
     if (p.help) return { command: 'compile-help' };
     if (p.error) return { command: 'invalid', error: `${p.error} for compile accept.` };
     if (p.positionals.length !== 1) {
@@ -346,6 +542,9 @@ function parseCompileArgs(args) {
       session: p.values.session,
       surface: p.values.surface,
       dir: p.values.dir,
+      // --reviewed-digest <sha>: refuse in-child if the draft's current bytes differ from the bytes the
+      // operator reviewed (closes the accept byte-race at the true promotion boundary).
+      reviewedDigest: p.values['reviewed-digest'],
     };
   }
   if (sub === 'reject') {
@@ -366,7 +565,7 @@ function parseCompileArgs(args) {
   }
   if (sub === 'review') {
     const p = parseOptions(rest, {
-      values: ['domain', 'session', 'surface', 'dir', 'rationale'],
+      values: ['domain', 'session', 'surface', 'dir', 'rationale', 'approve-only'],
       flags: ['approve-all', 'resume', 'json'],
     });
     if (p.help) return { command: 'compile-help' };
@@ -382,6 +581,8 @@ function parseCompileArgs(args) {
       dir: p.values.dir,
       rationale: p.values.rationale,
       approveAll: Boolean(p.flags['approve-all']),
+      // --approve-only <comma-list>: restrict approve-all to a caller-reviewed subset (else all eligible).
+      approveOnly: p.values['approve-only'],
       resume: Boolean(p.flags.resume),
       json: Boolean(p.flags.json),
     };
@@ -441,7 +642,7 @@ function parseSkillsArgs(args) {
   if (sub === 'bump') {
     const p = parseOptions(rest, {
       values: ['to', 'repo', 'k', 'coverage-floor', 'quality-floor', 'rationale', 'accepted-by', 'judge-model', 'goldens-dir', 'domain'],
-      flags: ['accept-regression', 'rebaseline', 'shape-change', 'json'],
+      flags: ['accept-regression', 'rebaseline', 'verify-current', 'shape-change', 'json'],
     });
     if (p.help) return { command: 'skills-help' };
     if (p.error) return { command: 'invalid', error: `${p.error} for skills bump.` };
@@ -488,6 +689,7 @@ function parseSkillsArgs(args) {
       domain: p.values.domain,
       acceptRegression: Boolean(p.flags['accept-regression']),
       rebaseline: Boolean(p.flags.rebaseline),
+      verifyCurrent: Boolean(p.flags['verify-current']),
       shapeChange: Boolean(p.flags['shape-change']),
       json: Boolean(p.flags.json),
     };
@@ -532,6 +734,31 @@ function parseEvalArgs(args) {
 function parseHooksArgs(args) {
   const [sub, ...rest] = args;
   if (sub === undefined || sub === '--help' || sub === '-h') return { command: 'hooks-help' };
+  if (sub === 'refresh') {
+    const p = parseOptions(rest, {
+      values: ['dir'],
+      multiValues: ['apply'],
+      flags: ['apply-all', 'persist', 'no-persist'],
+    });
+    if (p.help) return { command: 'hooks-help' };
+    if (p.error) return { command: 'invalid', error: `${p.error} for hooks refresh.` };
+    if (p.positionals.length) {
+      return { command: 'invalid', error: 'hooks refresh takes no positional arguments.' };
+    }
+    if (p.flags.persist && p.flags['no-persist']) {
+      return { command: 'invalid', error: 'hooks refresh: --persist and --no-persist are mutually exclusive.' };
+    }
+    if (p.flags['apply-all'] && p.values.apply?.length) {
+      return { command: 'invalid', error: 'hooks refresh: --apply and --apply-all are mutually exclusive.' };
+    }
+    return {
+      command: 'hooks-refresh',
+      dir: p.values.dir,
+      apply: p.values.apply || [],
+      applyAll: Boolean(p.flags['apply-all']),
+      persist: p.flags.persist ? true : p.flags['no-persist'] ? false : undefined,
+    };
+  }
   if (sub === 'due-check') {
     const p = parseOptions(rest, { values: ['session', 'dir', 'actor', 'surface'] });
     if (p.help) return { command: 'hooks-help' };
@@ -618,12 +845,31 @@ function parseHooksArgs(args) {
     command: 'invalid',
     error:
       `Unknown hooks subcommand: ${sub} ` +
-      '(expected: due-check | sweep-status | skill-start | skill-complete | skill-abandon | skill-sweep-stale).',
+      '(expected: refresh | due-check | sweep-status | skill-start | skill-complete | skill-abandon | skill-sweep-stale).',
+  };
+}
+
+function parseHookArgs(args) {
+  const p = parseOptions(args, { values: ['surface', 'mode'] });
+  if (p.help) return { command: 'hook-help' };
+  if (p.error) return { command: 'invalid', error: `${p.error} for hook.` };
+  if (p.positionals.length !== 1) {
+    return { command: 'invalid', error: 'hook takes exactly one <event> argument.' };
+  }
+  if (!p.values.surface) {
+    return { command: 'invalid', error: 'hook requires --surface <surface>.' };
+  }
+  return {
+    command: 'hook',
+    event: p.positionals[0],
+    surface: p.values.surface,
+    mode: p.values.mode,
   };
 }
 
 // `adapter test <surface>` — the per-surface adapter self-check (specs/tech-stack.md
-// §"Adapter test command"; change 0028 / core-0034). V1 ships `adapter test codex`.
+// §"Adapter test command"; change 0028 / core-0034; change 0055). V1 ships `adapter test codex`
+// and `adapter test desktop`.
 function parseAdapterArgs(args) {
   const [sub, ...rest] = args;
   if (sub === undefined || sub === '--help' || sub === '-h') return { command: 'adapter-help' };
@@ -632,7 +878,7 @@ function parseAdapterArgs(args) {
     if (p.help) return { command: 'adapter-help' };
     if (p.error) return { command: 'invalid', error: `${p.error} for adapter test.` };
     if (p.positionals.length !== 1) {
-      return { command: 'invalid', error: 'adapter test takes one <surface> argument (V1: codex).' };
+      return { command: 'invalid', error: 'adapter test takes one <surface> argument (V1: codex, desktop).' };
     }
     return {
       command: 'adapter-test',
@@ -818,6 +1064,7 @@ Usage: phronesis <command>
 
 Commands:
   init [dir]      Create a Phronesis installation (default dir: phronesis-installation)
+  launcher <sub>  Install or remove the managed command dispatcher
   export [dir]    Tar an installation into a portable archive (default dir: current)
   validate [dir]  Check compiled + codex objects against the ontology contract
   search <query>  Stage 1 retrieval — BM25 over active-domain compiled/ + shared codex
@@ -832,7 +1079,8 @@ Commands:
   registry <sub>  Show the install's action-type + hook registry (status)
   skills <sub>    Show the install's skill registry (status)
   eval <sub>      Local eval data viewer (view) — goldens, scores, candidate output
-  hooks <sub>     Session-boundary hooks: due-check, sweep-status
+  hook <event>    Surface hook dispatcher (stdin JSON → surface-shaped stdout)
+  hooks <sub>     Refresh installed hook wiring; session-boundary hook support
   adapter <sub>   Per-surface adapter self-check (test codex)
   guard           Prompt-submit recall guard (stdin-only)
   ingest <source> Stage one URL, file, or stdin paste into domain raw/
@@ -851,6 +1099,7 @@ function showInitHelp() {
     `
 Usage: phronesis init [dir] [--force] [--domain <slug>]
                       [--name <name>] [--role <role>] [--company <co>] [--working-style <style>]
+                      [--persist | --no-persist]
 
 Creates a three-layer installation at [dir]:
   codex/             shared principles across all domains (seed + personal)
@@ -862,13 +1111,86 @@ install does not load [Name]/[Role] placeholders. On an interactive terminal, a
 missing name/role is prompted; a non-interactive (scripted/CI) init never prompts
 or blocks — it completes and leaves the placeholders.
 
+On an interactive terminal, init asks once whether to install the managed
+\`phronesis\` command for automatic hooks. --persist opts in for scripts;
+--no-persist suppresses the interactive persistence prompt.
+
 Options:
   --force, -f          Replace a non-empty target directory
   --domain <slug>      Domain workspace to create (default: pm)
-  --name <name>        Operator name (fills USER.md + AGENTS.md §1)
-  --role <role>        Operator role
-  --company <co>       Operator company (USER.md only; optional)
-  --working-style <s>  Operator working style (USER.md only; optional)
+  --name <name>        Operator name, max 48 chars (fills USER.md + AGENTS.md §1)
+  --role <role>        Operator role, max 48 chars
+  --company <co>       Operator company, max 64 chars (USER.md only; optional)
+  --working-style <s>  Operator working style, max 80 chars (USER.md only; optional)
+  --persist             Install the managed command after workspace creation
+  --no-persist          Do not install or prompt to install the managed command
+`.trim(),
+  );
+}
+
+function showLauncherHelp() {
+  console.log(
+    `
+Usage: phronesis launcher install [--force-launcher] [--no-path-offer]
+       phronesis launcher install --backend app --app-target <absolute cli.js>
+                                  --app-runtime <absolute Electron> [--app-version <asserted-version>]
+                                  [--if-owned] [--force-launcher] [--no-path-offer]
+                                  [--expect-absent | --expect-owner <backend> --expect-version <version>]
+       phronesis launcher remove [--backend app|self-copy] [--force-launcher]
+       phronesis launcher path [--append] [--append-consented-by-surface] [--json]
+       phronesis launcher status [--json]
+
+Installs or removes the managed command at ~/.phronesis/bin/phronesis. Install
+defaults to a self-copy generation. App mode records an installed app's bundled
+CLI and Electron runtime without copying either one. Both modes commit by atomically
+renaming launcher.env. Remove is backend-owner-checked and removes the manifest
+before the dispatcher. Cross-backend replacement requires --force-launcher. The path
+command reports the exact shell-profile edit; --append prompts on a TTY and never
+writes off-TTY without the documented consenting-surface integration flag.
+
+Options:
+  --force-launcher  Replace/remove a foreign owner, invalid or unreadable manifest, or unowned
+                    dispatcher; also permits a downgrade. Ownership by another uid is never overridden.
+  --backend          Launcher owner: app or self-copy (default: self-copy).
+  --app-target       Absolute bundled cli.js path (app installs only).
+  --app-runtime      Absolute Electron executable path (app installs only).
+  --app-version      Optional assertion; must match the target package.json version.
+  --if-owned         Re-stamp only when a valid app-owned manifest already exists; cannot be
+                    combined with the --expect-* disclosure-binding options.
+  --expect-absent    Refuse if the launcher slot changed since an absent-slot disclosure.
+  --expect-owner     Expected prior app|self-copy owner; requires --expect-version.
+  --expect-version   Expected prior version; requires --expect-owner.
+  --no-path-offer    Commit the launcher without the terminal PATH offer.
+  --append           On a TTY, disclose and confirm before appending; off-TTY, print only.
+  --append-consented-by-surface
+                    Off-TTY only: append after the calling surface has shown the exact file
+                    and line and received operator confirmation, then print both as a record.
+                    On a TTY this still discloses and prompts. Integration surfaces only;
+                    scripts must not pass this flag.
+  --json             Print launcher path/status data as JSON.
+`.trim(),
+  );
+}
+
+function showProfileHelp() {
+  console.log(
+    `
+Usage: phronesis profile set [--name <name>] [--role <role>]
+                             [--company <co>] [--working-style <style>] [--domain <slug>] [--dir <install>]
+
+Updates the stamped operator profile in place — the non-destructive repair verb for an
+install that still carries [Name]/[Role] placeholders (a scripted init leaves them) or a
+profile that has changed. Touches only the stamped field lines in USER.md and the always-loaded
+AGENTS.md §1 operator line; never rewrites surrounding operator prose, and never needs --force.
+If a field line cannot be located uniquely, it fails closed and points you at the file to edit.
+
+Options:
+  --name <name>        Operator name, max 48 chars (updates USER.md + AGENTS.md §1)
+  --role <role>        Operator role, max 48 chars
+  --company <co>       Operator company, max 64 chars (USER.md only)
+  --working-style <s>  Operator working style, max 80 chars (USER.md only)
+  --domain <slug>      Domain whose profile to update (default: the sole registered domain)
+  --dir <install>      Installation root (default: walk up to .phronesis/registry.json)
 `.trim(),
   );
 }
@@ -965,12 +1287,17 @@ function showActHelp() {
   console.log(
     `
 Usage: phronesis act <type> --json '<payload>' --session <id> [--domain <slug>] [--actor <a>] [--surface <s>] [--invocation-id <id>] [--dir <install>]
+       phronesis act <type> --schema [--dir <install>]
 
 The action-type execution floor (specs/ontology.md §"Action type contract") — plumbing,
 not porcelain: skills compose it; it is not a promoted operator verb. One shared core
 runs every action: schema validation, permission gate, action_type.requested/committed
 events, and a staged atomic write that must pass the ontology contract before it lands.
 
+Use --schema to PRINT a type's effective payload schema (fields, kinds, required markers,
+and enum values) instead of running it — a read-only introspection of the same registry
+table --json is validated against. --schema and --json are mutually exclusive.
+
 Registered types: log_decision, enrich_person, update_project_state,
 track_commitment, record_outcome, promote_to_codex (handlers: core-0009/0010),
 compile (the agentic quality-gate writer for insight + organization, core-0017 — review
@@ -983,13 +1310,15 @@ table (operator overrides in .phronesis/registry.json action_types) is shown by
                      validated. Execution context never goes here.
   --session <id>     Session the action belongs to (required).
   --domain <slug>    Domain workspace (default: the domains/<slug>/ the cwd is inside,
-                     else "pm"). Must be registered in the installation.
+                     else the sole registered domain; several registered → pass one).
   --actor <a>        Defaults to $PHRONESIS_ACTOR, else 'agent'.
   --surface <s>      Defaults to 'cli'.
   --invocation-id <i> Attribution provenance for a surrounding skill invocation. It is
                      caller-controlled (not an authority); adapters and the eval harness
                      may supply it. PHRONESIS_INVOCATION_ID is the equivalent env input.
   --dir <install>    Installation root (default: walk up to .phronesis/registry.json).
+  --schema           Print <type>'s effective payload schema and exit (read-only; no
+                     write, no event). Mutually exclusive with --json.
 
 Approval-gated actions refuse without an approval signal: the env var
 PHRONESIS_APPROVAL_SOURCE (e.g. operator:interactive), set by an approving adapter and
@@ -1039,7 +1368,7 @@ function showCompileHelp() {
 Usage:
   phronesis compile accept <draft_path> --session <id> [--dir <install>] [--surface <s>]
   phronesis compile reject <draft_path> --session <id> [--reason '<why>'] [--dir <install>] [--surface <s>]
-  phronesis compile review --session <id> [--domain <slug>] [--approve-all --rationale '<why>'] [--resume] [--json]
+  phronesis compile review --session <id> [--domain <slug>] [--approve-all --rationale '<why>'] [--approve-only '<p1,p2>'] [--resume] [--json]
 
 The operator review primitives over a compile candidate (specs/security.md draft
 lifecycle; core-0017 H9). An untrusted compile stages a draft under .phronesis/drafts/ and
@@ -1069,8 +1398,11 @@ review:  The batch-approval UX over the same per-draft accept move (T7.5). Lists
   <draft_path>       (accept/reject) The .phronesis/drafts/{domain}/{type-dir}/{name}.md candidate.
   --session <id>     Review session the events belong to (required).
   --reason '<why>'   (reject) recorded on compile.rejected.
-  --domain <slug>    (review) Domain whose drafts to review (default: pm).
+  --domain <slug>    (review) Domain whose drafts to review (default: the sole registered domain; several registered → pass one).
   --approve-all      (review) Promote the provably-clean set as one batch.
+  --approve-only '<p1,p2>' (review) Restrict --approve-all to a caller-reviewed SUBSET (drafts the
+                     operator confirmed); an eligible-but-unreviewed draft is not promoted. Absent →
+                     all eligible. A subset filter only — digest/suspicious eligibility is unchanged.
   --rationale '<why>'(review) Required with --approve-all; recorded on every batch compile.accepted.
   --resume           (review) Reconcile a crashed batch from the durable journal.
   --json             (review) Emit the plan / result as JSON.
@@ -1164,6 +1496,8 @@ a repo root (skills/ + changes/ present), never an install.
   --rebaseline         Reset the comparison basis after evaluation-identity drift: re-seed
                        the baseline under the new identity (absolute floor on both axes,
                        no regression check) and write a rebaseline record
+  --verify-current     Certify the already-deployed --to pin and seed/refresh PINS.md
+                       without changing the skill version or prompt_pin
   --coverage-floor <f> Min per-run warranted-capture hit-rate (default: 1.0)
   --quality-floor <f>  Min per-criterion score across k runs (default: 4)
   --rationale <text>   Recorded on an override / rebaseline record
@@ -1220,6 +1554,8 @@ function showHooksHelp() {
   console.log(
     `
 Usage:
+  phronesis hooks refresh [--dir <install>] [--apply <path> ... | --apply-all]
+                          [--persist | --no-persist]
   phronesis hooks due-check --session <id> [--actor <a>] [--surface <s>] [--dir <install>]
   phronesis hooks sweep-status --session <id> [--json] [--dir <install>]
   phronesis hooks skill-start --payload '<hook-json>' [--dir <install>]
@@ -1227,6 +1563,20 @@ Usage:
   phronesis hooks skill-abandon --payload '<hook-json>' [--json] [--dir <install>]
   phronesis hooks skill-sweep-stale --session <id> [--json] [--dir <install>]
 
+refresh:        Reports every init-derived hook-manifest path as current / differs /
+                missing, plus unknown siblings as extra-unknown (never touched). The
+                default is report-only off-TTY. Writes require per-path --apply or
+                --apply-all; blanket approval covers only safely attributable stamped
+                updates. Unstamped or operator-modified paths require targeted per-path
+                approval. Restamps re-check reviewed bytes at the final atomic/no-follow
+                write boundary and update only .phronesis/hook-stamp.json, never
+                the broader upgrade baseline. .claude/settings.json receives a bounded
+                Phronesis-hook-entry merge that preserves operator settings and hooks.
+                If the launcher is absent or self-copy-owned but stale, --persist
+                installs/repairs it off-TTY; --no-persist suppresses the TTY offer.
+                App-owned or ownership-unreadable launchers are reported and never
+                force-replaced by this hook migration.
+
 Session-boundary hook support (specs/hooks.md §"Emission discipline"; change 0010 D4).
 The scaffolded Claude Code hooks (.phronesis/hooks/session-start.sh, session-sweep.sh,
 skill-lifecycle.sh) shell out to these; any Tier-1 surface adapter can do the same.
@@ -1254,18 +1604,50 @@ skill-start / skill-complete / skill-abandon / skill-sweep-stale:
   );
 }
 
+function showHookHelp() {
+  console.log(
+    `
+Usage: phronesis hook <event> --surface <surface> [--mode <start|abandon>]
+
+The resolved executable interface used by emitted surface hooks (change 0065). It reads
+the surface event JSON from stdin, runs the deterministic hook logic in this CLI process,
+and emits the surface's required stdout shape. Hook scripts resolve one managed-first
+executable and contain no JSON parser or nested runtime invocation.
+
+Events:
+  recall-guard
+  session-start
+  session-sweep
+  session-sweep-subagent
+  session-sweep-precompact
+  skill-lifecycle          (--mode start|abandon)
+  compile-active-context
+
+Options:
+  --surface <surface>      Surface attribution/output contract (claude-code or codex)
+  --mode <mode>            skill-lifecycle variant: start or abandon
+`.trim(),
+  );
+}
+
 function showAdapterHelp() {
   console.log(
     `
 Usage: phronesis adapter test <surface> [--dir <install>] [--domain <slug>] [--json]
 
 The per-surface adapter self-check (specs/tech-stack.md §"Adapter test command";
-specs/event-log.md §"Adapter test"). V1 ships the Codex adapter test.
+specs/event-log.md §"Adapter test"). V1 ships the Codex and Craft Phronesis Desktop adapter tests.
+
+adapter test desktop (change 0055) — auto-asserts the first-party in-process reinforcement +
+lifecycle CONTRACT via @phronesis/core against a throwaway synthetic install: three guard fixtures
+(seeded-state injection / no-cue / honest-negative), due-check surfacing, sweep block-once, and no
+fabricated skill.invoked/completed on the error path. The live app UI half stays operator-verified.
 
 adapter test codex — asserts the deterministic mechanics of the project-local Codex
 wiring (change 0028 / core-0034): domains/<slug>/.codex/hooks.json wires each native
-event to its bare-path launcher, the launchers resolve the install root and hand off to
-the shared .phronesis/hooks/ scripts, and an unswept Stop yields {"decision":"block"}.
+event to its bare-path launcher, the launchers resolve the install root and bind stdin
+directly to phronesis hook <event> --surface codex, and an unswept Stop yields
+{"decision":"block"}.
 It reports the compliance LEVEL — Level 1 (reinforcement: recall / due-check / sweep) and
 Level 2 (skill-lifecycle), which is PARTIAL on Codex (no UserPromptExpansion/StopFailure;
 no fabricated skill.invoked/completed) — and points at the operator-verified desktop-app
@@ -1274,7 +1656,10 @@ It is read-only: no canonical state is written and no events are emitted.
 
 Open Codex AT the domain workspace dir (Codex loads .codex/ only from the opened
 directory, no parent-walk) and trust the project hooks (CLI /hooks, or the app's
-Settings → Coding → Hooks). Editing the config re-hashes the hooks → re-trust required.
+Settings → Coding → Hooks). Empirically verified 2026-07-18 on Codex
+v0.145.0-alpha.18, per-hook trust keys on the hooks.json registration, not script
+bytes: launcher/_resolve.sh edits did not invalidate trust; a changed config should
+show the review banner. This is version-scoped and may change in later Codex versions.
 
 Options:
   --dir <install>      Installation root (default: walk up to .phronesis/registry.json)
@@ -1326,7 +1711,7 @@ Arguments:
   query                The search text (quote it)
 
 Options:
-  --domain <slug>      Domain scope (default: the domains/<slug>/ the cwd is inside, else "${DEFAULT_DOMAIN}")
+  --domain <slug>      Domain scope (default: the domains/<slug>/ the cwd is inside, else the sole registered domain)
   --all-domains        Search every domain (default scope is one domain + codex)
   --include-artifacts  Explicitly include durable artifacts for this search (not indexed by default)
   --limit N            Max results (default: 10)
@@ -1347,7 +1732,7 @@ decisions, the people involved, and the raw sources they cite (per-result "sourc
 Semantic rerank (Stage 3) is V1.5+/BYO; this surface stays the same.
 
 Options:
-  --domain <slug>      Domain scope (default: the domains/<slug>/ the cwd is inside, else "${DEFAULT_DOMAIN}")
+  --domain <slug>      Domain scope (default: the domains/<slug>/ the cwd is inside, else the sole registered domain)
   --all-domains        Query every domain (default scope is one domain + codex)
   --include-artifacts  Explicitly include durable artifacts for this query (not indexed by default)
   --limit N            Max seed results (default: 10)
@@ -1372,7 +1757,7 @@ It writes nothing: no compiled edits, no raw/degraded captures, no events, no dr
 and no machine-index repair.
 
 Options:
-  --domain <slug>      Domain scope (default: the active domain, else "${DEFAULT_DOMAIN}")
+  --domain <slug>      Domain scope (default: the active domain, else the sole registered domain)
   --all-domains        Lint every registered domain
   --stale-months N     Staleness threshold for forward refs and seed adoption (default: 6)
   --json               Emit the machine-readable lint envelope
@@ -1388,15 +1773,16 @@ Usage: phronesis doctor [--dir <install>] [--json]
 
 Read-only install-health overview — the dogfood "is my install wired correctly?"
 command. Composes existing diagnostics into a one-screen OK / warn / fail report:
-install root, registered domain(s), skill registry, hook wiring, Codex surface-adapter
-status, USER.md placeholder check, and pending-draft count.
+install root, managed launcher/manifest integrity, registered domain(s), skill registry,
+hook wiring, Codex surface-adapter status, USER.md placeholder check, and pending-draft count.
 
 It writes nothing to the install and emits no events (the install is byte-identical
 after a run). It reports; it does not fix.
 
 Exit is non-zero only on a FAIL check (no/invalid/unreadable install, an invalid skill
-registry). WARN checks (incomplete hook wiring, a non-compliant Codex adapter, USER.md
-placeholders, pending drafts) are informational and never fail the command.
+registry). WARN checks (missing or non-compliant launcher state, incomplete hook wiring,
+a non-compliant Codex adapter, USER.md placeholders, pending drafts) are informational
+and never fail the command.
 
 Options:
   --dir <install>      Installation root (default: walk up to .phronesis/registry.json)
@@ -1490,6 +1876,12 @@ async function run(argv) {
     case 'init-help':
       showInitHelp();
       break;
+    case 'launcher-help':
+      showLauncherHelp();
+      break;
+    case 'profile-help':
+      showProfileHelp();
+      break;
     case 'export-help':
       showExportHelp();
       break;
@@ -1529,6 +1921,9 @@ async function run(argv) {
     case 'hooks-help':
       showHooksHelp();
       break;
+    case 'hook-help':
+      showHookHelp();
+      break;
     case 'adapter-help':
       showAdapterHelp();
       break;
@@ -1566,6 +1961,78 @@ async function run(argv) {
         role: parsed.role,
         company: parsed.company,
         workingStyle: parsed.workingStyle,
+        persist: parsed.persist,
+      });
+      break;
+    }
+    case 'launcher-install': {
+      const [{ runLauncherInstall }, { confirmPathAppend }] = await Promise.all([
+        import('./launcher.js'),
+        import('./prompts.js'),
+      ]);
+      try {
+        await runLauncherInstall({
+          forceLauncher: parsed.forceLauncher,
+          backend: parsed.backend,
+          appTarget: parsed.appTarget,
+          appRuntime: parsed.appRuntime,
+          appVersion: parsed.appVersion,
+          ifOwned: parsed.ifOwned,
+          offerPath: parsed.offerPath,
+          expectedPrior: parsed.expectedPrior,
+          promptPath: confirmPathAppend,
+        });
+      } catch (error) {
+        console.error(`Launcher install failed: ${error.message}`);
+        process.exitCode = 1;
+      }
+      break;
+    }
+    case 'launcher-remove': {
+      const { runLauncherRemove } = await import('./launcher.js');
+      try {
+        await runLauncherRemove({ forceLauncher: parsed.forceLauncher, backend: parsed.backend });
+      } catch (error) {
+        console.error(`Launcher remove failed: ${error.message}`);
+        process.exitCode = 1;
+      }
+      break;
+    }
+    case 'launcher-path': {
+      const [{ runLauncherPath }, { confirmPathAppend }] = await Promise.all([
+        import('./launcher.js'),
+        import('./prompts.js'),
+      ]);
+      try {
+        await runLauncherPath({
+          append: parsed.append,
+          surfaceConsented: parsed.surfaceConsented,
+          json: parsed.json,
+          prompt: confirmPathAppend,
+        });
+      } catch (error) {
+        console.error(`Launcher PATH update failed: ${error.message}`);
+        process.exitCode = 1;
+      }
+      break;
+    }
+    case 'launcher-status': {
+      const { launcherStatus } = await import('./launcher.js');
+      const status = launcherStatus();
+      if (parsed.json) console.log(JSON.stringify(status));
+      else if (!status.exists) console.log('Managed `phronesis` command is not installed.');
+      else console.log(`Managed command owner=${status.owner ?? 'unrecognized'}, version=${status.version ?? 'unknown'}.`);
+      break;
+    }
+    case 'profile-set': {
+      const { runProfileSet } = await import('./profile.js');
+      await runProfileSet({
+        dir: parsed.dir,
+        domain: parsed.domain,
+        name: parsed.name,
+        role: parsed.role,
+        company: parsed.company,
+        workingStyle: parsed.workingStyle,
       });
       break;
     }
@@ -1637,6 +2104,11 @@ async function run(argv) {
       });
       break;
     }
+    case 'act-schema': {
+      const { runActSchema } = await import('./act.js');
+      await runActSchema({ type: parsed.type, dir: parsed.dir });
+      break;
+    }
     case 'ingest': {
       const { runIngest } = await import('./ingest.js');
       await runIngest({
@@ -1662,6 +2134,7 @@ async function run(argv) {
         session: parsed.session,
         surface: parsed.surface,
         dir: parsed.dir,
+        reviewedDigest: parsed.reviewedDigest,
       });
       break;
     }
@@ -1685,6 +2158,7 @@ async function run(argv) {
         dir: parsed.dir,
         rationale: parsed.rationale,
         approveAll: parsed.approveAll,
+        approveOnly: parsed.approveOnly,
         resume: parsed.resume,
         json: parsed.json,
       });
@@ -1727,6 +2201,7 @@ async function run(argv) {
         k: parsed.k,
         acceptRegression: parsed.acceptRegression,
         rebaseline: parsed.rebaseline,
+        verifyCurrent: parsed.verifyCurrent,
         shapeChange: parsed.shapeChange,
         qualityFloor: parsed.qualityFloor,
         coverageFloor: parsed.coverageFloor,
@@ -1749,6 +2224,21 @@ async function run(argv) {
       });
       break;
     }
+    case 'hooks-refresh': {
+      const { runHooksRefresh } = await import('./hooks-refresh.js');
+      try {
+        await runHooksRefresh({
+          dir: parsed.dir,
+          apply: parsed.apply,
+          applyAll: parsed.applyAll,
+          persist: parsed.persist,
+        });
+      } catch (error) {
+        console.error(`hooks refresh failed: ${error.message}`);
+        process.exitCode = 1;
+      }
+      break;
+    }
     case 'hooks-sweep-status': {
       const { runHooksSweepStatus } = await import('./hooks.js');
       await runHooksSweepStatus({ session: parsed.session, dir: parsed.dir, json: parsed.json });
@@ -1780,6 +2270,11 @@ async function run(argv) {
       await runHooksSkillSweepStale({ session: parsed.session, dir: parsed.dir, json: parsed.json });
       break;
     }
+    case 'hook': {
+      const { runHook } = await import('./hook.js');
+      await runHook({ event: parsed.event, surface: parsed.surface, mode: parsed.mode });
+      break;
+    }
     case 'adapter-test': {
       const { runAdapterTest } = await import('./adapter.js');
       await runAdapterTest({
@@ -1880,7 +2375,7 @@ async function run(argv) {
   }
 }
 
-export { parseArgs, run, showHelp, showInitHelp };
+export { parseArgs, run, showHelp, showInitHelp, showLauncherHelp, showHooksHelp };
 
 if (process.argv[1]) {
   try {