@ijfw/memory-server 1.3.0 → 1.4.1

package/README.md

@@ -0,0 +1,67 @@
+# @ijfw/memory-server
+
+IJFW MCP memory server — the runtime backend that powers memory, metrics,
+update checks, and the extension sandbox for all supported AI coding agents.
+
+## Install
+
+This package is installed automatically by `@ijfw/install`. You generally
+do not need to install it manually.
+
+```bash
+npm install -g @ijfw/memory-server
+```
+
+## Extension CLI
+
+IJFW ships a full extension system for installing and sandboxing third-party skills.
+
+```bash
+# Publisher key management
+ijfw extension keygen <author>              # Generate an Ed25519 publisher keypair
+ijfw extension trust <keyId> <publicKey>   # Add a publisher to your trusted store
+ijfw extension trust-registry [<url>]      # Pull + apply the hosted publisher registry
+ijfw extension untrust <keyId>             # Remove a publisher from your trusted store
+ijfw extension trusted                     # List all trusted publishers
+
+# Extension lifecycle
+ijfw extension add <source> [flags]        # Install an extension (npm name, local path, or https git URL)
+  --allow-unsigned                         #   Accept extensions with no signature
+  --accept-untrusted                       #   Accept extensions signed by an untrusted publisher (prompts on TTY)
+  --activate                               #   Auto-activate after install
+ijfw extension activate <name>             # Activate an installed extension (enforces declared permissions)
+ijfw extension deactivate                  # Deactivate the current extension
+
+# Admin / registry maintainer (rare)
+ijfw extension rotate-keys <oldKeyId> <newKeyId>   # Produce a signed rotation token
+ijfw extension keygen-meta <author>                # Generate the registry meta-keypair
+ijfw extension sign-registry <path>                # Sign a registry JSON file in place
+ijfw extension verify-registry <path>              # Verify a registry JSON signature
+ijfw extension registry-status                     # Show registry cache age + signature status
+```
+
+The rotation flow and registry maintainer docs live in `docs/REGISTRY-MAINTAINER.md`.
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `ijfw_memory_store` | Store a memory entry |
+| `ijfw_memory_recall` | Recall memory entries |
+| `ijfw_memory_search` | Full-text search over memories |
+| `ijfw_memory_prelude` | Load project context at session start |
+| `ijfw_cross_project_search` | Search memories across projects |
+| `ijfw_metrics` | Read cost + usage metrics |
+| `ijfw_update_check` | Check for IJFW updates |
+| `ijfw_update_apply` | Apply a pending IJFW update |
+| `ijfw_prompt_check` | Validate a prompt against IJFW rules |
+| `ijfw_run` | Run a sandboxed IJFW command |
+
+## Build (contributors)
+
+```bash
+cd mcp-server
+npm install
+npm test
+node --experimental-sqlite --test test-*.js
+```

package/fixtures/team/book.json

@@ -0,0 +1,47 @@
+{
+  "charter": {
+    "schema_version": "team-charter/v1",
+    "team_name": "book-development-team",
+    "project_archetypes": ["book"],
+    "roles": [
+      {
+        "name": "chapter-writer",
+        "role_type": "book",
+        "model": "sonnet",
+        "effort": "medium",
+        "phase_scope": ["outline", "draft", "revise"],
+        "owns": [{"artifact_type": "chapter", "paths": ["manuscript/chapters/**"]}],
+        "reviews": [{"artifact_type": "outline", "criteria": ["structure", "continuity"]}],
+        "handoff": {"format": "markdown", "required_sections": ["chapter_summary", "open_threads", "changed_artifacts"]},
+        "coordination": {"parallel_safe": true, "claim_required": true, "conflicts_with": ["manuscript/chapters/**"]}
+      },
+      {
+        "name": "continuity-editor",
+        "role_type": "review",
+        "model": "sonnet",
+        "effort": "medium",
+        "phase_scope": ["review", "revise"],
+        "owns": [{"artifact_type": "continuity_notes", "paths": ["manuscript/notes/**"]}],
+        "reviews": [{"artifact_type": "chapter", "criteria": ["timeline", "voice", "consistency"]}],
+        "handoff": {"format": "markdown", "required_sections": ["findings", "continuity_risks"]},
+        "coordination": {"parallel_safe": true, "claim_required": true, "conflicts_with": []}
+      }
+    ]
+  },
+  "workflow": {
+    "schema_version": "team-workflow/v1",
+    "project_archetypes": ["book"],
+    "artifacts": [
+      {"id": "chapter-draft", "type": "chapter", "paths": ["manuscript/chapters/ch01.md"], "owner": "chapter-writer", "reviewers": ["continuity-editor"], "depends_on": [], "verification": ["continuity review"]},
+      {"id": "continuity-notes", "type": "continuity_notes", "paths": ["manuscript/notes/continuity.md"], "owner": "continuity-editor", "reviewers": ["chapter-writer"], "depends_on": ["chapter-draft"], "verification": ["open thread audit"]}
+    ],
+    "waves": [
+      {"id": "w1", "mode": "parallel", "artifact_ids": ["chapter-draft"]},
+      {"id": "w2", "mode": "review", "artifact_ids": ["continuity-notes"]}
+    ]
+  },
+  "blackboard": {
+    "tasks": [{"id": "task-chapter", "title": "Draft chapter one", "status": "ready", "artifact_ids": ["chapter-draft"], "owner": "chapter-writer"}],
+    "claims": [{"id": "claim-chapter", "artifact_id": "chapter-draft", "agent": "chapter-writer", "status": "active", "paths": ["manuscript/chapters/ch01.md"]}]
+  }
+}

