mindforge-cc 11.0.0 → 11.2.1

package/bin/autonomous/auto-runner.js

@@ -19,7 +19,7 @@ const progressStream = require('./progress-stream');
 const ContextRefactorer = require('./context-refactorer');
 
 // Extracted modules (lightweight, always needed)
-const { createAuditWriter } = require('./audit-writer');
+const { appendAuditEntrySync } = require('./audit-writer');
 const { createStateManager } = require('./state-manager');
 const { createWaveExecutor, Semaphore } = require('./wave-executor');
 
@@ -44,6 +44,68 @@ function lazyRequire(cached, modulePath) {
   return cached;
 }
 
+/**
+ * UC-14: Pure timeout predicate evaluated at wave boundaries.
+ *
+ * Three cases:
+ *   1. falsy `timeoutAt` (null / undefined / '') → NO timeout is configured →
+ *      false. Autonomous mode never times out in that case.
+ *   2. truthy but UNPARSEABLE deadline (`Date.parse` → NaN, e.g. 'garbage') → a
+ *      MALFORMED deadline. We FAIL CLOSED: warn to stderr AND return true (treat
+ *      as expired). For a stability/bounding feature, a broken deadline silently
+ *      never firing would let a run proceed UNBOUNDED — the wrong direction. A
+ *      malformed deadline must be VISIBLE and must HALT, not silently fail open.
+ *   3. valid date → `now > parsed` (timed out once `now` strictly exceeds it).
+ *
+ * `Date.now()` is the sane default for a RUNTIME comparison (unlike the council
+ * UC, which avoided `Date.now()` only for deterministic/resumable FILENAMES — a
+ * wall-clock read here is exactly what a timeout check wants). Callers inside the
+ * run-loop should still pass an explicit `now` for testability/consistency within
+ * a single iteration.
+ *
+ * NOTE: this is otherwise a PURE function (used directly in tests). The only
+ * side-effect is the diagnostic stderr write on the malformed branch — never on
+ * the falsy or valid-date paths — so existing pure assertions are unaffected.
+ *
+ * @param {string|null|undefined} timeoutAt — ISO-8601 deadline, or falsy for "no timeout"
+ * @param {number} [now=Date.now()] — Epoch ms to compare against
+ * @returns {boolean} true iff a deadline is set AND it has passed (or is malformed)
+ */
+function isTimedOut(timeoutAt, now = Date.now()) {
+  if (!timeoutAt) return false;
+  const parsed = Date.parse(timeoutAt);
+  if (Number.isNaN(parsed)) {
+    // Malformed deadline → fail CLOSED (visible + halt), never silently fail open.
+    process.stderr.write(`[auto-runner] malformed timeout_at "${timeoutAt}" — treating as expired to fail closed\n`);
+    return true;
+  }
+  return now > parsed;
+}
+
+/**
+ * UC-14: Pure decision for the opt-in terminal-ESCALATE rollback hook.
+ *
+ * SAFE BY DEFAULT: rollback-on-escalate is opt-in via
+ * `wave_execution.rollback_on_escalate` (default false). Even when enabled, an
+ * actual destructive `git reset` is gated on the runner tracking per-wave commit
+ * SHAs — which it does NOT today. So `gitReset` is always false until commit
+ * tracking exists; we only ever RECORD the rollback point.
+ *
+ * @param {object} config — Parsed .mindforge/config.json (or {})
+ * @param {boolean} [hasCommitTracking=false] — Whether per-wave commit SHAs are tracked
+ * @returns {{ record: boolean, gitReset: boolean, reason: string }}
+ */
+function decideRollback(config, hasCommitTracking = false) {
+  const enabled = config?.wave_execution?.rollback_on_escalate === true;
+  if (!enabled) {
+    return { record: true, gitReset: false, reason: 'rollback_on_escalate disabled (default) — recording intent only' };
+  }
+  if (!hasCommitTracking) {
+    return { record: true, gitReset: false, reason: 'rollback_on_escalate enabled but per-wave commit tracking unavailable — recording intent only, actual git reset deferred' };
+  }
+  return { record: true, gitReset: true, reason: 'rollback_on_escalate enabled and commit tracking available' };
+}
+
 class AutoRunner {
   constructor(options = {}) {
     if (options.phase != null && !/^[a-zA-Z0-9_-]+$/.test(String(options.phase))) {
@@ -61,7 +123,6 @@ class AutoRunner {
 
     // Extracted module instances
     this.stateManager = createStateManager(planningDir);
-    this.auditWriter = createAuditWriter(this.auditPath);
     this.waveExecutor = createWaveExecutor({
       onTaskStart: ({ task, wave }) => this.writeAudit({ event: 'task_started', phase: this.phase, wave: wave + 1, task_id: task.id, task_name: task.name }),
       onTaskComplete: ({ task, wave, duration_ms }) => this.writeAudit({ event: 'task_completed', phase: this.phase, wave: wave + 1, task_id: task.id, task_name: task.name, duration_ms }),
@@ -173,6 +234,10 @@ class AutoRunner {
 
     while (await this.hasNextWave()) {
       if (this.isPaused) break;
+      // UC-14: enforce the wave-boundary timeout BEFORE dispatching this wave.
+      // Re-read auto-state each iteration so an externally-updated timeout_at is
+      // honored; stop cleanly (status 'timeout' + resumable state) when passed.
+      if (this._enforceWaveTimeout()) return;
       const permit = await this.evaluateWavePolicy();
       if (!permit) { this.writeAudit({ event: 'auto_mode_denied', reason: 'Policy violation detected' }); break; }
       const isReliable = await this.checkArbitrage();
@@ -188,10 +253,77 @@ class AutoRunner {
     await this.complete();
   }
 
+  /**
+   * UC-14: Wave-boundary timeout enforcement.
+   *
+   * Re-reads the current `timeout_at` from auto-state.json (V9 design field) and,
+   * if the deadline has passed, stops the run CLEANLY:
+   *   1. persists resumable state (currentWaveIndex + completedTasks) so a later
+   *      `/mindforge:auto` resumes exactly where it left off,
+   *   2. sets status to 'timeout' (a VALID_STATUS), keeping the resumable fields,
+   *   3. writes an `auto_mode_timeout` audit event,
+   *   4. logs the resume command and returns true so the caller stops the loop.
+   *
+   * Returns false (no-op) when no timeout is set or the deadline hasn't passed.
+   * @returns {boolean} true iff the run timed out and the loop should stop
+   */
+  _enforceWaveTimeout() {
+    const autoState = this.stateManager.getState();
+    if (!isTimedOut(autoState.timeout_at)) return false;
+
+    const waveNum = this.currentWaveIndex + 1;
+
+    // 1 + 2: persist resumable progress AND flip status to 'timeout' in one write.
+    this.updateState({
+      status: 'timeout',
+      currentWaveIndex: this.currentWaveIndex,
+      completedTasks: Array.from(this.completedTasks),
+      timedOutAt: new Date().toISOString(),
+    });
+
+    // 3: audit the clean stop.
+    this.writeAudit({
+      event: 'auto_mode_timeout',
+      phase: this.phase,
+      wave: waveNum,
+      timeout_at: autoState.timeout_at,
+      completed_tasks: this.completedTasks.size,
+      timestamp: new Date().toISOString(),
+    });
+
+    // 4: clear operator-facing message including the resume command.
+    console.warn(
+      `\n⏲️  TIMEOUT at wave boundary ${waveNum}/${this.waves.length} ` +
+      `(deadline ${autoState.timeout_at}). Stopped cleanly with ${this.completedTasks.size} task(s) completed.\n` +
+      `   Resume with: /mindforge:auto --phase ${this.phase}`
+    );
+    return true;
+  }
+
   runPreFlight() {
     console.log('🔍 Running pre-flight checks...');
+
+    // UC-01: fail closed on version drift before any wave executes
+    try {
+      const { assertVersionConsistency } = require('../utils/version-check');
+      assertVersionConsistency(process.cwd());
+    } catch (e) {
+      throw new Error(`[pre-flight] ${e.message}`);
+    }
+
     const handoff = this.stateManager.readHandoff();
-    this.waves = this._buildWaves(handoff.handoffs);
+
+    // FIX 3.2: read config ONCE for the whole pre-flight path and thread the
+    // resolved useDag boolean into both _assertNoCycles and _buildWaves, instead
+    // of each method re-reading + re-parsing .mindforge/config.json.
+    const useDag = this._useDagMode();
+
+    // UC-03: when DAG ordering is enabled (opt-in via config), detect cycles
+    // BEFORE any wave executes and HALT LOUD. Default OFF — legacy behavior
+    // (single-wave / explicit .wave grouping) is untouched.
+    this._assertNoCycles(handoff.handoffs, useDag);
+
+    this.waves = this._buildWaves(handoff.handoffs, useDag);
     this.currentWaveIndex = 0;
 
     const savedState = this.stateManager.getState();
@@ -253,6 +385,9 @@ class AutoRunner {
         const strategy = repairOperator.determineRepairStrategy({ planId: task.plan || taskId, phase: this.phase, attemptNumber: 1, errorOutput: error.message, isTier3Change: false, isOnCriticalPath: (task.depends_on || []).length > 0 });
         if (strategy === 'ESCALATE') {
           this.writeAudit({ event: 'auto_mode_escalated', reason: `Task ${taskId} unrecoverable` });
+          // UC-14: opt-in rollback hook on terminal ESCALATE. SAFE DEFAULT —
+          // records the rollback point only; never mutates git (see decideRollback).
+          this._recordRollbackPoint(waveNum, taskId);
           this.isPaused = true;
           return;
         }
@@ -277,12 +412,158 @@ class AutoRunner {
     return 3;
   }
 
+  /**
+   * UC-14: Rollback-on-escalate is OPT-IN. Reads
+   * `wave_execution.rollback_on_escalate` from config; defaults to false so the
+   * SAFE behavior (record rollback intent only — NO git mutation) is the default.
+   * Even when true, an actual git reset is further gated on per-wave commit
+   * tracking, which the runner does not yet have (see decideRollback).
+   * @returns {boolean}
+   */
+  _rollbackOnEscalate() {
+    try {
+      const configPath = path.join(process.cwd(), '.mindforge', 'config.json');
+      if (fs.existsSync(configPath)) {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        return config.wave_execution?.rollback_on_escalate === true;
+      }
+    } catch (e) { /* Fall through to default */ }
+    return false;
+  }
+
+  /**
+   * UC-14: Records the rollback point on terminal ESCALATE WITHOUT mutating git.
+   *
+   * The runner does NOT track per-wave commit SHAs, so even with
+   * `rollback_on_escalate` enabled the actual `git reset --hard` is deferred —
+   * we never run a destructive reset against untracked commit boundaries. We
+   * emit a `rollback_point_recorded` audit event (and a clear log) recording the
+   * intended rollback wave so a human can act on it.
+   *
+   * @param {number} waveNum — 1-based wave number that hit terminal escalation
+   * @param {string} taskId — The task id whose repair was exhausted
+   */
+  _recordRollbackPoint(waveNum, taskId) {
+    const config = (() => {
+      try {
+        const configPath = path.join(process.cwd(), '.mindforge', 'config.json');
+        if (fs.existsSync(configPath)) return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      } catch (e) { /* ignore — treat as no config */ }
+      return {};
+    })();
+
+    // hasCommitTracking is hard-false: no per-wave SHA tracking exists yet.
+    const decision = decideRollback(config, /* hasCommitTracking */ false);
+
+    // DRY: derive the flag from the `config` we ALREADY read above instead of
+    // calling _rollbackOnEscalate(), which would re-read + re-parse the SAME
+    // config.json a second time within this single escalation path.
+    const rollbackEnabled = config?.wave_execution?.rollback_on_escalate === true;
+
+    this.writeAudit({
+      event: 'rollback_point_recorded',
+      phase: this.phase,
+      wave: waveNum,
+      task_id: taskId,
+      commits: [], // none tracked yet — rollback target is the prior wave boundary
+      git_reset_performed: decision.gitReset,
+      reason: decision.reason,
+      timestamp: new Date().toISOString(),
+    });
+    console.warn(`↩️  ROLLBACK POINT recorded at wave ${waveNum} (task ${taskId}): ${decision.reason}`);
+    if (rollbackEnabled && !decision.gitReset) {
+      console.warn('   (rollback_on_escalate is ON, but actual git reset is deferred until per-wave commit tracking exists.)');
+    }
+    return decision;
+  }
+
+  /**
+   * UC-03: DAG wave ordering is OPT-IN. Reads `wave_execution.use_dag` from
+   * config; defaults to false so legacy single-wave / explicit-.wave behavior
+   * is untouched. Enabling this reorders tasks by `depends_on` topology.
+   * @returns {boolean}
+   */
+  _useDagMode() {
+    try {
+      const configPath = path.join(process.cwd(), '.mindforge', 'config.json');
+      if (fs.existsSync(configPath)) {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        return config.wave_execution?.use_dag === true;
+      }
+    } catch (e) { /* Fall through to default */ }
+    return false;
+  }
+
+  /**
+   * UC-03: Pre-flight cycle detection. ONLY active when DAG mode is enabled
+   * (opt-in) AND no explicit numeric `.wave` field is present (DAG would be the
+   * active strategy). Throws `[pre-flight] Circular dependency...` to HALT LOUD
+   * before any wave executes — never warn-and-continue. No-op when DAG is off.
+   *
+   * FIX 1: the pre-flight graph must NOT differ from the graph planWaves
+   * actually executes. planWaves builds its graph from normalizeTask, which
+   * SYNTHESIZES a random id (`task_<rand>`) for any handoff lacking both id and
+   * task_id. A random id can't be matched between two separate calls, AND a task
+   * with no stable id can never be a `depends_on` TARGET (nothing can reference
+   * an id that doesn't exist until it's randomly minted). So we cycle-check the
+   * SUBSET of handoffs that carry a real, stable id (id || task_id) — a subset
+   * guaranteed consistent with execution — and log a warning for any id-less
+   * handoff excluded from the check.
+   *
+   * @param {Array} handoffs — Raw handoffs array from HANDOFF.json
+   * @param {boolean} [useDag] — Resolved DAG mode (threaded from runPreFlight to
+   *   avoid re-reading config). Falls back to _useDagMode() for direct callers.
+   */
+  _assertNoCycles(handoffs, useDag = this._useDagMode()) {
+    if (!Array.isArray(handoffs) || handoffs.length === 0) return;
+    if (!useDag) return;
+
+    // Explicit .wave field wins over DAG, so cycle check is irrelevant there.
+    const hasWaveField = handoffs.some(h => typeof h.wave === 'number');
+    if (hasWaveField) return;
+
+    // Only handoffs with a STABLE id participate in cycle-checking (see above).
+    const stable = handoffs.filter(h => h.id || h.task_id);
+    const idless = handoffs.length - stable.length;
+    if (idless > 0) {
+      console.warn(
+        `[pre-flight] ${idless} handoff(s) lack a stable id (id/task_id) and are ` +
+        'excluded from cycle-checking; an id-less task cannot be a dependency target.'
+      );
+    }
+    if (stable.length === 0) return;
+
+    const { buildGraph, groupIntoWaves } = require('./dependency-dag');
+    let graph;
+    try {
+      graph = buildGraph(stable.map(h => ({
+        id: h.id || h.task_id,
+        depends_on: Array.isArray(h.depends_on) ? h.depends_on : [],
+      })));
+    } catch (e) {
+      // Unknown-dependency reference — also a planning error; fail loud.
+      throw new Error(`[pre-flight] ${e.message}`);
+    }
+    // FIX 3.1: hasCircularDependency() is itself `try{groupIntoWaves}catch`, so
+    // running it then groupIntoWaves again ran Kahn 2-3 times and left an
+    // unreachable defensive throw. Run Kahn ONCE here; on throw, rethrow with the
+    // descriptive (circular OR unknown-dep) message prefixed for pre-flight.
+    try {
+      groupIntoWaves(graph);
+    } catch (e) {
+      throw new Error(`[pre-flight] ${e.message}`);
+    }
+  }
+
   /**
    * Build wave groups from HANDOFF handoffs array.
    * Kept as instance method for backward compatibility with tests.
+   * @param {Array} handoffs — Raw handoffs array from HANDOFF.json
+   * @param {boolean} [useDag] — Resolved DAG mode (threaded from runPreFlight).
+   *   Falls back to _useDagMode() for direct callers (e.g. tests).
    */
-  _buildWaves(handoffs) {
-    return this.waveExecutor.planWaves(handoffs);
+  _buildWaves(handoffs, useDag = this._useDagMode()) {
+    return this.waveExecutor.planWaves(handoffs, { useDag });
   }
 
   async checkIntelligenceDrift() {
@@ -359,27 +640,23 @@ class AutoRunner {
     } catch (e) { /* GC failure is non-critical */ }
 
     this.writeAudit({ event: 'auto_mode_completed', timestamp: new Date().toISOString() });
-    await this.auditWriter.close();
   }
 
   writeAudit(event) {
-    const crypto = require('crypto');
-    if (!event.id) event = Object.assign({}, event, { id: crypto.randomBytes(8).toString('hex') });
-    if (!event.timestamp) event = Object.assign({}, event, { timestamp: new Date().toISOString() });
-
-    // Synchronous write for backward compat (monitor needs immediate data)
-    fs.appendFileSync(this.auditPath, JSON.stringify(event) + '\n');
-
-    // Also buffer in async writer for future async consumers
-    this.auditWriter.write(event);
+    // UC-04b: single unified, hash-chained, synchronous-DURABLE append. The sync
+    // fsync'd write means in-process consumers (StuckMonitor reads the event
+    // object directly below; any file re-readers see it immediately) get durable
+    // data at once — replacing the old dual raw-appendFileSync + async-buffer write
+    // that left the live AUDIT.jsonl chain unverifiable.
+    const stamped = appendAuditEntrySync(this.auditPath, event);
 
     const STATE_CHANGING_EVENTS = ['auto_mode_started', 'phase_planned', 'phase_execution_started', 'task_completed', 'hindsight_injected', 'auto_mode_completed'];
-    if (STATE_CHANGING_EVENTS.includes(event.event)) {
+    if (STATE_CHANGING_EVENTS.includes(stamped.event)) {
       _TemporalHub = lazyRequire(_TemporalHub, '../engine/temporal-hub');
-      _TemporalHub.captureState(event.id, { agent: event.agent || 'auto-runner', event: event.event, phase: this.phase }).catch(() => {});
+      _TemporalHub.captureState(stamped.id, { agent: stamped.agent || 'auto-runner', event: stamped.event, phase: this.phase }).catch(() => {});
     }
 
-    const result = this.monitor.analyze(event);
+    const result = this.monitor.analyze(stamped);
     if (result) this.handleStuck(result);
   }
 
@@ -412,7 +689,7 @@ class AutoRunner {
 
   async evaluateWavePolicy() {
     _ZTAIManager = lazyRequire(_ZTAIManager, '../governance/ztai-manager');
-    const manager = new _ZTAIManager();
+    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);
@@ -504,4 +781,12 @@ class AutoRunner {
   }
 }
 
+// Primary export remains the AutoRunner class (back-compat with all callers/tests
+// that do `const AutoRunner = require('./auto-runner')`). UC-14 pure helpers are
+// attached as named properties so `require('./auto-runner').isTimedOut` works too.
+AutoRunner.isTimedOut = isTimedOut;
+AutoRunner.decideRollback = decideRollback;
+
 module.exports = AutoRunner;
+module.exports.isTimedOut = isTimedOut;
+module.exports.decideRollback = decideRollback;

package/bin/autonomous/dependency-dag.js

@@ -0,0 +1,59 @@
+'use strict';
+/**
+ * MindForge — Dependency DAG (UC-03).
+ * Kahn topological sort + cycle detection.
+ * Ported from the previously test-only implementation into the real engine.
+ *
+ * TODO(UC-xx): same-wave file-conflict detection once tasks carry file lists.
+ *   Handoff tasks (see normalizeTask in wave-executor.js and validateHandoff in
+ *   state-manager.js) currently expose only id/name/plan/depends_on — there is
+ *   no `files` field to compare. A `findFileConflicts(plans)` check (two tasks
+ *   in the SAME wave writing the same file -> warn) cannot be wired meaningfully
+ *   until the handoff schema captures per-task file lists, so it is intentionally
+ *   not implemented here rather than left as dead exported surface.
+ */
+function groupIntoWaves(graph) {
+  // Self-defense: every dependency target must be a known graph node. Throw a
+  // DISTINCT "unknown dependency" error (not the misleading "Circular" message)
+  // so callers that invoke groupIntoWaves standalone still fail descriptively.
+  for (const id of Object.keys(graph)) {
+    const deps = graph[id].dependsOn || [];
+    for (const d of deps) {
+      if (!(d in graph)) {
+        throw new Error(`Unknown dependency "${d}" referenced by "${id}"`);
+      }
+    }
+  }
+  const remaining = new Set(Object.keys(graph));
+  const completed = new Set();
+  const waves = [];
+  while (remaining.size > 0) {
+    const wave = [];
+    for (const id of remaining) {
+      const deps = graph[id].dependsOn || [];
+      if (deps.every(d => completed.has(d))) wave.push(id);
+    }
+    if (wave.length === 0 && remaining.size > 0) {
+      throw new Error(`Circular dependency detected among: ${[...remaining].join(', ')}`);
+    }
+    waves.push(wave.sort());
+    wave.forEach(id => { completed.add(id); remaining.delete(id); });
+  }
+  return waves;
+}
+function hasCircularDependency(graph) {
+  try { groupIntoWaves(graph); return false; } catch { return true; }
+}
+function buildGraph(tasks) {
+  const ids = new Set(tasks.map(t => t.id));
+  const graph = {};
+  for (const t of tasks) {
+    const deps = Array.isArray(t.depends_on) ? t.depends_on : [];
+    for (const d of deps) {
+      if (!ids.has(d)) throw new Error(`Task "${t.id}" depends on unknown task "${d}"`);
+    }
+    graph[t.id] = { dependsOn: deps };
+  }
+  return graph;
+}
+module.exports = { groupIntoWaves, hasCircularDependency, buildGraph };

package/bin/autonomous/mesh-self-healer.js

@@ -1,10 +1,18 @@
 /**
  * MindForge v7 — Proactive Semantic Homing (Pillar XII)
  * Mesh Self-Healer: Peer agents "home in" on drifting nodes to provide collaborative reasoning.
+ *
+ * UC-22 (audit finding #16) — HONEST LABELLING:
+ * There is no live, runtime peer-reasoning mesh in this build. Previously this
+ * module FABRICATED a collective consensus (hardcoded peers, canned
+ * confidence:94, "100% agreement" log). That emitted false assurance on the
+ * live auto-runner self-heal path. It now consults the ONLY real peer source
+ * available — the ztai-manager session-agent registry — and, when that yields
+ * no real peers (the common case at runtime), degrades GRACEFULLY to a clearly
+ * labelled single-source advisory with NO fabricated confidence or consensus.
  */
 'use strict';
 
-const fs = require('node:fs');
 const path = require('node:path');
 
 class MeshSelfHealer {
@@ -14,52 +22,117 @@ class MeshSelfHealer {
 
   /**
    * Peer agents "home in" on a node with high logic drift.
+   *
+   * @param {string} driftingAgentDid - DID of the drifting node.
+   * @param {number} driftScore - Logic-drift score (only acts on >= 80).
+   * @param {object} [options] - { sessionId } to scope the real peer lookup.
+   * @returns {Promise<object|null>} Honest advisory object, or null below threshold.
    */
-  async homeIn(driftingAgentDid, driftScore) {
+  async homeIn(driftingAgentDid, driftScore, options = {}) {
     if (driftScore < 80) return null; // Only home in on major drift
-    
-    console.log(`[HOMING-HEAL] Global Mesh Alert: Agent ${driftingAgentDid} experiencing critical logic drift (${driftScore}). Peer agents redirecting...`);
-    
-    // Find nearby idle agents or specialists
-    const peers = this.findAvailablePeers(driftingAgentDid);
-    const healingNodes = [];
 
+    console.log(`[HOMING-HEAL] Global Mesh Alert: Agent ${driftingAgentDid} experiencing critical logic drift (${driftScore}). Seeking peer reasoning support...`);
+
+    // Consult the only REAL peer source: the ztai-manager session registry.
+    // Returns an empty array when no live peers are registered.
+    const peers = this.findAvailablePeers(driftingAgentDid, options.sessionId);
+
+    if (peers.length === 0) {
+      return this.degradedAdvisory(driftingAgentDid);
+    }
+
+    const healingNodes = [];
     for (const peer of peers) {
-      console.log(`[HOMING-HEAL] Agent ${peer.did} homing in on ${driftingAgentDid} to provide collective reasoning support.`);
+      console.log(`[HOMING-HEAL] Peer ${peer.did} homing in on ${driftingAgentDid} to provide reasoning support.`);
       const supportTrace = await this.provideCollectiveReasoning(peer, driftingAgentDid);
       healingNodes.push(supportTrace);
     }
 
-    return this.reconcileReasoning(healingNodes);
+    return this.reconcileReasoning(healingNodes, driftingAgentDid);
+  }
+
+  /**
+   * Discovers REAL peer agents from the live registry. There are no invented
+   * peers — if nothing is registered for the session, this returns []
+   * and the caller degrades honestly.
+   *
+   * @param {string} driftingAgentDid - The node being healed (excluded from peers).
+   * @param {string|null} sessionId - Session scope for the registry lookup.
+   * @returns {Array<{did:string, persona?:string}>} Real peers (possibly empty).
+   */
+  findAvailablePeers(driftingAgentDid, sessionId = null) {
+    let agents = [];
+    try {
+      // Lazy require to avoid a hard coupling / load cost on the cold path.
+      const ztaiManager = require('../governance/ztai-manager');
+      if (typeof ztaiManager.getSessionAgents === 'function') {
+        agents = ztaiManager.getSessionAgents(sessionId) || [];
+      }
+    } catch {
+      // No registry available — treat as no live peers (honest degraded mode).
+      agents = [];
+    }
+
+    // Exclude the drifting node itself; only real, distinct peers may help.
+    return agents.filter(a => a && a.did && a.did !== driftingAgentDid);
   }
 
-  findAvailablePeers(driftingAgentDid) {
-    // Simulated peer discovery
-    return [
-      { did: 'did:mindforge:peer-1-specialist', name: 'Refactor Specialist' },
-      { did: 'did:mindforge:peer-2-architect', name: 'Security Architect' }
-    ];
+  /**
+   * Honest single-source advisory used when no live peer mesh is available.
+   * Carries NO fabricated confidence and makes NO consensus claim.
+   *
+   * @param {string} driftingAgentDid
+   * @returns {object}
+   */
+  degradedAdvisory(driftingAgentDid) {
+    console.log('[HOMING-HEAL] No live peer mesh available — emitting single-source advisory (degraded).');
+
+    return {
+      type: 'advisory',
+      mesh_available: false,
+      degraded: true,
+      confidence: null,
+      consensus: null,
+      target: driftingAgentDid,
+      recommendation: 'Heuristic single-source steering: pause the drifting node, re-anchor to the last verified plan/spec, and require human or higher-tier review before resuming. No multi-agent consensus was available to corroborate this.',
+      source: 'Mesh-Self-Healing (degraded: no live peers)'
+    };
   }
 
   async provideCollectiveReasoning(peer, target) {
-    // Peer agent provides a second opinion/reasoning node
+    // A real peer contributes a reasoning node. Confidence is left null here:
+    // this build has no model-backed scoring, so we do not invent a number.
     return {
       provider: peer.did,
-      target: target,
-      reasoning: 'Recommended steering for drift recovery based on Mesh-State: Re-syncing with Sovereign-Reason-Enclave.',
-      confidence: 94
+      target,
+      reasoning: 'Peer steering note: re-sync drifting node with the last verified plan state.',
+      confidence: null
     };
   }
 
-  reconcileReasoning(nodes) {
-    // Merge peer reasoning nodes into a single corrective steering vector
-    const consensus = nodes[0].reasoning; // Mock consensus
-    console.log('[HOMING-HEAL] Collective reasoning consensus acheived: 100% agreement on recovery vector.');
-    
+  /**
+   * Reconciles multiple REAL peer reasoning nodes. With live peers present we
+   * report how many corroborated, but we still never invent a confidence score
+   * or a "100% agreement" claim.
+   *
+   * @param {Array<object>} nodes - Real peer reasoning contributions.
+   * @param {string} driftingAgentDid
+   * @returns {object}
+   */
+  reconcileReasoning(nodes, driftingAgentDid) {
+    const peerCount = nodes.length;
+    console.log(`[HOMING-HEAL] Collective reasoning gathered from ${peerCount} live peer(s); no confidence fabricated.`);
+
     return {
-      type: 'collective_repair',
-      consensus,
-      source: 'Mesh-Self-Healing'
+      type: 'advisory',
+      mesh_available: true,
+      degraded: false,
+      confidence: null, // No model-backed scoring in this build — stay honest.
+      consensus: nodes[0].reasoning,
+      peer_count: peerCount,
+      target: driftingAgentDid,
+      recommendation: nodes[0].reasoning,
+      source: `Mesh-Self-Healing (${peerCount} live peer(s))`
     };
   }
 }

package/bin/autonomous/wave-executor.js

@@ -6,6 +6,7 @@
 'use strict';
 
 const crypto = require('crypto');
+const { buildGraph, groupIntoWaves } = require('./dependency-dag');
 
 /**
  * Semaphore for bounding concurrency within a wave.
@@ -64,10 +65,19 @@ function createWaveExecutor(config = {}) {
   /**
    * Groups handoff tasks into sequential waves based on wave field or dependency topology.
    * Returns a new array of wave objects — does not mutate input.
+   *
+   * Resolution order (UC-03):
+   *   1. Explicit numeric `.wave` field ALWAYS wins (legacy behavior, unchanged).
+   *   2. Else if `options.useDag === true` (OPT-IN), order by `depends_on` via Kahn
+   *      topological sort. Halts loud (throws) on cycles or unknown dependencies.
+   *   3. Else (legacy default), all tasks in a single parallel wave (unchanged).
+   *
+   * DAG ordering is OPT-IN to avoid silently reordering existing PLAN files.
    * @param {Array} handoffs — Raw handoffs array from HANDOFF.json
+   * @param {object} [options] — { useDag?: boolean }
    * @returns {Array<{ wave: number, tasks: Array }>}
    */
-  function planWaves(handoffs) {
+  function planWaves(handoffs, options = {}) {
     if (!Array.isArray(handoffs) || handoffs.length === 0) {
       waves = [];
       return [];
@@ -86,6 +96,15 @@ function createWaveExecutor(config = {}) {
       waves = Array.from(byWave.entries())
         .sort((a, b) => a[0] - b[0])
         .map(([waveNum, tasks]) => Object.freeze({ wave: waveNum, tasks: Object.freeze(tasks) }));
+    } else if (options.useDag === true) {
+      const normalized = handoffs.map(normalizeTask);
+      const graph = buildGraph(normalized);
+      const waveIds = groupIntoWaves(graph);
+      const byId = new Map(normalized.map(t => [t.id, t]));
+      waves = waveIds.map((ids, i) => Object.freeze({
+        wave: i,
+        tasks: Object.freeze(ids.map(id => byId.get(id))),
+      }));
     } else {
       // Single wave with all tasks
       waves = [Object.freeze({