@ijfw/memory-server 1.3.0 → 1.4.0

package/src/recovery/checkpoint.js

@@ -0,0 +1,191 @@
+// Workflow memory safety net.
+//
+// Checkpoints are durable, project-local markdown + JSON snapshots. They are
+// not a replacement for IJFW memory, but they make recovery possible when chat
+// context or a generated memory summary goes missing.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { writeAtomic } from '../lib/atomic-io.js';
+import { appendBlackboardEvent, blackboardStatus, readBlackboard } from '../blackboard.js';
+import { readTeamAssembly } from '../team/generator.js';
+import { buildSwarmPlan } from '../swarm/planner.js';
+
+export function checkpointPaths(projectRoot = process.cwd()) {
+  const root = resolve(projectRoot);
+  const dir = join(root, '.ijfw', 'checkpoints');
+  return { root, dir, latest: join(dir, 'latest.json') };
+}
+
+export function createCheckpoint(projectRoot = process.cwd(), label = 'checkpoint', options = {}) {
+  const paths = checkpointPaths(projectRoot);
+  mkdirSync(paths.dir, { recursive: true, mode: 0o700 });
+  const ts = new Date().toISOString();
+  const safeLabel = safeName(label);
+  const id = `${ts.replace(/[:.]/g, '-')}-${safeLabel}`;
+  const jsonPath = join(paths.dir, `${id}.json`);
+  const mdPath = join(paths.dir, `${id}.md`);
+  const snapshot = buildSnapshot(projectRoot, { id, label, ts, message: options.message });
+
+  writeAtomic(jsonPath, `${JSON.stringify(snapshot, null, 2)}\n`, { mode: 0o600 });
+  writeAtomic(mdPath, renderCheckpoint(snapshot), { mode: 0o600 });
+  writeAtomic(paths.latest, `${JSON.stringify({ id, label, ts, jsonPath, mdPath }, null, 2)}\n`, { mode: 0o600 });
+  appendBlackboardEvent(projectRoot, {
+    type: 'checkpoint.created',
+    actor: options.actor || 'ijfw',
+    message: label,
+    data: { id, jsonPath, mdPath },
+  });
+  return { ok: true, id, label, jsonPath, mdPath, snapshot };
+}
+
+export function recoveryStatus(projectRoot = process.cwd()) {
+  const paths = checkpointPaths(projectRoot);
+  const blackboard = readBlackboard(projectRoot);
+  const team = readTeamAssembly(projectRoot);
+  const plan = buildSwarmPlan(projectRoot);
+  const tasks = blackboard.tasks.data.tasks || [];
+  const latest = readLatest(paths.latest);
+  return {
+    ok: true,
+    latest,
+    team: {
+      ok: team.ok,
+      name: team.charter?.team_name || null,
+    },
+    swarm: plan.ok ? {
+      ok: true,
+      summary: plan.summary,
+    } : {
+      ok: false,
+      message: plan.message,
+    },
+    tasks: summarizeTasks(tasks),
+    claims: blackboardStatus(projectRoot).claims,
+    recent: {
+      events: blackboard.recent.events,
+      blockers: blackboard.recent.blockers,
+      decisions: blackboard.recent.decisions,
+    },
+    next: recommendedNext(team, plan, tasks),
+  };
+}
+
+export function latestCheckpoint(projectRoot = process.cwd()) {
+  const paths = checkpointPaths(projectRoot);
+  const latest = readLatest(paths.latest);
+  if (!latest) return { ok: false, error: 'no-checkpoint' };
+  let markdown = '';
+  try { markdown = readFileSync(latest.mdPath, 'utf8'); } catch { /* optional */ }
+  return { ok: true, ...latest, markdown };
+}
+
+export function listCheckpoints(projectRoot = process.cwd()) {
+  const paths = checkpointPaths(projectRoot);
+  if (!existsSync(paths.dir)) return [];
+  return readdirSync(paths.dir)
+    .filter((file) => file.endsWith('.json') && file !== 'latest.json')
+    .sort()
+    .map((file) => join(paths.dir, file));
+}
+
+function buildSnapshot(projectRoot, meta) {
+  const blackboard = readBlackboard(projectRoot);
+  const team = readTeamAssembly(projectRoot);
+  const plan = buildSwarmPlan(projectRoot);
+  const status = blackboardStatus(projectRoot);
+  const tasks = blackboard.tasks.data.tasks || [];
+  return {
+    schema_version: 'ijfw-checkpoint/v1',
+    id: meta.id,
+    label: meta.label,
+    message: meta.message || null,
+    created_at: meta.ts,
+    project: basename(resolve(projectRoot)),
+    team: team.ok ? {
+      name: team.charter.team_name,
+      archetypes: team.charter.project_archetypes,
+      roles: team.charter.roles.map((role) => role.name),
+    } : { ok: false },
+    swarm: plan.ok ? {
+      summary: plan.summary,
+      waves: plan.waves.map((wave) => ({
+        id: wave.id,
+        mode: wave.mode,
+        blocked: wave.blocked,
+        artifact_ids: wave.artifact_ids,
+      })),
+    } : { ok: false, message: plan.message },
+    tasks: summarizeTasks(tasks),
+    active_tasks: tasks.filter((task) => ['ready', 'in_progress', 'blocked'].includes(task.status)),
+    claims: status.claims,
+    recent: blackboard.recent,
+    next: recommendedNext(team, plan, tasks),
+  };
+}
+
+function renderCheckpoint(snapshot) {
+  const lines = [
+    `# IJFW Checkpoint: ${snapshot.label}`,
+    '',
+    `Created: ${snapshot.created_at}`,
+    `Project: ${snapshot.project}`,
+    `Next: ${snapshot.next}`,
+    '',
+    '## Team',
+    snapshot.team.ok === false ? 'No complete team assembly.' : `Team ${snapshot.team.name} (${snapshot.team.archetypes.join(', ')})`,
+    '',
+    '## Swarm',
+    snapshot.swarm.ok === false ? snapshot.swarm.message : snapshot.swarm.summary,
+    '',
+    '## Tasks',
+    `Ready: ${snapshot.tasks.ready}`,
+    `In progress: ${snapshot.tasks.in_progress}`,
+    `Blocked: ${snapshot.tasks.blocked}`,
+    `Done: ${snapshot.tasks.done}`,
+    '',
+    '## Active Tasks',
+  ];
+  for (const task of snapshot.active_tasks) lines.push(`- ${task.id} [${task.status}] ${task.owner || 'unowned'}`);
+  if (!snapshot.active_tasks.length) lines.push('- none');
+  lines.push('', '## Active Claims');
+  for (const claim of snapshot.claims.active_items || []) lines.push(`- ${claim.artifact_id} -> ${claim.agent}`);
+  if (!snapshot.claims.active_items?.length) lines.push('- none');
+  return `${lines.join('\n')}\n`;
+}
+
+function summarizeTasks(tasks) {
+  const counts = { total: tasks.length, ready: 0, in_progress: 0, blocked: 0, done: 0, other: 0 };
+  for (const task of tasks) {
+    if (task.status in counts) counts[task.status] += 1;
+    else counts.other += 1;
+  }
+  return counts;
+}
+
+function recommendedNext(team, plan, tasks) {
+  if (!team.ok) return 'Run: ijfw team init';
+  if (!plan.ok) return 'Run: ijfw swarm plan';
+  if (!tasks.length) return 'Run: ijfw swarm prepare';
+  const blocked = tasks.filter((task) => task.status === 'blocked');
+  if (blocked.length) return `Resolve blocked task: ${blocked[0].id}`;
+  const inProgress = tasks.find((task) => task.status === 'in_progress');
+  if (inProgress) return `Continue task: ${inProgress.id}`;
+  const ready = tasks.find((task) => task.status === 'ready');
+  if (ready) return `Start task: ${ready.id}`;
+  return 'Verify completed work or prepare next wave';
+}
+
+function readLatest(path) {
+  try {
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function safeName(label) {
+  return String(label || 'checkpoint').toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-|-$/g, '') || 'checkpoint';
+}
+

package/src/redactor.js

@@ -36,10 +36,12 @@ const PATTERNS = [
   // GCP / Google API keys -- `AIza...` (39 chars total).
   { re: /AIza[0-9A-Za-z_-]{35}/g,                  label: 'gcp'       },
   // Sentry DSN -- https://<key>@o<org>.ingest.sentry.io/<project>.
+  // eslint-disable-next-line security/detect-unsafe-regex -- redactor scans bounded tool output; this is an anchored secret pattern, not user-controlled matching logic.
   { re: /https?:\/\/[0-9a-f]{32,}(?::[0-9a-f]{32,})?@[\w.-]*sentry\.io\/[0-9]+/gi, label: 'sentry' },
   // Cloudflare API tokens (40 chars base64url). Conservative: only flag when
   // contextualized (CF_API_TOKEN=..., CLOUDFLARE_TOKEN=..., cf_auth_key=...)
   // so we don't eat bare git commit SHAs or content hashes.
+  // eslint-disable-next-line security/detect-unsafe-regex -- redactor scans bounded tool output and requires a Cloudflare context prefix before matching a token.
   { re: /(?:cf|cloudflare)[_-]?(?:api[_-]?)?(?:token|auth|key)s?[= :]+[A-Za-z0-9_-]{40,}/gi, label: 'cloudflare' },
   // Webhook URLs (Slack, Discord, MS Teams) -- include the secret path segment.
   { re: /https:\/\/hooks\.slack\.com\/services\/T[A-Z0-9]+\/B[A-Z0-9]+\/[A-Za-z0-9]+/g, label: 'webhook' },

package/src/runtime-mediator.js

@@ -0,0 +1,178 @@
+/**
+ * runtime-mediator.js -- IJFW 1.4.0 W7/B2
+ *
+ * Tier-1 cross-platform runtime sandbox mediation for installed extensions.
+ *
+ * Reads the active extension descriptor at ~/.ijfw/state/active-extension.json
+ * (written by the extension installer when an extension takes the active
+ * context). Maps MCP tool calls to (action, target) and decides whether the
+ * extension's declared permissions allow them.
+ *
+ * Backwards compat invariant: with NO state file present, behaviour is
+ * identical to today (allow all) -- callers see activeExt === null and
+ * checkPermission() returns { allowed: true }.
+ *
+ * Fail-closed invariant: if the file exists but is unparseable / malformed,
+ * the caller MUST treat it as a deny. A corrupted state file is not a free
+ * pass -- that would defeat the sandbox.
+ */
+
+import { readFile, mkdir, appendFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+// Sentinel returned from getActiveExtension when the file exists but is
+// invalid. Callers compare with === to distinguish from null (no file).
+const MALFORMED = Object.freeze({ __malformed: true });
+
+function stateDir(home) {
+  return join(home, '.ijfw', 'state');
+}
+
+function activeExtPath(home) {
+  return join(stateDir(home), 'active-extension.json');
+}
+
+function eventLogPath(home) {
+  return join(stateDir(home), 'permission-events.jsonl');
+}
+
+/**
+ * Read and validate ~/.ijfw/state/active-extension.json.
+ *
+ * Returns:
+ *   - null          -- file absent (bundled IJFW context, allow all).
+ *   - {name, scope, permissions:{reads,writes}} -- well-formed descriptor.
+ *   - {__malformed: true} (=== MALFORMED) -- file exists but broken; deny.
+ */
+export async function getActiveExtension(opts = {}) {
+  const home = opts.homeDir || process.env.HOME || homedir();
+  let raw;
+  try {
+    raw = await readFile(activeExtPath(home), 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    // Any other read error (permission denied, etc) is fail-closed.
+    return MALFORMED;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return MALFORMED;
+  }
+  if (!parsed || typeof parsed !== 'object') return MALFORMED;
+  if (typeof parsed.name !== 'string' || !parsed.name) return MALFORMED;
+  if (!parsed.permissions || typeof parsed.permissions !== 'object') return MALFORMED;
+  const reads = parsed.permissions.reads;
+  const writes = parsed.permissions.writes;
+  if (!Array.isArray(reads) || !Array.isArray(writes)) return MALFORMED;
+  return {
+    name: parsed.name,
+    scope: typeof parsed.scope === 'string' ? parsed.scope : 'project',
+    permissions: { reads, writes },
+  };
+}
+
+/**
+ * Match a target against an entry in a permissions list. Supports:
+ *   - exact match
+ *   - '*' wildcard (matches everything)
+ *   - prefix glob 'memory:*' (matches anything beginning with 'memory:')
+ */
+function matchesEntry(entry, target) {
+  if (entry === '*') return true;
+  if (entry === target) return true;
+  if (typeof entry === 'string' && entry.endsWith(':*')) {
+    const prefix = entry.slice(0, -1); // 'memory:*' -> 'memory:'
+    if (target.startsWith(prefix)) return true;
+  }
+  return false;
+}
+
+/**
+ * Decide whether `action` against `target` is permitted under the active
+ * extension's permissions.
+ *
+ *   - activeExt === null      -> allowed (bundled IJFW context).
+ *   - activeExt === MALFORMED -> denied with 'malformed active-extension state'.
+ *   - action === 'read'       -> target must match an entry in permissions.reads.
+ *   - action === 'write'      -> target must match an entry in permissions.writes.
+ *
+ * Returns { allowed: boolean, reason: string }.
+ */
+export function checkPermission(action, target, activeExt) {
+  if (activeExt === null || activeExt === undefined) {
+    return { allowed: true, reason: 'bundled context' };
+  }
+  if (activeExt && activeExt.__malformed) {
+    return { allowed: false, reason: 'malformed active-extension state' };
+  }
+  if (action !== 'read' && action !== 'write') {
+    return { allowed: false, reason: `unknown action: ${action}` };
+  }
+  const list = action === 'read' ? activeExt.permissions.reads : activeExt.permissions.writes;
+  for (const entry of list) {
+    if (matchesEntry(entry, target)) {
+      return { allowed: true, reason: `matched ${entry}` };
+    }
+  }
+  return {
+    allowed: false,
+    reason: `${action} ${target} not permitted by extension "${activeExt.name}"`,
+  };
+}
+
+/**
+ * Append one JSON line to ~/.ijfw/state/permission-events.jsonl. Best effort:
+ * never throws. The forensic trail is a nice-to-have, not a critical path.
+ */
+export async function logPermissionEvent(event, opts = {}) {
+  try {
+    const home = opts.homeDir || process.env.HOME || homedir();
+    await mkdir(stateDir(home), { recursive: true });
+    const line = JSON.stringify(event) + '\n';
+    await appendFile(eventLogPath(home), line, 'utf8');
+  } catch {
+    // Swallow: logging must never break tool dispatch.
+  }
+}
+
+/**
+ * Map an MCP tool name (+ args) to the (action, target) tuple used for
+ * permission checks. Returns null for unrecognised tool names; callers
+ * should treat null as "no policy applies, allow" (these are bundled-only).
+ */
+export function toolNameToActionTarget(toolName, args) {
+  switch (toolName) {
+    case 'ijfw_memory_store':
+      return { action: 'write', target: 'memory:write' };
+    case 'ijfw_memory_recall':
+    case 'ijfw_memory_search':
+    case 'ijfw_memory_status':
+    case 'ijfw_memory_prelude':
+    case 'ijfw_cross_project_search':
+      return { action: 'read', target: 'memory:read' };
+    case 'ijfw_metrics':
+      return { action: 'read', target: 'metrics:read' };
+    case 'ijfw_update_check':
+      return { action: 'read', target: 'update:check' };
+    case 'ijfw_update_apply':
+      return { action: 'write', target: 'update:apply' };
+    case 'ijfw_prompt_check':
+      return { action: 'read', target: 'prompt:check' };
+    case 'ijfw_run': {
+      // Parse the first colon-syntax token out of args.command -- e.g.
+      // "compute:python ..." -> subject 'compute'. Anything without a
+      // colon-prefixed leading token gets target 'run:*'.
+      let subject = '*';
+      if (args && typeof args.command === 'string') {
+        const m = args.command.match(/^\s*([A-Za-z][A-Za-z0-9_-]*)\s*:/);
+        if (m) subject = m[1];
+      }
+      return { action: 'write', target: `run:${subject}` };
+    }
+    default:
+      return null;
+  }
+}

package/src/sandbox.js

@@ -34,6 +34,7 @@ function sanitizeLabel(label) {
 export function runCommand(command, opts = {}) {
   return new Promise((resolve) => {
     const cwd = opts.cwd || process.cwd();
+    const timeoutMs = Number(opts.timeoutMs || opts.timeout || TIMEOUT_MS);
     const start = Date.now();
     let timedOut = false;
     let totalBytes = 0;
@@ -45,12 +46,25 @@ export function runCommand(command, opts = {}) {
       cwd,
       env: process.env,
       stdio: ['ignore', 'pipe', 'pipe'],
+      detached: process.platform !== 'win32',
     });
 
+    function killChild() {
+      try {
+        if (process.platform !== 'win32' && child.pid) {
+          process.kill(-child.pid, 'SIGKILL');
+        } else {
+          child.kill('SIGKILL');
+        }
+      } catch {
+        try { child.kill('SIGKILL'); } catch { /* already gone */ }
+      }
+    }
+
     const timer = setTimeout(() => {
       timedOut = true;
-      try { child.kill('SIGKILL'); } catch {}
-    }, TIMEOUT_MS);
+      killChild();
+    }, Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : TIMEOUT_MS);
 
     function onData(chunk) {
       if (capped) return;
@@ -59,7 +73,7 @@ export function runCommand(command, opts = {}) {
         chunks.push(chunk.slice(0, remaining));
         totalBytes += remaining;
         capped = true;
-        try { child.kill('SIGKILL'); } catch {}
+        killChild();
       } else {
         chunks.push(chunk);
         totalBytes += chunk.length;

package/src/server.js

@@ -45,6 +45,16 @@ import { runCommand, detectDomain, summarize, writeToSandbox, readFromSandbox, p
 // W1B (1.3.0-alpha) -- colon-syntax dispatcher. Extends ijfw_run + ijfw_memory_search
 // with compute:/index:/detect: sub-commands without registering new MCP tools.
 import { parseColonCommand, dispatchRun, dispatchSearch } from './dispatch/colon-syntax.js';
+// W7/B2 -- runtime sandbox mediation. With no installed extension active,
+// getActiveExtension() returns null and checkPermission() allows everything
+// (backwards-compat invariant). With an active extension, each MCP tool call
+// is gated against its declared permissions before the handler runs.
+import {
+  getActiveExtension,
+  checkPermission,
+  logPermissionEvent,
+  toolNameToActionTarget,
+} from './runtime-mediator.js';
 const SANDBOX_DIR = join(process.env.HOME || homedir(), '.ijfw', 'session-sandbox');
 
 // --- Constants ---
@@ -917,7 +927,7 @@ function cmpSemverPrelude(a, b) {
   return A.pre < B.pre ? -1 : 1;
 }
 
-function handlePrelude({ detail_level = 'summary' } = {}) {
+async function handlePrelude({ detail_level = 'summary' } = {}) {
   const KB_LINES = detail_level === 'full' ? 200 : detail_level === 'standard' ? 80 : 40;
   const HO_LINES = detail_level === 'full' ? 80  : detail_level === 'standard' ? 30 : 15;
   const JN_LINES = detail_level === 'full' ? 20  : detail_level === 'standard' ? 10 : 5;
@@ -999,6 +1009,56 @@ function handlePrelude({ detail_level = 'summary' } = {}) {
     if (body) parts.push('## Project preferences', body, '');
   }
 
+  // t14: cross-project override-use intelligence. Reads the current project's
+  // active overrides from ~/.ijfw/state/active-overrides.json and asks the
+  // override-use-registry whether N+ other projects share the set. Wrapped
+  // in a single try/catch — a registry failure must NEVER fail the prelude.
+  try {
+    const activePath = join(homedir(), '.ijfw', 'state', 'active-overrides.json');
+    let currentOverrides = [];
+    if (existsSync(activePath)) {
+      try {
+        const parsed = JSON.parse(readFileSync(activePath, 'utf8'));
+        const entry = parsed && parsed.projects && parsed.projects[PROJECT_DIR];
+        if (entry && Array.isArray(entry.active_overrides)) {
+          currentOverrides = entry.active_overrides
+            .filter((o) => o && typeof o.preset === 'string')
+            .map((o) => o.preset);
+        }
+      } catch {
+        // malformed json -- treat as no overrides, fall through silently
+      }
+    }
+    if (currentOverrides.length > 0) {
+      const { getPromoteSuggestion } = await import('./override-use-registry.js');
+      const suggestion = await getPromoteSuggestion(PROJECT_DIR, currentOverrides, {});
+      if (suggestion) {
+        parts.push('## Cross-project intelligence');
+        parts.push(suggestion.message);
+        parts.push(`Projects: ${suggestion.projects.join(', ')}`);
+        parts.push('Run: `' + suggestion.suggestion + '`');
+        parts.push('');
+      }
+    }
+  } catch {
+    // Registry failures are non-fatal -- the prelude must always succeed.
+  }
+
+  // B3 (1.4.0/W7): memory-feedback pattern hints. Reads gate-receipts and
+  // surfaces "N of last M flagged on artifact:type" hints. Wrapped in a
+  // single try/catch -- pattern detection failure must NEVER fail the prelude.
+  try {
+    const { getFeedbackSuggestions } = await import('./memory-feedback.js');
+    const suggestions = await getFeedbackSuggestions(PROJECT_DIR);
+    if (Array.isArray(suggestions) && suggestions.length > 0) {
+      parts.push('## Pattern hints');
+      for (const s of suggestions) parts.push(`- ${s}`);
+      parts.push('');
+    }
+  } catch {
+    // Best-effort; never fail the prelude on memory-feedback issues.
+  }
+
   parts.push('</ijfw-memory>');
 
   const text = parts.join('\n');
@@ -1213,6 +1273,38 @@ function handleMessage(msg) {
       return (async () => {
       let result;
       try {
+        // W7/B2 -- tier-1 runtime mediation. If an extension is active,
+        // gate the call against its declared permissions before any handler
+        // runs. With no extension active (bundled IJFW context), activeExt
+        // is null and the gate is a no-op -- preserving the backwards-compat
+        // invariant. Malformed state is fail-closed (denied).
+        let activeExt = null;
+        try {
+          activeExt = await getActiveExtension();
+        } catch {
+          activeExt = { __malformed: true };
+        }
+        if (activeExt !== null) {
+          const mapping = toolNameToActionTarget(name, args || {});
+          if (mapping) {
+            const check = checkPermission(mapping.action, mapping.target, activeExt);
+            if (!check.allowed) {
+              await logPermissionEvent({
+                tool: name,
+                extension: activeExt && activeExt.name ? activeExt.name : null,
+                action: mapping.action,
+                target: mapping.target,
+                allowed: false,
+                reason: check.reason,
+                ts: new Date().toISOString(),
+              }).catch(() => {});
+              return createResponse(id, {
+                content: [{ type: 'text', text: `extension permission denied: ${check.reason}` }],
+                isError: true,
+              });
+            }
+          }
+        }
         switch (name) {
           case 'ijfw_update_check': {
             const r = await ijfwUpdateCheck(args || {});
@@ -1259,7 +1351,7 @@ function handleMessage(msg) {
             result = handleStatus();
             break;
           case 'ijfw_memory_prelude':
-            result = handlePrelude(args || {});
+            result = await handlePrelude(args || {});
             break;
           case 'ijfw_metrics':
             result = handleMetrics(args || {});