package/fixtures/team/business.json

@@ -0,0 +1,47 @@
+{
+  "charter": {
+    "schema_version": "team-charter/v1",
+    "team_name": "strategy-operations-team",
+    "project_archetypes": ["business"],
+    "roles": [
+      {
+        "name": "strategy-lead",
+        "role_type": "business",
+        "model": "sonnet",
+        "effort": "medium",
+        "phase_scope": ["diagnose", "plan", "decide"],
+        "owns": [{"artifact_type": "strategy_doc", "paths": ["strategy/**"]}],
+        "reviews": [{"artifact_type": "risk_register", "criteria": ["assumptions", "decision-quality"]}],
+        "handoff": {"format": "markdown", "required_sections": ["recommendation", "assumptions", "tradeoffs"]},
+        "coordination": {"parallel_safe": true, "claim_required": true, "conflicts_with": []}
+      },
+      {
+        "name": "risk-reviewer",
+        "role_type": "review",
+        "model": "sonnet",
+        "effort": "medium",
+        "phase_scope": ["review", "verify"],
+        "owns": [{"artifact_type": "risk_register", "paths": ["strategy/risks/**"]}],
+        "reviews": [{"artifact_type": "strategy_doc", "criteria": ["feasibility", "downside", "metrics"]}],
+        "handoff": {"format": "markdown", "required_sections": ["risks", "mitigations", "decision_points"]},
+        "coordination": {"parallel_safe": true, "claim_required": true, "conflicts_with": []}
+      }
+    ]
+  },
+  "workflow": {
+    "schema_version": "team-workflow/v1",
+    "project_archetypes": ["business"],
+    "artifacts": [
+      {"id": "operating-plan", "type": "strategy_doc", "paths": ["strategy/operating-plan.md"], "owner": "strategy-lead", "reviewers": ["risk-reviewer"], "depends_on": [], "verification": ["decision review"]},
+      {"id": "risk-register", "type": "risk_register", "paths": ["strategy/risks/register.md"], "owner": "risk-reviewer", "reviewers": ["strategy-lead"], "depends_on": ["operating-plan"], "verification": ["assumption audit"]}
+    ],
+    "waves": [
+      {"id": "w1", "mode": "sequential", "artifact_ids": ["operating-plan"]},
+      {"id": "w2", "mode": "review", "artifact_ids": ["risk-register"]}
+    ]
+  },
+  "blackboard": {
+    "tasks": [{"id": "task-plan", "title": "Draft operating plan", "status": "ready", "artifact_ids": ["operating-plan"], "owner": "strategy-lead"}],
+    "claims": [{"id": "claim-plan", "artifact_id": "operating-plan", "agent": "strategy-lead", "status": "active", "paths": ["strategy/operating-plan.md"]}]
+  }
+}

package/fixtures/team/content.json

