@sabaiway/agent-workflow-kit 14.19.1 → 14.21.0

package/tools/jev-facts.mjs

@@ -1,8 +1,10 @@
 // spec:jev-guide — docs/ai/specs/kit/jev-guide/index.md
-// The one leaf the Jev surfaces share: the key rule, the connect line, and the vendor facts the
-// connect command's one request uses. No side effect, no import beyond node:path — the read-only
-// guide imports it under its closed import graph, the advisor and the connect command beside it.
-import { join } from 'node:path';
+// The one leaf the Jev surfaces share: the key rule, the connect line, the vendor facts the connect
+// command's one request uses, and the vendor skill's pin, targets, state rule and apply line. No side
+// effect, no import beyond node:path and node:crypto — the read-only guide imports it under its closed
+// import graph, the advisor and the two commands beside it; file primitives arrive through `io`.
+import { createHash } from 'node:crypto';
+import { join, posix, win32 } from 'node:path';
 
 export const KEY_VARIABLE = 'TYPESAFE_API_KEY';
 
@@ -56,3 +58,98 @@ export const JEV_ERROR_MEANINGS = Object.freeze({
   429: 'You have exceeded your rate limit. Back off and retry after a short delay.',
   529: 'TypeSafe is temporarily overloaded. Retry after a short delay.',
 });
