@celilo/cli 1.14.0 → 2.1.0

package/src/cli/commands/system-doctor.ts

@@ -32,13 +32,27 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
+import { hostname } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { resolveBrowser } from '@celilo/capabilities';
 import { defineEvents, openBus } from '@celilo/event-bus';
 import cliPkg from '../../../package.json' with { type: 'json' };
 import { getDbPath, getEventBusPath } from '../../config/paths';
 import { getDb } from '../../db/client';
+import {
+  JAIL_OFF_REASON,
+  type JailAvailability,
+  type JailModeRecord,
+  type JailPolicy,
+  SANDBOX_EXEC_AUTO_DEFERRED_REASON,
+  autoJailDefers,
+  detectJailBackend,
+  jailPolicy,
+  readJailMode,
+} from '../../hooks/jail';
 import type { ModuleManifest } from '../../manifest/schema';
+import { HOOK_JAIL_CHECK } from '../../services/alerting/hook-jail';
+import { findMonitorByTarget } from '../../services/alerting/monitors';
 import {
   type FleetFinding,
   type FleetFindingStatus,
@@ -336,6 +350,112 @@ function provisionedBrowserFlavor(): string | null {
   }
 }
 
+export interface HookExecutionInput {
+  availability: JailAvailability;
+  policy: JailPolicy;
+  /** What the last real module-hook run recorded, if any. */
+  record: JailModeRecord | undefined;
+  host: string;
+  /**
+   * Whether a `hook_jail` monitor exists. `null` when there is no celilo DB to
+   * ask (a dev box), which also suppresses the add-the-monitor hint.
+   */
+  monitored: boolean | null;
+}
+
+/**
+ * The hook-execution section (hook-process-boundary task 4.6).
+ *
+ * Reports design D8's three states the way the design assigns them: jailed is
+ * a ✔ and nothing more; unjailed-and-always-was is reported with the reason in
+ * one actionable sentence and is a warning, not an event; a host that USED to
+ * jail and has stopped is a failure, and the self-monitor (`celilo monitor add
+ * hook_jail`) is what turns it into an alert.
+ *
+ * The headline is the LIVE answer — the probe runs bubblewrap the way a real
+ * spawn would — while the recorded mode says what the last hook actually did.
+ * They disagree exactly when the host changed since the last hook ran, which
+ * is worth seeing, not reconciling away.
+ *
+ * Pure so every branch is testable on a host with no jail (Rule 10.4); the
+ * caller injects what the machine says.
+ */
+export function renderHookExecutionSection(input: HookExecutionInput): {
+  lines: string[];
+  failCount: number;
+  warnCount: number;
+} {
+  const { availability, policy, record, host, monitored } = input;
+  const lines: string[] = ['Hook execution'];
+  let failCount = 0;
+  let warnCount = 0;
+
+  // ce-29z: auto defers on sandbox-exec, so the doctor must not report a jail
+  // the executor will not build. One predicate, two consumers.
+  const autoDeferred = policy === 'auto' && autoJailDefers(availability);
+  const liveJailed = policy !== 'off' && availability.backend !== 'none' && !autoDeferred;
+  if (policy === 'required' && availability.backend === 'none') {
+    lines.push(
+      `  ${ANSI.red}✗${ANSI.reset} CELILO_HOOK_JAIL=required and no jail is available — every module hook on this host fails rather than run unjailed`,
+    );
+    lines.push(`      ${ANSI.dim}${availability.reason ?? 'no reason was recorded'}${ANSI.reset}`);
+    failCount++;
+  } else if (policy === 'off') {
+    lines.push(`  ${ANSI.yellow}⚠${ANSI.reset} hooks run unjailed — ${JAIL_OFF_REASON}`);
+    warnCount++;
+  } else if (availability.backend === 'none') {
+    lines.push(
+      `  ${ANSI.yellow}⚠${ANSI.reset} hooks run unjailed — ${availability.reason ?? 'no reason was recorded'}`,
+    );
+    warnCount++;
+  } else if (autoDeferred) {
+    lines.push(
+      `  ${ANSI.yellow}⚠${ANSI.reset} hooks run unjailed — ${SANDBOX_EXEC_AUTO_DEFERRED_REASON}`,
+    );
+    warnCount++;
+  } else {
+    lines.push(`  ${ANSI.green}✔${ANSI.reset} hooks run jailed (${availability.backend})`);
+  }
+
+  const regressed =
+    record && record.host === host && record.mode === 'unjailed' && record.lastJailed;
+  if (regressed && record.lastJailed) {
+    lines.push(
+      `  ${ANSI.red}✗${ANSI.reset} this host ran hooks jailed (${record.lastJailed.backend}) until ${record.lastJailed.recordedAt} and has stopped`,
+    );
+    if (record.reason) lines.push(`      ${ANSI.dim}${record.reason}${ANSI.reset}`);
+    failCount++;
+    if (monitored === false) {
+      lines.push(
+        `    ${ANSI.dim}→ nothing alerts on this — celilo monitor add ${HOOK_JAIL_CHECK}${ANSI.reset}`,
+      );
+    }
+  } else if (!record) {
+    lines.push(
+      `  ${ANSI.dim}no execution mode recorded yet — the first real module-hook run writes it${ANSI.reset}`,
+    );
+  } else if (record.host !== host) {
+    lines.push(
+      `  ${ANSI.dim}last recorded mode belongs to host "${record.host}" (this data directory moved) — the next hook run re-records${ANSI.reset}`,
+    );
+  } else {
+    const backend = record.mode === 'jailed' ? ` (${record.backend})` : '';
+    lines.push(
+      `  ${ANSI.dim}last hook ran ${record.mode}${backend} at ${record.recordedAt}${ANSI.reset}`,
+    );
+  }
+
+  // The moment this hint pays for itself is BEFORE a regression: the monitor
+  // has to exist for the transition to page anyone.
+  if (liveJailed && monitored === false) {
+    lines.push(
+      `    ${ANSI.dim}→ a host that stops jailing alerts only if monitored: celilo monitor add ${HOOK_JAIL_CHECK}${ANSI.reset}`,
+    );
+  }
+
+  return { lines, failCount, warnCount };
+}
+
 /**
  * mtime (ms) of the installed dispatcher code (`@celilo/event-bus`
  * package.json). The fleet dispatcher check compares this against the
@@ -616,6 +736,33 @@ export async function handleSystemDoctor(
   lines.push(...prereqResult.lines);
   lines.push('');
 
+  // Hook execution mode (hook-process-boundary task 4.6). The policy read
+  // throws on a typo'd CELILO_HOOK_JAIL — report that rather than crash the
+  // doctor, since the same throw is about to fail every hook invocation too.
+  let hookExec: { lines: string[]; failCount: number; warnCount: number };
+  try {
+    hookExec = renderHookExecutionSection({
+      availability: detectJailBackend(),
+      policy: jailPolicy(),
+      record: readJailMode(),
+      host: hostname(),
+      monitored: existsSync(getDbPath())
+        ? findMonitorByTarget(getDb(), HOOK_JAIL_CHECK) !== undefined
+        : null,
+    });
+  } catch (error) {
+    hookExec = {
+      lines: [
+        'Hook execution',
+        `  ${ANSI.red}✗${ANSI.reset} ${error instanceof Error ? error.message : String(error)}`,
+      ],
+      failCount: 1,
+      warnCount: 0,
+    };
+  }
+  lines.push(...hookExec.lines);
+  lines.push('');
+
   const workspaceRoot = findWorkspaceRoot(process.cwd());
   const workspaceVersions = workspaceRoot ? collectWorkspaceVersions(workspaceRoot) : [];
   const workspaceMap = new Map(workspaceVersions.map((w) => [w.name, w]));
@@ -748,6 +895,9 @@ export async function handleSystemDoctor(
   }
   if (driftCount > 0) problems.push(`${driftCount} package(s) behind workspace`);
   if (unresolvedCount > 0) problems.push(`${unresolvedCount} unresolved`);
+  if (hookExec.failCount > 0) {
+    problems.push(`${hookExec.failCount} hook-execution problem(s)`);
+  }
   if (fleet.failCount > 0) problems.push(`${fleet.failCount} fleet check(s) failing`);
   if (aspectFailCount > 0) problems.push(`${aspectFailCount} system(s) missing a fleet aspect`);
 
@@ -760,7 +910,7 @@ export async function handleSystemDoctor(
   }
 
   // Fleet warnings don't fail the run, but they shouldn't read as a clean bill.
-  const warnTotal = fleet.warnCount + aspectWarnCount;
+  const warnTotal = fleet.warnCount + aspectWarnCount + hookExec.warnCount;
   if (warnTotal > 0) {
     lines.push(`${ANSI.yellow}OK with warnings${ANSI.reset} — ${warnTotal} warning(s); see above`);
   } else {

package/src/cli/completion.ts

@@ -8,6 +8,8 @@ import { getDb } from '../db/client';
 import { capabilities, modules } from '../db/schema';
 import type { ModuleManifest } from '../manifest/schema';
 import { SCHEDULABLE_BUILTIN_CHECKS } from '../services/alerting/builtin-source';
+import { HEALTH_COVERAGE_CHECK } from '../services/alerting/health-coverage';
+import { HOOK_JAIL_CHECK } from '../services/alerting/hook-jail';
 import { listPrincipals } from '../services/api-access';
 import { listBackups } from '../services/backup-metadata';
 import { listBackupStorages } from '../services/backup-storage';
@@ -532,7 +534,9 @@ export async function getCompletions(words: string[], current: number): Promise<
 
   // Monitor targets - a module ID or one of celilo's own schedulable checks.
   // Sourced from SCHEDULABLE_BUILTIN_CHECKS rather than a hand-copied list, so
-  // a new built-in check is completable the moment it is schedulable.
+  // a new built-in check is completable the moment it is schedulable. The two
+  // local-state checks (health coverage, hook jail) are deliberately not in
+  // that list — it is the audit categories — so they ride alongside by name.
   if (
     command === 'monitor' &&
     (args[1] === 'add' ||
@@ -548,7 +552,10 @@ export async function getCompletions(words: string[], current: number): Promise<
       .from(modules)
       .all()
       .map((m) => m.id);
-    return filterSuggestions([...SCHEDULABLE_BUILTIN_CHECKS, ...moduleIds], args[2] || '');
+    return filterSuggestions(
+      [...SCHEDULABLE_BUILTIN_CHECKS, HEALTH_COVERAGE_CHECK, HOOK_JAIL_CHECK, ...moduleIds],
+      args[2] || '',
+    );
   }
 
   // Alerts subcommands

package/src/cli/index.ts

@@ -619,7 +619,7 @@ Subcommands:
   show-config <id>                     Show all config including auto-derived values
   show-zone <id>                       Show module's network zone and config
 
-  build <module-id>                    Execute build scripts (Nix + Ansible)
+  build <module-id>                    Execute module build scripts (Ansible)
 
   generate <id>                        Generate infrastructure code for module
     Options:

package/src/console/control-plane-boundary.test.ts

@@ -15,12 +15,12 @@
  * caddy-internal" for a further round after that. Prose did not hold this.
  */
 import { describe, expect, test } from 'bun:test';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
 import { parse } from 'yaml';
 
