mindforge-cc 11.0.0 → 11.2.1

package/bin/security/trust-boundaries.js

@@ -0,0 +1,194 @@
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * Recursively sorts object keys for deterministic JSON serialization.
+ * Arrays are preserved in order; nested objects get sorted keys.
+ */
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return '[' + value.map(item => stableStringify(item)).join(',') + ']';
+  }
+  const sortedKeys = Object.keys(value).sort();
+  const pairs = sortedKeys.map(key => {
+    return JSON.stringify(key) + ':' + stableStringify(value[key]);
+  });
+  return '{' + pairs.join(',') + '}';
+}
+
+/**
+ * Computes SHA-256 hash of a manifest using stable key-sorted serialization.
+ * Returns { name, hash, pinnedAt }.
+ */
+function pinManifest(manifest) {
+  const serialized = stableStringify(manifest);
+  const hash = crypto.createHash('sha256').update(serialized).digest('hex');
+  return {
+    name: manifest.name,
+    hash,
+    pinnedAt: Date.now()
+  };
+}
+
+/**
+ * Verifies a manifest against a previously pinned hash.
+ * Returns { valid: true } or { valid: false, reason }.
+ */
+function verifyManifest(manifest, pin) {
+  const serialized = stableStringify(manifest);
+  const computed = crypto.createHash('sha256').update(serialized).digest('hex');
+  if (computed === pin.hash) {
+    return { valid: true };
+  }
+  return {
+    valid: false,
+    reason: `hash mismatch: expected ${pin.hash}, got ${computed}`
+  };
+}
+
+/**
+ * Wraps content with untrusted provenance metadata.
+ * Returns { content, trusted: false, provenance: { source, tool, timestamp } }.
+ */
+function tagUntrusted(content, meta) {
+  return {
+    content,
+    trusted: false,
+    provenance: {
+      source: meta.source,
+      tool: meta.tool,
+      timestamp: Date.now()
+    }
+  };
+}
+
+// Null byte (char code 0). Built via fromCharCode so we never embed a control
+// character in a regex literal (eslint no-control-regex).
+const NUL = String.fromCharCode(0);
+
+// ${IFS} / $IFS are shell-internal field separators that expand to whitespace.
+// Attackers use them to avoid literal spaces between a destructive token and
+// its flags (rm${IFS}-rf${IFS}/). We normalize them back to a space so the
+// existing rm/-rf patterns catch the de-obfuscated form (audit #8).
+const IFS_TOKEN = /\$\{IFS\}|\$IFS/g;
+
+/**
+ * De-obfuscates shell metacharacter tricks WITHOUT emulating a real shell.
+ * Strips quotes (' ") and backslash escapes, collapses ${IFS}/$IFS to a space,
+ * then collapses runs of whitespace. This turns r''m, r"m, r\m and
+ * rm${IFS}-rf${IFS}/ back into plain `rm -rf /` so the existing patterns fire.
+ * Intentionally conservative: it removes characters rather than interpreting
+ * them, which can only make a string MORE likely to match (fail-toward-block).
+ */
+function normalizeShell(input) {
+  return input
+    .split(NUL).join('')          // shells ignore NUL; never let it split a token
+    .replace(IFS_TOKEN, ' ')       // ${IFS}/$IFS -> space
+    .replace(/[\\'"]/g, '')        // drop backslash escapes and quote chars
+    .replace(/\s+/g, ' ');         // collapse whitespace runs
+}
+
+/**
+ * Detects high-impact / destructive commands via case-insensitive pattern matching.
+ * Returns true if the command matches known destructive patterns.
+ *
+ * The detector errs toward blocking by design: this feeds a PreToolUse gate
+ * where approval friction is strictly preferable to a destructive bypass.
+ */
+function isHighImpact(command) {
+  // Normalize first so metacharacter-obfuscated commands (audit #8) are matched
+  // by the SAME pattern set as their plain-text equivalents.
+  const sanitized = normalizeShell(String(command));
+  const patterns = [
+    // ── Original allowlist (unchanged) ──────────────────────────────────────
+    /rm\s+(-\w*r\w*\s+-\w*f|(-\w*f\w*\s+-\w*r)|-\w*rf|-\w*fr)/i,
+    /git\s+push\s+.*--force/i,
+    /git\s+push\s+.*-f/i,
+    /drop\s+(table|database)/i,
+    /git\s+reset\s+--hard/i,
+    /delete\s+from/i,
+    /truncate\s+table/i,
+    /\bmkfs(\.\w+)?\s+\/dev\//i,
+    // #11: any dd write target, not just /dev/ (dd if=... of=important.db).
+    // Original /dev/-only check is a subset of this, so it stays covered.
+    /\bdd\b.*\bof=/i,
+    /\b(curl|wget)\b.*\|\s*(bash|sh|zsh)\b/i,
+    /^\s*find\s+.*-delete\b/i,
+
+    // ── #4 Command/process substitution RCE ─────────────────────────────────
+    // `eval` anywhere is high-impact (dynamic code execution).
+    /\beval\b/i,
+    // Command substitution $(...) or backtick combined with a network fetch.
+    /\$\(\s*(curl|wget)\b/i,
+    new RegExp(String.fromCharCode(96) + '\\s*(curl|wget)\\b', 'i'),
+    // Process substitution feeding an interpreter: bash <(...), sh <(...).
+    /\b(bash|sh|zsh)\b.*<\(/i,
+    // Curl/wget directly inside a process substitution.
+    /<\(\s*(curl|wget)\b/i,
+
+    // ── #5 Interpreter invocation of a script file ──────────────────────────
+    // source <file> and `. <file>` are unambiguous script execution.
+    /\bsource\s+\S+/i,
+    /(^|[;&|]|\s)\.\s+\S+\.\w+/i,
+    // bash/sh/zsh running a .sh script — clearly script execution. Kept broad
+    // (any .sh) because shelling out to an arbitrary shell script is itself a
+    // strong execution signal; this also covers untrusted paths like
+    // `bash /tmp/x.sh`.
+    /\b(bash|sh|zsh)\s+\S*\.sh\b/i,
+    // node/python/etc. running a script — narrowed (UC-22). Running a project
+    // file is THE default safe action in a Node/Python repo, so a blanket
+    // `node <file>.js` match is a terrible signal-to-noise ratio and blocked
+    // the project's OWN idiom (`node tests/run-all.js`). We now flag ONLY when
+    // the script path looks UNTRUSTED — an absolute path (/...), a writable
+    // temp dir (/tmp, /var/tmp, /dev/shm), or a home-relative path (~/...) —
+    // i.e. the write-then-execute attack chain (drop payload in a writable
+    // location, then run it). Project-relative paths (tests/run-all.js,
+    // bin/foo.js, scripts/build.py, index.js) are NOT matched. Piped/
+    // substituted execution (curl | bash, $(...), <(...), backticks) is
+    // already covered by the #4 patterns above.
+    /\b(node|python3?|ruby|perl)\s+(~\/|\/)\S*\.(js|mjs|cjs|ts|py|rb|pl)\b/i,
+
+    // ── #7 Redirect-overwrite of critical files / devices ───────────────────
+    // > or >> targeting an absolute sensitive path (/etc/, /dev/, /boot/, /sys/,
+    // /proc/, /var/, /usr/, /bin/, /sbin/, /lib/). Project-local redirects
+    // (> out.log) are NOT matched.
+    />>?\s*\/(etc|dev|boot|sys|proc|var|usr|bin|sbin|lib|root|lib64)\//i,
+
+    // ── #8 handled by normalizeShell() above (de-obfuscation), no pattern here.
+
+    // ── #9 chmod dangerous modes ────────────────────────────────────────────
+    // Canonical dangerous octal modes only: 000 (full lockout) and the
+    // world-writable 666/777 family. Common safe modes (644/755/600/700/640)
+    // and symbolic modes (chmod +x build.sh) are intentionally NOT matched.
+    // ANY recursive chmod is also treated as high-impact regardless of mode.
+    /\bchmod\b.*\b(000|0?666|0?777)\b/i,
+    /\bchmod\s+-\w*[rR]/i,
+
+    // ── #10 chown recursive ─────────────────────────────────────────────────
+    /\bchown\s+-\w*[rR]/i,
+
+    // ── #12 mv of root / into /dev/null ─────────────────────────────────────
+    /\bmv\b.*\/dev\/null\b/i,
+    /\bmv\s+(-\w+\s+)?\/\s/i,
+
+    // ── #13 Process killers ─────────────────────────────────────────────────
+    /\bkill\s+-9\s+-1\b/i,
+    /\bkillall\b/i,
+    /\bpkill\b/i,
+
+    // ── #14 Power-state commands ────────────────────────────────────────────
+    /\b(shutdown|reboot|halt|poweroff)\b/i,
+  ];
+  return patterns.some(pattern => pattern.test(sanitized));
+}
+
+module.exports = {
+  pinManifest,
+  verifyManifest,
+  tagUntrusted,
+  isHighImpact
+};

package/bin/security/trust-gate-hook.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+'use strict';
+
+const { isHighImpact } = require('./trust-boundaries');
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const event = JSON.parse(input);
+
+    // Only gate Bash tool calls
+    if (event.tool_name !== 'Bash') {
+      process.exit(0); // allow
+    }
+
+    const fullCommand = event.tool_input?.command || '';
+
+    // Check the whole command AND every individual line, blocking if ANY
+    // segment is high-impact. Per-line scanning means a benign first line
+    // cannot cloak a destructive command on a later line; the whole-string
+    // check catches patterns a line split might fragment. This is a security
+    // gate, so it errs toward blocking: a destructive keyword in (e.g.) a
+    // commit message will prompt for approval rather than risk a cloaked
+    // command slipping through. Approval friction is preferable to a bypass.
+    const lines = fullCommand.split('\n');
+    const offending = [fullCommand, ...lines].find((segment) => isHighImpact(segment));
+
+    if (offending) {
+      const display = offending.length > 80 ? offending.slice(0, 80) + '...' : offending;
+      // Output a block reason (Claude Code shows this to the user)
+      process.stdout.write(JSON.stringify({
+        decision: 'block',
+        reason: `[TrustGate] High-impact command detected: "${display}" — requires explicit user approval`
+      }));
+      process.exit(2); // block
+    }
+
+    process.exit(0); // allow
+  } catch (e) {
+    process.stderr.write('[trust-gate-hook] parse error (BLOCKING): ' + e.message + '\n');
+    process.stdout.write(JSON.stringify({
+      decision: 'block',
+      reason: '[TrustGate] Could not verify command safety — parse error'
+    }));
+    process.exit(2);
+  }
+});

package/bin/skill-registry.js

@@ -124,31 +124,42 @@ function handleInstall() {
   if (tier === '1') targetBase = '.mindforge/skills';
   if (tier === '3') targetBase = '.mindforge/project-skills';
 
+  // Resolve a real local source for the skill. There is no remote registry
+  // backend, so the ONLY honest sources are an examples/ entry or a SKILL.md in
+  // the current working directory (the agentic authoring flow).
+  const exampleSrc = path.join(process.cwd(), 'examples', 'skills', `${skillName}.md`);
+  const localSrc = path.join(process.cwd(), 'SKILL.md');
+
+  let source = null;
+  if (fs.existsSync(exampleSrc)) {
+    source = exampleSrc;
+  } else if (fs.existsSync(localSrc)) {
+    source = localSrc;
+  }
+
+  if (!source) {
+    // HONEST REFUSAL (UC-22): no local source and no remote registry is
+    // configured. Do NOT write a placeholder file that masquerades as an
+    // installed skill — that would falsely report success. Refuse clearly and
+    // exit non-zero so callers can detect the failure.
+    console.error(
+      `❌ Skill '${skillName}' not found locally and no remote registry is configured — nothing installed.`
+    );
+    console.error(
+      '   Provide a source first: place a SKILL.md in the current directory ' +
+      `or add examples/skills/${skillName}.md, then re-run.`
+    );
+    process.exit(1);
+  }
+
+  // Real source found → perform the actual install.
   const targetDir = path.join(process.cwd(), targetBase, skillName);
   if (!fs.existsSync(targetDir)) {
     fs.mkdirSync(targetDir, { recursive: true });
   }
-
-  // Mock behavior for Day 3/4 testing if no real registry
-  // Expect source to be in examples/ if it exists, otherwise just touch it
-  const mockSrc = path.join(process.cwd(), 'examples', 'skills', `${skillName}.md`);
   const targetFile = path.join(targetDir, 'SKILL.md');
-
-  if (fs.existsSync(mockSrc)) {
-    fs.copyFileSync(mockSrc, targetFile);
-    console.log(`  ✅ Copied from ${mockSrc}`);
-  } else {
-    // If no source, we look for it in the current dir for the agentic flow
-    const localSrc = path.join(process.cwd(), 'SKILL.md');
-    if (fs.existsSync(localSrc)) {
-       fs.copyFileSync(localSrc, targetFile);
-       console.log('  ✅ Copied from local SKILL.md');
-    } else {
-       // Just create a placeholder for testing if nothing else
-       fs.writeFileSync(targetFile, `---\nname: ${skillName}\nversion: 1.0.0\nstatus: alpha\ntriggers: test, mock, placeholder\n---\n# ${skillName}\nPlaceholder for ${skillName} skill.\n`);
-       console.log('  ⚠️  Created mock SKILL.md (no source found)');
-    }
-  }
+  fs.copyFileSync(source, targetFile);
+  console.log(`  ✅ Installed ${skillName} from ${path.relative(process.cwd(), source)}`);
 
   process.exit(0);
 }
@@ -215,7 +226,6 @@ function handleAudit() {
   }
 
   const entry = {
-    timestamp: new Date().toISOString(),
     event: 'skill_installed',
     skill_name: skillName,
     skill_version: version,
@@ -224,7 +234,9 @@ function handleAudit() {
     validation_passed: true
   };
 
-  fs.appendFileSync(auditPath, JSON.stringify(entry) + '\n', 'utf8');
+  // UC-04b: unified, hash-chained, durable append into the single verifiable chain.
+  const { appendAuditEntrySync } = require('./autonomous/audit-writer');
+  appendAuditEntrySync(auditPath, entry);
   console.log(`  📝 Audit entry written for ${skillName}`);
   process.exit(0);
 }

package/bin/skills-builder/marketplace-cli.js

@@ -19,7 +19,7 @@ if (!CMD) {
 async function main() {
   try {
     switch (CMD) {
-      case 'search':
+      case 'search': {
         const results = await Marketplace.search(QUERY);
         console.table(results.map(r => ({
           name: r.name,
@@ -28,12 +28,14 @@ async function main() {
           description: r.description.slice(0, 50) + '...'
         })));
         break;
-        
+      }
+
       case 'featured':
-      case 'trending':
+      case 'trending': {
         const list = await Marketplace.getFeatured();
         console.table(list);
         break;
+      }
         
       case 'install':
         if (!QUERY) throw new Error('Package name required for install');

package/bin/skills-builder/skill-registrar.js

@@ -82,11 +82,10 @@ function register(params) {
     );
   }
 
-  // Write AUDIT entry
+  // Write AUDIT entry via the unified, hash-chained, durable append (UC-04b).
   if (fs.existsSync(path.dirname(AUDIT_PATH))) {
-    const entry = {
-      id:            require('crypto').randomBytes(8).toString('hex'),
-      timestamp:     new Date().toISOString(),
+    const { appendAuditEntrySync } = require('../autonomous/audit-writer');
+    appendAuditEntrySync(AUDIT_PATH, {
       event:         'skill_learned',
       agent:         'mindforge-skills-builder',
       phase:         null,
@@ -97,8 +96,7 @@ function register(params) {
       source_type:   sourceType,
       source:        String(source).slice(0, 200),
       skill_path:    relativePath,
-    };
-    fs.appendFileSync(AUDIT_PATH, JSON.stringify(entry) + '\n');
+    });
   }
 
   return { registered: true, skillName, tier, qualityScore };

package/bin/sre/sentinel.js

@@ -109,13 +109,15 @@ class Sentinel {
   }
 
   logToAudit(event, targetPath) {
-    const logEntry = {
-      id: crypto.randomBytes(8).toString('hex'),
-      timestamp: new Date().toISOString(),
+    // UC-04b: route through the unified, hash-chained, durable append so Sentinel's
+    // incident entries link into the single verifiable chain (was a raw appendFileSync
+    // that broke the chain). appendAuditEntrySync caches the chain head per resolved
+    // path, so an explicit targetPath is chained correctly too.
+    const { appendAuditEntrySync } = require('../autonomous/audit-writer');
+    appendAuditEntrySync(targetPath || this.auditPath, {
       agent: 'mindforge-sentinel',
       ...event
-    };
-    fs.appendFileSync(targetPath || this.auditPath, JSON.stringify(logEntry) + '\n');
+    });
   }
 
   stop() {

package/bin/sre/shadow-mirror.js

@@ -1,13 +1,28 @@
 /**
  * MindForge v9.0.0 — Temporal Shadow Mirror (Pillar XXI)
- * Hybrid isolation for incident replication.
+ *
+ * Incident replication via git-worktree isolation.
+ *
+ * ISOLATION HONESTY (audit finding #24 / UC-22):
+ * This module provides GIT WORKTREE isolation only — a separate working tree
+ * and branch off the current repo. It does NOT provide container/Docker
+ * isolation (no separate kernel, network, filesystem, or process namespaces).
+ * A `docker --version` probe gates an "enhanced" path, but that path still runs
+ * in a git worktree; real Docker orchestration (build/run/mount) is a
+ * NOT-YET-IMPLEMENTED future enhancement. The returned mirror is always a
+ * worktree, and `activeMirror.isolation` reports the actual level provided.
  */
 'use strict';
 
-const { execSync } = require('node:child_process');
+const { execSync, execFileSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
-const crypto = require('node:crypto');
+
+// remediation_id flows from the SRE sentinel (a trust boundary) into git
+// branch/worktree names. Only allow a safe identifier charset and reject
+// anything that could be read as a flag or shell metacharacter. Defence in
+// depth on top of execFileSync (argv array, no shell). Fail-closed.
+const SAFE_REMEDIATION_ID = /^[A-Za-z0-9._-]+$/;
 
 class ShadowMirror {
   constructor(options = {}) {
@@ -15,32 +30,58 @@ class ShadowMirror {
     this.activeMirror = null;
   }
 
+  /**
+   * Validates a remediation_id (trust-boundary input) before it is used to
+   * build git branch/worktree names. Fail-closed: throws on missing, empty,
+   * overlong, flag-like, or metacharacter-bearing ids. Returns the id on pass.
+   * Static so it can be unit-tested in isolation.
+   */
+  static sanitizeRemediationId(id) {
+    if (typeof id !== 'string' || id.length === 0 || id.length > 128) {
+      throw new Error('[ShadowMirror] invalid remediation_id: must be a non-empty string of <=128 chars');
+    }
+    if (id.startsWith('-')) {
+      throw new Error('[ShadowMirror] invalid remediation_id: must not start with "-"');
+    }
+    if (!SAFE_REMEDIATION_ID.test(id)) {
+      throw new Error('[ShadowMirror] invalid remediation_id: only [A-Za-z0-9._-] characters allowed');
+    }
+    return id;
+  }
+
   /**
    * Orchestrates replication based on incident severity and requirements.
    */
   async replicate(incident) {
     console.log(`🌀 Shadow Mirror: Replicating incident [${incident.remediation_id}]...`);
-    
-    // Choose isolation level
-    const level = (incident.details?.severity === 'CRITICAL') ? 2 : 1;
-    
-    if (level === 2 && this.isDockerAvailable()) {
-      return this.replicateLevel2(incident);
-    } else {
-      return this.replicateLevel1(incident);
+
+    // All replication currently runs in a git worktree (see file header).
+    // For CRITICAL incidents where a Docker toolchain is present we note that a
+    // future container-isolation path could be used, but we DO NOT claim to run
+    // it — we still replicate in a worktree and label it honestly.
+    const wantsContainer = incident.details?.severity === 'CRITICAL' && this.isDockerAvailable();
+
+    if (wantsContainer) {
+      return this.replicateCriticalWorktree(incident);
     }
+    return this.replicateLevel1(incident);
   }
 
   /**
    * Level 1 Replication: Git Worktree
-   * High-speed, lightweight logic isolation.
+   * High-speed, lightweight logic isolation (NOT container isolation).
+   *
+   * Provides a separate working tree + branch off the current repo. This
+   * isolates source/logic changes; it shares the host kernel, network,
+   * filesystem and process namespaces with the running engine.
    */
   async replicateLevel1(incident) {
-    const mirrorId = `mirror-${incident.remediation_id}`;
+    const remediationId = ShadowMirror.sanitizeRemediationId(incident.remediation_id);
+    const mirrorId = `mirror-${remediationId}`;
     const mirrorPath = path.join(this.baseDir, mirrorId);
-    const branchName = `sre-repro-${incident.remediation_id}`;
+    const branchName = `sre-repro-${remediationId}`;
 
-    console.log(`[Level 1] Creating git worktree at ${mirrorPath}...`);
+    console.log(`[worktree] Creating git worktree at ${mirrorPath}...`);
 
     try {
       if (!fs.existsSync(this.baseDir)) {
@@ -49,41 +90,46 @@ class ShadowMirror {
 
       // 1. Create a reproduction branch and add worktree in one step (Atomic)
       // In a real system, we'd base this on the commit hash from the trace_id
-      execSync(`git worktree add -b ${branchName} ${mirrorPath}`, { stdio: 'ignore' });
-      
-      this.activeMirror = { path: mirrorPath, branch: branchName, type: 'worktree' };
+      // execFileSync with an argv array — no shell, so branchName/mirrorPath
+      // cannot inject commands even if they somehow contained metacharacters.
+      execFileSync('git', ['worktree', 'add', '-b', branchName, mirrorPath], { stdio: 'ignore' });
+
+      this.activeMirror = {
+        path: mirrorPath,
+        branch: branchName,
+        type: 'worktree-isolation',
+        // Honest disclosure of the isolation actually provided.
+        isolation: 'git-worktree',
+      };
 
       // 3. Inject incident metadata for the agent to use
       fs.writeFileSync(path.join(mirrorPath, 'REPLICATION.json'), JSON.stringify(incident, null, 2));
 
       return mirrorPath;
     } catch (err) {
-      console.error(`[ShadowMirror] Level 1 replication failed: ${err.message}`);
+      console.error(`[ShadowMirror] worktree replication failed: ${err.message}`);
       throw err;
     }
   }
 
   /**
-   * Level 2 Replication: Docker Sandbox
-   * Full environment isolation for state-bound incidents.
+   * CRITICAL-incident replication when a Docker toolchain is detected.
+   *
+   * HONESTY: This still replicates in a GIT WORKTREE. It does not build or run
+   * a container, does not mount any volume, and does not provide container
+   * isolation. Real Docker sandboxing (build/run/mount) is a NOT-YET-IMPLEMENTED
+   * enhancement tracked separately; until it lands, this path is identical in
+   * isolation guarantees to {@link replicateLevel1} and is labelled as such.
    */
-  async replicateLevel2(incident) {
-    console.log('[Level 2] Initializing Docker sandbox interface...');
-    // For the hackathon demo, we'll scaffold the Docker-ready worktree which would then be mounted
+  async replicateCriticalWorktree(incident) {
+    console.log('[worktree] CRITICAL incident: replicating in git worktree (container isolation not implemented).');
     const mirrorPath = await this.replicateLevel1(incident);
-    
-    const dockerfile = `
-FROM node:18-slim
-WORKDIR /app
-COPY . .
-RUN npm install --production
-CMD ["node", "bin/engine/logic-validator.js"]
-    `;
-    
-    fs.writeFileSync(path.join(mirrorPath, 'Dockerfile.sre'), dockerfile);
-    console.log(`[Level 2] Dockerfile.sre generated at ${mirrorPath}. Mounting volume for isolation.`);
-    
-    this.activeMirror.type = 'docker-hybrid';
+
+    // Note the unimplemented future path without claiming it ran.
+    this.activeMirror.dockerAvailable = true;
+    this.activeMirror.note =
+      'docker binary detected; real container isolation is a future enhancement — this mirror used git-worktree isolation only';
+
     return mirrorPath;
   }
 
@@ -104,9 +150,13 @@ CMD ["node", "bin/engine/logic-validator.js"]
 
     console.log(`🧹 Cleaning up Shadow Mirror: ${this.activeMirror.path}...`);
     try {
-      if (this.activeMirror.type === 'worktree' || this.activeMirror.type === 'docker-hybrid') {
-        execSync(`git worktree remove ${this.activeMirror.path} --force`, { stdio: 'ignore' });
-        execSync(`git branch -D ${this.activeMirror.branch}`, { stdio: 'ignore' });
+      // Every mirror this module produces is a git worktree (see replicate()).
+      // Accept the legacy 'worktree'/'docker-hybrid' labels for backward compat
+      // in case an older serialized mirror is handed in.
+      const worktreeTypes = ['worktree-isolation', 'worktree', 'docker-hybrid'];
+      if (worktreeTypes.includes(this.activeMirror.type)) {
+        execFileSync('git', ['worktree', 'remove', this.activeMirror.path, '--force'], { stdio: 'ignore' });
+        execFileSync('git', ['branch', '-D', this.activeMirror.branch], { stdio: 'ignore' });
         // Clean up the folder just in case
         if (fs.existsSync(this.activeMirror.path)) {
           fs.rmSync(this.activeMirror.path, { recursive: true });

package/bin/utils/append-queue.js

@@ -0,0 +1,67 @@
+'use strict';
+/**
+ * MindForge — Single-writer serialized append queue (UC-09).
+ * Guarantees: (1) appends to a given file are serialized (no interleaving across
+ * concurrent callers in this process), (2) each append() resolves only after the
+ * bytes are fsync'd to disk (durability), (3) a trailing newline delimits records.
+ *
+ * Scope: protects against in-process concurrent-write interleaving and crash-loss
+ * of acknowledged writes. Cross-PROCESS locking is out of scope for the
+ * single-operator localhost model (documented; revisit if multi-process writers appear).
+ */
+const fs = require('fs');
+
+// path -> Promise chain tail. NOTE: this is intended for a small, fixed set of
+// known paths (e.g. AUDIT.jsonl). Per-path entries are NEVER evicted, so do NOT
+// key this by high-cardinality dynamic paths — doing so would leak memory
+// unboundedly. Revisit with an LRU/eviction policy if dynamic paths are needed.
+const queues = new Map();
+
+/**
+ * @deprecated No production caller. The real durable-append path is
+ * `appendDurableSync` in `bin/memory/knowledge-store.js` (synchronous
+ * openSync+writeSync+fsyncSync+closeSync), which all audit/KB write sites use.
+ * This async single-writer queue is retained only as a tested reference
+ * implementation for the in-process serialized-append pattern (UC-09) and is
+ * exercised solely by `tests/append-queue.test.js`. Do NOT wire it into new
+ * code without first reconciling it with the canonical sync path.
+ *
+ * @param {string} filePath — file to serialize appends for
+ * @returns {{append: (line: string) => Promise<void>, drain: () => Promise<void>}}
+ */
+function createAppendQueue(filePath) {
+  if (!queues.has(filePath)) queues.set(filePath, Promise.resolve());
+
+  function append(line) {
+    const record = line.endsWith('\n') ? line : line + '\n';
+    const tail = queues.get(filePath).then(() => writeDurable(filePath, record));
+    queues.set(filePath, tail.catch(() => {}));
+    return tail;
+  }
+
+  function drain() {
+    return queues.get(filePath);
+  }
+
+  return Object.freeze({ append, drain });
+}
+
+function writeDurable(filePath, data) {
+  return new Promise((resolve, reject) => {
+    fs.open(filePath, 'a', (openErr, fd) => {
+      if (openErr) return reject(openErr);
+      fs.write(fd, data, (writeErr) => {
+        if (writeErr) { fs.close(fd, () => {}); return reject(writeErr); }
+        fs.fsync(fd, (syncErr) => {
+          fs.close(fd, (closeErr) => {
+            if (syncErr) return reject(syncErr);
+            if (closeErr) return reject(closeErr);
+            resolve();
+          });
+        });
+      });
+    });
+  });
+}
+
+module.exports = { createAppendQueue };