mindforge-cc 11.3.1 → 11.5.0

package/CHANGELOG.md

@@ -1,5 +1,116 @@
 # Changelog
 
+## [11.5.0] - 2026-06-11 — Governance hardening + autonomous-engine repair (Waves 4–7)
+
+This release bundles four waves of work: orchestration primitives, an **inert** manifest
+engine + the new instinct CLI + GAN harness personas, governance/security hardening, and a
+repair that makes the autonomous engine (`/mindforge:auto`) actually functional. Several
+items ship deliberately **inert** (scaffolding present, not wired into any live path) and
+are flagged as such below — they introduce **no behavior change yet**.
+
+### Added
+
+- **Instinct CLI** (`/mindforge:instinct`, `bin/learning/instinct-cli.js`) — deterministic,
+  no-LLM management of the JSONL instinct store: `list`, `export`, `import`,
+  `promote-candidates` (list + flag), and `prune`.
+- **Typed Inter-Agent Message Protocol** (`bin/autonomous/handoff-schema.js`) — five message
+  kinds (`task_handoff`, `query`, `response`, `completed`, `conflict`) with priority levels
+  (`low`/`normal`/`high`/`critical`) and message validation. Internal orchestration primitive.
+- **Manifest-driven install resolver** (`bin/installer/install-manifests.js`,
+  `.mindforge/manifests/install-*.json`) — profile-to-module expansion and dependency
+  detection. Ships **INERT**: the adapter wiring it into `bin/installer-core.js`'s live
+  `install()` path is deferred to a future PR. No behavior change.
+- **GAN-style harness personas** (`.mindforge/personas/gan-evaluator.md`, `gan-generator.md`,
+  `gan-planner.md`) — fully scoped and documented. Ships **INERT**: not wired to any live
+  command or automated workflow. No behavior change.
+- **Governance test coverage** — `tests/trust-verifier.test.js` (7 tests) and
+  `tests/rbac-manager.test.js` (8 tests) lock the fail-closed contracts for future
+  safety-critical governance changes.
+
+### Fixed
+
+- **SSRF import-URL guard** (`bin/learning/lib/ssrf-guard.js`) — closed an IPv6 link-local
+  bypass (`fe81`–`fe8f` reachable via string-prefix check) and a symlink path-traversal
+  bypass, using numeric bitmask validation and canonical-path checking before system-dir
+  validation.
+- **Federated EIS sync** (`bin/memory/eis-client.js`) — `getAuthHeader` no longer throws on
+  every call; it now registers a node identity via `ZTAI.registerAgent` and signs with
+  `ZTAI.signData`, restoring sync to non-localhost EIS endpoints.
+- **RBAC tier elevation** (`bin/governance/rbac-manager.js`) — `getRolesByTier` now fails
+  safely for unregistered agents (no thrown exception) and resolves agent tier via the
+  correct ZTAI API.
+- **Autonomous engine — wave crash** (`bin/autonomous/auto-runner.js`) — replaced ZTAI
+  singleton misuse (`getIdentity()`, non-existent) with `_getRunnerIdentity()` using the
+  real `registerAgent` API; `/mindforge:auto` no longer crashes on every wave.
+- **Autonomous policy gate — fail-open** (`bin/autonomous/auto-runner.js`) — the async
+  policy verdict is now `await`ed (`this.policyEngine.evaluate(intent)`); the per-wave gate
+  previously always allowed.
+- **Autonomous engine — fail-closed identity** (`bin/autonomous/auto-runner.js`) — if runner
+  identity cannot be established, the policy gate now denies and audits (`auto_mode_denied`)
+  instead of proceeding ungoverned.
+
+### Changed
+
+- **Instinct store schema** (`.mindforge/engine/instincts/instinct-schema.md`) — added
+  `project_id` (stable scope key) and `source` (`auto-capture`/`manual`/`imported`/
+  `observer`), plus origin-based confidence scoring: auto-capture starts at `0.3`, manual
+  at `0.7`.
+- **Cost-routing shadow mode** (`bin/revops/router-steering-v2.js`) — arbitrage steering now
+  respects `cost_routing.shadow_mode` (default `true`); in observe-only mode `steer()`
+  returns `{ shadow, authoritative: false }` with SHADOW vs LIVE logging.
+
+### Security
+
+- **Tier-3 approvals now fail closed** (`bin/governance/approve.js`) — approvals require GPG
+  verification and **throw before writing any record** when no GPG key is configured, unless
+  `MINDFORGE_ALLOW_UNVERIFIED_APPROVAL=1` is set; unverified approvals are marked
+  `verified: false`.
+- **Persona supply-chain scan** (`scripts/ci/validate-assets.js`) — persona asset validation
+  now detects dangerous invisible unicode (zero-width, bidi overrides, Unicode tags) across
+  `.mindforge/personas` to prevent ASCII-smuggling injection.
+- **Destructive-command detector** (`bin/security/trust-boundaries.js`) — `normalizeShell`
+  now strips bare `#` tokens after quote-stripping, blocking quoted-hash evasion (e.g.
+  `rm "#" -rf /`).
+- **Instinct import port allowlist** (`bin/learning/lib/ssrf-guard.js`) — `validateImportUrl`
+  enforces an `ALLOWED_IMPORT_PORTS` allowlist (`{'', '443'}`), blocking attempts to reach
+  internal services (Redis `:6379`, Mongo `:27017`, etc.) on otherwise-allowed public hosts.
+
+## [11.4.0] - 2026-06-06 — Claude Code plugin distribution
+
+MindForge is now installable as a native **Claude Code plugin** from a marketplace, in
+addition to the `npx mindforge-cc` installer. This release ships the plugin tooling so
+both the GitHub plugin channel and the npm tarball stay coherent.
+
+### Added
+
+- **Plugin marketplace** (`.claude-plugin/marketplace.json` at the repo root) — users run
+  `/plugin marketplace add sairam0424/MindForge` then `/plugin install mindforge@mindforge`.
+  Lists 11 plugins: the comprehensive `mindforge` plugin + 10 à-la-carte subagent packs.
+- **Comprehensive `mindforge` plugin** (`plugins/mindforge/`) bundling the full surface:
+  174 commands, 154 subagents, 73 skills + a synthesized `mindforge-protocol` skill (the
+  CLAUDE.md operating directive, since a plugin-root CLAUDE.md isn't loaded as context),
+  and governance hooks (translated to Claude `PreToolUse`/`PostToolUse` events with
+  `${CLAUDE_PLUGIN_ROOT}`-relative paths).
+- **Bundled MindForge MCP server** — a self-contained esbuild single-file build
+  (`mcp/dist/index.js`, all deps inlined, no runtime `node_modules`) exposing 7 tools over
+  stdio: `mindforge_health`, `mindforge_status`, `mindforge_memory_query`,
+  `mindforge_memory_stats`, `mindforge_memory_find_related`, `mindforge_audit_log`
+  (read-only), and append-only `mindforge_memory_remember`. Scoped to the user's project
+  via `${CLAUDE_PROJECT_DIR}`; degrades gracefully when MindForge isn't set up.
+- **Generators** (single source of truth, drift-guarded): `build-plugin-marketplace.js`,
+  `build-subagent-plugins.js`, `build-mindforge-plugin.js`, `vendor-sdk-into-mcp.js`,
+  `fix-command-frontmatter.js`; new `mcp-server/` package with esbuild build.
+- **`tests/plugin-packaging.test.js`** (in `npm test`) — guards the generated plugin tree,
+  frontmatter validity, and MCP-bundle self-containment.
+
+### Fixed
+
+- Quoted YAML-unsafe `name`/`description` frontmatter across commands/agents/skills that
+  the plugin validator flagged (leading `-`/`@`, embedded `: `, trailing `:`) — these
+  silently loaded empty metadata. The npx installer inherits the fix.
+- Per-category subagent `plugin.json` `agents[]` now derived from on-disk files, fixing
+  stale bare names for the 16 collision-renamed (`-cc`) agents.
+
 ## [11.3.1] - 2026-06-05 — Packaging hotfix (commands, skills & framework now ship)
 
 Critical fix for v11.3.0, where a too-narrow npm `files` allowlist silently dropped

package/MINDFORGE.md

@@ -1,12 +1,12 @@
-# MINDFORGE.md — Parameter Registry (v11.3.1)
+# MINDFORGE.md — Parameter Registry (v11.5.0)
 
 ## 1. IDENTITY & VERSIONING
 
 [NAME]    = MindForge
-[VERSION] = 11.3.1
+[VERSION] = 11.5.0
 [STABLE]  = true
 [MODE]    = "Platform Sovereign"
-[REQUIRED_CORE_VERSION] = 11.3.1
+[REQUIRED_CORE_VERSION] = 11.5.0
 [SOVEREIGN_IDENTITY] = true
 [SRE_LAYER_ENABLED]  = true
 

package/README.md

@@ -4,6 +4,13 @@
 
 ---
 
+## Latest: v11.3.1
+
+- **v11.3.1 — Packaging hotfix.** Restores the full published payload: every `npx mindforge-cc` install now delivers all 174 slash commands, 73 skills, 154 subagents, and the complete `.mindforge/` framework. (v11.3.0 shipped a too-narrow npm allowlist that silently dropped commands and skills — fixed here, with a tarball regression test so it cannot recur.)
+- **v11.3.0 — "Legion".** Imports 154 specialized Claude-Code-native subagents across 10 categories into `.claude/agents/`, fully rebranded and collision-safe. Additive and backward-compatible.
+
+See [CHANGELOG.md](./CHANGELOG.md) for full release history.
+
 ## v11.0.0 — Sovereign Stability
 
 MindForge v11.0.0 "Sovereign Stability" is a production-hardening release focused on reliability, performance, and real-world deployment readiness. Key highlights:
@@ -15,14 +22,29 @@ MindForge v11.0.0 "Sovereign Stability" is a production-hardening release focuse
 - **Production observability** — `/api/v1/system` health endpoint, P95 latency tracking, heap health monitoring, and real EIS client with retry logic.
 - **Graduated intelligence** — Adaptive tier escalation (+1/+2/MAX) with cost-awareness, 3-tier stuck detection, and adaptive context windows.
 
-This release ships 200+ skills, 400+ personas, 154 specialized subagents, 18 pillars, and 49 swarm templates across 12 engineering domains.
+This release ships 211 personas, 73 skills, 154 specialized subagents, 174 commands, 18 pillars, and 49 swarm templates across 12 engineering domains.
 
 
 ## Installation & Setup
 
-### 🚀 Quick Start (No Install)
+### 🔌 Claude Code Plugin (fastest)
+
+Install MindForge's commands, subagents, and skills directly from the marketplace —
+no project files written:
+
+```bash
+/plugin marketplace add sairam0424/MindForge
+/plugin install mindforge@mindforge
+```
+
+Prefer just a slice (e.g. Python agents)? Install a focused pack like
+`mindforge-lang@mindforge` instead. See [docs/plugin-installation.md](docs/plugin-installation.md)
+for all 11 plugins, token-budget guidance, and team setup.
+
+### 🚀 Quick Start (npx — full framework engine)
 
-Run MindForge immediately for a specific runtime without a permanent installation:
+The npx installer also writes the complete `.mindforge/` engine (governance, memory,
+planning) into your project:
 
 ```bash
 # For Claude Code

package/RELEASENOTES.md

@@ -1,4 +1,134 @@
-# Release Notes — v11.0.0 "Sovereign Stability"
+# Release Notes
+
+## v11.5.0 — Governance hardening + autonomous-engine repair
+
+**Release Date**: 2026-06-11
+**Type**: Minor (one behavior change — see "Heads-up" below)
+**Upgrade Path**: `npx mindforge-cc@latest`
+
+This release consolidates four waves of work into a single minor: new orchestration and
+learning primitives, a broad governance/security hardening pass, and — most importantly —
+a repair that takes the autonomous engine from "crashes on every wave" to actually
+functional. Some new pieces ship deliberately **inert** (present but not wired in); those
+are called out so you know not to expect new behavior from them yet.
+
+### Heads-up — Tier-3 approvals now fail closed (the one behavior change)
+
+`bin/governance/approve.js` no longer rubber-stamps approvals. Tier-3 approvals now
+**require GPG verification** and will **fail before writing any record** if no GPG key is
+configured. If you relied on the old, unverified path, you have two choices:
+
+- Configure a GPG key (recommended), or
+- Set `MINDFORGE_ALLOW_UNVERIFIED_APPROVAL=1` to keep the old behavior — in which case the
+  approval record is written with `verified: false` so the gap is auditable.
+
+This is the only item in v11.5.0 that can change an existing workflow's outcome.
+
+### The autonomous engine is functional again
+
+`/mindforge:auto` was effectively broken. Three fixes in `bin/autonomous/auto-runner.js`
+bring it back:
+
+- **No more per-wave crash.** The runner was calling a non-existent `getIdentity()` on the
+  ZTAI singleton and dying on every wave. It now establishes identity through the real
+  `registerAgent` API (`_getRunnerIdentity()`).
+- **The policy gate actually enforces now.** The async policy verdict was never `await`ed,
+  so the gate silently allowed everything. It now awaits `policyEngine.evaluate(intent)` on
+  every wave.
+- **It fails closed.** If runner identity can't be established, the gate now **denies and
+  audits** (`auto_mode_denied`) rather than running ungoverned.
+
+### Security & governance hardening
+
+- **SSRF guard hardened (twice).** The import-URL guard now closes an IPv6 link-local
+  bypass and a symlink path-traversal bypass via numeric bitmask + canonical-path checks.
+  Separately, remote instinct imports now enforce a port allowlist (`443`/none only), so an
+  attacker can no longer pivot through an allowed public host to reach internal services
+  like Redis (`:6379`) or Mongo (`:27017`).
+- **Persona supply-chain scan.** Persona asset validation now flags dangerous invisible
+  unicode (zero-width, bidi overrides, Unicode tags) across `.mindforge/personas`, closing
+  an ASCII-smuggling injection vector.
+- **Destructive-command detector closed an evasion.** Quoted-hash tricks like
+  `rm "#" -rf /` are now caught.
+- **Federated memory sync works again.** `eis-client`'s `getAuthHeader` was throwing on
+  every call; it now correctly registers a node identity and signs requests, so sync to
+  non-localhost EIS endpoints functions.
+- **RBAC fails safe.** Tier elevation no longer throws for unregistered agents and resolves
+  tiers through the correct ZTAI API.
+- **Fail-closed contracts are now tested.** New `trust-verifier` and `rbac-manager` test
+  suites lock in identity-verification and tier-authorization behavior so future governance
+  changes can't quietly regress them.
+
+### Learning & cost routing
+
+- **New instinct CLI** — `/mindforge:instinct` manages the JSONL instinct store
+  deterministically (no LLM spawn): `list`, `export`, `import`, `promote-candidates`, and
+  `prune`.
+- **Instinct store schema** gains `project_id` (stable scoping) and a `source` field
+  (`auto-capture`/`manual`/`imported`/`observer`), with origin-weighted confidence —
+  auto-captured instincts start at `0.3`, manually added ones at `0.7`.
+- **Cost-routing shadow mode is now real.** Arbitrage steering respects
+  `cost_routing.shadow_mode` (default on); in observe-only mode, selections are returned as
+  `authoritative: false` and logged as SHADOW, so you can watch the router's
+  recommendations without it taking the wheel.
+
+### Shipped inert (no behavior change yet)
+
+These landed as scaffolding and are **not** wired into any live path — they do nothing
+until a follow-up enables them:
+
+- **Manifest-driven install resolver** (`install-manifests.js`) — profile-to-module
+  expansion and dependency detection are implemented, but the adapter into the installer's
+  live `install()` path is deferred.
+- **GAN-style harness personas** (`gan-evaluator`, `gan-generator`, `gan-planner`) — fully
+  scoped and documented, not yet attached to any command or workflow.
+- **Typed Inter-Agent Message Protocol** (`handoff-schema.js`) — an internal orchestration
+  primitive (five message kinds, four priority levels, validation) for upcoming
+  agent-handoff work.
+
+## v11.3.1 — Packaging hotfix
+
+**Release Date**: 2026-06-05
+**Type**: Patch (no API changes)
+**Upgrade Path**: `npm install -g mindforge-cc@latest` (or `npx mindforge-cc@latest`)
+
+Fixes a critical packaging regression in v11.3.0, where a too-narrow npm `files`
+allowlist silently dropped most of the product from the published tarball. Users who
+installed v11.3.0 received only hooks, personas, subagents, and three `.mindforge/`
+folders — **no slash commands, no skills, and an incomplete framework** — with no error,
+because the installer skips any source absent from the tarball.
+
+- **Restored payload** — every install now delivers all **174 slash commands**, **73 skills**,
+  **154 subagents**, the entry `CLAUDE.md`, and the full `.mindforge/` framework
+  (`governance`, `integrations`, `intelligence`, `memory`, `metrics`, `models`, `org`,
+  `plugins`, `team`). Runtime state (`celestial.db`, telemetry `.jsonl`) is explicitly excluded.
+- **`.planning/` scaffolding** now ships from a clean generic source (never the framework's
+  own dev state) so the autonomous engine has its templates.
+- **docs/References + docs/Templates** case-sensitivity fixed (worked on macOS, silently
+  missed on Linux/npm — they now install correctly).
+- **Regression test** (`tests/packaging-allowlist.test.js`) packs the real tarball and
+  asserts the full payload ships — proven to fail under the broken v11.3.0 allowlist.
+
+> v11.3.0 is deprecated on npm. Upgrade to v11.3.1.
+
+## v11.3.0 — "Legion" (154-subagent expansion)
+
+**Release Date**: 2026-06-04
+**Type**: Minor (additive, backward-compatible)
+
+Imports 154 specialized Claude-Code-native subagents across 10 categories
+(`01-core-development` … `10-research-analysis`) into `.claude/agents/`, fully rebranded
+and collision-safe (16 names that clashed with existing personas were suffixed `-cc`).
+Adds `bin/spawn-agent.js subagent <name>` with a hardened name allowlist and path-traversal
+guards, plus a generated `.mindforge/imported-agents.jsonl` index. No existing persona,
+skill, or command changed behavior.
+
+> Note: the v11.3.0 npm artifact was affected by the packaging regression fixed in v11.3.1.
+> Install v11.3.1 to get the subagents and the rest of the payload.
+
+---
+
+# v11.0.0 "Sovereign Stability"
 
 **Release Date**: 2026-05-28  
 **Type**: Major (breaking changes)  

package/SECURITY.md

@@ -108,6 +108,22 @@ Before submitting code that touches security-sensitive paths:
 
 ---
 
+## Agentic-Harness Threat Model
+
+This document covers application/code vulnerabilities. The **outward** harness threat
+model — prompt injection, poisoned project config / hooks / MCP, supply-chain risk in
+skills/agents, the lethal trifecta, sandboxing, and the autonomous-agent minimum-bar
+checklist — lives in **[MINDFORGE-AGENTIC-SECURITY.md](./MINDFORGE-AGENTIC-SECURITY.md)**.
+Both are required reading before running MindForge autonomously.
+
+Minimum bar (see that doc for detail): separate agent identities · short-lived scoped
+creds · sandbox untrusted work · deny egress by default · `permissions.deny` on
+secret-bearing paths · sanitize foreign content · human approval for shell/egress/deploy
+(TrustGate + Tier-3) · log tool calls (AUDIT.jsonl) · process-group kill + heartbeat ·
+narrow disposable memory · scan skills/hooks/MCP/agents as supply-chain artifacts.
+
+---
+
 ## Known Mitigations & Limitations
 
 - **ZK-proofs are simulated** — The Dilithium-5 / ZK-proof layer uses cryptographic simulation, not hardware-backed TEEs. It provides logical governance enforcement, not hardware-grade isolation.

package/bin/autonomous/auto-runner.js

@@ -687,12 +687,53 @@ class AutoRunner {
     fs.writeFileSync(this.statePath, JSON.stringify(state, null, 2));
   }
 
+  /**
+   * Lazily registers (once) the autonomous runner's own ZTAI identity and
+   * returns { did, tier }. ztai-manager is a SINGLETON (not a constructor) and
+   * exposes no getIdentity() — the runner must register a DID to obtain one.
+   * Cached on the instance so every wave evaluates under one stable identity.
+   * Tier 3: autonomous phase processing is a high-trust operation; the policy
+   * engine still runs its own blast-radius analysis on top, so this is an INPUT
+   * to evaluation, not a self-granted bypass.
+   */
+  async _getRunnerIdentity() {
+    if (!this._runnerIdentity) {
+      _ZTAIManager = lazyRequire(_ZTAIManager, '../governance/ztai-manager');
+      const did = await _ZTAIManager.registerAgent(
+        `auto-runner:${process.env.MF_PROJECT_ID || 'MF-ALPHA'}:phase-${this.phase}`,
+        3,
+        this._sessionId
+      );
+      const agent = _ZTAIManager.getAgent(did);
+      this._runnerIdentity = { did, tier: agent && typeof agent.tier === 'number' ? agent.tier : 3 };
+    }
+    return this._runnerIdentity;
+  }
+
   async evaluateWavePolicy() {
-    _ZTAIManager = lazyRequire(_ZTAIManager, '../governance/ztai-manager');
-    const manager = _ZTAIManager;
-    const identity = await manager.getIdentity();
-    const intent = { did: identity.did, action: 'process_phase_wave', resource: `projects/${process.env.MF_PROJECT_ID || 'MF-ALPHA'}/phases/${this.phase}/*`, tier: identity.tier || 1, metadata: { engine: 'Nimbus-S4', mode: 'autonomous', wave_timestamp: new Date().toISOString() } };
-    const result = this.policyEngine.evaluate(intent);
+    let identity;
+    try {
+      identity = await this._getRunnerIdentity();
+    } catch (err) {
+      // Fail CLOSED: if the runner cannot establish a verifiable identity, deny
+      // the wave rather than proceeding ungoverned.
+      console.warn(`[APO-DENY] Could not establish runner identity: ${err.message}`);
+      this.writeAudit({ event: 'auto_mode_denied', reason: `identity unavailable: ${err.message}`, phase: this.phase });
+      return false;
+    }
+
+    const intent = {
+      did: identity.did,
+      action: 'process_phase_wave',
+      resource: `projects/${process.env.MF_PROJECT_ID || 'MF-ALPHA'}/phases/${this.phase}/*`,
+      tier: identity.tier,
+      sessionId: this._sessionId,
+      metadata: { engine: 'Nimbus-S4', mode: 'autonomous', wave_timestamp: new Date().toISOString() }
+    };
+
+    // policyEngine.evaluate is ASYNC — must be awaited, or `result` is a Promise
+    // and `result.verdict === 'DENY'` is always false (the gate never fires).
+    const result = await this.policyEngine.evaluate(intent);
     if (result.verdict === 'DENY') { console.warn(`[APO-DENY] ${result.reason}`); return false; }
     return true;
   }

package/bin/autonomous/handoff-schema.js

@@ -0,0 +1,114 @@
+'use strict';
+
+/**
+ * MindForge — Typed inter-agent message protocol.
+ *
+ * Ports ECC's ecc2/src/comms/mod.rs MessageType + TaskPriority as a JSON-schema
+ * validator. Complements state-manager.js validateHandoff (which validates the
+ * HANDOFF.json envelope) by typing the individual messages agents exchange:
+ *
+ *   kinds:    task_handoff | query | response | completed | conflict
+ *   priority: low | normal | high | critical  (default normal; legacy fallback)
+ *
+ * The Conflict kind pairs with the worktree engine's merge-readiness output
+ * (bin/worktree/engine.js). This is discipline/typing, not new runtime behavior.
+ */
+
+const MESSAGE_KINDS = ['task_handoff', 'query', 'response', 'completed', 'conflict'];
+const PRIORITIES = ['low', 'normal', 'high', 'critical'];
+const DEFAULT_PRIORITY = 'normal';
+
+// Required fields per kind (mirrors ECC's MessageType variants).
+const REQUIRED_FIELDS = {
+  task_handoff: ['task', 'context'],
+  query: ['question'],
+  response: ['answer'],
+  completed: ['summary'],          // files_changed optional, defaults []
+  conflict: ['file', 'description'],
+};
+
+/**
+ * Validate a typed message object. Returns { valid, warnings }.
+ * Fail-open style (matches validateHandoff): collects warnings, never throws.
+ */
+function validateMessage(msg) {
+  const warnings = [];
+  if (!msg || typeof msg !== 'object' || Array.isArray(msg)) {
+    return { valid: false, warnings: ['message is not an object'] };
+  }
+  if (!MESSAGE_KINDS.includes(msg.kind)) {
+    warnings.push(`invalid kind: "${msg.kind}". Expected one of: ${MESSAGE_KINDS.join(', ')}`);
+    return { valid: false, warnings };
+  }
+  for (const field of REQUIRED_FIELDS[msg.kind]) {
+    if (typeof msg[field] !== 'string' || msg[field].length === 0) {
+      warnings.push(`${msg.kind} missing required string field: ${field}`);
+    }
+  }
+  if (msg.kind === 'completed' && msg.files_changed !== undefined && !Array.isArray(msg.files_changed)) {
+    warnings.push('completed.files_changed must be an array');
+  }
+  if (msg.kind === 'task_handoff' && msg.priority !== undefined && !PRIORITIES.includes(msg.priority)) {
+    warnings.push(`invalid priority: "${msg.priority}". Expected one of: ${PRIORITIES.join(', ')}`);
+  }
+  return { valid: warnings.length === 0, warnings };
+}
+
+/**
+ * Resolve a handoff message's priority, defaulting to "normal" and tolerating
+ * legacy entries that lack a typed priority (ECC's legacy fallback).
+ */
+function handoffPriority(msg) {
+  if (!msg || typeof msg !== 'object') return DEFAULT_PRIORITY;
+  const p = msg.priority;
+  return PRIORITIES.includes(p) ? p : DEFAULT_PRIORITY;
+}
+
+/**
+ * One-line human preview of a typed message (for status/log surfaces).
+ */
+function preview(msg) {
+  const trunc = (s, n) => {
+    const t = String(s || '').trim();
+    return t.length <= n ? t : `${t.slice(0, n - 1)}…`;
+  };
+  switch (msg && msg.kind) {
+    case 'task_handoff': {
+      const p = handoffPriority(msg);
+      return p === DEFAULT_PRIORITY
+        ? `handoff ${trunc(msg.task, 56)}`
+        : `handoff [${p}] ${trunc(msg.task, 48)}`;
+    }
+    case 'query': return `query ${trunc(msg.question, 56)}`;
+    case 'response': return `response ${trunc(msg.answer, 56)}`;
+    case 'completed': {
+      const n = Array.isArray(msg.files_changed) ? msg.files_changed.length : 0;
+      return n === 0 ? `completed ${trunc(msg.summary, 48)}` : `completed ${trunc(msg.summary, 40)} | ${n} files`;
+    }
+    case 'conflict': return `conflict ${msg.file} | ${trunc(msg.description, 40)}`;
+    default: return `unknown ${trunc(JSON.stringify(msg), 56)}`;
+  }
+}
+
+/**
+ * Build a well-formed message of a given kind (convenience + normalization).
+ * Throws if the result fails validation, so callers can't emit a bad message.
+ */
+function makeMessage(kind, fields = {}) {
+  const msg = Object.assign({ kind }, fields);
+  if (kind === 'task_handoff' && msg.priority === undefined) msg.priority = DEFAULT_PRIORITY;
+  if (kind === 'completed' && msg.files_changed === undefined) msg.files_changed = [];
+  const { valid, warnings } = validateMessage(msg);
+  if (!valid) throw new Error(`invalid ${kind} message: ${warnings.join('; ')}`);
+  return msg;
+}
+
+module.exports = {
+  MESSAGE_KINDS,
+  PRIORITIES,
+  DEFAULT_PRIORITY,
+  validateMessage,
+  handoffPriority,
+  preview,
+  makeMessage,
+};

package/bin/autonomous/session-guardian.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# session-guardian.sh — Autonomous-loop session guard (MindForge)
+# Exit 0 = proceed. Exit 1 = skip this loop cycle.
+# Called by any bin/autonomous loop (and the deferred background observer)
+# BEFORE spawning a model session, so the loop cannot burn tokens overnight,
+# AFK, or faster than its cooldown.
+#
+# Ported near-verbatim from ECC (continuous-learning-v2/agents/session-guardian.sh).
+# Env defaults map to a new instincts.observer config block (default-off posture):
+#   OBSERVER_INTERVAL_SECONDS    default: 300   (per-project cooldown)
+#   OBSERVER_LAST_RUN_LOG        default: ~/.mindforge/observer-last-run.log
+#   OBSERVER_ACTIVE_HOURS_START  default: 800   (8:00 AM local, 0 to disable)
+#   OBSERVER_ACTIVE_HOURS_END    default: 2300  (11:00 PM local, 0 to disable)
+#   OBSERVER_MAX_IDLE_SECONDS    default: 1800  (30 min; 0 to disable)
+#
+# Gate order (cheapest first):
+#   Gate 1: Time window check    (~0ms)
+#   Gate 2: Project cooldown log (~1ms, mkdir lock)
+#   Gate 3: Idle detection       (~5-50ms, OS syscall; fail open)
+
+set -euo pipefail
+
+INTERVAL="${OBSERVER_INTERVAL_SECONDS:-300}"
+LOG_PATH="${OBSERVER_LAST_RUN_LOG:-$HOME/.mindforge/observer-last-run.log}"
+ACTIVE_START="${OBSERVER_ACTIVE_HOURS_START:-800}"
+ACTIVE_END="${OBSERVER_ACTIVE_HOURS_END:-2300}"
+MAX_IDLE="${OBSERVER_MAX_IDLE_SECONDS:-1800}"
+
+# ── Gate 1: Time Window ───────────────────────────────────────────────────────
+if [ "$ACTIVE_START" -ne 0 ] || [ "$ACTIVE_END" -ne 0 ]; then
+  current_hhmm=$(date +%k%M | tr -d ' ')
+  current_hhmm_num=$(( 10#${current_hhmm:-0} ))
+  active_start_num=$(( 10#${ACTIVE_START:-800} ))
+  active_end_num=$(( 10#${ACTIVE_END:-2300} ))
+
+  within_active_hours=0
+  if [ "$active_start_num" -lt "$active_end_num" ]; then
+    if [ "$current_hhmm_num" -ge "$active_start_num" ] && [ "$current_hhmm_num" -lt "$active_end_num" ]; then
+      within_active_hours=1
+    fi
+  else
+    if [ "$current_hhmm_num" -ge "$active_start_num" ] || [ "$current_hhmm_num" -lt "$active_end_num" ]; then
+      within_active_hours=1
+    fi
+  fi
+
+  if [ "$within_active_hours" -ne 1 ]; then
+    echo "session-guardian: outside active hours (${current_hhmm}, window ${ACTIVE_START}-${ACTIVE_END})" >&2
+    exit 1
+  fi
+fi
+
+# ── Gate 2: Project Cooldown Log ─────────────────────────────────────────────
+project_root="${PROJECT_DIR:-}"
+if [ -z "$project_root" ] || [ ! -d "$project_root" ]; then
+  project_root="$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")"
+fi
+project_name="$(basename "$project_root")"
+now="$(date +%s)"
+
+mkdir -p "$(dirname "$LOG_PATH")" || {
+  echo "session-guardian: cannot create log dir, proceeding" >&2
+  exit 0
+}
+
+_lock_dir="${LOG_PATH}.lock"
+if ! mkdir "$_lock_dir" 2>/dev/null; then
+  echo "session-guardian: log locked by concurrent process, skipping cycle" >&2
+  exit 1
+else
+  trap 'rm -rf "$_lock_dir"' EXIT INT TERM
+
+  last_spawn=0
+  last_spawn=$(awk -F '\t' -v key="$project_root" '$1 == key { value = $2 } END { if (value != "") print value }' "$LOG_PATH" 2>/dev/null) || true
+  last_spawn="${last_spawn:-0}"
+  [[ "$last_spawn" =~ ^[0-9]+$ ]] || last_spawn=0
+
+  elapsed=$(( now - last_spawn ))
+  if [ "$elapsed" -lt "$INTERVAL" ]; then
+    rm -rf "$_lock_dir"
+    trap - EXIT INT TERM
+    echo "session-guardian: cooldown active for '${project_name}' (last spawn ${elapsed}s ago, interval ${INTERVAL}s)" >&2
+    exit 1
+  fi
+
+  tmp_log="$(mktemp "$(dirname "$LOG_PATH")/observer-last-run.XXXXXX")"
+  awk -F '\t' -v key="$project_root" '$1 != key' "$LOG_PATH" > "$tmp_log" 2>/dev/null || true
+  printf '%s\t%s\n' "$project_root" "$now" >> "$tmp_log"
+  mv "$tmp_log" "$LOG_PATH"
+
+  rm -rf "$_lock_dir"
+  trap - EXIT INT TERM
+fi
+
+# ── Gate 3: Idle Detection ────────────────────────────────────────────────────
+get_idle_seconds() {
+  local _raw
+  case "$(uname -s)" in
+    Darwin)
+      _raw=$( { /usr/sbin/ioreg -c IOHIDSystem \
+        | /usr/bin/awk '/HIDIdleTime/ {print int($NF/1000000000); exit}'; } \
+        2>/dev/null ) || true
+      printf '%s\n' "${_raw:-0}" | head -n1
+      ;;
+    Linux)
+      if command -v xprintidle >/dev/null 2>&1; then
+        _raw=$(xprintidle 2>/dev/null) || true
+        echo $(( ${_raw:-0} / 1000 ))
+      else
+        echo 0  # fail open: xprintidle not installed
+      fi
+      ;;
+    *MINGW*|*MSYS*|*CYGWIN*)
+      _raw=$(powershell.exe -NoProfile -NonInteractive -Command \
+        "try { \
+          Add-Type -MemberDefinition '[DllImport(\"user32.dll\")] public static extern bool GetLastInputInfo(ref LASTINPUTINFO p); [StructLayout(LayoutKind.Sequential)] public struct LASTINPUTINFO { public uint cbSize; public int dwTime; }' -Name WinAPI -Namespace PInvoke; \
+          \$l = New-Object PInvoke.WinAPI+LASTINPUTINFO; \$l.cbSize = 8; \
+          [PInvoke.WinAPI]::GetLastInputInfo([ref]\$l) | Out-Null; \
+          [int][Math]::Max(0, [long]([Environment]::TickCount - [long]\$l.dwTime) / 1000) \
+        } catch { 0 }" \
+        2>/dev/null | tr -d '\r') || true
+      printf '%s\n' "${_raw:-0}" | head -n1
+      ;;
+    *)
+      echo 0  # fail open: unknown platform
+      ;;
+  esac
+}
+
+if [ "$MAX_IDLE" -gt 0 ]; then
+  idle_seconds=$(get_idle_seconds)
+  if [ "$idle_seconds" -gt "$MAX_IDLE" ]; then
+    echo "session-guardian: user idle ${idle_seconds}s (threshold ${MAX_IDLE}s), skipping" >&2
+    exit 1
+  fi
+fi
+
+exit 0