+
+// ── the vendor skill (part jev-skill) ─────────────────────────────────────────────────────────────
+// Each target file name -> the name the kit ships it under. The shipped SKILL.md is renamed so no agent
+// walking the kit's own tree (a skill folder itself) loads the vendor's text before the user's --apply.
+export const SKILL_FILES = Object.freeze({ 'SKILL.md': 'SKILL.md.pinned', LICENSE: 'LICENSE' });
+// Newest first; a release that moves the pin puts the new entry first and removes none.
+export const SKILL_PINS = Object.freeze([Object.freeze({
+  tag: 'v0.5.7',
+  commit: '65a39f393687675ce170e6094757de20370365b9',
+  digests: Object.freeze({
+    'SKILL.md': '71ea90d7906c6554c4f4c460ef7361b2d26f59116ccdae986dc6d997b9389f52',
+    LICENSE: '835f233f1d6ed84a9b9a351aba0689b47644a4137d6316911fc7957bde523b02',
+  }),
+})]);
+export const AFTER_INSTALL = 'After an install, quit the agent and start it again from a new terminal.';
+export const NO_APPLY_LINE = 'the apply line cannot be printed here: a path holds a control character';
+
+const isControl = (char) => char.charCodeAt(0) < 0x20 || char.charCodeAt(0) === 0x7f;
+// Display only: every path, entry name and reason a surface prints; never a command line.
+export const printable = (text) => [...String(text)].map((char) => (isControl(char) ? '?' : char)).join('');
+
+// The Claude Code dir the agent's environment names: an absolute CLAUDE_CONFIG_DIR for the platform, else <home>/.claude.
+export const claudeDirOf = (env = {}, home = '', platform) => {
+  const value = env.CLAUDE_CONFIG_DIR;
+  const set = typeof value === 'string' && value !== '';
+  if (set && (platform === 'win32' ? win32 : posix).isAbsolute(value)) return { dir: value, fromEnv: true, note: '' };
+  const dir = home === '' ? '' : join(home, '.claude');
+  return { dir, fromEnv: false,
+    note: set ? printable(`CLAUDE_CONFIG_DIR is set to ${value}, not an absolute path: the Claude Code target is ${dir}`) : '' };
+};
+
+// The host separator, read off the host's own join.
+const SEP = join('a', 'b').slice(1, -1);
+const within = (path, dir) => path.startsWith(dir.endsWith(SEP) ? dir : `${dir}${SEP}`);
+// The three targets in their order; a later record on an earlier one's path merges into it, and a later
+// record inside an earlier one's path, or holding it, carries `overlaps`.
+export const skillTargets = ({ home = '', claudeDir = '' } = {}) => {
+  if (home === '') return [];
+  const records = [
+    { agent: 'Codex', base: home, root: join(home, '.agents', 'skills') },
+    { agent: 'Claude Code', base: within(claudeDir, home) ? home : claudeDir, root: join(claudeDir, 'skills') },
+    { agent: 'Antigravity CLI', base: home, root: join(home, '.gemini', 'config', 'skills') },
+  ].map((record) => ({ ...record, path: join(record.root, 'typesafe-ai') }));
+  return records.reduce((kept, record) => {
+    const same = kept.find(({ path }) => path === record.path);
+    if (same) return kept.map((item) => (item === same ? { ...item, agent: `${item.agent} and ${record.agent}` } : item));
+    const other = kept.find(({ path }) => within(record.path, path) || within(path, record.path));
+    return [...kept, other ? { ...record, overlaps: other.path } : record];
+  }, []);
+};
+
+const digestOf = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const codeOf = (error) => error?.code ?? error?.message ?? String(error);
+// The state of one target, by content and never by name; pure over io.lstat, io.readdir, io.readFile and io.pins.
+export const skillState = (target, io) => {
+  const foreign = (reason) => ({ state: 'foreign', tag: null, reason });
+  if (target.overlaps) return foreign(`overlaps ${target.overlaps}`);
+  const pins = io.pins ?? SKILL_PINS;
+  try {
+    const names = target.path.slice(target.base.length).split(SEP).filter(Boolean);
+    let at = target.base;
+    for (const [index, name] of names.entries()) {
+      at = join(at, name);
+      let stat;
+      try { stat = io.lstat(at); } catch (error) {
+        if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return { state: 'absent', tag: null, reason: null };
+        return foreign(codeOf(error));
+      }
+      if (stat.isSymbolicLink()) return foreign(`a link at ${at}`);
+      if (!stat.isDirectory()) return foreign(index === names.length - 1 ? 'not a directory' : `${at} is not a directory`);
+    }
+    const entries = [...io.readdir(target.path)].map(String).sort();
+    if (entries.join('/') !== 'LICENSE/SKILL.md') return foreign(`holds ${entries.join(', ') || 'no entry'}`);
+    for (const name of entries) {
+      if (!io.lstat(join(target.path, name)).isFile()) return foreign(`${name} is not a regular file`);
+    }
+    const found = Object.fromEntries(entries.map((name) => [name, digestOf(io.readFile(join(target.path, name)))]));
+    const pinAt = pins.findIndex(({ digests }) => Object.keys(SKILL_FILES).every((name) => digests[name] === found[name]));
+    if (pinAt === 0) return { state: 'current', tag: pins[0].tag, reason: null };
+    if (pinAt > 0) return { state: 'earlier', tag: pins[pinAt].tag, reason: null };
+    return foreign('matches no pin');
+  } catch (error) {
+    return foreign(codeOf(error));
+  }
+};
+
+// The skill command's apply line, always with the Claude Code dir its caller resolved; '' when a path holds a control byte.
+export const skillLine = (toolsDir, platform, claudeDir) => {
+  if ([...`${toolsDir}${claudeDir}`].some(isControl)) return '';
+  if (platform === 'win32') {
+    const quoted = (value) => `'${value.replace(/'/g, "''")}'`;
+    return `node ${quoted(`${toolsDir}\\jev-skill.mjs`)} --apply --claude-dir ${quoted(claudeDir)}`;
+  }
+  return `node ${quoteArg(join(toolsDir, 'jev-skill.mjs'))} --apply --claude-dir ${quoteArg(claudeDir)}`;
+};

package/tools/jev-guide.mjs

@@ -1,17 +1,17 @@
 #!/usr/bin/env node
 // spec:jev-guide — docs/ai/specs/kit/jev-guide/index.md
