@sabaiway/agent-workflow-kit 14.25.1 → 14.26.0

package/tools/apply-danger-check.mjs

@@ -0,0 +1,364 @@
+#!/usr/bin/env node
+import { existsSync, lstatSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve, win32 } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  BRIDGE_REVIEW_WRAPPERS, CLAUDE_DIR, KIT_GROUNDING_TOOL, RENDER_OWNED_REDLINE_RULES,
+  SAFE_DEFAULT_MODES, SETTINGS_FILE, SETTINGS_LOCAL_FILE, UNIVERSAL_READONLY_ALLOWLIST,
+  deriveBridgeTierAllowlist, deriveKitToolsAllowlist, mergeAutonomySettings,
+  writeAutonomyProfile, writeVelocityProfile,
+} from './velocity-profile.mjs';
+import { bundledSandboxRecipe } from './bridge-sandbox-recipe.mjs';
+import { HOOK_FILE_REL, HOOKS_DIR, buildHookSettingsEntry, mergeHookEntry, writeGateHook } from './gate-hook.mjs';
+import { writeMcp } from './mcp.mjs';
+import { ENABLED_KEY, MCP_JSON_REL, SERVERS_KEY, SERVER_NAME, allowRulesFor, buildServerEntry } from './mcp-registration.mjs';
+import { AGENTS_DIR, writeCheapAgents } from './cheap-agents.mjs';
+import { planFor } from './jev-skill.mjs';
+import { SKILL_FILES, claudeDirOf, skillTargets } from './jev-facts.mjs';
+import { findOnPath } from './detect-backends.mjs';
+import { consoleArgv } from './write-lanes.mjs';
+import { isDirectRun } from './direct-run.mjs';
+import { dirCovers as covers } from './declared-paths.mjs';
+
+const TOOLS = dirname(fileURLToPath(import.meta.url));
+const SKILL_VARIANTS = ['jev-skill', 'jev-skill.earlier'];
+const VELOCITY_VARIANTS = ['velocity-core', 'kit-tools-tier', 'bridge-tier'];
+const HOOK_VARIANTS = ['gate-hook', 'read-lane.missing'];
+const MCP_VARIANTS = ['mcp-channel', 'mcp-channel.differing'];
+const AGENT_VARIANTS = ['agents', 'executor-vehicle'];
+const VARIANTS = [...VELOCITY_VARIANTS, 'autonomy-render', ...HOOK_VARIANTS, ...MCP_VARIANTS, ...AGENT_VARIANTS, ...SKILL_VARIANTS];
+const CREDENTIALS = 'sandbox.credentials.envVars';
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const stable = (value) => object(value)
+  ? `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stable(value[key])}`).join(',')}}`
+  : Array.isArray(value) ? `[${value.map(stable).join(',')}]` : JSON.stringify(value);
+const equal = (left, right) => stable(left) === stable(right);
+const sha = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const textValue = (value) => typeof value === 'string' ? value : JSON.stringify(value);
+
+export const CHANGE_CLASSES = Object.freeze([
+  'hosts reachable', 'paths writable', 'commands outside the sandbox',
+  'prompts removed', 'commands the harness runs', 'nothing widened',
+]);
+export const KEY_TABLE = Object.freeze({
+  'sandbox.network.allowedDomains': 0,
+  'sandbox.filesystem.allowWrite': 1,
+  'sandbox.excludedCommands': 2,
+  'permissions.allow': 3,
+  'permissions.defaultMode': 3,
+  'sandbox.autoAllowBashIfSandboxed': 3,
+  'permissions.ask': 3,
+  'permissions.deny': 3,
+  'sandbox.enabled': 3,
+  'hooks.PreToolUse': 4,
+  [ENABLED_KEY]: 4,
+  [SERVERS_KEY]: 4,
+  [CREDENTIALS]: 5,
+});
+const SCALARS = ['permissions.defaultMode', 'sandbox.enabled', 'sandbox.autoAllowBashIfSandboxed'];
+const valid = (key, value, element = false) => {
+  if (key.startsWith(`${SERVERS_KEY}.`) || key === SERVERS_KEY) return object(value);
+  if (key === 'permissions.defaultMode') return typeof value === 'string';
+  if (SCALARS.includes(key)) return typeof value === 'boolean';
+  if (!element) return Array.isArray(value) && value.every((entry) => valid(key, entry, true));
+  if (key === CREDENTIALS) return object(value) && typeof value.name === 'string' && typeof value.mode === 'string';
+  return key === 'hooks.PreToolUse' ? object(value) : typeof value === 'string';
+};
+const keyOf = (key) => key.startsWith(`${SERVERS_KEY}.`) ? SERVERS_KEY : key;
+
+export const diffFiles = (before, after) => {
+  const entries = [];
+  const scalar = (key, left, right) => {
+    if (equal(left, right)) return;
+    if (left === undefined) entries.push({ key, change: 'added', value: right });
+    else if (right === undefined) entries.push({ key, change: 'removed', value: left });
+    else entries.push({ key, change: 'altered', value: right, previous: left });
+  };
+  const walk = (left, right, key) => {
+    if (equal(left, right)) return;
+    const known = Object.hasOwn(KEY_TABLE, key);
+    if (known && [left, right].some((value) => value !== undefined && !valid(key, value))) {
+      scalar(key, left, right);
+    } else if (key === SERVERS_KEY) {
+      for (const name of new Set([...Object.keys(left ?? {}), ...Object.keys(right ?? {})])) {
+        scalar(`${key}.${name}`, left?.[name], right?.[name]);
+      }
+    } else if (known && !SCALARS.includes(key)) {
+      const old = left ?? [];
+      const next = right ?? [];
+      const unpaired = old.filter((value) => !next.some((entry) => equal(value, entry)));
+      const changes = next.filter((value) => !old.some((entry) => equal(value, entry))).map((value) => {
+        const at = key === CREDENTIALS ? unpaired.findIndex((entry) => entry.name === value.name) : -1;
+        return at < 0 ? { key, change: 'added', value } : { key, change: 'altered', value, previous: unpaired.splice(at, 1)[0] };
+      });
+      for (const value of unpaired) entries.push({ key, change: 'removed', value });
+      entries.push(...changes);
+    } else if (!known && (key === '' || Object.keys(KEY_TABLE).some((path) => path.startsWith(`${key}.`)))
+      && [left, right].every((value) => value === undefined || object(value))) {
+      for (const name of new Set([...Object.keys(left ?? {}), ...Object.keys(right ?? {})])) {
+        walk(left?.[name], right?.[name], key ? `${key}.${name}` : name);
+      }
+    } else scalar(key, left, right);
+  };
+  walk(before ?? {}, after ?? {}, '');
+  const order = Object.keys(KEY_TABLE);
+  const rank = (key) => order.includes(keyOf(key)) ? order.indexOf(keyOf(key)) : order.length;
+  return entries.sort((a, b) => rank(a.key) - rank(b.key));
+};
+
+const classOf = ({ key, change, value }) => {
+  const base = keyOf(key);
+  if (!Object.hasOwn(KEY_TABLE, base)) return null;
+  let index = KEY_TABLE[base];
+  if (change === 'removed') index = ['permissions.ask', 'permissions.deny', CREDENTIALS].includes(key) ? 3 : 5;
+  else if (['permissions.ask', 'permissions.deny'].includes(key)) index = 5;
+  else if (key === 'permissions.defaultMode') index = value === 'acceptEdits' ? 3 : 5;
+  else if (key === 'sandbox.enabled') index = value === false ? 3 : 5;
+  else if (key === 'sandbox.autoAllowBashIfSandboxed') index = value === true ? 3 : 5;
+  return CHANGE_CLASSES[index];
+};
+export const judgeChange = ({ variant, files, scope }) => {
+  const entries = [];
+  const refused = [];
+  for (const { path, before, after } of files) {
+    for (const diff of diffFiles(before, after)) {
+      const entry = { ...diff, path, class: classOf(diff) };
+      entries.push(entry);
+      const { key, change } = diff;
+      const atKey = (data) => key.split('.').reduce((value, name) => value?.[name], data);
+      const wrongType = [atKey(before), atKey(after)].some((value) => value !== undefined && !valid(key, value));
+      const reason = entry.class === null ? 'unknown key' : wrongType ? 'wrong type'
+        : key === CREDENTIALS && change !== 'added' ? 'credentials entry removed or altered'
+          : !scope.admits(entry) ? `beyond the declared scope of ${variant}` : null;
+      if (reason) refused.push({ path, key, reason });
+    }
+  }
+  return { entries, refused };
+};
+const writerFacts = (facts, deps) => ({
+  ...deps, ...facts,
+  findWrapper: (name) => findOnPath(name, { getenv: facts.env }).state === 'present',
+  findOnPath: (name) => findOnPath(name, { getenv: facts.env }),
+});
+
+export const scopeOf = (variant, facts) => {
+  const allowed = {};
+  const set = (key, values) => {
+    allowed[key] = (value) => values.some((entry) => equal(entry, value));
+  };
+  if (VELOCITY_VARIANTS.includes(variant)) {
+    const allow = [...UNIVERSAL_READONLY_ALLOWLIST];
+    if (variant === 'kit-tools-tier') allow.push(...deriveKitToolsAllowlist({ projectDir: facts.root }));
+    if (variant === 'bridge-tier') {
+      const deps = writerFacts(facts, {});
+      const placed = BRIDGE_REVIEW_WRAPPERS.filter(deps.findWrapper);
+      allow.push(...deriveBridgeTierAllowlist({ findWrapper: deps.findWrapper,
+        groundingAbsPath: join(facts.toolsDir, '..', KIT_GROUNDING_TOOL) }).allow);
+      set('sandbox.excludedCommands', placed);
+      set('sandbox.network.allowedDomains', bundledSandboxRecipe(placed, deps).hosts);
+    }
+    set('permissions.allow', allow);
+  } else if (variant === 'autonomy-render') {
+    set('permissions.defaultMode', SAFE_DEFAULT_MODES);
+    set('sandbox.enabled', [true]);
+    set('sandbox.autoAllowBashIfSandboxed', [true, false]);
+    set('permissions.ask', RENDER_OWNED_REDLINE_RULES);
+    set('permissions.deny', RENDER_OWNED_REDLINE_RULES);
+    allowed[CREDENTIALS] = (value) => value.mode === 'deny';
+  } else if (HOOK_VARIANTS.includes(variant)) set('hooks.PreToolUse', [buildHookSettingsEntry()]);
+  else if (MCP_VARIANTS.includes(variant)) {
+    set(`${SERVERS_KEY}.${SERVER_NAME}`, [buildServerEntry(join(facts.toolsDir, 'mcp-server.mjs'))]);
+    set(ENABLED_KEY, [SERVER_NAME]);
+    set('permissions.allow', allowRulesFor());
+  }
+  const targets = SKILL_VARIANTS.includes(variant) ? skillTargets({ home: facts.home,
+    claudeDir: facts.claudeDir ?? claudeDirOf(facts.env, facts.home, facts.platform).dir }) : [];
+  const filePaths = HOOK_VARIANTS.includes(variant) ? [join(facts.root, HOOK_FILE_REL)] : [];
+  const directories = VELOCITY_VARIANTS.includes(variant) || variant === 'autonomy-render'
+    || HOOK_VARIANTS.includes(variant) || MCP_VARIANTS.includes(variant) || AGENT_VARIANTS.includes(variant)
+    ? [join(facts.root, CLAUDE_DIR)] : [];
+  if (HOOK_VARIANTS.includes(variant)) directories.push(join(facts.root, HOOKS_DIR));
+  if (AGENT_VARIANTS.includes(variant)) directories.push(join(facts.root, AGENTS_DIR));
+  for (const target of targets) {
+    for (let at = target.root; at !== target.base && covers(target.base, at); at = dirname(at)) directories.push(at);
+    filePaths.push(target.path);
+  }
+  return {
+    admits: ({ path, key, change, value }) => {
+      const correctFile = key.startsWith(`${SERVERS_KEY}.`) ? path === MCP_JSON_REL : path === SETTINGS_FILE;
+      const gains = key === 'hooks.PreToolUse' || key === ENABLED_KEY || key === CREDENTIALS;
+      return correctFile && (!gains || change === 'added') && Boolean(allowed[key]?.(value));
+    },
+    admitsPath: (path, directory = false) => directory ? directories.includes(path)
+      : filePaths.includes(path) || (AGENT_VARIANTS.includes(variant) && covers(join(facts.root, AGENTS_DIR), path)),
+  };
+};
+
+const jsonAt = (path) => existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : null;
+const halted = (lines) => Object.assign(new Error(lines.join('\n')), { code: 'CHECK_HALTED', lines });
+const maskedFiles = (variant, facts) => {
+  const paths = VELOCITY_VARIANTS.includes(variant) || variant === 'autonomy-render' || HOOK_VARIANTS.includes(variant)
+    ? [SETTINGS_FILE, SETTINGS_LOCAL_FILE] : MCP_VARIANTS.includes(variant) ? [MCP_JSON_REL, SETTINGS_FILE] : [];
+  return paths.flatMap((path) => lstatSync(join(facts.root, path), { throwIfNoEntry: false })?.isCharacterDevice()
+    ? [`masked: ${path}`] : []);
+};
+export const plannedChange = (variant, facts, deps = {}) => {
+  const files = [];
+  const writes = [];
+  const temporaries = [];
+  const writerDeps = writerFacts(facts, deps);
+  const addFile = (path, before, after) => {
+    files.push({ path, before: before ?? null, after });
+  };
+  try {
+    const masks = maskedFiles(variant, facts);
+    if (masks.length) throw halted(masks);
+    if (VELOCITY_VARIANTS.includes(variant)) {
+      const plan = writeVelocityProfile({ cwd: facts.root, dryRun: true,
+        kitTools: variant === 'kit-tools-tier', bridgeTier: variant === 'bridge-tier' }, writerDeps);
+      const before = plan.projectSettings.data ?? {};
+      const after = structuredClone(before);
+      after.permissions = { ...before.permissions,
+        allow: [...(before.permissions?.allow ?? []), ...plan.toAdd, ...plan.tierToAdd, ...plan.bridgeToAdd] };
+      if (plan.excludedToAdd.length || plan.hostsToAdd.length) {
+        after.sandbox = { ...before.sandbox };
+        if (plan.excludedToAdd.length) after.sandbox.excludedCommands = [...(before.sandbox?.excludedCommands ?? []), ...plan.excludedToAdd];
+        if (plan.hostsToAdd.length) after.sandbox.network = { ...before.sandbox?.network,
+          allowedDomains: [...(before.sandbox?.network?.allowedDomains ?? []), ...plan.hostsToAdd] };
+      }
+      addFile(SETTINGS_FILE, plan.projectSettings.data, after);
+    } else if (variant === 'autonomy-render') {
+      const render = writeAutonomyProfile({ cwd: facts.root, apply: false }, writerDeps);
+      const before = jsonAt(join(facts.root, SETTINGS_FILE));
+      addFile(SETTINGS_FILE, before, mergeAutonomySettings(before, render));
+    } else if (HOOK_VARIANTS.includes(variant)) {
+      const plan = writeGateHook({ cwd: facts.root, dryRun: true }, writerDeps);
+      if (plan.wirePlanned) addFile(SETTINGS_FILE, plan.projectSettings.data, mergeHookEntry(plan.projectSettings.data));
+      if (plan.placePlanned) writes.push({ path: join(facts.root, HOOK_FILE_REL), bytes: plan.bundleContent });
+    } else if (MCP_VARIANTS.includes(variant)) {
+      const result = writeMcp({ cwd: facts.root, dryRun: true, replace: variant === 'mcp-channel.differing' }, writerDeps);
+      const { plan, registration } = result;
+      if (plan.writeMcpJson) addFile(MCP_JSON_REL, registration.mcpJson.data, JSON.parse(plan.mcpBody));
+      if (plan.writeSettings) addFile(SETTINGS_FILE, registration.settings.data, JSON.parse(plan.settingsBody));
+    } else if (AGENT_VARIANTS.includes(variant)) {
+      const plan = writeCheapAgents({ cwd: facts.root, dryRun: true }, writerDeps);
+      for (const item of plan.plan.filter(({ action }) => ['place', 're-derive'].includes(action))) {
+        writes.push({ path: item.abs, bytes: item.content });
+      }
+    } else if (SKILL_VARIANTS.includes(variant)) {
+      const plan = planFor({ ...writerDeps, lstat: lstatSync, readdir: readdirSync, readFile: readFileSync });
+      for (const target of plan.targets.filter(({ action }) => ['install', 'replace'].includes(action))) {
+        const stem = basename(target.path);
+        const bytes = Object.keys(SKILL_FILES).sort().map((name) => [name,
+          readFileSync(join(facts.toolsDir, '..', 'references', 'vendor', stem, SKILL_FILES[name]))]);
+        writes.push({ path: target.path, bytes: Buffer.concat(bytes.flatMap(([name, body]) => [Buffer.from(`${name}\0`), body])), directory: true });
+        temporaries.push(`temporary: ${dirname(target.root)}/.${stem}.kit-tmp-*`);
+        if (target.action === 'replace') temporaries.push(`temporary: ${dirname(target.root)}/.${stem}.kit-old-*`);
+      }
+    } else throw new Error(`unsupported variant: ${variant}`);
+  } catch (error) {
+    throw error.code === 'CHECK_HALTED' ? error : halted([error.message]);
+  }
+  const directories = new Set();
+  const changedFiles = files.filter(({ before, after }) => diffFiles(before, after).length);
+  for (const path of [...changedFiles.map(({ path }) => join(facts.root, path)), ...writes.map(({ path }) => path)]) {
+    for (let parent = dirname(path); !existsSync(parent); parent = dirname(parent)) directories.add(parent);
+  }
+  return { files, writes, temporaries, directories: [...directories] };
+};
+
+export const checkApply = (variant, facts, deps = {}) => {
+  const plan = plannedChange(variant, facts, deps);
+  const scope = scopeOf(variant, facts);
+  const { entries, refused } = judgeChange({ variant, files: plan.files, scope });
+  const lines = [];
+  const display = (path) => facts.root && covers(facts.root, path) ? relative(facts.root, path) : path;
+  for (const file of plan.files) {
+    const changes = entries.filter(({ path }) => path === file.path);
+    if (!changes.length) continue;
+    lines.push(`${file.path}:`);
+    for (const entry of changes) {
+      const old = entry.change === 'altered' ? `${textValue(entry.previous)} → ` : '';
+      lines.push(`  ${entry.key}: ${entry.change} ${old}${textValue(entry.value)} — ${entry.class ?? 'unknown'}`);
+    }
+  }
+  const pathLine = (path, directory, line) => {
+    lines.push(line);
+    if (!scope.admitsPath(path, directory)) refused.push({ path: display(path), key: display(path),
+      reason: `beyond the declared scope of ${variant}` });
+  };
+  for (const write of plan.writes) pathLine(write.path, false, `writes: ${display(write.path)} sha256:${sha(write.bytes)}`);
+  for (const path of plan.directories) pathLine(path, true, `writes: ${display(path)}/ created`);
+  lines.push(...plan.temporaries);
+  if (refused.length) {
+    for (const entry of refused) lines.push(`refused: ${entry.path} ${entry.key} — ${entry.reason}`);
+    lines.push('nothing written');
+  } else lines.push(lines.length ? `scope: within the declared scope of ${variant}` : `nothing to change: ${variant} is already applied`);
+  const digest = sha(lines.join('\n'));
+  return { lines: [...lines, `digest: ${digest}`], digest, refused };
+};
+
+const USAGE = 'usage: apply-danger-check --variant <v> --cwd <root> [--claude-dir <abs>] [--apply --expect <digest>]';
+const parse = (argv, platform) => {
+  if (argv.length === 1 && ['--help', '-h'].includes(argv[0])) return { help: true };
+  const args = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index];
+    if (flag === '--apply') args.apply = true;
+    else if (['--variant', '--cwd', '--claude-dir', '--expect'].includes(flag)) {
+      const value = argv[index + 1];
+      if (!value || value.startsWith('-')) throw new Error(`${flag} takes a value`);
+      args[flag.slice(2)] = value;
+      index += 1;
+    } else throw new Error(`unknown argument: ${flag}`);
+  }
+  if (!VARIANTS.includes(args.variant) || !args.cwd) throw new Error('--variant and --cwd are required for a harness variant');
+  if (args['claude-dir'] && (!SKILL_VARIANTS.includes(args.variant)
+    || !(platform === 'win32' ? win32.isAbsolute : isAbsolute)(args['claude-dir']))) throw new Error('--claude-dir requires a skill variant and an absolute path');
+  if (Boolean(args.apply) !== Boolean(args.expect) || (args.expect && !/^[0-9a-f]{64}$/.test(args.expect))) {
+    throw new Error('--apply requires --expect with 64 lowercase hex characters');
+  }
+  args.root = resolve(args.cwd);
+  if (!statSync(args.root).isDirectory()) throw new Error('--cwd must be a directory');
+  return args;
+};
+export const main = (argv, io = {}) => {
+  const resolved = { log: console.log, error: console.error, env: process.env, home: homedir(),
+    platform: process.platform, toolsDir: TOOLS,
+    spawn: (argv, options) => spawnSync(argv[0], argv.slice(1), options), ...io };
+  let args;
+  try {
+    args = parse(argv, resolved.platform);
+  } catch (error) {
+    resolved.error(error.message);
+    return 2;
+  }
+  if (args.help) {
+    resolved.log(USAGE);
+    return 0;
+  }
+  const facts = { toolsDir: resolved.toolsDir, root: args.root, env: resolved.env, home: resolved.home,
+    platform: resolved.platform, claudeDir: args['claude-dir'] };
+  let result;
+  try {
+    result = checkApply(args.variant, facts);
+  } catch (error) {
+    for (const line of error.lines ?? [error.message]) resolved.log(line);
+    return 3;
+  }
+  for (const line of result.lines) resolved.log(line);
+  if (result.refused.length) return 1;
+  if (!args.apply) return 0;
+  if (args.expect !== result.digest) return 5;
+  const spawnFacts = facts.claudeDir ? { ...facts, env: { ...facts.env, CLAUDE_CONFIG_DIR: facts.claudeDir } } : facts;
+  const child = resolved.spawn(consoleArgv(args.variant, spawnFacts).apply,
+    { cwd: facts.root, env: resolved.env, stdio: 'inherit' });
+  if (child.status === 0) return 0;
+  resolved.error(`apply exited ${child.status}`);
+  return 6;
+};
+
+if (isDirectRun(import.meta.url)) process.exitCode = main(process.argv.slice(2));

package/tools/init-project.mjs

@@ -4,15 +4,16 @@ import { homedir } from 'node:os';
 import { basename, dirname, join, resolve, sep } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { fileURLToPath } from 'node:url';
+import { checkApply } from './apply-danger-check.mjs';
 import { resolveGitHooksPath } from './commit-guard.mjs';
 import { dirCovers } from './declared-paths.mjs';
 import { isDirectRun } from './direct-run.mjs';
-import { GIT_MAX_BUFFER } from './git-env.mjs';
+import { GIT_MAX_BUFFER, stripGitLocationEnv } from './git-env.mjs';
 import { preflightInit } from './init-preflight.mjs';
 import { buildRecommendations, hostFacts } from './recommendations.mjs';
 import { compareSemver } from './semver-lite.mjs';
 import { EXPECTED_WORKFLOW_VERSION } from './velocity-profile.mjs';
-import { LANE_CONSOLE, VARIANT_LANES, consoleArgv, isProtectedPath, laneOf, routeLine, writesOf } from './write-lanes.mjs';
+import { LANE_HARNESS, VARIANT_LANES, consoleArgv, isEnvDependent, isProtectedPath, laneOf, writesOf } from './write-lanes.mjs';
 
 const INSIDE_LINE = 'you are inside an agent; run this in your own terminal';
 const APPLY_PROMPT = 'apply? y/N: ';
@@ -96,29 +97,21 @@ const readState = (path, io) => {
   if (stat.isSymbolicLink()) return `link:${io.readlink(path)}:${followedState(path, io)}`;
   return statState(path, stat, io);
 };
-const stateOf = (path, io) => {
+const readStateOrElse = (path, io, onError) => {
   try {
     return readState(path, io);
   } catch (error) {
-    throw new Error(`${path} could not be read: ${error.code ?? error.message}`);
+    return onError(error);
   }
 };
+const stateOf = (path, io) => readStateOrElse(path, io, (error) => {
+  throw new Error(`${path} could not be read: ${error.code ?? error.message}`);
+});
 const recordPaths = (paths, io) => new Map([...new Set(paths)].map((path) => [path, stateOf(path, io)]));
-const findChanged = (record, io) => [...record].find(([path, state]) => {
-  try {
-    return readState(path, io) !== state;
-  } catch {
-    return true;
-  }
-})?.[0];
+const findChanged = (record, io) => [...record].find(([path, state]) =>
+  readStateOrElse(path, io, () => null) !== state)?.[0];
 // After an apply a path that cannot be read is recorded as such, so the next comparison stops the batch on it.
-const refreshState = (path, io) => {
-  try {
-    return readState(path, io);
-  } catch (error) {
-    return `unreadable:${error.code ?? error.message}`;
-  }
-};
+const refreshState = (path, io) => readStateOrElse(path, io, (error) => `unreadable:${error.code ?? error.message}`);
 const DIRECTORY = 'directory:';
 const entriesOf = (state) => (state === 'absent' ? [] : JSON.parse(state.slice(DIRECTORY.length)));
 // A recorded parent moves only by the written entry, so an entry created or removed beside it still stops the batch.
@@ -179,16 +172,13 @@ const reachesQueue = (variant, facts) => {
 const isMasked = (variant, context) => (writesOf(variant, context.facts) ?? [])
   .some((write) => [...context.masks].some((mask) => dirCovers(write, mask)));
 
-// context.items keeps the console items of the advisor's latest return, before the queue's filters.
 const getQueue = async (context) => {
-  const { items } = await context.recommend(context.facts.root, { keySet: context.keySet });
-  context.items = items.filter(({ variant }) => laneOf(variant) === LANE_CONSOLE);
+  context.items = (await context.recommend(context.facts.root, { keySet: context.keySet })).items;
   return context.items.filter(({ variant }) => reachesQueue(variant, context.facts) && !isMasked(variant, context));
 };
 
 const printNotPending = (context) => {
-  const plain = routeLine('velocity-core');
-  const variants = Object.keys(VARIANT_LANES).filter((variant) => laneOf(variant) === LANE_CONSOLE && routeLine(variant)?.length > plain.length);
+  const variants = Object.keys(VARIANT_LANES).filter(isEnvDependent);
   const keys = new Set();
   for (const variant of variants) {
     const key = variant.split('.')[0];
@@ -227,6 +217,16 @@ const previewQueue = async (context, queue) => {
     context.print(result.stdout);
     const tuple = result.stdout.match(/--apply\s+(\S+)/)?.[1];
     const facts = { ...context.facts, tuple };
+    if (laneOf(item.variant) === LANE_HARNESS) {
+      try {
+        const { lines, refused } = context.checkApply(item.variant, facts, {});
+        for (const line of lines) context.print(line);
+        if (refused.length > 0) throw new Error(refused.map(({ key }) => key).join(', '));
+      } catch (error) {
+        context.print(`not applied: ${item.variant} — the danger check refused: ${error.message}`);
+        continue;
+      }
+    }
     batch.push({ ...item, applyArgv: consoleArgv(item.variant, facts).apply, writes: writesOf(item.variant, facts) });
     printNote(context, item.key);
   }
@@ -295,7 +295,7 @@ const runPass = async (context, queue) => {
 const selectRoot = async (context) => {
   const { candidates } = findProject({ cwd: context.cwd, lstat: context.io.lstat });
   if (candidates.length === 0) {
-    context.print("no agent-workflow project here — the project items apply when init runs from that project's folder");
+    context.print('no agent-workflow project here — run /agent-workflow-kit upgrade in your agent from that project, or deploy it there first: its yes applies the project items');
     return { root: null };
   }
   if (candidates.length === 1) return candidates[0];
@@ -317,7 +317,7 @@ const gateStamp = (candidate, context) => {
   if (compareSemver(stamp, EXPECTED_WORKFLOW_VERSION) === 1) {
     context.print(`this project's stamp ${stamp} is ahead of this kit's lineage ${EXPECTED_WORKFLOW_VERSION} — update the kit, then init again`);
   } else {
-    context.print('run /agent-workflow-kit upgrade, then init again');
+    context.print('run /agent-workflow-kit upgrade in your agent: its yes applies the items');
   }
   return null;
 };
@@ -334,10 +334,8 @@ export const runInitProject = async (deps) => {
     print(INSIDE_LINE);
     return { code: 0 };
   }
-  const spawnEnv = { ...deps.env };
-  delete spawnEnv.GIT_DIR;
-  delete spawnEnv.GIT_WORK_TREE;
-  const context = { ...deps, io, print, spawnEnv, masks: new Set(), keySet: false, restart: false };
+  const spawnEnv = stripGitLocationEnv(deps.env);
+  const context = { ...deps, checkApply: deps.checkApply ?? checkApply, io, print, spawnEnv, masks: new Set(), keySet: false, restart: false };
   const candidate = await selectRoot(context);
   if (candidate === null) return { code: 0 };
   if (!preflightInit({ ...deps, root: candidate.root, io }).ok) {

package/tools/jev-connect.mjs

@@ -4,8 +4,8 @@
 // their own: it reads the key with no echo, verifies it with one request, saves it where the shell
 // reads it (bash, zsh, fish) or in the Windows user environment, and prints the restart step. It never
 // prints the key, never puts it in an argv, and refuses when stdin is not a terminal, so a
-// non-interactive run (the agent's) cannot reach the prompt — the mode doc keeps the rule that the
-// agent never runs it. It claims no connection: the guide's key mark, read after the restart, is the proof.
+// non-interactive run cannot reach the prompt. The key never reaches the agent or the chat.
+// It claims no connection: the guide's key mark, read after the restart, is the proof.
 import { spawnSync } from 'node:child_process';
 import { lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';

package/tools/jev-guide.mjs

@@ -45,11 +45,11 @@ export const JEV_TEXT = Object.freeze([
 ]);
 
 const KEY_GET = 'Get a key at console.typesafe.ai and set it on every host the agent runs on.';
-const KEY_CONNECT = 'Connect it from a terminal of your own, never through the agent: the command asks for the key with no echo, checks it with one request and saves it for bash, zsh or fish in your shell\'s startup files, or on Windows as a user environment variable.';
+const KEY_CONNECT = 'Connect it from a terminal of your own — the key never reaches the agent or the chat: the command asks for the key with no echo, checks it with one request and saves it for bash, zsh or fish in your shell\'s startup files, or on Windows as a user environment variable.';
 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 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); if Recommendations offers this item, the agent applies it on your chat yes after its danger check; you can also run this yourself in a terminal of your own:';
 const NO_HOME = 'no home directory found: the kit\'s install needs one';
 const INSTALL = [
   'Or the vendor\'s own routes:',

package/tools/recommendations.mjs

@@ -49,7 +49,7 @@ import {
 } from './velocity-profile.mjs';
 import { loadAutonomy, isSparseSeedConfig, AUTONOMY_REL } from './autonomy-config.mjs';
 import { deriveDoctorPlan, TRUSTED_DIRS } from './autonomy-doctor.mjs';
-import { laneOf, routeLine } from './write-lanes.mjs';
+import { laneOf, applySlot } from './write-lanes.mjs';
 import { detectBackends, findOnPath } from './detect-backends.mjs';
 import { isDirectRun } from './direct-run.mjs';
 import { ACTIVITIES, resolveActivityRecipe, composeReadiness, safeLine } from './recipes.mjs';
@@ -1574,7 +1574,7 @@ export const probeJevConnect = ({ root, deps, add, skip }) => {
     const host = deps.jevHost ?? {};
     const place = placeOf({ env, platform: host.platform, hostname: host.hostname, container: host.container });
     const decline = `node ${q(toolPath('ack-write.mjs'))} --lane jev-connect --fingerprint ${JEV_CONNECT_DECLINE} --cwd ${q(root)}`;
-    add('jev-connect', WHATS['jev-connect'], routeLine('jev-connect'), 'jev-connect',
+    add('jev-connect', WHATS['jev-connect'], applySlot('jev-connect', { toolsDir: HERE }).apply, 'jev-connect',
       `${place ? `run the apply in ${place}; ` : ''}HAND-APPLY alternative (instead of the apply, never after it): decline the offer by recording it — ${decline}`);
   } catch (err) {
     skip('jev-connect', err);
@@ -1582,7 +1582,7 @@ export const probeJevConnect = ({ root, deps, add, skip }) => {
 };
 
 // The Jev skill offer (contract: kit/jev-guide, part jev-offer): only once the key is set, so one jev item shows at a time.
-// Each target is judged by the facts leaf's one state rule; the apply is the skill command the USER runs (HAND-APPLY).
+// Each target is judged by the facts leaf's one state rule; the item's apply comes from the lane leaf's checked slot.
 export const probeJevSkill = ({ root, deps, add, skip }) => {
   try {
     const env = deps.getenv ?? {};
@@ -1608,7 +1608,7 @@ export const probeJevSkill = ({ root, deps, add, skip }) => {
     const untouched = judged.filter(({ state }) => state === 'foreign')
       .map(({ path, reason }) => `left untouched: ${printable(path)} — ${printable(reason)}; `).join('');
     const record = `node ${q(toolPath('ack-write.mjs'))} --lane jev-skill --fingerprint ${decline} --cwd ${q(root)}`;
-    add('jev-skill', what, `HAND-APPLY: ${line}`, behind.length ? 'jev-skill.earlier' : 'jev-skill',
+    add('jev-skill', what, line, behind.length ? 'jev-skill.earlier' : 'jev-skill',
       `${place ? `run the apply in ${place}; ` : ''}${untouched}${note ? `${note}; ` : ''}HAND-APPLY alternative (instead of the apply, never after it): decline the offer by recording it — ${record}`);
   } catch (err) {
     skip('jev-skill', err);
@@ -1686,7 +1686,13 @@ export const buildRecommendations = ({ cwd, deps = {} } = {}) => {
       skip(key, new Error(`item shape violation — ${problems.join('; ')}`));
       return false;
     }
-    items.push({ key, variant, severity: SEVERITIES[variant], lane: laneOf(variant), what, benefit: BENEFITS[key], apply: routeLine(variant) ?? apply, detail });
+    const slot = applySlot(variant, {
+      toolsDir: HERE, root, env: deps.getenv ?? {},
+      home: deps.jevHost?.home ?? deps.home ?? '',
+      platform: deps.jevHost?.platform ?? deps.platform,
+    });
+    items.push({ key, variant, severity: SEVERITIES[variant], lane: laneOf(variant), what, benefit: BENEFITS[key],
+      check: slot?.check ?? null, apply: slot?.apply ?? apply, detail });
     return true;
   };
   // The per-run scratch a probe uses to tell a LATER probe what it actually did. Written by exactly
@@ -1736,6 +1742,7 @@ export const formatRecommendations = ({ items, skips }) => {
       lines.push(`   benefit: ${item.benefit}`);
       lines.push(`   lane: ${item.lane}`);
       if (item.detail) lines.push(`   recipe: ${item.detail}`);
+      if (item.check != null) lines.push(`   check: ${item.check}`);
       lines.push(`   apply: ${item.apply}`);
     });
   }
@@ -1752,9 +1759,9 @@ Usage:
 
 Computes the deterministic Recommendations section every kit upgrade ends with — VERDICT-FIRST:
 one composed verdict line opens every non-optimal render, then per item {severity · what is
-sub-optimal · the benefit in one plain line · an optional \`recipe:\` line (the sandbox-lane live
+sub-optimal · the benefit in one plain line · the lane · an optional \`recipe:\` line (the sandbox-lane live
 recipe, the worktrees-dir hand-apply-first grant advice, or the agents hidden-mode reconcile
-follow-up) · the exact consent-gated apply one-liner}. --cwd is
+follow-up) · the harness check line · the exact consent-gated apply one-liner}. --cwd is
 REQUIRED (the target project is explicit, never inferred from the shell's current directory). The
 section renders present-even-when-empty ("${RECOMMENDATIONS_EMPTY_LINE}"); a probe failure is a
 stated skipped-item line. Apply lines are cwd-independent (absolute tool paths, a pinned --cwd;