loki-mode 7.53.0 → 7.54.0

package/README.md

@@ -40,7 +40,7 @@ _The free, source-available autonomous coding agent by [Autonomi](https://www.au
 - **Legacy system healing** -- `loki modernize heal` archaeology/stabilize/isolate/modernize/validate phases (v6.67.0, see `skills/healing.md`)
 - **MCP server** -- 34 tools (including ChromaDB code search) plus 3 resources and 2 prompts (`mcp/server.py`, with magic tools registered from `mcp/magic_tools.py` and the managed-memory tool from `mcp/managed_tools.py`). Of the 34, 33 are always available; `loki_memory_redact` is registered but only succeeds when `LOKI_MANAGED_AGENTS=true` and `LOKI_MANAGED_MEMORY=true`. Launch with `loki mcp` (bootstraps the Python MCP SDK on first run).
 - **Full-stack output** -- Source code, tests, Docker Compose stacks (multi-service with healthchecks), CI/CD pipelines, audit logs
-- **Provider-agnostic** -- runs on Claude, Codex, Cline, or Aider with automatic failover (`loki-ts/src/runner/providers.ts`); no vendor lock-in. Gemini CLI deprecated v7.5.18; Antigravity CLI coming soon.
+- **Provider-agnostic** -- runs on Claude, Codex, Cline, or Aider with automatic failover (`loki-ts/src/runner/providers.ts`); no vendor lock-in. Gemini CLI deprecated v7.5.18.
 - **Source-available (BUSL-1.1)** -- Free for personal, internal, and academic use.
 
 ---
@@ -326,7 +326,6 @@ Loki's autonomy and quality loop are the product; the underlying coding CLI is s
 | **Cline CLI** | Experimental (Tier 2) | `-y` | Sequential | `npm i -g @anthropic-ai/cline` |
 | **Aider** | Experimental (Tier 3) | `--yes-always` | Sequential | `pip install aider-chat` |
 | **Google Gemini CLI** | DEPRECATED v7.5.18 | -- | -- | Upstream deprecated; runtime removed. `LOKI_PROVIDER=gemini` exits with migration message. |
-| **Anthropic Antigravity CLI** | Coming soon | -- | -- | Integration planned. |
 
 Status legend: "E2E-verified" means we run real spec-to-code builds on it ourselves. Claude Code is the primary, fully supported provider and the one Loki Mode is built for; it gets full features (subagents, parallelization, MCP, Task tool). "Experimental" means the wiring is in place but we have not produced an end-to-end verified build ourselves; treat as community-tested. Experimental providers run sequentially. Auto-failover switches providers when rate-limited. See [Provider Guide](skills/providers.md).
 

package/SKILL.md

@@ -3,7 +3,7 @@ name: loki-mode
 description: Autonomous spec-driven build system with a built-in trust layer. It does not call work done until it is verified (RARV-C closure loop, 8 quality gates, completion council, verified-completion evidence gate). Triggers on "Loki Mode". Takes a spec (PRD, GitHub issue, OpenAPI doc, etc.) to deployed product with minimal human intervention. Provider-agnostic. Requires --dangerously-skip-permissions flag.
 ---
 
-# Loki Mode v7.53.0
+# Loki Mode v7.54.0
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -238,7 +238,6 @@ loki docker --image IMG start prd.md          # override the image
 - **Cline**: Multi-provider CLI, degraded mode (sequential only, no Task tool)
 - **Aider**: 18+ provider backends, degraded mode (sequential only, no Task tool)
 - **Google Gemini CLI**: DEPRECATED starting v7.5.18 (upstream deprecated; runtime removed)
-- **Anthropic Antigravity CLI**: Coming soon
 
 ---
 
@@ -407,4 +406,4 @@ See `CHANGELOG.md` entries [7.5.7], [7.5.8], [7.5.13] for the per-fix list and r
 
 ---
 
-**v7.53.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**
+**v7.54.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-7.53.0
+7.54.0

package/autonomy/run.sh

@@ -1454,7 +1454,13 @@ stop_enterprise_services() {
 # Exit 0 = ALLOW, Exit 1 = DENY, Exit 2 = REQUIRE_APPROVAL (logged but allowed for now)
 check_policy() {
     local enforcement_point="$1"
-    local context_json="${2:-{}}"
+    # Default to a valid empty-object JSON. Do NOT inline `${2:-{}}`: the
+    # closing brace of the parameter expansion eats the first `}` of the
+    # `{}` default, so a non-empty $2 like {"a":1} would pass through as
+    # {"a":1}} (invalid JSON -> check.js JSON.parse fails -> exit 1 DENY
+    # every iteration). Split the default assignment to avoid the footgun.
+    local context_json="${2:-}"
+    [ -z "$context_json" ] && context_json='{}'
 
     # Only check if policy files exist
     if [ ! -f ".loki/policies.json" ] && [ ! -f ".loki/policies.yaml" ]; then

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "7.53.0"
+__version__ = "7.54.0"
 
 # Expose the control app for easy import
 try:

package/docs/INSTALLATION.md

@@ -2,7 +2,7 @@
 
 The flagship product of [Autonomi](https://www.autonomi.dev/). Loki Mode is a spec-driven autonomous builder with a built-in trust layer that takes any spec to a deployed product and verifies completion with evidence (quality gates plus a completion council), not just a "done" claim. Complete installation instructions for all platforms and use cases.
 
-**Version:** v7.53.0
+**Version:** v7.54.0
 
 ---
 
@@ -312,7 +312,6 @@ Loki Mode supports four active providers across three tiers, plus historical/upc
 | `codex`  | Active | Tier 3 (degraded) | Sequential only, no Task tool; aligned with `@openai/codex` v0.125+. |
 | `aider`  | Active | Tier 3 (degraded) | Sequential only; `ollama_chat/<model>` works for local models. |
 | `gemini` | DEPRECATED v7.5.18 | -- | Upstream Gemini CLI deprecated by Google. Runtime removed; `LOKI_PROVIDER=gemini` exits with migration message. |
-| `antigravity` | Coming soon | -- | Anthropic Antigravity CLI integration planned. |
 
 ### Configuration
 
@@ -396,7 +395,7 @@ provider works inside the container. Provide auth with your Anthropic API key:
 # Run Loki Mode in Docker (Claude provider, API-key auth)
 docker run --rm -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
   -v $(pwd):/workspace -w /workspace \
-  asklokesh/loki-mode:7.53.0 start ./my-spec.md
+  asklokesh/loki-mode:7.54.0 start ./my-spec.md
 ```
 
 ##### docker compose + .env (no host install)

package/loki-ts/dist/loki.js

@@ -1,5 +1,5 @@
 // @bun
-var r6=Object.defineProperty;var t6=($)=>$;function i6($,Q){this[$]=t6.bind(null,Q)}var h=($,Q)=>{for(var Z in Q)r6($,Z,{get:Q[Z],enumerable:!0,configurable:!0,set:i6.bind(Q,Z)})};var L=($,Q)=>()=>($&&(Q=$($=0)),Q);var K$=import.meta.require;var D1={};h(D1,{lokiDir:()=>P,homeLokiDir:()=>n$,findRepoRootForVersion:()=>o$,REPO_ROOT:()=>g});import{resolve as n,dirname as d$}from"path";import{fileURLToPath as e6}from"url";import{existsSync as P$}from"fs";import{homedir as $Q}from"os";function QQ(){let $=S1;for(let Q=0;Q<6;Q++){if(P$(n($,"VERSION"))&&P$(n($,"autonomy/run.sh")))return $;let Z=d$($);if(Z===$)break;$=Z}return n(S1,"..","..","..")}function o$($){let Q=$;for(let Z=0;Z<6;Z++){if(P$(n(Q,"VERSION"))&&P$(n(Q,"autonomy/run.sh")))return Q;let z=d$(Q);if(z===Q)break;Q=z}return n($,"..","..","..")}function P(){return process.env.LOKI_DIR??n(process.cwd(),".loki")}function n$(){return n($Q(),".loki")}var S1,g;var b=L(()=>{S1=d$(e6(import.meta.url));g=QQ()});import{readFileSync as ZQ}from"fs";import{resolve as zQ,dirname as XQ}from"path";import{fileURLToPath as KQ}from"url";function j$(){if($$!==null)return $$;let $="7.53.0";if(typeof $==="string"&&$.length>0)return $$=$,$$;try{let Q=XQ(KQ(import.meta.url)),Z=o$(Q);$$=ZQ(zQ(Z,"VERSION"),"utf-8").trim()}catch{$$="unknown"}return $$}var $$=null;var a$=L(()=>{b()});var b1={};h(b1,{runOrThrow:()=>qQ,run:()=>k,commandVersion:()=>WQ,commandExists:()=>f,ShellError:()=>s$});async function k($,Q={}){let Z=Bun.spawn({cmd:[...$],stdout:"pipe",stderr:"pipe",env:Q.env?{...process.env,...Q.env}:process.env,cwd:Q.cwd}),z,X;if(Q.timeoutMs&&Q.timeoutMs>0)z=setTimeout(()=>{try{Z.kill("SIGTERM")}catch{}X=setTimeout(()=>{try{Z.kill("SIGKILL")}catch{}},2000)},Q.timeoutMs);try{let[q,K,W]=await Promise.all([new Response(Z.stdout).text(),new Response(Z.stderr).text(),Z.exited]);return{stdout:q,stderr:K,exitCode:W}}finally{if(z)clearTimeout(z);if(X)clearTimeout(X)}}async function qQ($,Q={}){let Z=await k($,Q);if(Z.exitCode!==0)throw new s$(`command failed (${Z.exitCode}): ${$.join(" ")}`,Z.exitCode,Z.stdout,Z.stderr);return Z}async function f($){let Q=VQ($),Z=await k(["sh","-c",`command -v ${Q}`],{timeoutMs:5000});if(Z.exitCode===0)return Z.stdout.trim()||null;return null}function VQ($){if(!/^[A-Za-z0-9._/-]+$/.test($))throw Error(`refused to shell-escape suspect token: ${$}`);return $}async function WQ($,Q="--version"){if(!await f($))return null;let z=await k([$,Q],{timeoutMs:5000});if(z.exitCode!==0)return null;return((z.stdout||z.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var s$;var d=L(()=>{s$=class s$ extends Error{message;exitCode;stdout;stderr;constructor($,Q,Z,z){super($);this.message=$;this.exitCode=Q;this.stdout=Z;this.stderr=z;this.name="ShellError"}}});function a($){return JQ?"":$}var JQ,T,S,_,wZ,I,R,y,V;var c=L(()=>{JQ=(process.env.NO_COLOR??"").length>0;T=a("\x1B[0;31m"),S=a("\x1B[0;32m"),_=a("\x1B[1;33m"),wZ=a("\x1B[0;34m"),I=a("\x1B[0;36m"),R=a("\x1B[1m"),y=a("\x1B[2m"),V=a("\x1B[0m")});import{existsSync as wQ}from"fs";async function Q$(){if(G$!==void 0)return G$;let $="/opt/homebrew/bin/python3.12";if(wQ($))return G$=$,$;let Q=await f("python3.12");if(Q)return G$=Q,Q;let Z=await f("python3");return G$=Z,Z}async function Z$($,Q={}){let Z=await Q$();if(!Z)return{stdout:"",stderr:"python3 not found",exitCode:127};return k([Z,"-c",$],Q)}var G$;var q$=L(()=>{d()});var e1={};h(e1,{runStatus:()=>uQ});import{existsSync as v,readFileSync as W$,readdirSync as d1,statSync as o1}from"fs";import{resolve as C,basename as DQ}from"path";import{homedir as CQ}from"os";function n1($){let Q=Math.trunc($);if(Q>=1e6)return`${(Math.trunc(Q/1e6*10)/10).toFixed(1)}M`;if(Q>=1000)return`${(Math.trunc(Q/1000*10)/10).toFixed(1)}K`;return String(Q)}function a1($,Q,Z){if(Q===0)return null;let z=Math.trunc($*100/Q),X=Math.trunc($*k$/Q);if(X>k$)X=k$;let q=k$-X,K=S;if(z>=80)K=T;else if(z>=50)K=_;let W="=".repeat(Math.max(0,X))+" ".repeat(Math.max(0,q)),J=n1($),U=n1(Q);return`  ${R}${Z}${V} ${K}[${W}]${V} ${z}% (${J} / ${U})`}async function hQ(){if(await f("jq"))return!0;return process.stdout.write(`${T}Error: jq is required but not installed.${V}
+var r6=Object.defineProperty;var t6=($)=>$;function i6($,Q){this[$]=t6.bind(null,Q)}var h=($,Q)=>{for(var Z in Q)r6($,Z,{get:Q[Z],enumerable:!0,configurable:!0,set:i6.bind(Q,Z)})};var L=($,Q)=>()=>($&&(Q=$($=0)),Q);var K$=import.meta.require;var D1={};h(D1,{lokiDir:()=>P,homeLokiDir:()=>n$,findRepoRootForVersion:()=>o$,REPO_ROOT:()=>g});import{resolve as n,dirname as d$}from"path";import{fileURLToPath as e6}from"url";import{existsSync as P$}from"fs";import{homedir as $Q}from"os";function QQ(){let $=S1;for(let Q=0;Q<6;Q++){if(P$(n($,"VERSION"))&&P$(n($,"autonomy/run.sh")))return $;let Z=d$($);if(Z===$)break;$=Z}return n(S1,"..","..","..")}function o$($){let Q=$;for(let Z=0;Z<6;Z++){if(P$(n(Q,"VERSION"))&&P$(n(Q,"autonomy/run.sh")))return Q;let z=d$(Q);if(z===Q)break;Q=z}return n($,"..","..","..")}function P(){return process.env.LOKI_DIR??n(process.cwd(),".loki")}function n$(){return n($Q(),".loki")}var S1,g;var b=L(()=>{S1=d$(e6(import.meta.url));g=QQ()});import{readFileSync as ZQ}from"fs";import{resolve as zQ,dirname as XQ}from"path";import{fileURLToPath as KQ}from"url";function j$(){if($$!==null)return $$;let $="7.54.0";if(typeof $==="string"&&$.length>0)return $$=$,$$;try{let Q=XQ(KQ(import.meta.url)),Z=o$(Q);$$=ZQ(zQ(Z,"VERSION"),"utf-8").trim()}catch{$$="unknown"}return $$}var $$=null;var a$=L(()=>{b()});var b1={};h(b1,{runOrThrow:()=>qQ,run:()=>k,commandVersion:()=>WQ,commandExists:()=>f,ShellError:()=>s$});async function k($,Q={}){let Z=Bun.spawn({cmd:[...$],stdout:"pipe",stderr:"pipe",env:Q.env?{...process.env,...Q.env}:process.env,cwd:Q.cwd}),z,X;if(Q.timeoutMs&&Q.timeoutMs>0)z=setTimeout(()=>{try{Z.kill("SIGTERM")}catch{}X=setTimeout(()=>{try{Z.kill("SIGKILL")}catch{}},2000)},Q.timeoutMs);try{let[q,K,W]=await Promise.all([new Response(Z.stdout).text(),new Response(Z.stderr).text(),Z.exited]);return{stdout:q,stderr:K,exitCode:W}}finally{if(z)clearTimeout(z);if(X)clearTimeout(X)}}async function qQ($,Q={}){let Z=await k($,Q);if(Z.exitCode!==0)throw new s$(`command failed (${Z.exitCode}): ${$.join(" ")}`,Z.exitCode,Z.stdout,Z.stderr);return Z}async function f($){let Q=VQ($),Z=await k(["sh","-c",`command -v ${Q}`],{timeoutMs:5000});if(Z.exitCode===0)return Z.stdout.trim()||null;return null}function VQ($){if(!/^[A-Za-z0-9._/-]+$/.test($))throw Error(`refused to shell-escape suspect token: ${$}`);return $}async function WQ($,Q="--version"){if(!await f($))return null;let z=await k([$,Q],{timeoutMs:5000});if(z.exitCode!==0)return null;return((z.stdout||z.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var s$;var d=L(()=>{s$=class s$ extends Error{message;exitCode;stdout;stderr;constructor($,Q,Z,z){super($);this.message=$;this.exitCode=Q;this.stdout=Z;this.stderr=z;this.name="ShellError"}}});function a($){return JQ?"":$}var JQ,T,S,_,wZ,I,R,y,V;var c=L(()=>{JQ=(process.env.NO_COLOR??"").length>0;T=a("\x1B[0;31m"),S=a("\x1B[0;32m"),_=a("\x1B[1;33m"),wZ=a("\x1B[0;34m"),I=a("\x1B[0;36m"),R=a("\x1B[1m"),y=a("\x1B[2m"),V=a("\x1B[0m")});import{existsSync as wQ}from"fs";async function Q$(){if(G$!==void 0)return G$;let $="/opt/homebrew/bin/python3.12";if(wQ($))return G$=$,$;let Q=await f("python3.12");if(Q)return G$=Q,Q;let Z=await f("python3");return G$=Z,Z}async function Z$($,Q={}){let Z=await Q$();if(!Z)return{stdout:"",stderr:"python3 not found",exitCode:127};return k([Z,"-c",$],Q)}var G$;var q$=L(()=>{d()});var e1={};h(e1,{runStatus:()=>uQ});import{existsSync as v,readFileSync as W$,readdirSync as d1,statSync as o1}from"fs";import{resolve as C,basename as DQ}from"path";import{homedir as CQ}from"os";function n1($){let Q=Math.trunc($);if(Q>=1e6)return`${(Math.trunc(Q/1e6*10)/10).toFixed(1)}M`;if(Q>=1000)return`${(Math.trunc(Q/1000*10)/10).toFixed(1)}K`;return String(Q)}function a1($,Q,Z){if(Q===0)return null;let z=Math.trunc($*100/Q),X=Math.trunc($*k$/Q);if(X>k$)X=k$;let q=k$-X,K=S;if(z>=80)K=T;else if(z>=50)K=_;let W="=".repeat(Math.max(0,X))+" ".repeat(Math.max(0,q)),J=n1($),U=n1(Q);return`  ${R}${Z}${V} ${K}[${W}]${V} ${z}% (${J} / ${U})`}async function hQ(){if(await f("jq"))return!0;return process.stdout.write(`${T}Error: jq is required but not installed.${V}
 `),process.stdout.write(`Install with:
 `),process.stdout.write(`  brew install jq    (macOS)
 `),process.stdout.write(`  apt install jq     (Debian/Ubuntu)
@@ -790,4 +790,4 @@ Set LOKI_LEGACY_BASH=1 to force the bash CLI for every command.
 `),2}default:return process.stderr.write(`Unknown command: ${Q}
 `),process.stderr.write(s6),2}}l1();process.on("SIGINT",()=>process.exit(130));process.on("SIGTERM",()=>process.exit(143));var KZ=await XZ(Bun.argv.slice(2));process.exit(KZ);
 
-//# debugId=3BF6CF9B99A2BD7E64756E2164756E21
+//# debugId=45D73957F12E90DF64756E2164756E21

package/mcp/__init__.py

@@ -57,4 +57,4 @@ try:
 except ImportError:
     __all__ = ['mcp']
 
-__version__ = '7.53.0'
+__version__ = '7.54.0'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "loki-mode",
   "mcpName": "io.github.asklokesh/loki-mode",
-  "version": "7.53.0",
+  "version": "7.54.0",
   "description": "Loki Mode by Autonomi. Autonomous spec-to-product system: takes a PRD, GitHub issue, OpenAPI/JSON/YAML, or one-line brief to a deployed app via the RARV-C closure loop with 8 quality gates. Provider-agnostic (Claude Code, OpenAI Codex, Cline, Aider).",
   "keywords": [
     "agent",

package/plugins/loki-mode/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "loki-mode",
   "displayName": "Loki Mode",
-  "version": "7.53.0",
+  "version": "7.54.0",
   "description": "Autonomous spec-to-product build system with a built-in trust layer (RARV-C closure loop, 8 quality gates, completion council). Ships Loki's spec-hardening, drift-detection, and deterministic PR verification commands plus the Loki MCP server.",
   "author": {
     "name": "Autonomi",

package/src/audit/compliance-scheduler.js

@@ -0,0 +1,287 @@
+'use strict';
+
+/**
+ * Compliance snapshot scheduler (lightweight helper, NOT a daemon).
+ *
+ * v7.53.0 shipped a live GET /api/compliance endpoint that regenerates a
+ * compliance report on demand. This module is the remaining P3-11 piece:
+ * OPTIONAL scheduled/continuous generation so a compliance snapshot is
+ * periodically PERSISTED to disk. That gives two things a live dashboard
+ * call cannot:
+ *
+ *   1. Trend / history: a series of timestamped snapshots over time.
+ *   2. Air-gapped audit evidence: durable, self-contained proof on disk
+ *      without anyone making a live API call.
+ *
+ * It is deliberately NOT a background process. The gate function
+ * (maybeGenerateSnapshot) is meant to be invoked opportunistically (for
+ * example once per autonomous run) and self-rate-limits: it only writes a
+ * new snapshot when the configured interval has elapsed since the last one.
+ * That makes it "continuous" when enabled without needing a daemon or any
+ * always-running loop.
+ *
+ * HONESTY: every snapshot is generated from the REAL current audit chain
+ * (AuditLog.readEntries) and the REAL tamper-evidence verdict
+ * (AuditLog.verifyChain), exactly like index.js getReport. An empty chain
+ * yields an honest empty snapshot (totalAuditEntries: 0), never a
+ * fabricated "compliant" verdict.
+ *
+ * DEFAULT DISABLED: with no configured interval (LOKI_COMPLIANCE_SNAPSHOT_INTERVAL_HOURS
+ * unset or 0), maybeGenerateSnapshot is a no-op and adds zero behavior for
+ * existing users.
+ *
+ * NOT YET AUTO-INVOKED: this wave ships the tested helper only. It is not
+ * wired into run.sh or any live loop here (that is integration, owned by the
+ * run.sh owners). See "How to invoke" below for the intended call site.
+ *
+ * How to invoke (intended integration, not yet wired):
+ *   var scheduler = require('./src/audit/compliance-scheduler');
+ *   // Once per run, after init:
+ *   scheduler.maybeGenerateSnapshot({ projectDir: process.cwd() });
+ *   // Reads LOKI_COMPLIANCE_SNAPSHOT_INTERVAL_HOURS; no-op unless elapsed.
+ */
+
+var fs = require('fs');
+var path = require('path');
+var { AuditLog } = require('./log');
+var compliance = require('./compliance');
+
+var ENV_INTERVAL = 'LOKI_COMPLIANCE_SNAPSHOT_INTERVAL_HOURS';
+var SNAPSHOT_DIRNAME = 'compliance-snapshots';
+var MARKER_FILENAME = 'last-snapshot.json';
+var MS_PER_HOUR = 3600 * 1000;
+
+/**
+ * Parse a configured interval (hours) into a number. Returns 0 (disabled)
+ * for unset, empty, non-numeric, negative, or NaN values. 0 means the
+ * scheduler is disabled and maybeGenerateSnapshot is a no-op.
+ *
+ * @param {*} raw - Raw value (typically process.env.LOKI_COMPLIANCE_SNAPSHOT_INTERVAL_HOURS)
+ * @returns {number} Interval in hours, or 0 if disabled / invalid.
+ */
+function parseIntervalHours(raw) {
+  if (raw === undefined || raw === null || raw === '') return 0;
+  var n = Number(raw);
+  if (!isFinite(n) || n <= 0) return 0;
+  return n;
+}
+
+/**
+ * Resolve the snapshot directory for a project: <projectDir>/.loki/audit/compliance-snapshots.
+ */
+function snapshotDir(projectDir) {
+  return path.join(projectDir || process.cwd(), '.loki', 'audit', SNAPSHOT_DIRNAME);
+}
+
+/**
+ * Resolve the rate-limit marker file path.
+ */
+function markerPath(projectDir) {
+  return path.join(snapshotDir(projectDir), MARKER_FILENAME);
+}
+
+/**
+ * Read the last-generated timestamp (ms) from the marker file. Returns null
+ * if no marker exists or it is unreadable / malformed (treated as "never
+ * generated" so the next call generates).
+ */
+function readLastGeneratedAtMs(projectDir) {
+  var p = markerPath(projectDir);
+  try {
+    if (!fs.existsSync(p)) return null;
+    var raw = fs.readFileSync(p, 'utf8');
+    var obj = JSON.parse(raw);
+    var ms = Number(obj && obj.lastGeneratedAtMs);
+    if (!isFinite(ms)) return null;
+    return ms;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Build a compliance snapshot from the REAL audit chain for a project.
+ *
+ * Bundles all three report types (soc2, iso27001, gdpr), each generated
+ * from the live audit entries, plus the single shared tamper-evidence
+ * verdict. This mirrors index.js getReport's honesty: the chainIntegrity
+ * verdict comes from verifyChain(), and a verification error is recorded
+ * as a valid:false verdict rather than being allowed to throw or fabricate
+ * a pass. An empty chain produces totalAuditEntries: 0 honestly.
+ *
+ * This does NOT use the index.js singleton; it reads the chain directly so
+ * it is self-contained and free of shared-state coupling.
+ *
+ * @param {object} args
+ * @param {string} args.projectDir - Project root whose .loki/audit chain is read.
+ * @param {object} [args.reportOpts] - Options forwarded to the generators (projectName, period, etc.)
+ * @param {number} [args.nowMs] - Clock for generatedAt (defaults to Date.now()).
+ * @returns {object} The snapshot object.
+ */
+function buildSnapshot(args) {
+  args = args || {};
+  var projectDir = args.projectDir || process.cwd();
+  var reportOpts = args.reportOpts || {};
+  var nowMs = (typeof args.nowMs === 'number') ? args.nowMs : Date.now();
+
+  var log = new AuditLog({ projectDir: projectDir });
+  var entries;
+  try {
+    entries = log.readEntries();
+  } catch (e) {
+    entries = [];
+  }
+
+  // Real tamper-evidence verdict. Do not let a verification error fabricate
+  // a pass: capture it honestly as a valid:false verdict instead.
+  var chainIntegrity;
+  try {
+    chainIntegrity = log.verifyChain();
+  } catch (e) {
+    chainIntegrity = {
+      valid: false,
+      entries: entries.length,
+      brokenAt: null,
+      error: 'chain verification failed: ' + String((e && e.message) || e),
+    };
+  }
+
+  try { log.destroy(); } catch (_) { /* noop */ }
+
+  var soc2 = compliance.generateSoc2Report(entries, reportOpts);
+  soc2.chainIntegrity = chainIntegrity;
+  var iso27001 = compliance.generateIso27001Report(entries, reportOpts);
+  iso27001.chainIntegrity = chainIntegrity;
+  var gdpr = compliance.generateGdprReport(entries, reportOpts);
+  gdpr.chainIntegrity = chainIntegrity;
+
+  return {
+    snapshotVersion: 1,
+    generatedAt: new Date(nowMs).toISOString(),
+    projectName: reportOpts.projectName || 'Loki Mode',
+    totalAuditEntries: entries.length,
+    chainIntegrity: chainIntegrity,
+    reports: {
+      soc2: soc2,
+      iso27001: iso27001,
+      gdpr: gdpr,
+    },
+  };
+}
+
+/**
+ * Build a filesystem-safe snapshot filename from an ISO timestamp. ISO
+ * strings contain colons and dots which are fine on macOS/Linux but are
+ * sanitized to hyphens anyway for portability.
+ */
+function snapshotFilename(isoTimestamp) {
+  var safe = String(isoTimestamp).replace(/[:.]/g, '-');
+  return 'compliance-' + safe + '.json';
+}
+
+/**
+ * Persist a snapshot to disk and update the rate-limit marker.
+ *
+ * Writes <snapshotDir>/compliance-<timestamp>.json and updates
+ * <snapshotDir>/last-snapshot.json with the generation clock so the next
+ * gate decision reads the same clock that produced the snapshot.
+ *
+ * @param {object} args
+ * @param {string} args.projectDir - Project root.
+ * @param {object} args.snapshot - Snapshot object (from buildSnapshot).
+ * @param {number} args.nowMs - Generation clock in ms (stored in the marker).
+ * @returns {string} The absolute path of the written snapshot file.
+ */
+function persistSnapshot(args) {
+  var projectDir = args.projectDir || process.cwd();
+  var snapshot = args.snapshot;
+  var nowMs = args.nowMs;
+  var dir = snapshotDir(projectDir);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  var file = path.join(dir, snapshotFilename(snapshot.generatedAt));
+  fs.writeFileSync(file, JSON.stringify(snapshot, null, 2), 'utf8');
+  fs.writeFileSync(
+    markerPath(projectDir),
+    JSON.stringify({ lastGeneratedAtMs: nowMs, lastSnapshotFile: path.basename(file) }, null, 2),
+    'utf8'
+  );
+  return file;
+}
+
+/**
+ * Opportunistic, self-rate-limiting snapshot generation.
+ *
+ * Decides whether to generate a snapshot now based on the configured
+ * interval and the persisted last-generated timestamp:
+ *
+ *   - Interval 0 / unset (default) -> no-op, reason 'disabled'.
+ *   - No prior snapshot and interval > 0 -> generate (first run).
+ *   - now - lastGeneratedAt >= interval -> generate.
+ *   - Otherwise -> no-op, reason 'not-elapsed'.
+ *
+ * Both the interval and the clock are injectable via opts so callers (and
+ * tests) can control them; env is the fallback for the interval and
+ * Date.now() the fallback for the clock.
+ *
+ * Return contract:
+ *   { generated: true, path: <file>, report: <snapshot>, intervalHours }
+ *   { generated: false, reason: 'disabled', intervalHours: 0 }
+ *   { generated: false, reason: 'not-elapsed', intervalHours, nextEligibleAtMs }
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.projectDir] - Project root (default process.cwd()).
+ * @param {number} [opts.intervalHours] - Interval override; falls back to env.
+ * @param {number} [opts.now] - Current time in ms; falls back to Date.now().
+ * @param {object} [opts.reportOpts] - Options forwarded to report generators.
+ * @returns {object} Result per the return contract above.
+ */
+function maybeGenerateSnapshot(opts) {
+  opts = opts || {};
+  var projectDir = opts.projectDir || process.cwd();
+  var intervalHours = (typeof opts.intervalHours === 'number')
+    ? parseIntervalHours(opts.intervalHours)
+    : parseIntervalHours(process.env[ENV_INTERVAL]);
+  var now = (typeof opts.now === 'number') ? opts.now : Date.now();
+
+  if (intervalHours <= 0) {
+    return { generated: false, reason: 'disabled', intervalHours: 0 };
+  }
+
+  var lastMs = readLastGeneratedAtMs(projectDir);
+  var intervalMs = intervalHours * MS_PER_HOUR;
+
+  if (lastMs !== null && (now - lastMs) < intervalMs) {
+    return {
+      generated: false,
+      reason: 'not-elapsed',
+      intervalHours: intervalHours,
+      nextEligibleAtMs: lastMs + intervalMs,
+    };
+  }
+
+  var snapshot = buildSnapshot({
+    projectDir: projectDir,
+    reportOpts: opts.reportOpts,
+    nowMs: now,
+  });
+  var file = persistSnapshot({ projectDir: projectDir, snapshot: snapshot, nowMs: now });
+
+  return {
+    generated: true,
+    path: file,
+    report: snapshot,
+    intervalHours: intervalHours,
+  };
+}
+
+module.exports = {
+  maybeGenerateSnapshot: maybeGenerateSnapshot,
+  buildSnapshot: buildSnapshot,
+  persistSnapshot: persistSnapshot,
+  parseIntervalHours: parseIntervalHours,
+  snapshotDir: snapshotDir,
+  markerPath: markerPath,
+  ENV_INTERVAL: ENV_INTERVAL,
+};