@@ -0,0 +1,47 @@
+{
+  "charter": {
+    "schema_version": "team-charter/v1",
+    "team_name": "content-production-team",
+    "project_archetypes": ["content"],
+    "roles": [
+      {
+        "name": "content-strategist",
+        "role_type": "content",
+        "model": "sonnet",
+        "effort": "medium",
+        "phase_scope": ["plan", "execute"],
+        "owns": [{"artifact_type": "brief", "paths": ["content/briefs/**"]}],
+        "reviews": [{"artifact_type": "article", "criteria": ["positioning", "brand-voice"]}],
+        "handoff": {"format": "markdown", "required_sections": ["message", "audience", "risks"]},
+        "coordination": {"parallel_safe": true, "claim_required": true, "conflicts_with": []}
+      },
+      {
+        "name": "editor",
+        "role_type": "review",
+        "model": "sonnet",
+        "effort": "medium",
+        "phase_scope": ["review", "verify"],
+        "owns": [{"artifact_type": "article", "paths": ["content/posts/**"]}],
+        "reviews": [{"artifact_type": "brief", "criteria": ["clarity", "seo", "voice"]}],
+        "handoff": {"format": "markdown", "required_sections": ["edits", "findings", "publication_status"]},
+        "coordination": {"parallel_safe": true, "claim_required": true, "conflicts_with": ["content/posts/**"]}
+      }
+    ]
+  },
+  "workflow": {
+    "schema_version": "team-workflow/v1",
+    "project_archetypes": ["content"],
+    "artifacts": [
+      {"id": "campaign-brief", "type": "brief", "paths": ["content/briefs/campaign.md"], "owner": "content-strategist", "reviewers": ["editor"], "depends_on": [], "verification": ["brand voice review"]},
+      {"id": "article-draft", "type": "article", "paths": ["content/posts/*.mdx"], "owner": "editor", "reviewers": ["content-strategist"], "depends_on": ["campaign-brief"], "verification": ["seo checklist"]}
+    ],
+    "waves": [
+      {"id": "w1", "mode": "sequential", "artifact_ids": ["campaign-brief"]},
+      {"id": "w2", "mode": "review", "artifact_ids": ["article-draft"]}
+    ]
+  },
+  "blackboard": {
+    "tasks": [{"id": "task-brief", "title": "Prepare campaign brief", "status": "ready", "artifact_ids": ["campaign-brief"], "owner": "content-strategist"}],
+    "claims": [{"id": "claim-brief", "artifact_id": "campaign-brief", "agent": "content-strategist", "status": "active", "paths": ["content/briefs/campaign.md"]}]
+  }
+}

package/fixtures/team/design.json

@@ -0,0 +1,47 @@
+{
+  "charter": {
+    "schema_version": "team-charter/v1",
+    "team_name": "design-studio-team",
+    "project_archetypes": ["design"],
+    "roles": [
+      {
+        "name": "product-designer",
+        "role_type": "design",
+        "model": "sonnet",
+        "effort": "medium",
+        "phase_scope": ["discovery", "shape", "execute"],
+        "owns": [{"artifact_type": "screen", "paths": ["design/screens/**"]}],
+        "reviews": [{"artifact_type": "prototype", "criteria": ["usability", "accessibility"]}],
+        "handoff": {"format": "markdown", "required_sections": ["rationale", "changed_artifacts", "open_questions"]},
+        "coordination": {"parallel_safe": true, "claim_required": true, "conflicts_with": ["design/tokens/**"]}
+      },
+      {
+        "name": "visual-qa",
+        "role_type": "review",
+        "model": "sonnet",
+        "effort": "low",
+        "phase_scope": ["review", "verify"],
+        "owns": [{"artifact_type": "audit", "paths": ["design/reviews/**"]}],
+        "reviews": [{"artifact_type": "screen", "criteria": ["layout", "contrast", "responsive-fit"]}],
+        "handoff": {"format": "markdown", "required_sections": ["findings", "severity", "recommendations"]},
+        "coordination": {"parallel_safe": true, "claim_required": true, "conflicts_with": []}
+      }
+    ]
+  },
+  "workflow": {
+    "schema_version": "team-workflow/v1",
+    "project_archetypes": ["design"],
+    "artifacts": [
+      {"id": "screen-system", "type": "screen", "paths": ["design/screens/**"], "owner": "product-designer", "reviewers": ["visual-qa"], "depends_on": [], "verification": ["visual audit"]},
+      {"id": "design-review", "type": "audit", "paths": ["design/reviews/**"], "owner": "visual-qa", "reviewers": ["product-designer"], "depends_on": ["screen-system"], "verification": ["accessibility checklist"]}
+    ],
+    "waves": [
+      {"id": "w1", "mode": "parallel", "artifact_ids": ["screen-system"]},
+      {"id": "w2", "mode": "review", "artifact_ids": ["design-review"]}
+    ]
+  },
+  "blackboard": {
+    "tasks": [{"id": "task-screens", "title": "Draft core screens", "status": "ready", "artifact_ids": ["screen-system"], "owner": "product-designer"}],
+    "claims": [{"id": "claim-screens", "artifact_id": "screen-system", "agent": "product-designer", "status": "active", "paths": ["design/screens/**"]}]
+  }
+}

