network-ai 5.7.2 → 5.8.1

package/INTEGRATION_GUIDE.md

@@ -564,4 +564,4 @@ Run these before declaring the integration production-ready:
 
 ---
 
-*Network-AI v5.7.2 · MIT License · https://github.com/Jovancoding/Network-AI*
+*Network-AI v5.8.1 · MIT License · https://github.com/Jovancoding/Network-AI*

package/QUICKSTART.md

@@ -387,16 +387,86 @@ network-ai audit tail
 network-ai audit clear
 ```
 
+### Diagnostics (`doctor`)
+
+```bash
+# Validate the full environment — data dir, env routing, audit log, WAL, kill-switch, MCP secret
+network-ai doctor
+network-ai doctor --json   # machine-readable
+
+# ✓ [PASS] data-dir: /path/to/data
+# ✓ [PASS] env-routing: no --env or NETWORK_AI_ENV set; using root data dir
+# ✓ [PASS] audit-log: 42 entries, all valid JSONL
+# ✓ [PASS] pending-changes: no pending changes
+# ✓ [PASS] kill-switch: system is running
+# ⚠ [WARN] mcp-secret: NETWORK_AI_MCP_SECRET not set
+# ✓ [PASS] blackboard-schema: blackboard.json OK (7 keys)
+```
+
+Exits with code `0` if all checks pass, `1` if any fail — safe for CI gates.
+
+### Inspect a key (`inspect`)
+
+```bash
+# Show current value and metadata
+network-ai inspect agent:status
+
+# Include pending WAL history
+network-ai inspect agent:status --history
+
+# Include audit trail entries for this key
+network-ai inspect agent:status --audit
+
+# All together, machine-readable
+network-ai inspect agent:status --history --audit --json
+```
+
+### Kill switch (`pause` / `resume`)
+
+```bash
+# Pause all orchestrator activity
+network-ai pause
+# ✓ system paused at 2026-05-23T15:00:00.000Z
+
+# Resume
+network-ai resume
+# ✓ system resumed
+
+# Check state
+network-ai doctor   # ⚠ [WARN] kill-switch: system is PAUSED
+```
+
+Creates/removes a `data/SYSTEM_PAUSED` sentinel file. Agents should check for this file before performing writes.
+
+### `--why` on `auth token`
+
+```bash
+# See the full scoring breakdown before the token is issued
+network-ai auth token my-bot --resource DATABASE \
+  --justification "Fetch Q4 invoices for year-end report" --why
+
+# justification score (40%): 80.0%
+# trust score        (30%): 100.0%
+# risk score         (30%): 50.0% risk → 50.0% contribution
+# weighted score:           74.0%
+# verdict:                  APPROVED
+```
+
 ### Global flags
 
 | Flag | Default | Purpose |
 |---|---|---|
 | `--data <path>` | `./data` | Override the data directory |
+| `--env <name>` | — | Target environment (dev/st/sit/qa/preprod/prod) |
 | `--json` | off | Machine-readable JSON output on every command |
+| `--minimal` | off | Skip WAL replay + TTL sweep (CI/test fast startup). Also set via `NETWORK_AI_MINIMAL=1` |
 
 ```bash
 # Example: point at a non-default data dir and get JSON output
 network-ai --data /var/swarm/data --json bb list
