mindforge-cc 11.4.0 → 11.5.1

package/CHANGELOG.md

@@ -1,5 +1,125 @@
 # Changelog
 
+## [11.5.1] - 2026-06-11 — Robustness + governance-gate patch (Wave 8)
+
+A fast-follow patch from a fresh adversarial audit of the shipped v11.5.0 tree.
+Hardens crash-prone JSON parsing in the autonomous/memory pipelines, closes a
+CI governance-gate gap, and tightens two security surfaces. No new features.
+
+### Fixed
+
+- **Crash-proof AUDIT.jsonl parsing** (`bin/memory/pillar-health-tracker.js`) —
+  `summarizePhase()` parsed every audit line with an unguarded `JSON.parse`, so a
+  single malformed/torn line crashed the knowledge-capture pipeline. Now parses
+  per-line in try/catch and skips bad lines.
+- **Crash-proof compaction capture** (`bin/memory/knowledge-capture.js`) — a
+  malformed `handoff.json` no longer throws out of `captureFromCompaction()`; it
+  logs and returns `[]`, mirroring the missing-file path.
+- **Resilient federated-sync stats** (`bin/memory/federated-sync.js`) — the two
+  unguarded `JSON.parse` calls on `sync-stats.json` (`handleSyncFailure`,
+  `resetFailures`) now fall back to `{failures:0}` on corruption, matching the
+  sibling `getLastSyncTimestamp` pattern.
+
+### Security
+
+- **CI Tier-3 governance gate now validates content** (`.github/workflows/control-plane.yml`)
+  — the gate counted approval files but never checked them; it now requires at
+  least one approval with `identity_verification.verified === true` and a
+  signature, and rejects any unverified/empty file. Completes the Wave-6
+  fail-closed `approve.js` work (a hand-committed empty approval no longer passes).
+- **Dashboard approval attribution** (`bin/dashboard/api-router.js`) —
+  `POST /api/approve/:id` no longer records the client-supplied `approver`
+  (forgeable audit identity); it attributes the action to a fixed authenticated
+  actor. The dashboard remains localhost-bound + token-gated.
+- **Destructive-command detector blocks Unix `truncate`** (`bin/security/trust-boundaries.js`)
+  — the SQL-only `truncate table` pattern missed `truncate -s 0 <path>` (in-place
+  file zeroing). Added a size-flag pattern so it is gated; benign uses stay allowed.
+- **CI Tier-3 gate accepts an explicitly-acknowledged unverified approval**
+  (`.github/workflows/control-plane.yml`, `bin/governance/approve.js`) — since this
+  repo has no GPG signing infra, the gate accepts an approval that is either
+  GPG-verified OR an opted-in `unverified_ack` record (`approve.js` under
+  `MINDFORGE_ALLOW_UNVERIFIED_APPROVAL=1`), while still rejecting bare/stale
+  `verified:false` files. Replaced the stale v11.4.0 approval with a fresh one.
+- **`uuid` dependency removed from `ads-engine`** (`bin/review/ads-engine.js`) — it
+  required the uninstalled `uuid` package, making `ads-engine` and (transitively)
+  `federated-sync` un-loadable in a clean install. Swapped to the built-in
+  `crypto.randomUUID()` (zero-native-deps); both modules now load.
+
+## [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

package/MINDFORGE.md

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

package/README.md

@@ -501,4 +501,3 @@ MindForge never stores credentials in files. Review:
 
 ## ⚖️ License
 MIT © 2026 MindForge Team
-eam

package/RELEASENOTES.md

@@ -1,5 +1,136 @@
 # Release Notes
 
+## v11.5.1 — Robustness + governance-gate patch
+
+**Release Date**: 2026-06-11
+**Type**: Patch (no API changes; one CI-gate behavior change)
+**Upgrade Path**: `npx mindforge-cc@latest`
+
+A fast-follow patch driven by a fresh adversarial audit of the shipped v11.5.0
+tree. It hardens crash-prone JSON parsing in the autonomous/memory pipelines,
+closes a governance-gate gap left by the v11.5.0 approval work, and tightens two
+security surfaces. No features, no API changes.
+
+### Robustness — no more crashes on a torn JSONL line
+
+Three pipelines parsed JSON without guards, so one malformed/partially-written
+line could crash them:
+
+- `summarizePhase()` (pillar-health) parsed every `AUDIT.jsonl` line unguarded —
+  it now skips bad lines and keeps the valid ones.
+- `captureFromCompaction()` (knowledge-capture) now returns `[]` on a malformed
+  `handoff.json` instead of throwing.
+- `federated-sync` now tolerates a corrupted `sync-stats.json` in both
+  `handleSyncFailure` and `resetFailures` (falls back to `{failures:0}`).
+
+### Security & governance
+
+- **The CI Tier-3 gate now actually validates approvals.** Previously it only
+  counted approval files; a hand-committed empty file would pass. It now requires
+  each approval to carry a signature and be EITHER GPG-verified
+  (`verified: true`) OR an explicitly opted-in unverified approval
+  (`unverified_ack`, minted by `approve.js` under
+  `MINDFORGE_ALLOW_UNVERIFIED_APPROVAL=1` for repos without GPG infra). Bare or
+  stale `verified:false` files are still rejected — completing the v11.5.0
+  fail-closed `approve.js` work.
+- **Dashboard approvals can't forge an identity.** `POST /api/approve/:id` no
+  longer records a client-supplied `approver` into the audit trail; it attributes
+  the action to a fixed authenticated actor. (The dashboard is already
+  localhost-bound and Bearer-token gated, so this is attribution hardening.)
+- **The destructive-command guard now blocks Unix `truncate -s`.** In-place file
+  zeroing (`truncate -s 0 <path>`) was missed by the SQL-only pattern; it is now
+  gated, with benign uses unaffected.
+- **A shipped module that couldn't load is fixed.** `bin/review/ads-engine.js`
+  required the uninstalled `uuid` package — so it (and the `federated-sync` that
+  imports it) threw on load in a clean install. Swapped to the built-in
+  `crypto.randomUUID()`; no new dependency.
+
+## 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

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