package/fixtures/team/mixed.json

@@ -0,0 +1,59 @@
+{
+  "charter": {
+    "schema_version": "team-charter/v1",
+    "team_name": "mixed-launch-team",
+    "project_archetypes": ["software", "design", "content", "mixed"],
+    "roles": [
+      {
+        "name": "app-engineer",
+        "role_type": "software",
+        "model": "sonnet",
+        "effort": "medium",
+        "phase_scope": ["execute", "verify"],
+        "owns": [{"artifact_type": "app", "paths": ["app/**"]}],
+        "reviews": [{"artifact_type": "screen", "criteria": ["integration", "accessibility"]}],
+        "handoff": {"format": "markdown", "required_sections": ["changed_artifacts", "tests", "risks"]},
+        "coordination": {"parallel_safe": true, "claim_required": true, "conflicts_with": ["app/routes/**"]}
+      },
+      {
+        "name": "ux-designer",
+        "role_type": "design",
+        "model": "sonnet",
+        "effort": "medium",
+        "phase_scope": ["shape", "review"],
+        "owns": [{"artifact_type": "screen", "paths": ["design/**"]}],
+        "reviews": [{"artifact_type": "app", "criteria": ["usability", "visual-fit"]}],
+        "handoff": {"format": "markdown", "required_sections": ["rationale", "screens", "review_notes"]},
+        "coordination": {"parallel_safe": true, "claim_required": true, "conflicts_with": ["design/tokens/**"]}
+      },
+      {
+        "name": "launch-editor",
+        "role_type": "content",
+        "model": "sonnet",
+        "effort": "low",
+        "phase_scope": ["execute", "review"],
+        "owns": [{"artifact_type": "launch_copy", "paths": ["content/launch/**"]}],
+        "reviews": [{"artifact_type": "screen", "criteria": ["message-match", "voice"]}],
+        "handoff": {"format": "markdown", "required_sections": ["copy_changes", "voice_notes"]},
+        "coordination": {"parallel_safe": true, "claim_required": true, "conflicts_with": []}
+      }
+    ]
+  },
+  "workflow": {
+    "schema_version": "team-workflow/v1",
+    "project_archetypes": ["software", "design", "content", "mixed"],
+    "artifacts": [
+      {"id": "app-shell", "type": "app", "paths": ["app/**"], "owner": "app-engineer", "reviewers": ["ux-designer"], "depends_on": [], "verification": ["npm test"]},
+      {"id": "product-screens", "type": "screen", "paths": ["design/**"], "owner": "ux-designer", "reviewers": ["app-engineer", "launch-editor"], "depends_on": [], "verification": ["visual audit"]},
+      {"id": "launch-copy", "type": "launch_copy", "paths": ["content/launch/**"], "owner": "launch-editor", "reviewers": ["ux-designer"], "depends_on": ["product-screens"], "verification": ["brand voice review"]}
+    ],
+    "waves": [
+      {"id": "w1", "mode": "parallel", "artifact_ids": ["app-shell", "product-screens"]},
+      {"id": "w2", "mode": "review", "artifact_ids": ["launch-copy"]}
+    ]
+  },
+  "blackboard": {
+    "tasks": [{"id": "task-launch", "title": "Coordinate launch surface", "status": "ready", "artifact_ids": ["app-shell", "product-screens"], "owner": "app-engineer"}],
+    "claims": [{"id": "claim-copy", "artifact_id": "launch-copy", "agent": "launch-editor", "status": "active", "paths": ["content/launch/**"]}]
+  }
+}

package/fixtures/team/research.json

