@shomra/agent 0.3.24 → 0.3.25

package/README.md

@@ -513,6 +513,7 @@ suppressed file drops to ALLOW and never fails the build:
 | `SHOMRA_AGENT` | Agent-identity handle presented to `llm-proxy` + firewall |
 | `SHOMRA_GATE_CONCURRENCY` | Parallel backend calls in batch gate / model lookups (default 8, 1-32) |
 | `SHOMRA_GH_TOKEN` | GitHub token for `shomra pr` (falls back to `GITHUB_TOKEN`) |
+| `SHOMRA_ENVIRONMENT` | Declare where this runs: `LOCAL` \| `CI` \| `REMOTE`. Set `REMOTE` on a cloud agent runtime whose markers Shomra does not yet detect (Codex cloud, Jules, Cursor background agents, Devin…), so its sessions are not counted as developer machines. ⚠ It may only ever RAISE — it can never relabel a detected cloud container as a laptop. |
 | `SHOMRA_GUARD_STRICT` | `1` = firewall fails closed on the server tier |
 | `SHOMRA_GUARD_LOCAL` | `0` = disable the on-machine Tier-0 guard |
 | `SHOMRA_GUARD_IGNORE` | Comma-separated file globs the runtime guard treats as known-safe (adds to `.shomraignore`) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shomra/agent",