-const MANIFEST_PATH = new URL(
-  '../../../../modules/celilo-web-console/manifest.yml',
-  import.meta.url,
-).pathname;
+const MODULE_DIR = new URL('../../../../modules/celilo-web-console/', import.meta.url).pathname;
+const MANIFEST_PATH = join(MODULE_DIR, 'manifest.yml');
 
 /**
  * Capabilities that give something a way in from the data plane.
@@ -73,3 +73,81 @@ describe('celilo-web-console stays in the control plane', () => {
     expect(manifest.provides?.capabilities ?? []).toEqual([]);
   });
 });
+
+/**
+ * The build output the manifest's `build:` step writes, which is not source.
+ *
+ * Excluded from the walk below for two reasons, and the second is the one that
+ * matters. It holds two ~100MB compiled binaries, so reading it as text is
+ * absurd. And it holds a minified React bundle, which contains almost every
+ * short string you could think to search for — so scanning it reports ingress
+ * that nobody wrote. Both are gitignored, so on a fresh checkout the directory
+ * is absent entirely and the walk would silently be checking a different set of
+ * files than it checks on a machine that has run a build.
+ */
+const BUILD_OUTPUT_DIR = 'files';
+
+/**
+ * Every source file in the module's deployable body.
+ *
+ * A walk rather than a list, because the hole this guards is a file somebody
+ * ADDS. Listing today's files would pass over exactly the new Ansible task that
+ * opens the port.
+ */
+function deployableBody(): { path: string; text: string }[] {
+  const found: { path: string; text: string }[] = [];
+  const walk = (dir: string) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (entry.name !== BUILD_OUTPUT_DIR) walk(join(dir, entry.name));
+        continue;
+      }
+      const path = join(dir, entry.name);
+      found.push({ path, text: readFileSync(path, 'utf8') });
+    }
+  };
+  for (const sub of ['terraform', 'ansible']) walk(join(MODULE_DIR, sub));
+  return found;
+}
+
+/**
+ * How a deployable body would open a path in from the data plane.
+ *
+ * A reverse-proxy vhost, a DNAT or port-forward rule, a `natIp`, or a dedicated
+ * ingress address. None belongs on a `secure-mgmt` module, and every one is a
+ * plausible one-line addition by someone who wanted to reach the console
+ * without bringing up the VPN.
+ */
+const INGRESS_TOKENS = [
+  'caddy',
+  'reverse_proxy',
+  'natip',
+  'exposeservice',
+  'port_forward',
+  'portforward',
+  'dnat',
+];
+
+describe("the console's deployable body opens no path in", () => {
+  test('the walk reaches the terraform and ansible it is checking', () => {
+    // Without this the assertion below is a confident statement about an empty
+    // set as soon as either directory is renamed — and the same is true on a
+    // fresh checkout, where the excluded build output does not exist at all.
+    const paths = deployableBody().map((file) => file.path);
+    expect(paths.some((path) => path.endsWith('terraform/main.tf.tpl'))).toBe(true);
+    expect(paths.some((path) => path.includes('/ansible/roles/'))).toBe(true);
+    expect(paths.some((path) => path.endsWith('.service.j2'))).toBe(true);
+  });
+
+  test('reads no build output, so a local build cannot change the verdict', () => {
+    const paths = deployableBody().map((file) => file.path);
+    expect(paths.filter((path) => path.includes(`/${BUILD_OUTPUT_DIR}/`))).toEqual([]);
+  });
+
+  test('names no reverse proxy, port forward or ingress address', () => {
+    const offenders = deployableBody()
+      .filter((file) => INGRESS_TOKENS.some((token) => file.text.toLowerCase().includes(token)))
+      .map((file) => file.path.slice(MODULE_DIR.length));
+    expect(offenders).toEqual([]);
+  });
+});