@@ -0,0 +1,47 @@
+{
+  "charter": {
+    "schema_version": "team-charter/v1",
+    "team_name": "research-synthesis-team",
+    "project_archetypes": ["research"],
+    "roles": [
+      {
+        "name": "research-lead",
+        "role_type": "research",
+        "model": "sonnet",
+        "effort": "high",
+        "phase_scope": ["question", "collect", "synthesize"],
+        "owns": [{"artifact_type": "evidence_table", "paths": ["research/evidence/**"]}],
+        "reviews": [{"artifact_type": "synthesis", "criteria": ["method", "source-quality"]}],
+        "handoff": {"format": "markdown", "required_sections": ["sources", "findings", "confidence"]},
+        "coordination": {"parallel_safe": true, "claim_required": true, "conflicts_with": []}
+      },
+      {
+        "name": "method-reviewer",
+        "role_type": "review",
+        "model": "sonnet",
+        "effort": "medium",
+        "phase_scope": ["review", "verify"],
+        "owns": [{"artifact_type": "method_audit", "paths": ["research/reviews/**"]}],
+        "reviews": [{"artifact_type": "evidence_table", "criteria": ["bias", "traceability", "coverage"]}],
+        "handoff": {"format": "markdown", "required_sections": ["limitations", "risk", "recommendations"]},
+        "coordination": {"parallel_safe": true, "claim_required": true, "conflicts_with": []}
+      }
+    ]
+  },
+  "workflow": {
+    "schema_version": "team-workflow/v1",
+    "project_archetypes": ["research"],
+    "artifacts": [
+      {"id": "evidence-table", "type": "evidence_table", "paths": ["research/evidence/table.md"], "owner": "research-lead", "reviewers": ["method-reviewer"], "depends_on": [], "verification": ["source audit"]},
+      {"id": "method-audit", "type": "method_audit", "paths": ["research/reviews/method.md"], "owner": "method-reviewer", "reviewers": ["research-lead"], "depends_on": ["evidence-table"], "verification": ["methodology review"]}
+    ],
+    "waves": [
+      {"id": "w1", "mode": "parallel", "artifact_ids": ["evidence-table"]},
+      {"id": "w2", "mode": "review", "artifact_ids": ["method-audit"]}
+    ]
+  },
+  "blackboard": {
+    "tasks": [{"id": "task-evidence", "title": "Build evidence table", "status": "ready", "artifact_ids": ["evidence-table"], "owner": "research-lead"}],
+    "claims": [{"id": "claim-evidence", "artifact_id": "evidence-table", "agent": "research-lead", "status": "active", "paths": ["research/evidence/table.md"]}]
+  }
+}

package/fixtures/team/software.json

