@fiodos/cli 0.1.23 → 0.1.26

package/src/wireSession.js

@@ -0,0 +1,755 @@
+/**
+ * wireSession — automatic session (auth) wiring. NO MANUAL STEP.
+ *
+ * WHY: actions marked `requiresAuth` are gated by the SDK on the host's
+ * `isAuthenticated()`. Until now connecting it was "the only manual step"
+ * documented in FYODOS_ORB_MOUNT.md — and the step people skip (we skipped it
+ * in our own dashboard). Without it the agent cannot know the session state
+ * and every requiresAuth action fails closed. This module closes that gap the
+ * same way handler wiring closed the `registries` gap: the SAME AI that read
+ * the app's code says WHERE the session lives, a mechanical verifier confirms
+ * every referenced symbol really exists, the wiring is applied under the same
+ * consent, and a build check reverts it if anything regressed.
+ *
+ * WHAT IT PRODUCES:
+ *   · `src/fyodos/session.generated.<ext>` exporting two functions consumed by
+ *     the orb mount:
+ *       - fyodosIsAuthenticated(): boolean | null   (null = UNKNOWN → the
+ *         engine fails closed with an HONEST message, never "you are signed out")
+ *       - fyodosGetUserId(): string | null          (keys conversation memory
+ *         per user; hashed locally by the SDK, never sent anywhere)
+ *   · MODULE strategy: the generated file imports the app's own auth source
+ *     (exported store/function) and reads it directly.
+ *   · BRIDGE strategy: the session lives in component state (React context,
+ *     hook, provider). We insert a tiny reversible registration block into
+ *     that component (markers FYODOS:SESSION:START/END — separate from the
+ *     handler FYODOS:BRIDGE blocks so neither strips the other) and the
+ *     generated file reads the live values through the shared bridge module.
+ *
+ * SECURITY / HONESTY:
+ *   · No secrets are read or embedded — only a boolean "is there a session?"
+ *     and an opaque user id string the app already holds.
+ *   · Everything the AI proposed is mechanically verified (files, anchors,
+ *     symbols) before writing; unverifiable → honest "review" report, never a
+ *     blind write.
+ *   · All edits are reversible (markers) and reverted automatically when the
+ *     app stops compiling.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  fileHasSymbol,
+  freeIdentifiers,
+  declaredLocals,
+  detachedInstanceReceiver,
+  countOccurrences,
+  readFileSafe,
+  normRel,
+  relImport,
+  detectTsEsm,
+  resolveFiodosDirRel,
+  askYesNo,
+  JS_KEYWORDS,
+  SAFE_GLOBALS,
+  GENERATED_FILE_DIRECTIVES,
+  INJECT_ESLINT_DISABLE,
+  INJECT_ESLINT_ENABLE,
+  BRIDGE_BASENAME,
+  buildBridgeModule,
+  insertImportBlock,
+  insertRegisterBlock,
+  deriveBridgeAnchor,
+} = require('./wireHandlers');
+
+const SESSION_BASENAME = 'session.generated';
+const DOC_BASENAME = 'FYODOS_SESSION.md';
+const IS_AUTH_EXPORT = 'fyodosIsAuthenticated';
+const USER_ID_EXPORT = 'fyodosGetUserId';
+const CAPS_EXPORT = 'fyodosGetSessionCapabilities';
+const BRIDGE_IS_AUTH = '__fyodos_is_authenticated';
+const BRIDGE_USER_ID = '__fyodos_user_id';
+const BRIDGE_CAPABILITIES = '__fyodos_capabilities';
+
+// Capability flags are short snake_case names ("has_payment_method"). Anything
+// else is dropped: a malformed name could never match the manifest's
+// requiredCapabilities anyway, so wiring it would be dead weight.
+const CAPABILITY_NAME_RE = /^[a-z][a-z0-9_]{0,63}$/;
+
+// Session edits carry their OWN markers: wireHandlers' stripFiodosBlocks
+// removes every FYODOS:BRIDGE block in a file, so if the session registration
+// shared that marker, re-running handler wiring on the same component would
+// silently delete the session bridge (and vice versa).
+const SESSION_EDIT_START_PREFIX = '// FYODOS:SESSION:START';
+const SESSION_EDIT_START = `${SESSION_EDIT_START_PREFIX} (generated by Fiodos — safe to remove)`;
+const SESSION_EDIT_END = '// FYODOS:SESSION:END';
+
+function esc(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Remove previously-inserted session blocks (idempotence across re-runs). */
+function stripSessionBlocks(content) {
+  const re = new RegExp(
+    `\\n?${esc(SESSION_EDIT_START_PREFIX)}[^\\n]*[\\s\\S]*?${esc(SESSION_EDIT_END)}\\n?`,
+    'g',
+  );
+  return content.replace(re, '\n');
+}
+
+// ── Mechanical verification of the AI's session proposal ───────────────────────
+
+function verifyImports({ appRoot, rawImports, importBaseDirRel }) {
+  const imports = [];
+  const importedNames = new Set();
+  for (const imp of Array.isArray(rawImports) ? rawImports : []) {
+    const name = String((imp && imp.name) || '').trim();
+    const from = normRel(imp && imp.from);
+    const kind = (imp && imp.kind) || 'named';
+    if (!name || !from) return { reason: 'a session import is incomplete (missing name/from)' };
+    if (!fs.existsSync(path.join(appRoot, from))) {
+      return { reason: `the session import points to a non-existent file: '${from}'` };
+    }
+    if (kind === 'named' && !fileHasSymbol(appRoot, from, name)) {
+      return { reason: `named import '${name}' does not exist in '${from}'` };
+    }
+    imports.push({ kind, name, importPath: relImport(importBaseDirRel, from) });
+    importedNames.add(name);
+  }
+  return { imports, importedNames };
+}
+
+function verifyExpr({ expr, importedNames, extraOk = new Set(), what }) {
+  const detached = detachedInstanceReceiver(expr);
+  if (detached) {
+    return `the ${what} expression instantiates '${detached}' with 'new' and uses it as the receiver; a fresh instance is disconnected from the app's real session state`;
+  }
+  const locals = declaredLocals(expr);
+  for (const id of freeIdentifiers(expr)) {
+    if (JS_KEYWORDS.has(id) || SAFE_GLOBALS.has(id) || importedNames.has(id) || locals.has(id) || extraOk.has(id)) {
+      continue;
+    }
+    return `the ${what} expression references '${id}', which could not be verified in your code`;
+  }
+  return null;
+}
+
+/**
+ * Verify the AI's fine-grained session capabilities (Eje B audience map:
+ * "has_payment_method", "is_admin"…) INDIVIDUALLY: a hallucinated capability
+ * is dropped with an honest note while the rest of the session wiring still
+ * applies — one bad flag must never cost the whole auth awareness.
+ * Returns { caps: [{ name, expr }], notes: [reason...] }.
+ */
+function verifyCapabilities({ rawCapabilities, exprKey, importedNames, extraOk = new Set() }) {
+  const caps = [];
+  const notes = [];
+  const seen = new Set();
+  for (const c of Array.isArray(rawCapabilities) ? rawCapabilities : []) {
+    const name = String((c && c.name) || '').trim();
+    const expr = String((c && c[exprKey]) || '').trim();
+    if (!CAPABILITY_NAME_RE.test(name)) {
+      notes.push(`capability '${name || '(unnamed)'}' dropped: not a short snake_case name`);
+      continue;
+    }
+    if (seen.has(name)) continue;
+    if (!expr) {
+      notes.push(`capability '${name}' dropped: no '${exprKey}' expression was provided`);
+      continue;
+    }
+    const err = verifyExpr({ expr, importedNames, extraOk, what: `capability '${name}'` });
+    if (err) {
+      notes.push(`capability '${name}' dropped: ${err}`);
+      continue;
+    }
+    seen.add(name);
+    caps.push({ name, expr });
+  }
+  return { caps: caps.slice(0, 8), notes };
+}
+
+/**
+ * Turn the AI's `session` block into a verified plan, or { reason }.
+ * Plan shapes:
+ *   { strategy:'module', imports, isAuthExpr, userIdExpr|null, capabilities, capabilityNotes }
+ *   { strategy:'bridge', bridge:{ file, anchor, scope, imports, isAuthInvoke, userIdInvoke|null,
+ *     capabilities }, capabilityNotes }
+ */
+function prepareSessionPlan({ appRoot, session, fyodosDirRel }) {
+  if (!session || typeof session !== 'object') return { reason: 'no session block' };
+  if (session.hasLogin === false || session.strategy === 'none') {
+    return { none: true, reason: String(session.reason || 'the app has no login') };
+  }
+
+  // Every requiredSymbol must really exist wherever the AI says it does.
+  const required = Array.isArray(session.requiredSymbols) ? session.requiredSymbols : [];
+  for (const r of required) {
+    if (!fileHasSymbol(appRoot, r && r.file, r && r.name)) {
+      return {
+        reason: `the verifier did not find symbol '${r && r.name}' in '${normRel(r && r.file)}'`,
+      };
+    }
+  }
+
+  if (session.strategy === 'bridge') {
+    const b = session.bridge || {};
+    const file = normRel(b.file);
+    let anchor = String(b.anchor || '').trim();
+    const isAuthInvoke = String(b.isAuthenticatedInvoke || '').trim();
+    const userIdInvoke = String(b.userIdInvoke || '').trim() || null;
+
+    if (!file) return { reason: 'the AI marked a session bridge but gave no component file' };
+    const content = readFileSafe(appRoot, file);
+    if (content == null) return { reason: `could not read the component '${file}'` };
+    if (!isAuthInvoke) return { reason: `no isAuthenticated expression was provided for '${file}'` };
+    // The anchor must be unique in the file WITHOUT counting our own previous
+    // insertions (idempotent re-runs). When the AI's anchor is missing or
+    // ambiguous, derive a deterministic one from the declaration of the symbol
+    // the invoke reads (same rescue as handler bridges) instead of giving up —
+    // safety is still guaranteed by the compile check + revert below.
+    const cleanContent = stripSessionBlocks(content);
+    const occ = anchor ? countOccurrences(cleanContent, anchor) : 0;
+    if (occ !== 1) {
+      const derived = deriveBridgeAnchor(cleanContent, isAuthInvoke);
+      if (derived) anchor = derived;
+      else if (!anchor || occ === 0) return { reason: `no safe insertion point was found in '${file}'` };
+      else return { reason: `the insertion anchor appears ${occ} times in '${file}'; it is ambiguous` };
+    }
+
+    const v = verifyImports({ appRoot, rawImports: b.imports, importBaseDirRel: path.dirname(file) });
+    if (v.reason) return v;
+
+    // Identifiers must be in-file, imported, args-free locals or safe globals.
+    const inFileOk = new Set();
+    const capExprs = (Array.isArray(session.capabilities) ? session.capabilities : [])
+      .map((c) => String((c && c.invoke) || '').trim())
+      .filter(Boolean);
+    for (const expr of [isAuthInvoke, userIdInvoke, ...capExprs].filter(Boolean)) {
+      for (const id of freeIdentifiers(expr)) {
+        if (fileHasSymbol(appRoot, file, id)) inFileOk.add(id);
+      }
+    }
+    for (const expr of [isAuthInvoke, userIdInvoke].filter(Boolean)) {
+      const err = verifyExpr({ expr, importedNames: v.importedNames, extraOk: inFileOk, what: 'session' });
+      if (err) return { reason: `${err} — in '${file}'` };
+    }
+    const capsV = verifyCapabilities({
+      rawCapabilities: session.capabilities,
+      exprKey: 'invoke',
+      importedNames: v.importedNames,
+      extraOk: inFileOk,
+    });
+
+    return {
+      plan: {
+        strategy: 'bridge',
+        reason: String(session.reason || ''),
+        capabilityNotes: capsV.notes,
+        bridge: {
+          file,
+          anchor,
+          scope: b.scope === 'class-field' ? 'class-field' : 'statement',
+          imports: v.imports,
+          isAuthInvoke,
+          userIdInvoke,
+          capabilities: capsV.caps,
+          importPathToBridge: relImport(path.dirname(file), path.join(fyodosDirRel, BRIDGE_BASENAME)),
+        },
+      },
+    };
+  }
+
+  // MODULE strategy (default): the generated file reads the session directly.
+  const isAuthExpr = String(session.isAuthenticatedCall || '').trim();
+  const userIdExpr = String(session.userIdCall || '').trim() || null;
+  if (!isAuthExpr) return { reason: 'the AI did not provide an isAuthenticated expression' };
+
+  const v = verifyImports({ appRoot, rawImports: session.imports, importBaseDirRel: fyodosDirRel });
+  if (v.reason) return v;
+  for (const expr of [isAuthExpr, userIdExpr].filter(Boolean)) {
+    const err = verifyExpr({ expr, importedNames: v.importedNames, what: 'session' });
+    if (err) return { reason: err };
+  }
+  const capsV = verifyCapabilities({
+    rawCapabilities: session.capabilities,
+    exprKey: 'call',
+    importedNames: v.importedNames,
+  });
+
+  return {
+    plan: {
+      strategy: 'module',
+      reason: String(session.reason || ''),
+      imports: v.imports,
+      isAuthExpr,
+      userIdExpr,
+      capabilities: capsV.caps,
+      capabilityNotes: capsV.notes,
+    },
+  };
+}
+
+// ── Codegen ─────────────────────────────────────────────────────────────────────
+
+function importLine(imp, esm) {
+  if (!esm) return `const { ${imp.name} } = require('${imp.importPath}');`;
+  if (imp.kind === 'default') return `import ${imp.name} from '${imp.importPath}';`;
+  if (imp.kind === 'namespace') return `import * as ${imp.name} from '${imp.importPath}';`;
+  return `import { ${imp.name} } from '${imp.importPath}';`;
+}
+
+/**
+ * The generated session module. Tri-state contract with the SDK:
+ * `null` = UNKNOWN (never claim "signed out" — the engine answers honestly
+ * and warns the developer); boolean = the app's real verdict.
+ */
+function buildSessionModule(plan, opts = {}) {
+  const ts = opts.ts !== false;
+  const esm = opts.esm !== false;
+  const boolRet = ts ? ': boolean | null' : '';
+  const strRet = ts ? ': string | null' : '';
+  const capsRet = ts ? ': Record<string, boolean> | null' : '';
+  const capsDecl = ts ? ': Record<string, boolean>' : '';
+
+  const L = [];
+  L.push(
+    `${GENERATED_FILE_DIRECTIVES}/** GENERATED by Fiodos — session wiring. Do not edit — re-run the Fiodos installer to regenerate. */`,
+  );
+  L.push('');
+
+  if (plan.strategy === 'bridge') {
+    L.push(
+      esm
+        ? `import { getFiodosBridge } from './${BRIDGE_BASENAME}';`
+        : `const { getFiodosBridge } = require('./${BRIDGE_BASENAME}');`,
+    );
+    L.push('');
+    L.push('/**');
+    L.push(' * Tri-state session check consumed by the orb (requiresAuth gate):');
+    L.push(' * true = signed in, false = signed out, null = UNKNOWN (the component');
+    L.push(' * that registers the live session has not rendered yet). On null the');
+    L.push(' * Fiodos engine fails closed with an honest message — it NEVER tells');
+    L.push(' * the user "you need to be signed in" when it cannot know.');
+    L.push(' */');
+    L.push(`export function ${IS_AUTH_EXPORT}()${boolRet} {`);
+    L.push('  try {');
+    L.push(`    const fn = getFiodosBridge()[${JSON.stringify(BRIDGE_IS_AUTH)}];`);
+    L.push("    if (typeof fn !== 'function') return null;");
+    L.push('    return Boolean(fn());');
+    L.push('  } catch {');
+    L.push('    return null;');
+    L.push('  }');
+    L.push('}');
+    L.push('');
+    L.push('/** Stable end-user id (hashed locally by the SDK) or null when signed out/unknown. */');
+    L.push(`export function ${USER_ID_EXPORT}()${strRet} {`);
+    L.push('  try {');
+    L.push(`    const fn = getFiodosBridge()[${JSON.stringify(BRIDGE_USER_ID)}];`);
+    L.push("    if (typeof fn !== 'function') return null;");
+    L.push('    const v = fn();');
+    L.push("    return v == null || v === '' ? null : String(v);");
+    L.push('  } catch {');
+    L.push('    return null;');
+    L.push('  }');
+    L.push('}');
+    L.push('');
+    L.push('/**');
+    L.push(' * Fine-grained session capability flags (audience map: has_payment_method,');
+    L.push(' * is_admin…). null = UNKNOWN — the orb then filters NOTHING (fail-open).');
+    L.push(' * Boolean flags only; never counts, names or any user data.');
+    L.push(' */');
+    L.push(`export function ${CAPS_EXPORT}()${capsRet} {`);
+    L.push('  try {');
+    L.push(`    const fn = getFiodosBridge()[${JSON.stringify(BRIDGE_CAPABILITIES)}];`);
+    L.push("    if (typeof fn !== 'function') return null;");
+    L.push('    const raw = fn();');
+    L.push("    if (!raw || typeof raw !== 'object') return null;");
+    L.push(`    const caps${capsDecl} = {};`);
+    L.push('    for (const k of Object.keys(raw)) {');
+    L.push("      if (typeof raw[k] === 'boolean') caps[k] = raw[k];");
+    L.push('    }');
+    L.push('    return Object.keys(caps).length > 0 ? caps : null;');
+    L.push('  } catch {');
+    L.push('    return null;');
+    L.push('  }');
+    L.push('}');
+  } else {
+    for (const imp of plan.imports || []) L.push(importLine(imp, esm));
+    if ((plan.imports || []).length) L.push('');
+    L.push('/**');
+    L.push(' * Tri-state session check consumed by the orb (requiresAuth gate):');
+    L.push(' * true = signed in, false = signed out, null = UNKNOWN (read failed).');
+    L.push(' */');
+    L.push(`export function ${IS_AUTH_EXPORT}()${boolRet} {`);
+    L.push('  try {');
+    L.push(`    return Boolean(${plan.isAuthExpr});`);
+    L.push('  } catch {');
+    L.push('    return null;');
+    L.push('  }');
+    L.push('}');
+    L.push('');
+    L.push('/** Stable end-user id (hashed locally by the SDK) or null when signed out/unknown. */');
+    L.push(`export function ${USER_ID_EXPORT}()${strRet} {`);
+    if (plan.userIdExpr) {
+      L.push('  try {');
+      L.push(`    const v = ${plan.userIdExpr};`);
+      L.push("    return v == null || v === '' ? null : String(v);");
+      L.push('  } catch {');
+      L.push('    return null;');
+      L.push('  }');
+    } else {
+      L.push('  return null;');
+    }
+    L.push('}');
+    L.push('');
+    L.push('/**');
+    L.push(' * Fine-grained session capability flags (audience map: has_payment_method,');
+    L.push(' * is_admin…). null = UNKNOWN — the orb then filters NOTHING (fail-open).');
+    L.push(' * Boolean flags only; never counts, names or any user data.');
+    L.push(' */');
+    L.push(`export function ${CAPS_EXPORT}()${capsRet} {`);
+    const moduleCaps = Array.isArray(plan.capabilities) ? plan.capabilities : [];
+    if (moduleCaps.length > 0) {
+      L.push(`  const caps${capsDecl} = {};`);
+      for (const c of moduleCaps) {
+        // Each flag is isolated: one throwing read stays UNKNOWN (omitted)
+        // instead of blanking every other capability.
+        L.push('  try {');
+        L.push(`    caps[${JSON.stringify(c.name)}] = Boolean(${c.expr});`);
+        L.push('  } catch {');
+        L.push('    /* unknown — omitted (fail-open) */');
+        L.push('  }');
+      }
+      L.push('  return Object.keys(caps).length > 0 ? caps : null;');
+    } else {
+      L.push('  return null;');
+    }
+    L.push('}');
+  }
+  L.push('');
+  if (!esm) L.push(`module.exports = { ${IS_AUTH_EXPORT}, ${USER_ID_EXPORT}, ${CAPS_EXPORT} };`);
+  let body = L.join('\n');
+  if (!esm) {
+    // CommonJS build: `export function` is invalid — rewrite to plain functions.
+    body = body.replace(/^export function /gm, 'function ');
+  }
+  return `${body}\n`;
+}
+
+/** Plan the reversible edit inserted into the session-owning component. */
+function planSessionComponentEdit(appRoot, plan) {
+  if (plan.strategy !== 'bridge') return null;
+  const b = plan.bridge;
+  const content = readFileSafe(appRoot, b.file) || '';
+
+  const methods = [`  ${JSON.stringify(BRIDGE_IS_AUTH)}: () => (${b.isAuthInvoke}),`];
+  if (b.userIdInvoke) methods.push(`  ${JSON.stringify(BRIDGE_USER_ID)}: () => (${b.userIdInvoke}),`);
+  const caps = Array.isArray(b.capabilities) ? b.capabilities : [];
+  if (caps.length > 0) {
+    const entries = caps.map((c) => `${JSON.stringify(c.name)}: Boolean(${c.expr})`).join(', ');
+    methods.push(`  ${JSON.stringify(BRIDGE_CAPABILITIES)}: () => ({ ${entries} }),`);
+  }
+
+  const importLines = [`import { registerFiodosBridge } from '${b.importPathToBridge}';`];
+  for (const imp of b.imports || []) importLines.push(importLine(imp, true));
+
+  const registerCall =
+    b.scope === 'class-field'
+      ? `private __fyodosSessionBridge = registerFiodosBridge({\n${methods.join('\n')}\n});`
+      : `registerFiodosBridge({\n${methods.join('\n')}\n});`;
+
+  const anchorIdx = content.indexOf(b.anchor);
+  const lineStart = content.lastIndexOf('\n', anchorIdx) + 1;
+  const indent = (content.slice(lineStart, anchorIdx).match(/^\s*/) || [''])[0];
+  const registerBlock = `${SESSION_EDIT_START}\n${INJECT_ESLINT_DISABLE}\n${registerCall}\n${INJECT_ESLINT_ENABLE}\n${SESSION_EDIT_END}`;
+
+  return {
+    file: b.file,
+    anchor: b.anchor,
+    scope: b.scope,
+    importBlock: `${SESSION_EDIT_START}\n${INJECT_ESLINT_DISABLE}\n${importLines.join('\n')}\n${INJECT_ESLINT_ENABLE}\n${SESSION_EDIT_END}`,
+    registerBlock: registerBlock
+      .split('\n')
+      .map((l) => (l ? indent + l : l))
+      .join('\n'),
+  };
+}
+
+/** True when the (TS/JS/TSX/JSX) source still parses. Fail-open without esbuild. */
+function parsesOk(source, file) {
+  if (file.endsWith('.vue') || file.endsWith('.svelte')) return true; // SFCs: not parseable standalone
+  try {
+    const esbuild = require('esbuild');
+    const loader = /\.tsx$/.test(file) ? 'tsx' : /\.jsx$/.test(file) ? 'jsx' : /\.ts$/.test(file) ? 'ts' : 'js';
+    esbuild.transformSync(source, { loader });
+    return true;
+  } catch (e) {
+    if (e && e.code === 'MODULE_NOT_FOUND') return true;
+    return false;
+  }
+}
+
+/** Apply the session component edit (idempotent, snapshot for revert). */
+function applySessionComponentEdit(appRoot, edit) {
+  const abs = path.join(appRoot, normRel(edit.file));
+  const original = fs.readFileSync(abs, 'utf8');
+  let next = stripSessionBlocks(original);
+  next = insertImportBlock(next, edit.importBlock);
+  next = insertRegisterBlock(next, edit.file, edit.anchor, edit.registerBlock, edit.scope);
+  // Last-line defense: never leave a component that does not even PARSE. The
+  // full build check (when available) still runs after this.
+  if (!parsesOk(next, edit.file)) {
+    throw new Error(`the session registration would break '${edit.file}' (parse check failed)`);
+  }
+  fs.writeFileSync(abs, next);
+  return { file: edit.file, abs, original };
+}
+
+// ── Document ────────────────────────────────────────────────────────────────────
+
+function buildSessionDoc(plan, ctx = {}) {
+  const { appName = 'your app', sessionRel = '', editedFile = '', verified = false, verifyNote = '' } = ctx;
+  const L = [];
+  L.push('# Fiodos — session wiring (auth awareness)');
+  L.push('');
+  L.push('Connects the orb to your app\'s REAL session state, automatically. This is what');
+  L.push('lets the agent know whether the user is signed in (actions marked `requiresAuth`)');
+  L.push('and keep each user\'s conversation memory private on shared devices (`getUserId`,');
+  L.push('hashed locally — never sent anywhere).');
+  L.push('');
+  L.push(`- App: \`${appName}\``);
+  L.push(`- Strategy: \`${plan.strategy}\`${plan.reason ? ` — ${plan.reason}` : ''}`);
+  L.push(`- Creates \`${sessionRel}\` — exports \`${IS_AUTH_EXPORT}()\`, \`${USER_ID_EXPORT}()\` and \`${CAPS_EXPORT}()\`.`);
+  if (editedFile) {
+    L.push(`- Edits \`${editedFile}\` (only reversible \`FYODOS:SESSION\` blocks) to register the live session.`);
+  }
+  const planCaps =
+    plan.strategy === 'bridge'
+      ? (plan.bridge && plan.bridge.capabilities) || []
+      : plan.capabilities || [];
+  if (planCaps.length > 0) {
+    L.push(
+      `- Capability flags (audience map): ${planCaps.map((c) => `\`${c.name}\``).join(', ')} — boolean-only, read live from the same session source. Actions whose \`requiredCapabilities\` report false are hidden from that user's orb.`,
+    );
+  }
+  for (const note of plan.capabilityNotes || []) {
+    L.push(`- Capability left out: ${note}.`);
+  }
+  L.push(`- Verification: ${verified ? 'build check passed' : verifyNote || 'compile check unavailable — applied with the mechanical symbol verification only'}.`);
+  L.push('');
+  L.push('## Honesty contract (tri-state)');
+  L.push('');
+  L.push(`\`${IS_AUTH_EXPORT}()\` returns \`true\` (signed in), \`false\` (signed out) or \`null\``);
+  L.push('(UNKNOWN — e.g. the registering component has not rendered yet). On `null` the');
+  L.push('Fiodos engine blocks the gated action with an honest "can\'t do that from here"');
+  L.push('message; it never claims the user is signed out when it cannot know.');
+  L.push('');
+  L.push('## Security');
+  L.push('');
+  L.push('- Only a boolean session verdict and an opaque user id the app already holds are read.');
+  L.push('- No tokens, credentials or secrets are referenced or embedded.');
+  L.push('- Remove the generated file and the `FYODOS:SESSION` blocks to revert entirely.');
+  L.push('');
+  return L.join('\n');
+}
+
+// ── Main entry ──────────────────────────────────────────────────────────────────
+
+/**
+ * Wire the session automatically. Options:
+ *   session      — the AI's `session` block from the analysis.
+ *   assumeYes    — apply without asking (piggybacks on the handler-wiring consent).
+ *   runTest / testRunner — same build safety net as handler wiring.
+ * Returns { status, sessionFile?, docPath?, editedFile?, reason? } with status in:
+ *   'applied' | 'applied-untested' | 'no-session' | 'review' | 'declined' |
+ *   'reverted' | 'skipped'.
+ */
+async function wireSession(appRoot, opts = {}) {
+  const {
+    session,
+    colors = {},
+    quiet = false,
+    assumeYes = false,
+    noWire = false,
+    framework = 'web',
+    appName,
+    runTest = false,
+    testRunner = null,
+    ts: tsOpt,
+    esm: esmOpt,
+  } = opts;
+  const { blue, cyan, dim, reset } = colors;
+  const tag = `${cyan || ''}◉${reset || ''} ${blue || ''}Fiodos${reset || ''}`;
+
+  if (noWire) return { status: 'skipped', reason: 'no-wire' };
+  if (!session) return { status: 'no-session', reason: 'the analysis returned no session block' };
+
+  const fyodosDirRel = resolveFiodosDirRel(appRoot);
+  const fyodosDirAbs = path.join(appRoot, fyodosDirRel);
+  const detected = detectTsEsm(appRoot);
+  const ts = tsOpt != null ? tsOpt : detected.ts;
+  const esm = esmOpt != null ? esmOpt : detected.esm;
+  const ext = ts ? '.ts' : esm ? '.js' : '.cjs';
+
+  const prep = prepareSessionPlan({ appRoot, session, fyodosDirRel });
+  if (prep.none) return { status: 'no-session', reason: prep.reason };
+  if (!prep.plan) {
+    if (!quiet) {
+      console.error(`${tag} · ${dim || ''}Session wiring left for review: ${prep.reason}${reset || ''}`);
+    }
+    return { status: 'review', reason: prep.reason };
+  }
+  const plan = prep.plan;
+
+  // Consent. Normally the handler-wiring consent already covered code edits
+  // (assumeYes=true from the caller); ask only when it did not.
+  if (!assumeYes) {
+    if (!process.stdin.isTTY) return { status: 'declined', reason: 'non-interactive' };
+    const target = plan.strategy === 'bridge' ? ` (registers it from \`${plan.bridge.file}\`)` : '';
+    const yes = await askYesNo(
+      `\n${tag} · Connect the orb to your app's session state automatically${target}? [yes/no] `,
+    );
+    if (!yes) return { status: 'declined' };
+  }
+
+  // Baseline BEFORE touching anything.
+  let baseline = null;
+  if (runTest && testRunner) {
+    try {
+      baseline = await testRunner(appRoot, { framework });
+    } catch (err) {
+      baseline = { ok: false, stage: 'runner', output: err && err.message };
+    }
+  }
+
+  fs.mkdirSync(fyodosDirAbs, { recursive: true });
+  const sessionAbs = path.join(fyodosDirAbs, `${SESSION_BASENAME}${ext}`);
+  const bridgeAbs = path.join(fyodosDirAbs, `${BRIDGE_BASENAME}${ext}`);
+  const generated = [sessionAbs];
+  let backups = [];
+  let bridgeCreatedByUs = false;
+
+  try {
+    if (plan.strategy === 'bridge' && !fs.existsSync(bridgeAbs)) {
+      fs.writeFileSync(bridgeAbs, buildBridgeModule({ ts, esm }));
+      bridgeCreatedByUs = true;
+      generated.push(bridgeAbs);
+    }
+    fs.writeFileSync(sessionAbs, buildSessionModule(plan, { ts, esm }));
+    const edit = planSessionComponentEdit(appRoot, plan);
+    if (edit) backups = [applySessionComponentEdit(appRoot, edit)];
+  } catch (err) {
+    for (const b of backups) fs.writeFileSync(b.abs, b.original);
+    for (const f of generated) {
+      try {
+        if (fs.existsSync(f)) fs.rmSync(f);
+      } catch {
+        /* best effort */
+      }
+    }
+    return { status: 'reverted', reason: err && err.message };
+  }
+
+  // Build safety net: if the app compiled before and stops compiling now,
+  // revert the session wiring entirely — never leave the app broken.
+  let verified = false;
+  let verifyNote = '';
+  if (runTest && testRunner) {
+    let after;
+    try {
+      after = await testRunner(appRoot, { framework });
+    } catch (err) {
+      after = { ok: false, stage: 'runner', output: err && err.message };
+    }
+    if (after && after.ok) {
+      verified = true;
+    } else if (baseline && baseline.ok) {
+      for (const b of backups) fs.writeFileSync(b.abs, b.original);
+      for (const f of generated) {
+        try {
+          if (fs.existsSync(f)) fs.rmSync(f);
+        } catch {
+          /* best effort */
+        }
+      }
+      if (!quiet) {
+        console.error(
+          `${tag} · ${dim || ''}Session wiring reverted: the app stopped compiling with it applied.${reset || ''}`,
+        );
+      }
+      return { status: 'reverted', reason: 'compile regression', output: after && after.output };
+    } else {
+      verifyNote = 'the app did not compile BEFORE wiring either — applied; symbols were verified mechanically';
+    }
+  }
+
+  const docAbs = path.join(fyodosDirAbs, DOC_BASENAME);
+  const sessionRel = path.relative(appRoot, sessionAbs).split(path.sep).join('/');
+  fs.writeFileSync(
+    docAbs,
+    buildSessionDoc(plan, {
+      appName: appName || path.basename(appRoot),
+      sessionRel,
+      editedFile: plan.strategy === 'bridge' ? plan.bridge.file : '',
+      verified,
+      verifyNote,
+    }),
+  );
+
+  return {
+    status: verified ? 'applied' : 'applied-untested',
+    sessionFile: sessionAbs,
+    docPath: docAbs,
+    editedFile: plan.strategy === 'bridge' ? plan.bridge.file : '',
+    strategy: plan.strategy,
+    bridgeCreated: bridgeCreatedByUs,
+  };
+}
+
+function reportSessionResult(result, colors = {}, { quiet = false } = {}) {
+  if (!result) return;
+  const { blue, cyan, dim, reset } = colors;
+  const tag = `${cyan || ''}◉${reset || ''} ${blue || ''}Fiodos${reset || ''}`;
+  switch (result.status) {
+    case 'applied':
+      console.error(`${tag} · session connected automatically (${result.strategy}) — the agent now knows when the user is signed in`);
+      break;
+    case 'applied-untested':
+      console.error(`${tag} · session connected (${result.strategy}; compile check unavailable)`);
+      break;
+    case 'review':
+      console.error(`${tag} · ${dim || ''}session left for review: ${result.reason}${reset || ''}`);
+      break;
+    case 'reverted':
+      console.error(`${tag} · ${dim || ''}session wiring reverted (${result.reason})${reset || ''}`);
+      break;
+    case 'no-session':
+      if (!quiet) console.error(`${tag} · ${dim || ''}no login detected — session wiring not needed${reset || ''}`);
+      break;
+    default:
+      break;
+  }
+}
+
+module.exports = {
+  wireSession,
+  reportSessionResult,
+  // exported for tests
+  prepareSessionPlan,
+  buildSessionModule,
+  buildSessionDoc,
+  planSessionComponentEdit,
+  applySessionComponentEdit,
+  stripSessionBlocks,
+  SESSION_BASENAME,
+  IS_AUTH_EXPORT,
+  USER_ID_EXPORT,
+  CAPS_EXPORT,
+  BRIDGE_IS_AUTH,
+  BRIDGE_USER_ID,
+  BRIDGE_CAPABILITIES,
+  SESSION_EDIT_START,
+  SESSION_EDIT_END,
+};