package/src/db/schema.ts

@@ -447,7 +447,6 @@ export const moduleBuilds = sqliteTable('module_builds', {
   version: text('version').notNull(),
   builtAt: integer('built_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
   artifacts: text('artifacts', { mode: 'json' }).$type<string[]>().notNull(), // Array of artifact paths
-  environment: text('environment').$type<'nix' | 'system'>(),
   status: text('status').$type<BuildStatus>().notNull(),
   buildLog: text('build_log'), // Build output for debugging
 });

package/src/hooks/capability-loader.ts

@@ -45,7 +45,7 @@ import { getOrCreateMasterKey } from '../secrets/master-key';
 import { buildControlPlaneApi } from '../services/api-principal-enrolment';
 import { recordCapabilityBinding, withBindingRecord } from '../services/capability-bindings';
 import { emitWebRoutesChangedAndWait } from '../services/celilo-events';
-import { getModuleSystems } from '../services/deployed-systems';
+import { CONTROL_PLANE_MODULE_ID, getModuleSystems } from '../services/deployed-systems';
 import { withDnsInternalLedger } from '../services/dns-internal-records';
 import { withDnsRegistrationLedger } from '../services/dns-registrations';
 import { buildPortForwardStore } from '../services/port-forwards';
@@ -605,6 +605,20 @@ export async function loadCapabilityFunctions(
         caddyModuleId: provider.moduleId,
         dnsManagedDomains,
         dnsRegistrarModuleId,
+        // Design D10: the bytes move through the provider's Ansible converge,
+        // not a hand-built ssh tar pipe. Core implements it over
+        // executeAnsible against the provider's generated project (task 4.3);
+        // awaited with everything else, so a publish returns only once the
+        // host matches. A failure here fails the deploy loudly — a publish
+        // that reports ready while the host never received the bytes is the
+        // exact "served but silently unreachable" anti-pattern.
+        convergeStaticContent: async () => {
+          const { convergeStaticContent } = await import('../services/static-content-converge');
+          const result = await convergeStaticContent(db, provider.moduleId);
+          if (!result.success) {
+            throw new Error(result.error ?? 'static-content converge failed');
+          }
+        },
         // ISS-0035: register_route/unregister_routes emit this coarse signal
         // instead of SSHing caddy; the caddy provider's reconcile_routes
         // subscription re-renders the Caddyfile from web_routes. We await the
@@ -938,7 +952,6 @@ interface FirewallZones {
 }
 
 /** The module that IS celilo's control plane; its network is what we trust. */
-const CONTROL_PLANE_MODULE_ID = 'celilo-mgmt';
 
 function readZoneSubnet(db: DbClient, zone: string): string | undefined {
   const row = db

package/src/hooks/executor.ts

@@ -31,17 +31,19 @@
  * exists (a Mac today, task 4.8) the hook runs unjailed and the mode is
  * RECORDED, so a host that quietly stops jailing is visible rather than silent.
  *
- * Hooks still do NOT execute on the target machine. One that needs to touch a
- * target initiates SSH outbound itself, so anything it depends on (chromium,
- * system binaries, credentials) must be available on the celilo CLI host.
- * Stage 3 scopes that reachability and has not landed, which is why `~/.ssh`
- * is still bound into the jail read-only.
+ * Hooks still do NOT execute on the target machine — a remote operation is
+ * initiated from the celilo host. **Stage 3 has landed and scopes that
+ * reachability by the credential (design D12):** `~/.ssh` is not bound into
+ * the jail, so a hand-built `ssh` cannot authenticate, and the remote
+ * primitives cross to the remote-ops broker (`remote-broker.ts`), which holds
+ * the key and checks every target against the policy in
+ * `services/remote-access.ts` — the module's own systems, or the module's own
+ * credential.
  *
  * Execution function (Rule 10.1) - performs side effects (script execution)
  */
 
 import { existsSync, mkdirSync, readdirSync, rmdirSync, statSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import {
   type DeployedSystem,
@@ -59,8 +61,10 @@ import { isPrivilegedCapability } from '../manifest/validate';
 import { pruneModuleArtifacts } from './artifact-retention';
 import { startBroker } from './broker';
 import {
+  HOOK_MOUNT_SET_ENV,
   HOOK_PROTOCOL_VERSION,
   HOOK_PROTOCOL_VERSION_ENV,
+  HOOK_REMOTE_SOCKET_ENV,
   HOOK_SOCKET_ENV,
   createLineReader,
   deserializeError,
@@ -74,8 +78,15 @@ import {
   recordJailMode,
   runtimeModulePathsFor,
 } from './jail';
-import { type DeclaredPathInput, type MountSetRequest, deriveMountSet } from './mount-set';
+import {
+  type DeclaredPathInput,
+  type MountSet,
+  type MountSetRequest,
+  deriveMountSet,
+} from './mount-set';
+import { type RemoteAccessPolicy, startRemoteBroker } from './remote-broker';
 import type { HookContext, HookDefinition, HookLogger, HookResult } from './types';
+import { mountSetEnvValue } from './unjailed-lint';
 
 /** Default total timeout: 60 seconds */
 const DEFAULT_TIMEOUT_MS = 60_000;
@@ -160,6 +171,14 @@ const FORWARDED_ENV = [
 
 /** The shim celilo spawns. Resolved from here so an npm install finds it too. */
 const HOOK_RUNNER_PATH = join(import.meta.dir, 'hook-runner.ts');
+/**
+ * What celilo actually SPAWNS: the entry that installs the advisory lint
+ * before the runner shim's own import graph can load `node:fs` (task 4.7).
+ * The runner path above is still what the mount set binds — the entry and the
+ * shim live in the same directory and resolve through the same
+ * `node_modules`.
+ */
+const HOOK_RUNNER_SPAWN_PATH = join(import.meta.dir, 'hook-runner-entry.ts');
 
 /**
  * Validate hook inputs against a contract signature.
@@ -265,6 +284,13 @@ export interface ExecuteHookOptions {
   idleTimeoutMs?: number;
   /** What to jail this run with. Absent runs the hook unjailed. */
   jail?: HookJailInputs;
+  /**
+   * D12's target policy for this run's remote operations, built by the caller
+   * (`services/remote-access.ts`) so the executor stays decoupled from the
+   * database the same way it is for `systems`. Absent means every
+   * fleet-credential operation is REFUSED, naming the gap (Rule 6.4).
+   */
+  remoteAccess?: RemoteAccessPolicy;
 }
 
 /**
@@ -308,12 +334,27 @@ export async function executeHookScript(
     logger,
     onActivity: markActive,
   });
+  let remoteBroker: Awaited<ReturnType<typeof startRemoteBroker>> | undefined;
 
   try {
+    // The remote-ops socket lives beside the capability socket, so the jail's
+    // one socket-directory mount covers both channels (design D12).
+    const roots = remoteRoots(context, options.jail);
+    remoteBroker = await startRemoteBroker({
+      socketDir: dirname(broker.socketPath),
+      policy: options.remoteAccess,
+      readableRoots: roots.readable,
+      writableRoots: roots.writable,
+      logger,
+      onActivity: markActive,
+    });
+
+    const mountSet = options.jail
+      ? deriveMountSet(realpathRequest(jailRequest(options.jail, context, broker.socketPath)))
+      : undefined;
     const jail = planJailedSpawn(
-      [process.execPath, HOOK_RUNNER_PATH],
-      options.jail &&
-        deriveMountSet(realpathRequest(jailRequest(options.jail, context, broker.socketPath))),
+      [process.execPath, HOOK_RUNNER_SPAWN_PATH],
+      mountSet,
       detectJailBackend(),
       jailPolicy(),
     );
@@ -326,7 +367,19 @@ export async function executeHookScript(
 
     const child = Bun.spawn({
       cmd: [...jail.cmd],
-      env: hookChildEnv(broker.socketPath),
+      // `sandbox-exec` has no `--chdir`, so the plan names one and the spawn
+      // sets it. Without it the child inherits the operator's shell directory,
+      // which the profile does not name — and `bun` reads its cwd before it
+      // runs anything, so the hook dies with a message about nothing in
+      // particular. bubblewrap plans leave this absent and use `--chdir`.
+      ...(jail.cwd ? { cwd: jail.cwd } : {}),
+      env: hookChildEnv(
+        broker.socketPath,
+        remoteBroker.socketPath,
+        // The lint rides only on an unjailed run — its presence in the child's
+        // environment is the shim's signal to install it (task 4.7).
+        jail.mode === 'unjailed' ? mountSet : undefined,
+      ),
       stdout: 'pipe',
       stderr: 'pipe',
     });
@@ -346,8 +399,10 @@ export async function executeHookScript(
       killedFor = reason;
       // Refuse capability calls FIRST. A hook between `kill` and its own death
       // can still have a call in flight, and answering it is exactly the
-      // failure this replaces.
+      // failure this replaces. The remote channel refuses for the same reason:
+      // a killed hook must not go on reaching systems (celilo#1003, D12).
       broker.stop();
+      remoteBroker?.stop();
       child.kill('SIGTERM');
       setTimeout(() => child.kill('SIGKILL'), SIGKILL_GRACE_MS).unref();
     };
@@ -398,10 +453,41 @@ export async function executeHookScript(
     if (!outcome.ok) throw deserializeError(outcome.error);
     return outcome.outputs;
   } finally {
+    // Remote first: its socket file lives inside the directory the capability
+    // broker's close removes.
+    remoteBroker?.close();
     broker.close();
   }
 }
 
+/**
+ * The local directories this run's stream primitives may touch (design D12).
+ *
+ * Derived from the same inputs as the jail's mount set, which is what keeps
+ * the two views from drifting: everything writable here is writable there,
+ * and a path outside these roots is a path the jailed hook could not see
+ * anyway — the broker writing to it would produce a file the hook cannot
+ * read, reported as success.
+ *
+ * Planning function (Rule 10.4) — pure.
+ */
+function remoteRoots(
+  context: HookContext,
+  jail: HookJailInputs | undefined,
+): { readable: string[]; writable: string[] } {
+  const writable: string[] = [context.stateDir, context.screenshotDir];
+  const readable: string[] = [];
+  if (jail) {
+    readable.push(jail.modulePath);
+    writable.push(join(jail.modulePath, 'generated'));
+    for (const input of jail.pathInputs) {
+      (input.access === 'write' ? writable : readable).push(input.value);
+    }
+  }
+  // Whatever a hook may write, it may also read back.
+  return { readable: [...readable, ...writable], writable };
+}
+
 /**
  * The child's environment, built from an allow-list (design D5).
  *
@@ -422,7 +508,11 @@ export async function executeHookScript(
  *
  * Planning function (Rule 10.4) — pure.
  */
-export function hookChildEnv(socketPath: string): Record<string, string> {
+export function hookChildEnv(
+  socketPath: string,
+  remoteSocketPath: string,
+  mountSet: MountSet | undefined,
+): Record<string, string> {
   const env: Record<string, string> = {};
 
   for (const name of FORWARDED_ENV) {
@@ -431,6 +521,10 @@ export function hookChildEnv(socketPath: string): Record<string, string> {
   }
 
   env[HOOK_SOCKET_ENV] = socketPath;
+  env[HOOK_REMOTE_SOCKET_ENV] = remoteSocketPath;
+  // The unjailed advisory lint's input (task 4.7). Absent when jailed — the
+  // shim installs the lint when and only when this variable is set.
+  if (mountSet) env[HOOK_MOUNT_SET_ENV] = mountSetEnvValue(mountSet);
   env[HOOK_PROTOCOL_VERSION_ENV] = String(HOOK_PROTOCOL_VERSION);
   // Forwarded when the operator set it, not synthesised from `debug` — a hook
   // reads the flag off `ctx.debug`, which crosses in the context frame.
@@ -465,10 +559,6 @@ function jailRequest(
     runnerPath: HOOK_RUNNER_PATH,
     runtimeModulePaths: runtimeModulePathsFor(HOOK_RUNNER_PATH),
     pathInputs: inputs.pathInputs,
-    // Stage 2 only. `remote.ts` still runs inside the hook and needs the key;
-    // stage 3 brokers those calls and drops this row (D9, D12). Dropping it
-    // early hardens nothing — it stops every hook reaching its own systems.
-    sshDir: join(homedir(), '.ssh'),
   };
 }
 
@@ -544,6 +634,14 @@ export interface InvokeHookOptions {
    * manifest hook's own `timeout`, being the more specific declaration.
    */
   timeoutMs?: number;
+  /**
+   * D12's target policy for the hook's remote operations, built by the caller
+   * via `remoteAccessPolicy(moduleId, db)` — the same caller-loads-it pattern
+   * as `systems`, and for the same reason: the executor stays decoupled from
+   * the database. Absent means every fleet-credential remote operation is
+   * refused (Rule 6.4).
+   */
+  remoteAccess?: RemoteAccessPolicy;
 }
 
 /**
@@ -846,6 +944,7 @@ export async function invokeHook(
       timeoutMs,
       idleTimeoutMs,
       jail: { modulePath, pathInputs: declaredPathInputs(signature, inputs) },
+      remoteAccess: options.remoteAccess,
     });
 
     // Validate outputs against the contract signature