@@ -0,0 +1,47 @@
+{
+  "charter": {
+    "schema_version": "team-charter/v1",
+    "team_name": "software-delivery-team",
+    "project_archetypes": ["software"],
+    "roles": [
+      {
+        "name": "implementation-engineer",
+        "role_type": "software",
+        "model": "sonnet",
+        "effort": "medium",
+        "phase_scope": ["plan", "execute", "verify"],
+        "owns": [{"artifact_type": "module", "paths": ["src/**/*.js"]}],
+        "reviews": [{"artifact_type": "test", "criteria": ["coverage", "regression"]}],
+        "handoff": {"format": "markdown", "required_sections": ["changed_artifacts", "tests", "risks"]},
+        "coordination": {"parallel_safe": true, "claim_required": true, "conflicts_with": ["src/shared/**"]}
+      },
+      {
+        "name": "test-reviewer",
+        "role_type": "qa",
+        "model": "sonnet",
+        "effort": "low",
+        "phase_scope": ["review", "verify"],
+        "owns": [{"artifact_type": "test", "paths": ["test/**/*.js"]}],
+        "reviews": [{"artifact_type": "module", "criteria": ["behavior", "edge-cases"]}],
+        "handoff": {"format": "markdown", "required_sections": ["findings", "verification"]},
+        "coordination": {"parallel_safe": true, "claim_required": true, "conflicts_with": []}
+      }
+    ]
+  },
+  "workflow": {
+    "schema_version": "team-workflow/v1",
+    "project_archetypes": ["software"],
+    "artifacts": [
+      {"id": "runtime-module", "type": "module", "paths": ["src/**/*.js"], "owner": "implementation-engineer", "reviewers": ["test-reviewer"], "depends_on": [], "verification": ["npm test"]},
+      {"id": "regression-tests", "type": "test", "paths": ["test/**/*.js"], "owner": "test-reviewer", "reviewers": ["implementation-engineer"], "depends_on": ["runtime-module"], "verification": ["node --test test/**/*.js"]}
+    ],
+    "waves": [
+      {"id": "w1", "mode": "parallel", "artifact_ids": ["runtime-module"]},
+      {"id": "w2", "mode": "review", "artifact_ids": ["regression-tests"]}
+    ]
+  },
+  "blackboard": {
+    "tasks": [{"id": "task-runtime", "title": "Implement runtime module", "status": "ready", "artifact_ids": ["runtime-module"], "owner": "implementation-engineer", "depends_on": []}],
+    "claims": [{"id": "claim-runtime", "artifact_id": "runtime-module", "agent": "implementation-engineer", "status": "active", "paths": ["src/**/*.js"], "claimed_at": "2026-05-15T00:00:00Z"}]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ijfw/memory-server",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Cross-platform persistent memory server for IJFW. 10 MCP tools (memory + admin/update). Works with 13 MCP-using platforms (Claude Code, Codex, Gemini CLI, Cursor, Windsurf, Copilot, Hermes, Wayland, OpenCode, QwenCode, Cline, KimiCode, OpenClaw) plus Aider via rules-only tier.",
   "author": "Sean Donahoe",
   "license": "MIT",
@@ -26,14 +26,6 @@
     "ajv": "^8.12.0",
     "ajv-formats": "^3.0.1"
   },
-  "optionalDependencies": {
-    "@xenova/transformers": "^2.17.0"
-  },
-  "peerDependenciesMeta": {
-    "@xenova/transformers": {
-      "optional": true
-    }
-  },
   "files": [
     "bin/",
     "src/",

package/src/.registry-meta-key.pem

@@ -0,0 +1,3 @@
+-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAL2lCdti0bYiFTGUo/hffy+NiBUBXdbDcdaDmjJS27i0=
+-----END PUBLIC KEY-----

package/src/active-extension-writer.js

@@ -0,0 +1,142 @@
+/**
+ * active-extension-writer.js -- IJFW v1.4.0 W7.1/B2-H-01
+ *
+ * Writes ~/.ijfw/state/active-extension.json from an extension manifest, and
+ * clears it on deactivate. Used by:
+ *   - `ijfw_run extension:activate <name>` CLI command
+ *   - installExtension when opts.activate is set
+ */
+
+import { readFile, writeFile, unlink, mkdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { randomBytes } from 'node:crypto';
+
+const STATE_PATH_REL = ['.ijfw', 'state', 'active-extension.json'];
+
+function statePath(home) {
+  return join(home || homedir(), ...STATE_PATH_REL);
+}
+
+/**
+ * Write the active-extension state file from a manifest + scope.
+ * Validates required fields before write. Atomic write via tmp+rename.
+ *
+ * @param {{ name: string, permissions: { reads: string[], writes: string[] } }} manifest
+ * @param {'project'|'org'|'user'} scope
+ * @param {{ homeDir?: string }} [opts]
+ * @returns {Promise<{ ok: boolean, path?: string, error?: string }>}
+ */
+export async function writeActiveExtension(manifest, scope, opts = {}) {
+  if (!manifest || typeof manifest !== 'object') {
+    return { ok: false, error: 'manifest must be an object' };
+  }
+  if (typeof manifest.name !== 'string' || manifest.name.length === 0) {
+    return { ok: false, error: 'manifest.name required' };
+  }
+  if (!['project', 'org', 'user'].includes(scope)) {
+    return { ok: false, error: `invalid scope: ${scope}` };
+  }
+  if (!manifest.permissions || typeof manifest.permissions !== 'object') {
+    return { ok: false, error: 'manifest.permissions required' };
+  }
+  const reads = Array.isArray(manifest.permissions.reads) ? manifest.permissions.reads : [];
+  const writes = Array.isArray(manifest.permissions.writes) ? manifest.permissions.writes : [];
+  const out = {
+    name: manifest.name,
+    scope,
+    permissions: { reads, writes },
+    activated_at: new Date().toISOString(),
+  };
+  const home = opts && opts.homeDir ? opts.homeDir : (process.env.HOME || homedir());
+  const path = statePath(home);
+  await mkdir(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp.${randomBytes(4).toString('hex')}`;
+  await writeFile(tmp, JSON.stringify(out, null, 2) + '\n', 'utf8');
+  const { rename } = await import('node:fs/promises');
+  await rename(tmp, path);
+  return { ok: true, path };
+}
+
+/**
+ * Clear the active-extension state file. Idempotent -- succeeds if file is absent.
+ *
+ * @param {{ homeDir?: string }} [opts]
+ * @returns {Promise<{ ok: boolean, removed: boolean }>}
+ */
+export async function clearActiveExtension(opts = {}) {
+  const home = opts && opts.homeDir ? opts.homeDir : (process.env.HOME || homedir());
+  try {
+    await unlink(statePath(home));
+    return { ok: true, removed: true };
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { ok: true, removed: false };
+    return { ok: false, removed: false };
+  }
+}
+
+/**
+ * Read an installed extension's manifest by name. Resolves from project/org/user
+ * scope (project first, then org, then user). Used by `extension activate <name>`
+ * which doesn't carry the full manifest in args.
+ *
+ * Scope paths (matching the rest of the codebase):
+ *   project: <projectRoot>/.ijfw/extensions/<name>/manifest.json
+ *   org:     ~/.ijfw/extensions-org/<name>/manifest.json
+ *   user:    ~/.ijfw/extensions-user/<name>/manifest.json
+ *
+ * @param {string} name
+ * @param {string} [projectRoot]
+ * @param {{ homeDir?: string, strictShadow?: boolean }} [opts]
+ * @returns {Promise<{ ok: boolean, manifest?: object, scope?: string, path?: string, error?: string }>}
+ */
+export async function findInstalledManifest(name, projectRoot, opts = {}) {
+  // eslint-disable-next-line security/detect-unsafe-regex -- anchored, bounded npm name shape; no nested ambiguous repetition
+  if (typeof name !== 'string' || !/^(@[a-z0-9-]+\/)?[a-z][a-z0-9-]*$/.test(name)) {
+    return { ok: false, error: 'invalid extension name' };
+  }
+  const home = opts && opts.homeDir ? opts.homeDir : (process.env.HOME || homedir());
+  const candidates = [];
+  if (projectRoot) {
+    candidates.push({ scope: 'project', path: join(projectRoot, '.ijfw', 'extensions', name, 'manifest.json') });
+  }
+  candidates.push({ scope: 'org', path: join(home, '.ijfw', 'extensions-org', name, 'manifest.json') });
+  candidates.push({ scope: 'user', path: join(home, '.ijfw', 'extensions-user', name, 'manifest.json') });
+
+  // Collect all found manifests to detect project-scope shadowing.
+  const found = [];
+  for (const c of candidates) {
+    try {
+      const raw = await readFile(c.path, 'utf8');
+      const manifest = JSON.parse(raw);
+      found.push({ scope: c.scope, path: c.path, manifest });
+    } catch (err) {
+      if (err && err.code === 'ENOENT') continue;
+      if (err instanceof SyntaxError) continue;
+    }
+  }
+
+  if (found.length === 0) {
+    return { ok: false, error: `extension "${name}" not found in project/org/user scope` };
+  }
+
+  const winner = found[0];
+
+  // B13.1: warn when project-scope shadows a lower-priority scope entry.
+  if (winner.scope === 'project' && found.length > 1) {
+    const shadowed = found[1];
+    const winnerKeyId = winner.manifest.signature?.keyId ?? '(unsigned)';
+    const shadowedKeyId = shadowed.manifest.signature?.keyId ?? '(unsigned)';
+    if (opts && opts.strictShadow) {
+      return {
+        ok: false,
+        error: `extension activate: project-scope "${name}" shadows ${shadowed.scope}-scope "${name}" (keyId ${winnerKeyId} vs ${shadowedKeyId}) — refused by strictShadow`,
+      };
+    }
+    process.stderr.write(
+      `[ijfw] extension activate: project-scope "${name}" shadows ${shadowed.scope}-scope "${name}" (keyId ${winnerKeyId} vs ${shadowedKeyId}) — using project\n`,
+    );
+  }
+
+  return { ok: true, manifest: winner.manifest, scope: winner.scope, path: winner.path };
+}