-  "version": "0.3.24",
+  "version": "0.3.25",
   "description": "Shomra - adversarial assurance for AI agents, as a local-first CLI. Blocks dangerous tool-calls before they run, attacks your own guardrails to prove they hold, and gates AI artifacts in your editor and CI.",
   "type": "module",
   "bin": {

package/src/agents/hook-command.mjs

@@ -1,4 +1,5 @@
 import { CLI_ENTRY_PATH } from '../core/package-root.mjs';
+import { VERSION } from '../core/version.mjs';
 
 export const LLM_PROXY_BASE = process.env.SHOMRA_LLM_PROXY_BASE || 'http://127.0.0.1:4141/openai/v1';
 
@@ -8,12 +9,27 @@ function quoteArg(argument) {
   return /\s/.test(argument) ? `"${argument}"` : argument;
 }
 
-export function hookCommand(args) {
+export const PACKAGE_SPEC = `@shomra/agent@${VERSION}`;
+
+/**
+ * ⚠⚠ AN ABSOLUTE PATH DOES NOT SURVIVE THE FILE IT IS WRITTEN INTO. A project
+ * install lands in `.claude/settings.json`, which is COMMITTED - so the hook is
+ * read on a colleague's laptop and inside the ephemeral cloud container Claude
+ * Code on the web clones the repo into. Neither has this checkout, so the hook
+ * points at nothing, the agent logs a spawn error, and NOTHING IS SCREENED while
+ * the settings file says it is. Portable mode resolves through npm instead.
+ *
+ * ⚠ THE VERSION IS PINNED, never `@latest`. A committed hook is code that runs
+ * on other people's machines; one that silently changes when we publish is not a
+ * control anybody reviewed.
+ */
+export function hookCommand(args, opts = {}) {
+  if (opts.portable) return `npx -y ${PACKAGE_SPEC} ${args}`;
   return `${quoteArg(process.execPath)} ${quoteArg(SELF_PATH)} ${args}`;
 }
 
 export function shomraHookRe(verb) {
-  return new RegExp(`shomra(\\.mjs"?)?\\s+${verb}`, 'i');
+  return new RegExp(`(?:shomra(?:\\.mjs"?)?|@shomra/agent(?:@[\\w.\\-]+)?)\\s+${verb}`, 'i');
 }
 
-export const SHOMRA_ANY_HOOK_RE = /shomra(\.mjs"?)?\s+(tool-guard|result-guard|prompt-guard|plan-guard)/i;
+export const SHOMRA_ANY_HOOK_RE = /(?:shomra(?:\.mjs"?)?|@shomra\/agent(?:@[\w.\-]+)?)\s+(tool-guard|result-guard|prompt-guard|plan-guard|session-guard)/i;

package/src/agents/installers.mjs

@@ -20,6 +20,7 @@ export const AGENT_KEYS = Object.keys(AGENT_LABELS);
 
 export const AGENT_INSTALLERS = {
   claude(global) {
+    const portable = !global;
     const dir = global ? path.join(os.homedir(), '.claude') : path.join(process.cwd(), '.claude');
     const file = path.join(dir, 'settings.json');
     const settings = readJsonFile(file);
@@ -28,22 +29,28 @@ export const AGENT_INSTALLERS = {
     const post = (settings.hooks.PostToolUse = settings.hooks.PostToolUse || []);
     let changed = false;
     if (!hasGroupedHook(pre, 'tool-guard')) {
-      pre.push({ matcher: 'Bash|Write|Edit|MultiEdit|NotebookEdit|mcp__.*', hooks: [{ type: 'command', command: hookCommand('tool-guard --agent claude') }] });
+      pre.push({ matcher: 'Bash|Write|Edit|MultiEdit|NotebookEdit|mcp__.*', hooks: [{ type: 'command', command: hookCommand('tool-guard --agent claude', { portable }) }] });
       changed = true;
     }
     if (!hasGroupedHook(post, 'result-guard')) {
-      post.push({ matcher: 'WebFetch|WebSearch|Read|NotebookRead|mcp__.*', hooks: [{ type: 'command', command: hookCommand('result-guard --agent claude') }] });
+      post.push({ matcher: 'WebFetch|WebSearch|Read|NotebookRead|mcp__.*', hooks: [{ type: 'command', command: hookCommand('result-guard --agent claude', { portable }) }] });
       changed = true;
     }
 
     const prompt = (settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit || []);
     if (!hasGroupedHook(prompt, 'prompt-guard')) {
-      prompt.push({ hooks: [{ type: 'command', command: hookCommand('prompt-guard --agent claude') }] });
+      prompt.push({ hooks: [{ type: 'command', command: hookCommand('prompt-guard --agent claude', { portable }) }] });
       changed = true;
     }
 
     if (!hasGroupedHook(pre, 'plan-guard')) {
-      pre.push({ matcher: 'ExitPlanMode', hooks: [{ type: 'command', command: hookCommand('plan-guard --agent claude') }] });
+      pre.push({ matcher: 'ExitPlanMode', hooks: [{ type: 'command', command: hookCommand('plan-guard --agent claude', { portable }) }] });
+      changed = true;
+    }
+
+    const start = (settings.hooks.SessionStart = settings.hooks.SessionStart || []);
+    if (!hasGroupedHook(start, 'session-guard')) {
+      start.push({ hooks: [{ type: 'command', command: hookCommand('session-guard --agent claude', { portable }) }] });
       changed = true;
     }
     if (changed) {
@@ -54,6 +61,7 @@ export const AGENT_INSTALLERS = {
   },
 
   codex(global) {
+    const portable = !global;
     const dir = global ? path.join(os.homedir(), '.codex') : path.join(process.cwd(), '.codex');
     const file = path.join(dir, 'hooks.json');
     const settings = readJsonFile(file);
@@ -61,11 +69,11 @@ export const AGENT_INSTALLERS = {
     const post = (settings.PostToolUse = settings.PostToolUse || []);
     let changed = false;
     if (!hasGroupedHook(pre, 'tool-guard')) {
-      pre.push({ matcher: 'Bash|Write|Edit|mcp__.*', hooks: [{ type: 'command', command: hookCommand('tool-guard --agent codex') }] });
+      pre.push({ matcher: 'Bash|Write|Edit|mcp__.*', hooks: [{ type: 'command', command: hookCommand('tool-guard --agent codex', { portable }) }] });
       changed = true;
     }
     if (!hasGroupedHook(post, 'result-guard')) {
-      post.push({ matcher: 'WebFetch|WebSearch|Read|mcp__.*', hooks: [{ type: 'command', command: hookCommand('result-guard --agent codex') }] });
+      post.push({ matcher: 'WebFetch|WebSearch|Read|mcp__.*', hooks: [{ type: 'command', command: hookCommand('result-guard --agent codex', { portable }) }] });
       changed = true;
     }
     if (changed) {
@@ -76,6 +84,7 @@ export const AGENT_INSTALLERS = {
   },
 
   gemini(global) {
+    const portable = !global;
     const dir = global ? path.join(os.homedir(), '.gemini') : path.join(process.cwd(), '.gemini');
     const file = path.join(dir, 'settings.json');
     const settings = readJsonFile(file);
@@ -84,11 +93,11 @@ export const AGENT_INSTALLERS = {
     const after = (settings.hooks.AfterTool = settings.hooks.AfterTool || []);
     let changed = false;
     if (!hasGroupedHook(before, 'tool-guard')) {
-      before.push({ matcher: '.*', hooks: [{ type: 'command', command: hookCommand('tool-guard --agent gemini') }] });
+      before.push({ matcher: '.*', hooks: [{ type: 'command', command: hookCommand('tool-guard --agent gemini', { portable }) }] });
       changed = true;
     }
     if (!hasGroupedHook(after, 'result-guard')) {
-      after.push({ matcher: '.*', hooks: [{ type: 'command', command: hookCommand('result-guard --agent gemini') }] });
+      after.push({ matcher: '.*', hooks: [{ type: 'command', command: hookCommand('result-guard --agent gemini', { portable }) }] });
       changed = true;
     }
     if (changed) {
@@ -99,6 +108,7 @@ export const AGENT_INSTALLERS = {
   },
 
   cursor(global) {
+    const portable = !global;
     const dir = global ? path.join(os.homedir(), '.cursor') : path.join(process.cwd(), '.cursor');
     const file = path.join(dir, 'hooks.json');
     const cfg = readJsonFile(file);
@@ -112,12 +122,12 @@ export const AGENT_INSTALLERS = {
         changed = true;
       }
     };
-    wire('beforeShellExecution', hookCommand('tool-guard --agent cursor'));
-    wire('beforeMCPExecution', hookCommand('tool-guard --agent cursor'));
-    wire('afterFileEdit', hookCommand('result-guard --agent cursor'));
-    wire('afterMCPExecution', hookCommand('result-guard --agent cursor'));
+    wire('beforeShellExecution', hookCommand('tool-guard --agent cursor', { portable }));
+    wire('beforeMCPExecution', hookCommand('tool-guard --agent cursor', { portable }));
+    wire('afterFileEdit', hookCommand('result-guard --agent cursor', { portable }));
+    wire('afterMCPExecution', hookCommand('result-guard --agent cursor', { portable }));
 
-    wire('beforeSubmitPrompt', hookCommand('prompt-guard --agent cursor'));
+    wire('beforeSubmitPrompt', hookCommand('prompt-guard --agent cursor', { portable }));
     if (changed) {
       fs.mkdirSync(dir, { recursive: true });
       fs.writeFileSync(file, JSON.stringify(cfg, null, 2));
@@ -126,6 +136,7 @@ export const AGENT_INSTALLERS = {
   },
 
   windsurf(global) {
+    const portable = !global;
     const dir = global ? path.join(os.homedir(), '.codeium', 'windsurf') : path.join(process.cwd(), '.windsurf');
     const file = path.join(dir, 'hooks.json');
     const cfg = readJsonFile(file);
@@ -138,10 +149,10 @@ export const AGENT_INSTALLERS = {
         changed = true;
       }
     };
-    wire('pre_run_command', hookCommand('tool-guard --agent windsurf'));
-    wire('pre_write_code', hookCommand('tool-guard --agent windsurf'));
-    wire('pre_mcp_tool_use', hookCommand('tool-guard --agent windsurf'));
-    wire('post_mcp_tool_use', hookCommand('result-guard --agent windsurf'));
+    wire('pre_run_command', hookCommand('tool-guard --agent windsurf', { portable }));
+    wire('pre_write_code', hookCommand('tool-guard --agent windsurf', { portable }));
+    wire('pre_mcp_tool_use', hookCommand('tool-guard --agent windsurf', { portable }));
+    wire('post_mcp_tool_use', hookCommand('result-guard --agent windsurf', { portable }));
     if (changed) {
       fs.mkdirSync(dir, { recursive: true });
       fs.writeFileSync(file, JSON.stringify(cfg, null, 2));
@@ -150,12 +161,13 @@ export const AGENT_INSTALLERS = {
   },
 
   copilot(global) {
+    const portable = !global;
     const dir = global ? path.join(os.homedir(), '.copilot', 'hooks') : path.join(process.cwd(), '.github', 'hooks');
     const file = path.join(dir, 'shomra.json');
     if (fs.existsSync(file)) return { file, changed: false };
     const cfg = {
-      preToolUse: [{ command: hookCommand('tool-guard --agent copilot') }],
-      postToolUse: [{ command: hookCommand('result-guard --agent copilot') }],
+      preToolUse: [{ command: hookCommand('tool-guard --agent copilot', { portable }) }],
+      postToolUse: [{ command: hookCommand('result-guard --agent copilot', { portable }) }],
     };
     fs.mkdirSync(dir, { recursive: true });
     fs.writeFileSync(file, JSON.stringify(cfg, null, 2));
@@ -163,6 +175,7 @@ export const AGENT_INSTALLERS = {
   },
 
   cline(global) {
+    const portable = !global;
     const dir = global ? path.join(os.homedir(), '.cline') : path.join(process.cwd(), '.cline');
     const file = path.join(dir, 'hooks.json');
     const settings = readJsonFile(file);
@@ -171,11 +184,11 @@ export const AGENT_INSTALLERS = {
     const post = (settings.hooks.PostToolUse = settings.hooks.PostToolUse || []);
     let changed = false;
     if (!hasGroupedHook(pre, 'tool-guard')) {
-      pre.push({ matcher: 'execute_command|write_to_file|replace_in_file|new_rule|use_mcp_tool', hooks: [{ type: 'command', command: hookCommand('tool-guard --agent cline') }] });
+      pre.push({ matcher: 'execute_command|write_to_file|replace_in_file|new_rule|use_mcp_tool', hooks: [{ type: 'command', command: hookCommand('tool-guard --agent cline', { portable }) }] });
       changed = true;
     }
     if (!hasGroupedHook(post, 'result-guard')) {
-      post.push({ matcher: 'read_file|web_fetch|use_mcp_tool', hooks: [{ type: 'command', command: hookCommand('result-guard --agent cline') }] });
+      post.push({ matcher: 'read_file|web_fetch|use_mcp_tool', hooks: [{ type: 'command', command: hookCommand('result-guard --agent cline', { portable }) }] });
       changed = true;
     }
     if (changed) {
@@ -186,6 +199,7 @@ export const AGENT_INSTALLERS = {
   },
 
   aider(global) {
+    const portable = !global;
     const file = global ? path.join(os.homedir(), '.aider.conf.yml') : path.join(process.cwd(), '.aider.conf.yml');
     let text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
     if (/#\s*shomra llm guard/i.test(text) || text.includes(LLM_PROXY_BASE)) {

package/src/cli/help-sections.mjs

@@ -33,7 +33,7 @@ const COMMANDS = () => `${bold('COMMANDS')}
 
   ${dim('Setup - run once per machine / repo')}
   ${cyan('init')}          Configure + enroll this machine       ${dim('--key shm_live_… [--url <backend>]')}
-  ${cyan('protect')}       Wire the runtime firewall for every coding agent ${dim('[--local] [--force]')}
+  ${cyan('protect')}       Wire the runtime firewall for every coding agent ${dim('[--project] [--force]')}
   ${cyan('install-hook')}  Wire the runtime firewall into ONE agent ${dim('[--agent claude|cursor|windsurf|gemini|codex|copilot|cline|aider|all] [--global]')}
   ${cyan('provenance')}    Which changed files an AI agent wrote   ${dim('[--staged | --base main] [--trailer] [--fail-on-blocked] [--json]')}
   ${cyan('install-precommit')} Gate staged AI artifacts on git commit ${dim('[dir] [--force]  ·  --pre-receive for the un-skippable server-side hook')}
@@ -76,7 +76,7 @@ const COMMANDS = () => `${bold('COMMANDS')}
   ${cyan('admin')}         Deep scans, red-team, hardening, agent identity, LLM proxy
                 ${dim('scan-zip · model-scan · memory-scan · redteam · campaign · harden · agent-identity · llm-proxy')}
 
-  ${dim('(internal hook handlers, invoked by install-hook - not run by hand: tool-guard, result-guard, prompt-guard, plan-guard)')}
+  ${dim('(internal hook handlers, invoked by install-hook - not run by hand: tool-guard, result-guard, prompt-guard, plan-guard, session-guard)')}
 `;
 
 const GATE = () => `${bold('GATE')}

package/src/cli/main.mjs

@@ -21,7 +21,7 @@ export async function main() {
     return;
   }
 
-  const guardCmd = command === 'tool-guard' || command === 'result-guard' || command === 'prompt-guard' || command === 'plan-guard';
+  const guardCmd = command === 'tool-guard' || command === 'result-guard' || command === 'prompt-guard' || command === 'plan-guard' || command === 'session-guard';
   if (unknown.length && !guardCmd) {
     for (const u of unknown) {
       const near = didYouMean(u, [...KNOWN_FLAGS]);

package/src/cli/registry.mjs

@@ -29,6 +29,7 @@ import { cmdSecrets } from '../commands/secrets.mjs';
 import { cmdStatus } from '../commands/status.mjs';
 import { cmdWhy } from '../commands/why.mjs';
 import { cmdPromptGuard } from '../guard/prompt-guard.mjs';
+import { cmdSessionGuard } from '../guard/session-guard.mjs';
 import { cmdResultGuard } from '../guard/result-guard.mjs';
 import { cmdToolGuard } from '../guard/tool-guard.mjs';
 
@@ -60,6 +61,7 @@ export const COMMANDS = {
   'result-guard': (f) => cmdResultGuard(f),
   'prompt-guard': (f) => cmdPromptGuard(f),
   'plan-guard': (f) => cmdPlanGuard(f),
+  'session-guard': (f) => cmdSessionGuard(f),
   plan: (f, p) => cmdPlan(f, p),
   corpus: (f, p) => cmdCorpus(f, p),
   rules: (f, p) => cmdRules(f, p),

package/src/commands/protect.mjs

@@ -16,7 +16,7 @@ export function cmdProtect(flags) {
     return;
   }
 
-  const global = !flags.local;
+  const global = !(flags.local || flags.project);
   console.log(bold(cyan('\n  Shomra protect')) + dim(` - wiring the runtime firewall for ${detected.length} coding agent${detected.length > 1 ? 's' : ''} (${global ? 'machine-wide' : 'this repo'})`));
   let wired = 0, already = 0;
   for (const a of detected) {
@@ -32,6 +32,16 @@ export function cmdProtect(flags) {
   }
   console.log(`\n  ${wired ? green(`✓ ${wired} newly protected`) : green('✓ Already protected')}${already ? dim(` · ${already} already wired`) : ''}${dim(' - tool calls, results and prompts now screened on-machine.')}`);
 
+  if (global) {
+    console.log(dim('\n  ⚠ Machine-wide only. A CLOUD session (Claude Code on the web) runs in a fresh'));
+    console.log(dim('    container with none of this, and so does a colleague\'s checkout. Run ') + bold('shomra protect --project'));
+    console.log(dim('    and COMMIT ') + bold('.claude/settings.json') + dim(' to cover both - the hooks resolve through npm there.'));
+  } else {
+    console.log(dim('\n  ✓ Written into this repo. ') + bold('Commit .claude/settings.json') + dim(' - it is what carries the firewall'));
+    console.log(dim('    into cloud sessions and onto every checkout. These hooks resolve through npm, so'));
+    console.log(dim('    they work on a machine that has never installed Shomra.'));
+  }
+
   console.log(dim('\n  Get in front of the model too - both write into this repo, so run them where you mean to:'));
   console.log(`    ${bold('shomra rules --write')}   ${dim('teach the agent what gets blocked, so it never writes it')}`);
   console.log(`    ${bold('shomra mcp install')}     ${dim('let the agent gate its own proposed content before writing')}\n`);

package/src/gate/environment.mjs

@@ -4,8 +4,79 @@ import path from 'node:path';
 
 export const GATE_KINDS = ['mcp', 'skill', 'command', 'subagent', 'hook', 'rules', 'agent-card', 'memory', 'auto'];
 
-export function detectEnv() {
-  const e = process.env;
+/**
+ * ⚠ A CLOUD AGENT SESSION IS NOT A DEVELOPER MACHINE, and until this existed it
+ * reported as one. Claude Code on the web runs in an EPHEMERAL container: fresh
+ * $HOME, no `shomra` config, a hostname nobody will ever see again. It carries
+ * no CI variables, so it fell through to LOCAL - and an operator counting
+ * "screened laptops" was counting containers that no longer exist.
+ *
+ * ⚠ CI IS CHECKED FIRST and stays first. A cloud session driven by a GitHub
+ * Action is CI: that branch carries repo, ref and commit, which is the stronger
+ * attribution. REMOTE is what is left when nothing else names where this ran.
+ */
+/**
+ * ⚠ ONE ENTRY PER RUNTIME, and only where the variable has been SEEN. A marker
+ * invented from a vendor's docs either never fires - useless - or fires on a
+ * name something else uses, which labels a real laptop as an ephemeral
+ * container and puts a `floor` on a machine the org actually owns. Add a row
+ * here once somebody has read the variable out of a live session of that
+ * runtime; until then that runtime uses SHOMRA_ENVIRONMENT below, which is the
+ * whole reason the override exists.
+ *
+ * `verified` records who has actually seen it, so the next person can tell a
+ * confirmed marker from an optimistic one.
+ */
+export const REMOTE_RUNTIMES = [
+  {
+    runner: 'claude-code-cloud',
+    label: 'Claude Code on the web',
+    verified: true,
+    vars: ['CLAUDE_CODE_CONTAINER_ID', 'CLAUDE_CODE_ENVIRONMENT_RUNNER_VERSION'],
+    prefixed: { CLAUDE_CODE_ENTRYPOINT: /^remote/i },
+  },
+];
+
+/**
+ * ⚠ CODESPACES AND DEVCONTAINERS ARE DELIBERATELY ABSENT. They are containers,
+ * but they PERSIST between sessions, can be enrolled, and their guard survives
+ * to report a window it spent blind - which is the whole distinction REMOTE
+ * draws. Filing them here would put "we cannot vouch for its silence" on
+ * machines that can in fact vouch for it.
+ */
+export function remoteRunner(e = process.env) {
+  for (const rt of REMOTE_RUNTIMES) {
+    for (const key of rt.vars) if (String(e?.[key] ?? '').trim()) return rt.runner;
+    for (const [key, re] of Object.entries(rt.prefixed ?? {})) {
+      if (re.test(String(e?.[key] ?? '').trim())) return rt.runner;
+    }
+  }
+  return null;
+}
+
+const ENV_RANK = { LOCAL: 0, CI: 1, REMOTE: 2 };
+
+export function declaredEnvironment(e = process.env) {
+  const v = String(e?.SHOMRA_ENVIRONMENT ?? '').trim().toUpperCase();
+  return v in ENV_RANK ? v : null;
+}
+
+/**
+ * ⚠⚠ THE OVERRIDE MAY ONLY EVER RAISE. `SHOMRA_ENVIRONMENT` exists so an
+ * operator can declare a runtime we do not yet detect - a cloud agent from a
+ * vendor whose markers nobody has read. Letting it go the other way would make
+ * it a switch that relabels a detected ephemeral container as a trusted laptop,
+ * clearing the `floor` its unreportable silence earns. That is the same
+ * privilege-reduction shape `mayRaiseOnly` and `foldTimeout` refuse on the
+ * server, and it would be reachable by anything that can set an env var.
+ */
+export function mergeEnvironment(detected, declared) {
+  if (!declared) return detected;
+  return ENV_RANK[declared] > ENV_RANK[detected] ? declared : detected;
+}
+
+export function detectEnv(env) {
+  const e = env ?? process.env;
   const pick = (...keys) => {
     for (const k of keys) if (e[k]?.trim()) return e[k].trim();
     return undefined;
@@ -54,6 +125,10 @@ export function detectEnv() {
   if (ci) {
 
     const git = gitContext();
+    const declared = declaredEnvironment(e);
+    if (mergeEnvironment('CI', declared) === 'REMOTE') {
+      return { environment: 'REMOTE', runner: remoteRunner(e) ?? 'declared', ...git };
+    }
     return {
       environment: 'CI',
       ciProvider: ci.ciProvider,
@@ -64,7 +139,11 @@ export function detectEnv() {
     };
   }
 
-  return { environment: 'LOCAL', ...gitContext() };
+  const runner = remoteRunner(e);
+  const environment = mergeEnvironment(runner ? 'REMOTE' : 'LOCAL', declaredEnvironment(e));
+  if (environment === 'REMOTE') return { environment, runner: runner ?? 'declared', ...gitContext() };
+
+  return { environment, ...gitContext() };
 }
 
 function gitContext() {

package/src/guard/session-guard.mjs

@@ -0,0 +1,66 @@
+import { loadConfig, resolveSettings } from '../core/config.mjs';
+import { detectEnv, remoteRunner } from '../gate/environment.mjs';
+import { envFlag, resolveAgentFlag } from './options.mjs';
+
+const PROBE_TIMEOUT_MS = 1500;
+
+export function sessionPosture(env, settings, reachable) {
+  const remote = env.environment === 'REMOTE';
+  if (!settings.apiKey) {
+    return {
+      enforcing: 'local-only',
+      remote,
+      message: remote
+        ? 'This is an EPHEMERAL CLOUD SESSION and no Shomra key reached it. Nothing you installed on your laptop is here. Only the offline Tier-0 screen is running; no policy, no server-side flow taint, and nothing about this session will appear in Shomra.'
+        : 'Shomra is not configured on this machine. Only the offline Tier-0 screen is running.',
+    };
+  }
+  if (reachable === false) {
+    return {
+      enforcing: 'degraded',
+      remote,
+      message: remote
+        ? 'This CLOUD SESSION cannot reach the Shomra backend - its network policy is blocking egress. Tool calls run screened by the offline tier only, and ⚠ THIS CONTAINER IS EPHEMERAL: the gap ledger dies with it, so these calls may never be reported as unscreened.'
+        : 'The Shomra backend is unreachable. The offline tier still screens; server-side policy does not.',
+    };
+  }
+  return { enforcing: 'full', remote, message: null };
+}
+
+async function reachable(url) {
+  if (!url) return false;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), PROBE_TIMEOUT_MS);
+  try {
+    await fetch(`${url.replace(/\/+$/, '')}/healthz`, { signal: ctrl.signal, headers: { Connection: 'close' } });
+    return true;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * ⚠ THE ONE THING A CLOUD SESSION CAN TELL YOU IS THAT IT STARTED. Everything
+ * downstream - the tool guard, the gap ledger, the enforcement record - needs
+ * egress the container may not have, and the container is reclaimed either way.
+ * So this runs first, says out loud what is and is not enforcing, and never
+ * blocks: a session that refuses to start is a control nobody keeps installed.
+ */
+export async function cmdSessionGuard(flags) {
+  resolveAgentFlag(flags);
+  if (envFlag('SHOMRA_SESSION_GUARD_OFF')) return process.exit(0);
+
+  try {
+    const env = detectEnv();
+    const settings = resolveSettings(loadConfig());
+    const posture = sessionPosture(env, settings, settings.apiKey ? await reachable(settings.url) : null);
+    if (posture.message) process.stderr.write(`[shomra] ${posture.message}\n`);
+  } catch {
+
+  }
+  process.exit(0);
+}
+
+export { remoteRunner };