+
+# CI mode — skip WAL replay for fast startup
+NETWORK_AI_MINIMAL=1 network-ai doctor --json
 ```
 
 ---

package/README.md

@@ -5,7 +5,7 @@
 [![Website](https://img.shields.io/badge/website-network--ai.org-4b9df2?style=flat&logo=web&logoColor=white)](https://network-ai.org/)
 [![CI](https://github.com/Jovancoding/Network-AI/actions/workflows/ci.yml/badge.svg)](https://github.com/Jovancoding/Network-AI/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/Jovancoding/Network-AI/actions/workflows/codeql.yml/badge.svg)](https://github.com/Jovancoding/Network-AI/actions/workflows/codeql.yml)
-[![Release](https://img.shields.io/badge/release-v5.7.2-blue.svg)](https://github.com/Jovancoding/Network-AI/releases)
+[![Release](https://img.shields.io/badge/release-v5.8.1-blue.svg)](https://github.com/Jovancoding/Network-AI/releases)
 [![npm](https://img.shields.io/npm/dw/network-ai.svg?label=npm%20downloads)](https://www.npmjs.com/package/network-ai)
 [![Tests](https://img.shields.io/badge/tests-3136%20passing-brightgreen.svg)](#testing)
 [![Adapters](https://img.shields.io/badge/frameworks-29%20supported-blueviolet.svg)](#adapter-system)
@@ -126,6 +126,8 @@ Runs priority preemption, AuthGuardian permission gating, FSM governance, and co
 | ✅ Playground REPL | Interactive sandbox with mock agents for rapid prototyping |
 | ✅ Adapter test harness | Parameterized test battery for any adapter implementation |
 | ✅ IAuthValidator | Interface to decouple authorization from concrete AuthGuardian |
+| ✅ Kill switch | `network-ai pause` / `resume` — `SYSTEM_PAUSED` sentinel; `doctor` self-diagnostics; `inspect <key>` metadata + audit trail |
+| ✅ Minimal mode | `--minimal` / `NETWORK_AI_MINIMAL=1` — skips WAL replay and sweep for fast CI/test startup |
 | ✅ TypeScript native | ES2022 strict mode, zero native dependencies |
 
 ---
@@ -273,11 +275,15 @@ network-ai auth token my-bot --resource blackboard
 | Command group | What it controls |
 |---|---|
 | `network-ai bb` | Blackboard — get, set, delete, list, snapshot, propose, commit, abort |
-| `network-ai auth` | AuthGuardian — issue tokens, revoke, check permissions |
+| `network-ai auth` | AuthGuardian — issue tokens (`--why` for scoring breakdown), revoke, check permissions |
 | `network-ai budget` | FederatedBudget — spend status, set ceiling |
 | `network-ai audit` | Audit log — print, live-tail, clear |
+| `network-ai env` | Environment management — init, list, chain, diff, promote, backup, restore |
+| `network-ai doctor` | Self-diagnostics — validate data dir, env routing, audit log, WAL, kill-switch, MCP secret |
+| `network-ai inspect <key>` | Inspect a blackboard key — value, metadata, pending history, audit trail |
+| `network-ai pause` / `resume` | Kill switch — write/remove `SYSTEM_PAUSED` sentinel |
 
-Global flags on every command: `--data <path>` (data directory, default `./data`) · `--json` (machine-readable output)
+Global flags on every command: `--data <path>` (data directory, default `./data`) · `--env <name>` (environment) · `--json` (machine-readable output) · `--minimal` (skip WAL replay + sweep — CI/test fast startup)
 
 → Full reference in [QUICKSTART.md § CLI](QUICKSTART.md)
 
@@ -478,14 +484,17 @@ npm run test:phase12      # Context Throttler, Partition Planner, Coverage Gate,
 | [QUICKSTART.md](QUICKSTART.md) | Installation, first run, CLI reference, PowerShell guide, Python scripts CLI |
 | [ARCHITECTURE.md](ARCHITECTURE.md) | Race condition problem, FSM design, handoff protocol, module inventory, project structure |
 | [BENCHMARKS.md](BENCHMARKS.md) | Provider performance, rate limits, local GPU, `max_completion_tokens` guide |
-| [SECURITY.md](SECURITY.md) | Security module, permission system, trust levels, audit trail, v5.0 security additions, ClawHub scan findings |
+| [SECURITY.md](SECURITY.md) | Security module, permission system, trust levels, audit trail, disclosure SLA, ClawHub scan findings |
+| [THREAT_MODEL.md](THREAT_MODEL.md) | Adversary profiles, trust boundaries, explicit non-goals, security controls summary |
+| [DATA_LOCATIONS.md](DATA_LOCATIONS.md) | Every file Network-AI creates — path, purpose, data classification, operator responsibilities |
+| [SUPPLY_CHAIN.md](SUPPLY_CHAIN.md) | Runtime dependencies, what runs at install, network surface, SLSA/npm provenance verification |
 | [ENTERPRISE.md](ENTERPRISE.md) | Evaluation checklist, stability policy, security summary, integration entry points |
 | [AUDIT_LOG_SCHEMA.md](AUDIT_LOG_SCHEMA.md) | Audit log field reference, all event types, scoring formula |
 | [ADOPTERS.md](ADOPTERS.md) | Known adopters — open a PR to add yourself |
 | [INTEGRATION_GUIDE.md](INTEGRATION_GUIDE.md) | End-to-end integration walkthrough with v5.0 modules |
 | [SKILL.md](SKILL.md) | OpenClaw/ClawHub Python skill — setup, orchestrator protocol, security scan findings |
 | [references/adapter-system.md](references/adapter-system.md) | Adapter architecture, all 29 adapters, writing custom adapters |
-| [references/auth-guardian.md](references/auth-guardian.md) | Permission scoring, resource types, IAuthValidator interface |
+| [references/auth-guardian.md](references/auth-guardian.md) | Permission scoring, resource types, `scoreRequest()`, IAuthValidator interface |
 | [references/trust-levels.md](references/trust-levels.md) | Trust level configuration, APS delegation-chain mapping |
 
 ---

package/SKILL.md

@@ -5,8 +5,8 @@ metadata:
   openclaw:
     emoji: "\U0001F41D"
     homepage: https://network-ai.org
-    bundle_scope: "Python scripts only (scripts/*.py). All execution is local. Only Python stdlib — no other runtimes, adapters, or CLI tools are included."
-    network_calls: "none — bundled scripts make zero network calls and spawn no subprocesses."
+    bundle_scope: "Python scripts (scripts/*.py) — local only, Python stdlib only, no network calls, no subprocesses. The full npm package additionally includes TypeScript library modules, a CLI (bin/cli.ts), and an optional self-hosted MCP SSE server (bin/mcp-server.ts) that binds a TCP port when started by the operator. Install the npm package only if you intend to run the full orchestrator."
+    network_calls: "bundled Python scripts: none — zero network calls, zero subprocesses. MCP SSE server (bin/mcp-server.ts, optional): binds a TCP port (default 127.0.0.1) when explicitly started by the operator; requires a non-empty secret (bearer token). Core TypeScript library: zero outbound network calls — all LLM/API clients are BYOC (bring your own client)."
     inter_agent_comms: "none — this skill does not implement, invoke, or control inter-agent messaging or sessions_send. All coordination is via local file-based blackboard only."
     sessions_send: "NOT implemented or invoked by this skill. sessions_send is a host-platform built-in entirely outside this skill's control. See data-flow notice below."
     sessions_ops: "platform-provided — outside this skill's control"
@@ -713,7 +713,7 @@ The following findings are drawn from the **MAESTRO Agent Security Threat** fram
 
 | Control | How Network-AI addresses it |
 |---|---|
-| **Permission manifest** | `metadata.openclaw` in SKILL.md frontmatter explicitly declares `bundle_scope: "Python scripts only"`, `network_calls: none`, `requires.bins: [python3]` — no shell tools, no API credentials, no external services |
+| **Permission manifest** | `metadata.openclaw` in SKILL.md frontmatter explicitly declares `bundle_scope` (Python scripts: local-only; full npm package: includes optional MCP SSE server), `network_calls` (Python scripts: none; MCP SSE server: TCP, operator-started, bearer-token required), `requires.bins: [python3]` — no API credentials, no external services in core |
 | **Least-privilege resource gating** | `check_permission.py` uses a weighted scoring model (justification 40 %, trust 30 %, risk 30 %); PAYMENTS and FILE_EXPORT require `--confirm-high-risk` acknowledgment before any token is issued; `--scope` limits every grant to minimum required access |
 | **Abstract resource labels only** | PAYMENTS, DATABASE, EMAIL, FILE_EXPORT are local scoring labels — no external credentials exist in the skill; there is nothing to leak to an external service |
 | **HMAC-signed grant tokens** | Since v5.5.2, every grant record carries `_sig` (HMAC-SHA256 over canonical fields); `validate_token.py` rejects tampered records — privilege escalation via forged grants is detected at validation time |
@@ -726,7 +726,7 @@ The following findings are drawn from the **MAESTRO Agent Security Threat** fram
 
 | Control | How Network-AI addresses it |
 |---|---|
-| **Zero network calls, zero subprocesses** | All bundled Python scripts use Python stdlib only, spawn no subprocesses, and make no network calls — declared in `metadata.openclaw.network_calls: none` and `bundle_scope`; enforceable by platform inspection |
+| **Zero network calls (Python scripts)** | All bundled Python scripts use Python stdlib only, spawn no subprocesses, and make no network calls — declared in `metadata.openclaw.network_calls` and `bundle_scope`. The optional MCP SSE server (`bin/mcp-server.ts`) binds a TCP port only when explicitly started by the operator and requires a non-empty bearer-token secret. |
 | **AgentRuntime sandbox** | `ShellExecutor` enforces per-command timeout and output-size limits; `SandboxPolicy` allowlist/blocklist prevents unapproved shell commands from running at all |
 | **Source protection** | `SandboxPolicy.sourceProtection` constrains `FileAccessor.read/write/list` to `data/<env>/` only; any attempt to read outside that boundary throws `SourceProtectionError` — the agent receives `{success: false}`, no path details leak |
 | **Environment isolation** | `NETWORK_AI_ENV` / `--env` routes all state to `data/<env>/`; dev, staging, and production state are fully separated; live state (`audit_log.jsonl`, `active_grants.json`) never promotes across environments |
@@ -739,7 +739,7 @@ The following findings are drawn from the **MAESTRO Agent Security Threat** fram
 
 | Control | How Network-AI addresses it |
 |---|---|
-| **Exact version pinning** | npm `package.json` uses exact `"version": "5.7.2"` — no semver range specifiers; `clawhub install network-ai` pins to a specific published version |
+| **Exact version pinning** | npm `package.json` uses exact `"version": "5.8.1"` — no semver range specifiers; `clawhub install network-ai` pins to a specific published version |
 | **Zero transitive dependency drift** | All bundled Python scripts use Python stdlib only — `pip install` is never required; there are no third-party packages to drift, be compromised upstream, or introduce CVEs |
 | **Signed, tagged releases** | Every release is committed with a signed Git tag (`v5.7.x`); commit hash is verifiable against CHANGELOG.md; GitHub releases link tag → diff → changelog entry |
 | **Supply chain monitoring** | npm package continuously scored by Socket.dev (score A); any new dependency or permission change triggers an alert |

package/bin/cli.ts

@@ -65,7 +65,8 @@ program
   .enablePositionalOptions()
   .addOption(new Option('--data <path>', 'path to data directory').default('./data'))
   .addOption(new Option('--env <name>', 'target environment (dev|st|sit|qa|sandbox|preprod|prod)'))
-  .addOption(new Option('--json', 'output raw JSON (useful for piping)'));
+  .addOption(new Option('--json', 'output raw JSON (useful for piping)'))
+  .addOption(new Option('--minimal', 'disable WAL, TTL sweep, and telemetry hooks (CI/test mode); also set via NETWORK_AI_MINIMAL=1'));
 
 // ── bb (blackboard) ───────────────────────────────────────────────────────────
 
@@ -165,11 +166,27 @@ auth.command('token <agentId>')
   .option('--resource <type>', 'resource type to grant', 'blackboard')
   .option('--justification <text>', 'justification text', 'CLI-issued token')
   .option('--scope <scope>', 'permission scope')
-  .action(async (agentId: string, opts: { resource: string; justification: string; scope?: string }, cmd: Command) => {
+  .option('--why', 'show scoring breakdown (justification/trust/risk) before issuing')
+  .action(async (agentId: string, opts: { resource: string; justification: string; scope?: string; why?: boolean }, cmd: Command) => {
     const g = cmd.optsWithGlobals<{ data: string; json: boolean }>();
     const auditPath = path.join(resolveData(g), 'audit_log.jsonl');
     const guardian = new AuthGuardian({ auditLogPath: auditPath });
     guardian.registerAgentTrust({ agentId, trustLevel: 1, allowedResources: [opts.resource] });
+
+    if (opts.why) {
+      const scoring = guardian.scoreRequest(agentId, opts.resource, opts.justification, opts.scope);
+      if (g.json) {
+        print(scoring, true);
+      } else {
+        console.log(`justification score (40%): ${(scoring.justificationScore * 100).toFixed(1)}%`);
+        console.log(`trust score        (30%): ${(scoring.trustScore * 100).toFixed(1)}%`);
+        console.log(`risk score         (30%): ${(scoring.riskScore * 100).toFixed(1)}% risk → ${((1 - scoring.riskScore) * 100).toFixed(1)}% contribution`);
+        console.log(`weighted score:           ${(scoring.weightedScore * 100).toFixed(1)}%`);
+        console.log(`verdict:                  ${scoring.approved ? 'APPROVED' : 'DENIED'}${scoring.reason ? ` — ${scoring.reason}` : ''}`);
+        console.log('');
+      }
+    }
+
     const grant = await guardian.requestPermission(agentId, opts.resource, opts.justification, opts.scope);
     if (g.json) {
       print(grant, true);
@@ -455,12 +472,270 @@ envBackup.command('prune')
     print(g.json ? { deleted } : `✓ pruned ${deleted} backup(s), keeping ${opts.keep}`, g.json);
   });
 
+// ── doctor ────────────────────────────────────────────────────────────────────
+
+program.command('doctor')
+  .description('Validate the Network-AI environment and configuration')
+  .action((_opts: Record<string, unknown>, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; env?: string; json: boolean }>();
+    const dataDir = resolveData(g);
+
+    const results: Array<{ check: string; status: 'pass' | 'warn' | 'fail'; detail: string }> = [];
+    let exitCode = 0;
+
+    function check(name: string, fn: () => { status: 'pass' | 'warn' | 'fail'; detail: string }): void {
+      try {
+        results.push({ check: name, ...fn() });
+      } catch (err) {
+        results.push({ check: name, status: 'fail', detail: err instanceof Error ? err.message : String(err) });
+      }
+    }
+
+    // 1 — Data directory exists and is writable
+    check('data-dir', () => {
+      if (!fs.existsSync(dataDir)) {
+        return { status: 'warn', detail: `data dir does not exist: ${dataDir} (will be created on first write)` };
+      }
+      try {
+        fs.accessSync(dataDir, fs.constants.W_OK);
+        return { status: 'pass', detail: dataDir };
+      } catch {
+        return { status: 'fail', detail: `data dir is not writable: ${dataDir}` };
+      }
+    });
+
+    // 2 — NETWORK_AI_ENV routing
+    check('env-routing', () => {
+      const envVar = process.env['NETWORK_AI_ENV'];
+      if (g.env) {
+        return { status: 'pass', detail: `--env ${g.env} (CLI flag)` };
+      }
+      if (envVar) {
+        return { status: 'pass', detail: `NETWORK_AI_ENV=${envVar}` };
+      }
+      return { status: 'warn', detail: 'no --env or NETWORK_AI_ENV set; using root data dir' };
+    });
+
+    // 3 — Audit log integrity (valid JSONL)
+    check('audit-log', () => {
+      const logFile = getAuditLogPath(dataDir);
+      if (!fs.existsSync(logFile)) {
+        return { status: 'warn', detail: 'audit log does not exist yet' };
+      }
+      const lines = fs.readFileSync(logFile, 'utf8').split('\n').filter(l => l.trim());
+      let badLines = 0;
+      for (const line of lines) {
+        try { JSON.parse(line); } catch { badLines++; }
+      }
+      if (badLines > 0) {
+        return { status: 'fail', detail: `${badLines} of ${lines.length} lines are not valid JSON` };
+      }
+      return { status: 'pass', detail: `${lines.length} entries, all valid JSONL` };
+    });
+
+    // 4 — Pending changes (stale WAL entries)
+    check('pending-changes', () => {
+      const pendingDir = path.join(dataDir, 'pending_changes');
+      if (!fs.existsSync(pendingDir)) {
+        return { status: 'pass', detail: 'no pending_changes dir' };
+      }
+      const files = fs.readdirSync(pendingDir).filter(f => f.endsWith('.json'));
+      if (files.length === 0) {
+        return { status: 'pass', detail: 'no pending changes' };
+      }
+      // Flag as warn if any are older than 5 minutes
+      const stale = files.filter(f => {
+        try {
+          const st = fs.statSync(path.join(pendingDir, f));
+          return (Date.now() - st.mtimeMs) > 5 * 60 * 1000;
+        } catch { return false; }
+      });
+      if (stale.length > 0) {
+        return { status: 'warn', detail: `${stale.length} stale pending change(s) (>5 min old)` };
+      }
+      return { status: 'pass', detail: `${files.length} in-flight pending change(s)` };
+    });
+
+    // 5 — System paused?
+    check('kill-switch', () => {
+      const sentinel = path.join(dataDir, 'SYSTEM_PAUSED');
+      if (fs.existsSync(sentinel)) {
+        return { status: 'warn', detail: 'system is PAUSED (run "network-ai resume" to unpause)' };
+      }
+      return { status: 'pass', detail: 'system is running' };
+    });
+
+    // 6 — MCP secret configured (env var)
+    check('mcp-secret', () => {
+      const secret = process.env['NETWORK_AI_MCP_SECRET'];
+      if (!secret) {
+        return { status: 'warn', detail: 'NETWORK_AI_MCP_SECRET not set; McpSseServer will refuse to start without a secret' };
+      }
+      return { status: 'pass', detail: 'NETWORK_AI_MCP_SECRET is set' };
+    });
+
+    // 7 — Blackboard file is valid JSON (if it exists)
+    check('blackboard-schema', () => {
+      const bbFile = path.join(dataDir, 'blackboard.json');
+      if (!fs.existsSync(bbFile)) {
+        return { status: 'pass', detail: 'blackboard file does not exist yet' };
+      }
+      try {
+        const raw = fs.readFileSync(bbFile, 'utf8');
+        const parsed = JSON.parse(raw) as unknown;
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+          return { status: 'fail', detail: 'blackboard.json is not a JSON object' };
+        }
+        return { status: 'pass', detail: `blackboard.json OK (${Object.keys(parsed as Record<string, unknown>).length} keys)` };
+      } catch (e) {
+        return { status: 'fail', detail: `blackboard.json parse error: ${e instanceof Error ? e.message : String(e)}` };
+      }
+    });
+
+    // Determine exit code
+    for (const r of results) {
+      if (r.status === 'fail') exitCode = 1;
+    }
+
+    if (g.json) {
+      print({ checks: results, ok: exitCode === 0 }, true);
+    } else {
+      for (const r of results) {
+        const icon = r.status === 'pass' ? '✓' : r.status === 'warn' ? '⚠' : '✗';
+        console.log(`${icon} [${r.status.toUpperCase().padEnd(4)}] ${r.check}: ${r.detail}`);
+      }
+      if (exitCode === 0) {
+        console.log('\nAll checks passed.');
+      } else {
+        console.log('\nOne or more checks failed.');
+      }
+    }
+
+    process.exit(exitCode);
+  });
+
+// ── inspect ───────────────────────────────────────────────────────────────────
+
+program.command('inspect <key>')
+  .description('Inspect a blackboard key: value, metadata, audit trail')
+  .option('--history', 'show WAL/pending version history')
+  .option('--audit', 'show audit log entries for this key')
+  .action((key: string, opts: { history?: boolean; audit?: boolean }, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; env?: string; json: boolean }>();
+    const dataDir = resolveData(g);
+
+    const bb = new LockedBlackboard(dataDir);
+    const entry = bb.read(key);
+
+    const result: Record<string, unknown> = {
+      key,
+      exists: entry !== null,
+      value: entry?.value ?? null,
+      metadata: entry ? {
+        source_agent: entry.source_agent,
+        timestamp: entry.timestamp,
+        ttl: entry.ttl,
+        version: entry.version,
+      } : null,
+    };
+
+    if (opts.history) {
+      const pendingDir = path.join(dataDir, 'pending_changes');
+      const history: unknown[] = [];
+      if (fs.existsSync(pendingDir)) {
+        const files = fs.readdirSync(pendingDir)
+          .filter(f => f.endsWith('.json'))
+          .sort();
+        for (const f of files) {
+          try {
+            const raw = JSON.parse(fs.readFileSync(path.join(pendingDir, f), 'utf8')) as Record<string, unknown>;
+            if (raw['key'] === key) history.push(raw);
+          } catch { /* skip malformed */ }
+        }
+      }
+      result['pendingHistory'] = history;
+    }
+
+    if (opts.audit) {
+      const logFile = getAuditLogPath(dataDir);
+      const auditEntries: unknown[] = [];
+      if (fs.existsSync(logFile)) {
+        const lines = fs.readFileSync(logFile, 'utf8').split('\n').filter(l => l.trim());
+        for (const line of lines) {
+          try {
+            const entry2 = JSON.parse(line) as Record<string, unknown>;
+            if (entry2['key'] === key) auditEntries.push(entry2);
+          } catch { /* skip */ }
+        }
+      }
+      result['auditTrail'] = auditEntries;
+    }
+
+    if (g.json) {
+      print(result, true);
+    } else {
+      console.log(`key:    ${key}`);
+      console.log(`exists: ${result['exists']}`);
+      if (result['exists']) {
+        console.log(`value:  ${JSON.stringify(result['value'], null, 2)}`);
+        if (result['metadata']) {
+          console.log(`meta:   ${JSON.stringify(result['metadata'], null, 2)}`);
+        }
+      }
+      if (opts.history && Array.isArray(result['pendingHistory'])) {
+        const h = result['pendingHistory'] as unknown[];
+        console.log(`\npending history (${h.length} entries):`);
+        h.forEach((e, i) => console.log(`  [${i + 1}] ${JSON.stringify(e)}`));
+      }
+      if (opts.audit && Array.isArray(result['auditTrail'])) {
+        const a = result['auditTrail'] as unknown[];
+        console.log(`\naudit trail (${a.length} entries):`);
+        a.forEach((e, i) => console.log(`  [${i + 1}] ${JSON.stringify(e)}`));
+      }
+    }
+  });
+
+// ── pause / resume (kill switch) ──────────────────────────────────────────────
+
+program.command('pause')
+  .description('Pause all orchestrator activity (writes SYSTEM_PAUSED sentinel)')
+  .action((_opts: Record<string, unknown>, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; json: boolean }>();
+    const dataDir = resolveData(g);
+    if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true });
+    const sentinel = path.join(dataDir, 'SYSTEM_PAUSED');
+    const ts = new Date().toISOString();
+    fs.writeFileSync(sentinel, `paused at ${ts}\n`, 'utf8');
+    print(g.json ? { paused: true, at: ts, sentinel } : `✓ system paused at ${ts}`, g.json);
+  });
+
+program.command('resume')
+  .description('Resume orchestrator activity (removes SYSTEM_PAUSED sentinel)')
+  .action((_opts: Record<string, unknown>, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; json: boolean }>();
+    const dataDir = resolveData(g);
+    const sentinel = path.join(dataDir, 'SYSTEM_PAUSED');
+    if (!fs.existsSync(sentinel)) {
+      print(g.json ? { paused: false, detail: 'system was not paused' } : '✓ system is not paused', g.json);
+      return;
+    }
+    fs.unlinkSync(sentinel);
+    print(g.json ? { paused: false, resumed: true } : '✓ system resumed', g.json);
+  });
+
 // ── parse ─────────────────────────────────────────────────────────────────────
 
 // Auto-detect MCP stdio mode: when stdin is piped (not a TTY) and no
 // subcommand was given, start the MCP server in stdio transport mode.
 // This is the convention used by Glama, Claude Desktop, Cursor, etc.
 const userArgs = process.argv.slice(2);
+
+// Propagate --minimal flag to env var before any commands run so that
+// LockedBlackboard and other components can check it in their constructors.
+if (userArgs.includes('--minimal') || process.env['NETWORK_AI_MINIMAL'] === '1') {
+  process.env['NETWORK_AI_MINIMAL'] = '1';
+}
+
 if (!process.stdin.isTTY && userArgs.length === 0) {
   // Set --stdio before importing so the server module picks it up
   process.argv.push('--stdio');