-import { statSync } from 'node:fs';
+import { lstatSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { homedir, hostname } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { fail } from '../references/scripts/markdown-blocks.mjs';
 import { isDirectRun } from './direct-run.mjs';
-import { KEY_VARIABLE, RESTART_STEP, connectLine, keySet, placeOf } from './jev-facts.mjs';
+import { AFTER_INSTALL, KEY_VARIABLE, NO_APPLY_LINE, RESTART_STEP, SKILL_PINS, claudeDirOf, connectLine, keySet, placeOf, printable, skillLine, skillState, skillTargets } from './jev-facts.mjs';
 
 const SCHEMA = 1;
 const TOOLS = dirname(fileURLToPath(import.meta.url));
 const SKILL_FILE = join('typesafe-ai', 'SKILL.md');
-const HELP = `jev — read-only: what Jev (TypeSafe) is, why it pays here, and the two steps to a set key.
+const HELP = `jev — read-only: what Jev (TypeSafe) is, why it pays here, and the two steps: the key and the vendor skill.
 
 Usage:
   node jev-guide.mjs [--dir PROJECT] [--json]
@@ -22,7 +22,7 @@ Usage:
 
 Exit codes: 0 rendered; 1 nothing rendered (a --dir that is not a directory); 2 usage.
 
-Reads only: the --dir, the home directory, the key variable's presence, five skill paths, and for the place WSL_DISTRO_NAME, SSH_CONNECTION, REMOTE_CONTAINERS, CODESPACES, the platform, the hostname and /.dockerenv; no network.`;
+Reads only: the --dir, the home directory, the key variable's presence, CLAUDE_CONFIG_DIR, five skill paths, the three skill targets, and for the place WSL_DISTRO_NAME, SSH_CONNECTION, REMOTE_CONTAINERS, CODESPACES, the platform, the hostname and /.dockerenv; no network.`;
 
 export const JEV_TEXT = Object.freeze([
   'WHAT: Jev is a decision model: it takes a state and typed questions (choice, score, noul) and returns typed answers with probabilities and a confidence; it does not write text.',
@@ -49,8 +49,10 @@ const KEY_CONNECT = 'Connect it from a terminal of your own, never through the a
 const KEY_RESTART = `Then ${RESTART_STEP}. Run /agent-workflow-kit jev again: the key mark should read set.`;
 const KEY_NEVER = 'Never paste the key into the chat or into a project file.';
 const KEY_NOT_SET = `key: ${KEY_VARIABLE} not set. A host setting that filters the environment of the agent's commands also hides it. If it still reads not set after that restart and no such setting applies, run the connect line again and follow its last line.`;
+const SKILL_OPTIONAL = 'Optional, for your own code and prompts — the vendor skill. The kit installs it pinned, one verified copy per agent skill root (Codex, Claude Code, Antigravity CLI); after your yes in the chat, run this in a terminal of your own:';
+const NO_HOME = 'no home directory found: the kit\'s install needs one';
 const INSTALL = [
-  'Optional, for your own code and prompts — the vendor skill:',
+  'Or the vendor\'s own routes:',
   'Claude Code:',
   'claude plugin marketplace add typesafe-ai/skills',
   'claude plugin install typesafe@typesafe-ai',
@@ -63,8 +65,8 @@ const NOT_SEEN = [
   'in a Claude Code session (the vendor); ask any other agent to use the TypeSafe skill (the vendor); or run Claude Code\'s own',
   'claude plugin list',
 ];
-const AFTER_INSTALL = [
-  'After an install, quit the agent and start it again from a new terminal.',
+const FIRST_USE = [
+  AFTER_INSTALL,
   'Then give the agent this prompt: using the TypeSafe skill, route these three tickets to billing, technical or sales, one request each, and print each choice and confidence — "I was charged twice this month.", "The app crashes when I upload a file.", "Is there a discount for a yearly plan?".',
   'Success: three choices, each with a confidence.',
 ];
@@ -109,11 +111,26 @@ const skillPaths = (dir, home) => [...new Set([join(dir, '.claude', 'skills'), j
   ...(home === '' ? [] : [join(home, '.claude', 'skills'), join(home, '.codex', 'skills'), join(home, '.cursor', 'skills')])]
   .map((root) => join(root, SKILL_FILE)))];
 
-const renderSteps = (found, set, connect, where) => [
+// The skill targets of the part jev-skill, each judged by the facts leaf's one state rule over the guide's own reads.
+const skillOf = (io, env, home, platform) => {
+  const { dir, note } = claudeDirOf(env, home, platform);
+  const fs = { lstat: lstatSync, readdir: readdirSync, readFile: readFileSync, pins: io.pins ?? SKILL_PINS };
+  const targets = skillTargets({ home, claudeDir: dir }).map((target) => {
+    const { state, tag, reason } = skillState(target, fs);
+    return { agent: target.agent, path: printable(target.path), state, tag, reason: reason === null ? null : printable(reason) };
+  });
+  return { targets, install: home === '' ? '' : skillLine(io.toolsDir ?? TOOLS, platform, dir), note: home === '' ? '' : note };
+};
+const markOf = ({ agent, path, state, tag, reason }) => `${agent} skill root: ${state} at ${path}${tag ? ` (${tag})` : ''}${
+  reason ? ` — ${reason}` : ''}`;
+const renderSteps = (found, set, connect, where, home, skill) => [
   ['STEP 1 — the key', KEY_GET, KEY_CONNECT, ...(where ? [`Run it in ${where}:`] : []), connect, KEY_RESTART, KEY_NEVER,
     set ? `key: ${KEY_VARIABLE} set.` : KEY_NOT_SET],
-  ['STEP 2 — the vendor skill', ...INSTALL,
-    ...(found.length ? found.map((path) => `skill: found at ${path}`) : NOT_SEEN), ...AFTER_INSTALL],
+  ['STEP 2 — the vendor skill', SKILL_OPTIONAL,
+    ...(home === '' ? [NO_HOME] : [...(where ? [`Run it in ${where}:`] : []), skill.install || NO_APPLY_LINE,
+      ...(skill.note ? [skill.note] : [])]),
+    ...INSTALL, ...skill.targets.map(markOf),
+    ...(found.length ? found.map((path) => `skill: found at ${path}`) : NOT_SEEN), ...FIRST_USE],
 ];
 
 export const main = (argv, io = {}) => {
@@ -132,9 +149,11 @@ export const main = (argv, io = {}) => {
   const platform = io.platform ?? process.platform;
   const connect = connectLine(io.toolsDir ?? TOOLS, platform);
   const where = placeFor(io, env, platform);
-  const steps = renderSteps(found, set, connect, where);
+  const home = homeOf(io);
+  const skill = skillOf(io, env, home, platform);
+  const steps = renderSteps(found, set, connect, where, home, skill);
   log(parsed.json
-    ? JSON.stringify({ schema: SCHEMA, command: 'jev', dir, text: JEV_TEXT, skill: { found }, key: { set }, connect, where, steps, prompts: PROMPTS }, null, 2)
+    ? JSON.stringify({ schema: SCHEMA, command: 'jev', dir, text: JEV_TEXT, skill: { found, targets: skill.targets, install: skill.install }, key: { set }, connect, where, steps, prompts: PROMPTS }, null, 2)
     : [...JEV_TEXT, ...steps.flat(), 'WHERE IT PAYS IN THIS WORKFLOW', ...PROMPTS].join('\n'));
   return 0;
 };

package/tools/jev-skill.mjs

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+// spec:jev-guide — docs/ai/specs/kit/jev-guide/jev-skill.md
+// The one command that installs the vendor's Jev skill, pinned and digest-checked, as a verified COPY into
+// the three agent skill roots. The USER runs it with --apply in a terminal of their own after their yes in
+// the chat; without --apply it is a read-only dry run. It reads no secret, needs no terminal, opens no
+// connection, never writes through a link below a base, and never removes what it did not mint this run.
+import { createHash } from 'node:crypto';
+import { lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, posix, win32 } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { fail } from '../references/scripts/markdown-blocks.mjs';
+import { isDirectRun } from './direct-run.mjs';
+import { AFTER_INSTALL, NO_APPLY_LINE, SKILL_FILES, SKILL_PINS, claudeDirOf, printable, skillLine, skillState,
+  skillTargets } from './jev-facts.mjs';
+
+export const EXIT = Object.freeze({ done: 0, nothingWritten: 1, usage: 2, inPart: 4 });
+const TOOLS = dirname(fileURLToPath(import.meta.url));
+const VENDOR_DIR = join(TOOLS, '..', 'references', 'vendor', 'typesafe-ai');
+const TMP_PREFIX = '.typesafe-ai.kit-tmp-';
+const OLD_PREFIX = '.typesafe-ai.kit-old-';
+const HELP = `jev-skill — installs the vendor's Jev (TypeSafe) skill, pinned, as one verified copy per agent skill root.
+
+Usage:
+  node jev-skill.mjs [--apply] [--claude-dir DIR]
+
+Without --apply: a dry run that writes nothing and prints the plan.
+--apply       install or replace the planned copies (Codex ~/.agents/skills, Claude Code <claude dir>/skills,
+              Antigravity CLI ~/.gemini/config/skills); a foreign copy is left untouched.
+--claude-dir  the Claude Code dir (absolute); default CLAUDE_CONFIG_DIR when absolute, else ~/.claude.
+--help        answered only when it is the whole invocation.
+
+Exit codes: 0 the dry run rendered or every planned write done; 1 nothing written (the kit's own copy fails
+its check, or no home directory); 2 usage; 4 applied in part (a target refused).`;
+
+const parseArgv = (argv, platform) => {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    if (argv.length !== 1) throw fail(EXIT.usage, '--help is answered only when it is the whole invocation');
+    return { help: true };
+  }
+  const parsed = { help: false, apply: false, claudeDir: null };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--apply') parsed.apply = true;
+    else if (arg === '--claude-dir') {
+      const value = argv[index + 1];
+      if (value === undefined || value === '' || value.startsWith('-')) throw fail(EXIT.usage, '--claude-dir takes a value');
+      if (!(platform === 'win32' ? win32 : posix).isAbsolute(value)) throw fail(EXIT.usage, `--claude-dir takes an absolute path, not ${printable(value)}`);
+      parsed.claudeDir = value;
+      index += 1;
+    } else throw fail(EXIT.usage, `unknown argument "${printable(arg)}" — run with --help`);
+  }
+  return parsed;
+};
+
+const digestOf = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const codeOf = (error) => error?.code ?? error?.message ?? String(error);
+const DEFAULT_IO = Object.freeze({
+  lstat: lstatSync, readdir: readdirSync, readFile: readFileSync, mkdir: mkdirSync, mkdtemp: mkdtempSync,
+  write: (path, bytes) => writeFileSync(path, bytes, { flag: 'wx' }), rename: renameSync, rm: rmSync,
+});
+const homeOf = (io) => {
+  if (io.home !== undefined) return io.home;
+  try { return homedir(); } catch { return ''; }
+};
+
+// The kit's own pair, digest-checked against the first pin: the bytes every install writes, or the refused file.
+const vendorBytes = (io) => {
+  const bytes = {};
+  for (const [name, shipped] of Object.entries(SKILL_FILES)) {
+    try { bytes[name] = io.readFile(join(io.vendorDir, shipped)); } catch { return { refused: shipped }; }
+    if (digestOf(bytes[name]) !== io.pins[0].digests[name]) return { refused: shipped };
+  }
+  return { bytes };
+};
+
+const ACTIONS = Object.freeze({ current: 'keep', earlier: 'replace', absent: 'install', foreign: 'untouched' });
+// Every target with its state and its action, the effective Claude Code dir, the note and the leftovers.
+export const planFor = (io) => {
+  const resolved = claudeDirOf(io.env, io.home, io.platform);
+  const claudeDir = io.claudeDir ?? resolved.dir;
+  const note = io.claudeDir ? '' : resolved.note;
+  const targets = skillTargets({ home: io.home, claudeDir }).map((target) => {
+    const state = skillState(target, io);
+    return { ...target, ...state, action: ACTIONS[state.state] };
+  });
+  const parents = [...new Set(targets.map(({ root }) => dirname(root)))];
+  const leftovers = parents.flatMap((parent) => {
+    try {
+      return [...io.readdir(parent)].map(String).filter((name) => name.startsWith(TMP_PREFIX) || name.startsWith(OLD_PREFIX))
+        .sort().map((name) => join(parent, name));
+    } catch { return []; }
+  });
+  return { claudeDir, note, targets, leftovers };
+};
+
+const countsOf = (targets) => Object.fromEntries(Object.values(ACTIONS)
+  .map((action) => [action, targets.filter((target) => target.action === action).length]));
+const detailOf = (target, newest) => ({
+  keep: `${target.tag}, keep`, replace: `${target.tag}, replace with ${newest}`, install: 'install',
+  untouched: `${printable(target.reason)}, left untouched`,
+})[target.action];
+
+// One target's write: install or replace, re-checking the target before each rename. Returns its lines and outcome.
+export const applyTarget = (entry, io) => {
+  const path = printable(entry.path);
+  const parent = dirname(entry.root);
+  const lines = [];
+  const minted = [];
+  const stateNow = () => skillState(entry, io).state;
+  const changed = (planned) => {
+    const now = stateNow();
+    return now === planned ? null : `changed since the plan: now ${now}`;
+  };
+  let aside = null;
+  const refuse = (cause) => {
+    lines.push(`refused: ${path} — ${cause}`);
+    for (const dir of minted) io.rm(dir, { recursive: true, force: true });
+    if (aside) {
+      const now = stateNow();
+      let kept = now === 'absent' ? null : `the target is now ${now}`;
+      if (kept === null) {
+        try {
+          io.rename(join(aside, 'typesafe-ai'), entry.path);
+          io.rm(aside, { recursive: true, force: true });
+        } catch (error) { kept = codeOf(error); }
+      }
+      if (kept !== null) lines.push(`kept aside: ${printable(join(aside, 'typesafe-ai'))} — ${kept}`);
+    }
+    return { lines, outcome: 'refused' };
+  };
+  try {
+    const below = entry.root.slice(entry.base.length).split(/[\\/]/).filter(Boolean);
+    below.reduce((at, name) => {
+      const next = join(at, name);
+      try { io.lstat(next); } catch (error) {
+        if (error?.code !== 'ENOENT') throw error;
+        io.mkdir(next, { mode: 0o700 });
+      }
+      return next;
+    }, entry.base);
+    const temp = io.mkdtemp(join(parent, TMP_PREFIX));
+    minted.push(temp);
+    const child = join(temp, 'typesafe-ai');
+    io.mkdir(child, { mode: 0o700 });
+    for (const name of Object.keys(SKILL_FILES)) io.write(join(child, name), io.bytes[name]);
+    for (const name of Object.keys(SKILL_FILES)) {
+      if (digestOf(io.readFile(join(child, name))) !== io.pins[0].digests[name]) return refuse('digest mismatch');
+    }
+    if (entry.state === 'earlier') {
+      const old = io.mkdtemp(join(parent, OLD_PREFIX));
+      minted.push(old);
+      const moved = changed('earlier');
+      if (moved) return refuse(moved);
+      io.rename(entry.path, join(old, 'typesafe-ai'));
+      minted.pop();
+      aside = old;
+    }
+    const placed = changed('absent');
+    if (placed) return refuse(placed);
+    io.rename(child, entry.path);
+    io.rm(temp, { recursive: true, force: true });
+    minted.length = 0;
+    if (!aside) {
+      lines.push(`installed: ${path} (${io.pins[0].tag})`);
+      return { lines, outcome: 'installed' };
+    }
+    const old = { base: aside, path: join(aside, 'typesafe-ai') };
+    const verified = skillState(old, io);
+    if (verified.state === 'earlier') io.rm(aside, { recursive: true, force: true });
+    else lines.push(`kept aside: ${printable(old.path)} — it reads ${verified.state}`);
+    lines.unshift(`replaced: ${path} (${entry.tag} → ${io.pins[0].tag})`);
+    return { lines, outcome: 'replaced' };
+  } catch (error) {
+    return refuse(codeOf(error));
+  }
+};
+
+const run = (parsed, io) => {
+  const pin = io.pins[0];
+  const { bytes, refused } = vendorBytes(io);
+  if (refused) {
+    io.error(`refused: the kit's own copy of ${refused} is missing, unreadable or does not match the pin — nothing written`);
+    return EXIT.nothingWritten;
+  }
+  if (io.home === '') { io.error('refused: no home directory found — nothing written'); return EXIT.nothingWritten; }
+  const plan = planFor({ ...io, claudeDir: parsed.claudeDir ?? undefined });
+  io.log(`pin: ${pin.tag}, commit ${pin.commit}`);
+  if (plan.note) io.log(plan.note);
+  const leftovers = plan.leftovers.map((path) => `leftover: ${printable(path)} — not removed; delete it by hand`);
+  const counts = countsOf(plan.targets);
+  if (!parsed.apply) {
+    for (const target of plan.targets) io.log(`${target.agent}: ${target.state} at ${printable(target.path)} — ${detailOf(target, pin.tag)}`);
+    for (const line of leftovers) io.log(line);
+    io.log(`dry run — nothing written. Planned: ${counts.install} to install, ${counts.replace} to replace, ${counts.keep} kept, ${counts.untouched} left untouched.`);
+    if (counts.install + counts.replace > 0) {
+      io.log('To install, run in a terminal of your own:');
+      io.log(skillLine(io.toolsDir, io.platform, plan.claudeDir) || NO_APPLY_LINE);
+    }
+    return EXIT.done;
+  }
+  const done = { installed: 0, replaced: 0, kept: 0, untouched: 0, refused: 0 };
+  for (const target of plan.targets) {
+    if (target.action === 'keep' || target.action === 'untouched') {
+      io.log(target.action === 'keep' ? `kept: ${printable(target.path)} (${target.tag})`
+        : `left untouched: ${printable(target.path)} — ${printable(target.reason)}`);
+      done[target.action === 'keep' ? 'kept' : 'untouched'] += 1;
+      continue;
+    }
+    const result = applyTarget(target, { ...io, bytes });
+    for (const line of result.lines) io.log(line);
+    done[result.outcome] += 1;
+  }
+  for (const line of leftovers) io.log(line);
+  io.log(`done — ${done.installed} installed, ${done.replaced} replaced, ${done.kept} kept, ${done.untouched} left untouched, ${done.refused} refused.`);
+  if (done.installed + done.replaced > 0) io.log(AFTER_INSTALL);
+  return done.refused === 0 ? EXIT.done : EXIT.inPart;
+};
+
+export const main = (argv, io = {}) => {
+  const resolved = {
+    ...DEFAULT_IO, log: console.log, error: console.error, env: process.env, platform: process.platform,
+    pins: SKILL_PINS, vendorDir: VENDOR_DIR, toolsDir: TOOLS, ...io,
+  };
+  let parsed;
+  try { parsed = parseArgv(argv, resolved.platform); } catch (err) { resolved.error(err.message); return EXIT.usage; }
+  if (parsed.help) { resolved.log(HELP); return EXIT.done; }
+  return run(parsed, { ...resolved, home: homeOf(io) });
+};
+
+if (isDirectRun(import.meta.url)) process.exitCode = main(process.argv.slice(2));

package/tools/manifest/schema.md

@@ -68,7 +68,7 @@ unlike `contract`, it is validated by `validate.mjs` itself: a malformed entry *
 this block). Each entry:
 
 - `key` (string, required) — UPPER_SNAKE_CASE env-var name; unique across the array.
-- `kind` (string, required) — `enum | integer | duration | boolean`.
+- `kind` (string, required) — `enum | integer | duration | boolean | posture` (`posture`: a non-empty string with no control byte and no leading or trailing whitespace — a bridge model or effort; the catalog, not the kind, decides which values a host offers).
   - `enum` → `values` (string[], non-empty, unique).
   - `integer` → `min` / `max` (safe integers, `min <= max`); values are decimal strings.
   - `duration` → the wrappers' shell duration grammar (`5m`, `30m`, `90s`): a unit suffix

package/tools/manifest/validate.mjs

@@ -40,7 +40,7 @@ export const INVALID = 'invalid';
 // declared `default`), the kit-side bridge-settings writer (for a user-supplied value), and — mirrored
 // in shell as aw_settings_valid — the wrappers all use, so a value the writer accepts is exactly a
 // value a wrapper honors. A value is always compared as a STRING (the settings-file wire format).
-export const SETTING_KINDS = new Set(['enum', 'integer', 'duration', 'boolean']);
+export const SETTING_KINDS = new Set(['enum', 'integer', 'duration', 'boolean', 'posture']);
 // The wrappers' shell duration grammar: a unit suffix is REQUIRED (a bare integer is invalid), and
 // zero durations are rejected — `timeout 0` DISABLES a hard cap, so a persistent settings line could
 // otherwise silently remove the stall guard.
@@ -56,6 +56,7 @@ export const settingValueValid = (entry, value) => {
     }
     case 'duration': return DURATION_RE.test(value) && !ZERO_DURATION_RE.test(value);
     case 'boolean': return value === '0' || value === '1';
+    case 'posture': return value !== '' && !/[\u0000-\u001f\u007f]/u.test(value) && !/^\s|\s$/u.test(value);
     default: return false;
   }
 };
@@ -613,7 +614,7 @@ export const validateManifest = (skillDir) => {
           }
         }
         if (!SETTING_KINDS.has(entry.kind)) {
-          errors.push(`${at}.kind must be one of enum|integer|duration|boolean`);
+          errors.push(`${at}.kind must be one of enum|integer|duration|boolean|posture`);
           return; // the typed checks below are meaningless without a kind
         }
         if (entry.kind === 'enum'

package/tools/procedures.mjs

@@ -154,8 +154,8 @@ export const extractSection = (text, activity) => {
 
 const resolveAllSlots = ({ activity, config, detection, overrides, surveyLens }) => {
   // The host-level settings knobs (manifest-as-source), best-effort: a corrupt bundle degrades to none
-  // and the advisor never crashes. Attached per wrapper cmd via each knob's `appliesTo`. Fact-only —
-  // model/effort are not knobs, so no model claim can ride here.
+  // and the advisor never crashes. Attached per wrapper cmd via each knob's `appliesTo` — the model
+  // keys included, as knobs with their allowed-value label, never an effective-model claim.
   const registry = (() => {
     try {
       return loadRegistry({});
@@ -494,7 +494,7 @@ const costLanesAdvice = () => [
   'Cost lanes (orchestration.md §5) — route every step to the cheapest adequate executor:',
   '  • L0 deterministic script — run the gate matrix as ONE batch: /agent-workflow-kit gates (the project-declared docs/ai/gates.json); rotation headroom: archive-changelog / archive-issues / archive-decisions --check. An exit code beats a model re-read.',
   '  • L1 cheap subagent (small model, low effort, read-only tools — /agent-workflow-kit agents places the vehicles) — mechanical sweeps, changelog fact-skeletons, gate-failure triage. Extraction/drafting ONLY; the orchestrator verifies the output and owns every conclusion.',
-  '  • L2 subscription bridge (codex / agy) — reviews per the resolved recipe above, on frontier bridge models (quality-first).',
+  '  • L2 subscription bridge (codex / agy) — reviews per the resolved recipe above, on each bridge\'s host posture (the model the user set, else the bridge default); a weaker model is the user\'s setting, never a per-call choice — a probe is the one route to a one-off and its review receipt never attests.',
   '  • L3 frontier — judgment: plan/fold/synthesis, ADR/handover/changelog-entry wording, persuasive copy, go/no-go, real code.',
   '  • A step with no named guardrail does not move down a lane; red lines never move down (council review models · real code · memory/copy wording · the maintainer approval asks).',
   '  • Sandbox lanes (under an OS sandbox): the L0 surfaces are sandbox-safe — gates/ledger/state/fold checks, git reads, plain no-network tests; the bridge wrappers are genuinely unsandboxed (network); npm-cache-touching commands are COMMAND-SHAPE dependent — first try the sandbox-safe shape (cache under $TMPDIR, offline/notifier off). Move ONLY the failing command out of the sandbox, never its class; BATCH consecutive unsandboxed calls. Pre-dispatch host-diff: before the FIRST dispatch of each bridge, diff its manifest networkHosts against the live sandbox allow-list — a missing host is surfaced to the maintainer BEFORE dispatching, never fired into a known prompt. Nested-sandbox honesty: a backend CLI shipping its OWN OS sandbox cannot run nested inside a harness sandbox — route it outside (excludedCommands / a per-run consented bypass) on the OBSERVED failure, never a preemptive blanket.',

package/tools/recipes.mjs

@@ -171,11 +171,11 @@ const dispatchFor = (recipe, detection) => {
     });
 };
 
-const QUOTA_NOTE = "Prefer the cheapest model that fits the task; don't reach for a top-tier model by reflex.";
+const QUOTA_NOTE = "Each bridge runs the host posture the user set; a weaker model is the user's bridge setting, never a per-call choice.";
 const COUNCIL_QUOTA_NOTE = "Council spends two backends' quota for one decision — reserve it for changes that justify the cost.";
 
 // The quota reminder rides a subscription-BACKEND dispatch only: the executor vehicle spends no
-// bridge quota, and its recipe is a frontier one, so the cheapest-model reminder would contradict it.
+// bridge quota, and its recipe is a frontier one, so a bridge-posture reminder would not apply to it.
 const notesFor = (recipe, dispatch) => {
   const notes = [];
   if (dispatch.some((d) => d.role !== CARRY_ROLE)) notes.push(QUOTA_NOTE);