@geraldmaron/construct 1.4.1 → 1.4.2

package/lib/providers/secret-resolver.mjs

@@ -12,11 +12,12 @@
  * `$(op read 'op://...')` — it is resolved through the `op` CLI and cached for
  * the process lifetime so a single launch prompts at most once per reference.
  *
- * One divergence from loadConstructEnv is intentional and tracked separately: that
- * merge ranks the config files above process.env to defeat stale shell exports,
- * while this resolver honors a directly-passed env value first so a hermetic caller
- * can inject its own credentials. Unifying the process.env tier touches the live
- * LLM path and is deferred to a follow-up.
+ * The process.env tier follows one precedence ladder shared with loadConstructEnv:
+ * when file discovery is enabled (allowAmbient), the file tiers win over an ambient
+ * shell export so a stale export cannot shadow a managed config value, with the same
+ * carve-out that a materialized credential injected on the env beats a stored op://
+ * reference (preferInjectedCredential). A hermetic caller sets allowAmbient:false to
+ * suppress all file/rc discovery and use only the directly-injected env.
  *
  * resolveSecret performs the `op read` (and may surface a structured
  * SecretResolutionError); hasSecret only checks presence and never invokes the
@@ -32,6 +33,7 @@ import os from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { discoverAlternateRawForVar } from './credential-sources.mjs';
 import { configDir } from '../config/xdg.mjs';
+import { preferInjectedCredential } from '../env-config.mjs';
 
 // The 1Password desktop integration prompts for biometric unlock on the first
 // read after the vault locks, and that interactive round-trip routinely takes
@@ -181,9 +183,8 @@ function readFromOpEnvCatalog(varName, { env, home }) {
 }
 
 function rawCandidate(varName, { env, cwd, home }) {
-  const direct = env?.[varName];
-  if (typeof direct === 'string' && direct.length > 0) return { raw: direct, source: 'env' };
-
+  // Pure file/store discovery: the ambient env tier is ranked by the callers
+  // (resolveSecret / hasSecret) so one precedence ladder governs env-vs-file.
   // File tier matches loadConstructEnv: the project .env (closest to the work)
   // wins over the machine-wide XDG config.env, which wins over a generic ~/.env.
   const files = [
@@ -218,18 +219,32 @@ function resolveAndAudit(varName, raw, source, opts) {
 
 export function resolveSecret(varName, { env = process.env, cwd = process.cwd(), allowAmbient = true, opRead } = {}) {
   const direct = env?.[varName];
-  if (typeof direct === 'string' && direct.length > 0) return resolveAndAudit(varName, direct, 'env', { opRead });
+  const hasDirect = typeof direct === 'string' && direct.length > 0;
+
+  // Hermetic mode: only the directly-injected env is consulted, no file/rc discovery,
+  // so a developer key never bleeds into an isolated run.
   if (!allowAmbient) {
+    if (hasDirect) return resolveAndAudit(varName, direct, 'env', { opRead });
     emitAudit({ event: 'secret.resolve', varName, source: null, isOpRef: false, ok: false });
     return null;
   }
+
   const home = os.homedir();
   const found = rawCandidate(varName, { env, cwd, home });
-  if (!found) {
-    emitAudit({ event: 'secret.resolve', varName, source: null, isOpRef: false, ok: false });
-    return null;
+
+  // Precedence parity with loadConstructEnv: the file tiers win over an ambient shell
+  // export, except a materialized credential injected on the env beats a stored op://
+  // reference so a single `op run` auth suffices.
+  if (found) {
+    if (hasDirect && preferInjectedCredential(direct, found.raw)) {
+      return resolveAndAudit(varName, direct, 'env', { opRead });
+    }
+    return resolveAndAudit(varName, found.raw, found.source, { opRead });
   }
-  return resolveAndAudit(varName, found.raw, found.source, { opRead });
+
+  if (hasDirect) return resolveAndAudit(varName, direct, 'env', { opRead });
+  emitAudit({ event: 'secret.resolve', varName, source: null, isOpRef: false, ok: false });
+  return null;
 }
 
 export function resolveFirstSecret(varNames, opts = {}) {

package/lib/registry/catalog.mjs

@@ -71,6 +71,11 @@ function buildCapabilityEdges(cap, { allScripts, pkgScriptsBody }) {
   return { cliCommands, npmScripts, workflows };
 }
 
+function semanticDigest(cap) {
+  const { description = '', criticality = '', verification = {} } = cap;
+  return JSON.stringify({ description, criticality, verification });
+}
+
 export function buildCatalogSnapshot({ rootDir = REPO_ROOT, now = new Date() } = {}) {
   const pkgPath = path.join(rootDir, 'package.json');
   const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
@@ -79,6 +84,7 @@ export function buildCatalogSnapshot({ rootDir = REPO_ROOT, now = new Date() } =
   const raw = loadCapabilityRegistry({ rootDir });
   const capabilities = (raw.capabilities ?? []).map((cap) => ({
     ...cap,
+    _semanticDigest: semanticDigest(cap),
     edges: buildCapabilityEdges(cap, { allScripts, pkgScriptsBody }),
   }));
 

package/lib/registry/loader.mjs

@@ -18,6 +18,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT_DIR = path.resolve(__dirname, '..', '..');
 
 let _registry = null;
+let _rootDir = null;
 let _orgMtime = null;
 let _legacyOverlayMtime = null;
 
@@ -62,7 +63,10 @@ export function loadRegistry(opts = {}) {
     legacyOverlay = null;
   }
 
-  if (_registry && _orgMtime === orgMtime && _legacyOverlayMtime === legacyOverlayMtime) {
+  // The cache key must include rootDir: two roots can share an orgMtime/overlay mtime
+  // (tmpdir tests, coincident timestamps), and a cache keyed only on mtimes bleeds one
+  // root's registry into another — a specialist can then surface without its promptFile.
+  if (_registry && _rootDir === rootDir && _orgMtime === orgMtime && _legacyOverlayMtime === legacyOverlayMtime) {
     return _registry;
   }
 
@@ -79,6 +83,7 @@ export function loadRegistry(opts = {}) {
   }
 
   _registry = registry;
+  _rootDir = rootDir;
   _orgMtime = orgMtime;
   _legacyOverlayMtime = legacyOverlayMtime;
 
@@ -127,6 +132,7 @@ export function listSpecialists(teamId, opts = {}) {
 
 export function clearCache() {
   _registry = null;
+  _rootDir = null;
   _orgMtime = null;
   _legacyOverlayMtime = null;
 }

package/lib/registry/validate.mjs

@@ -86,7 +86,7 @@ export function validateCapabilityRegistry({ rootDir = REPO_ROOT, now = Date.now
 
     const hasTest = ver.functional || ver.hostEmulation || ver.untestableRationale;
     if (!hasTest && (cap.criticality === 'P0' || cap.criticality === 'P1')) {
-      warnings.push(`${cap.id}: P0/P1 capability has no functional test or untestableRationale`);
+      errors.push(`${cap.id}: P0/P1 capability has no functional test or untestableRationale`);
     }
 
     const surfaces = cap.surfaces ?? {};
@@ -105,10 +105,10 @@ export function validateCapabilityRegistry({ rootDir = REPO_ROOT, now = Date.now
     if (cap.lastValidated) {
       const age = now - Date.parse(cap.lastValidated);
       if (Number.isFinite(age) && age > STALE_MS) {
-        warnings.push(`${cap.id}: lastValidated older than 90 days (${cap.lastValidated})`);
+        errors.push(`${cap.id}: lastValidated older than 90 days (${cap.lastValidated})`);
       }
     } else if (cap.criticality === 'P0') {
-      warnings.push(`${cap.id}: P0 capability never validated (lastValidated null)`);
+      errors.push(`${cap.id}: P0 capability never validated (lastValidated null)`);
     }
 
     for (const dep of cap.dependencies?.skills ?? []) {

package/lib/sandbox.mjs

@@ -55,7 +55,7 @@ export function createSandbox({ profile = null, seedContext = null } = {}) {
   fs.writeFileSync(path.join(root, '.cx', 'context.md'), ctx);
 
   const cfg = { version: 1, alias: 'Construct', deployment: { mode: 'solo' } };
-  if (profile) cfg.profile = profile;
+  if (profile) cfg.scope = profile;
   fs.writeFileSync(path.join(root, 'construct.config.json'), JSON.stringify(cfg, null, 2) + '\n');
 
   spawnSync('git', ['init', '--quiet'], { cwd: root, stdio: 'ignore' });

package/lib/service-manager.mjs

@@ -391,7 +391,16 @@ export async function startServices({
       results.push({ name: 'Memory (cm)', url: `http://127.0.0.1:${ports.memory}`, status: 'reused' });
     } else {
       const cm = wrapServiceSpawn('cm', ['serve', '--port', String(ports.memory)], homeDir, { env: liveEnv });
-      spawnDetachedFn(cm.command, cm.args, homeDir, 'cm.log');
+      const cmSpawn = spawnDetachedFn(cm.command, cm.args, homeDir, 'cm.log');
+      try {
+        if (cmSpawn?.child?.pid) {
+          writeJson(portOwnershipPath(ports.memory, homeDir), {
+            pid: cmSpawn.child.pid, command: `${cm.command} ${cm.args.join(' ')}`,
+            cwd: process.cwd(), marker: 'construct', constructManaged: true,
+            startedAt: new Date().toISOString(),
+          });
+        }
+      } catch { /* ownership record is advisory */ }
       results.push({ name: 'Memory (cm)', url: `http://127.0.0.1:${ports.memory}`, status: 'started' });
     }
   } else if (wants('memory')) {
@@ -404,7 +413,16 @@ export async function startServices({
       results.push({ name: 'OpenCode', url: `http://127.0.0.1:${ports.bridge}`, status: 'reused' });
     } else {
       const opencode = wrapServiceSpawn('opencode', ['serve', '--port', String(ports.bridge)], homeDir, { env: liveEnv });
-      spawnDetachedFn(opencode.command, opencode.args, homeDir, 'opencode.log');
+      const ocSpawn = spawnDetachedFn(opencode.command, opencode.args, homeDir, 'opencode.log');
+      try {
+        if (ocSpawn?.child?.pid) {
+          writeJson(portOwnershipPath(ports.bridge, homeDir), {
+            pid: ocSpawn.child.pid, command: `${opencode.command} ${opencode.args.join(' ')}`,
+            cwd: process.cwd(), marker: 'construct', constructManaged: true,
+            startedAt: new Date().toISOString(),
+          });
+        }
+      } catch { /* ownership record is advisory */ }
       results.push({ name: 'OpenCode', url: `http://127.0.0.1:${ports.bridge}`, status: 'started' });
     }
   }
@@ -420,7 +438,16 @@ export async function startServices({
         const proxyPath = path.join(INSTALL_ROOT, 'lib', 'bridges', 'copilot-proxy.mjs');
         if (fs.existsSync(proxyPath)) {
           const copilot = wrapServiceSpawn('node', [proxyPath, '--port', String(ports.copilotBridge)], homeDir, { env: liveEnv });
-          spawnDetachedFn(copilot.command, copilot.args, homeDir, 'copilot-bridge.log');
+          const copilotSpawn = spawnDetachedFn(copilot.command, copilot.args, homeDir, 'copilot-bridge.log');
+          try {
+            if (copilotSpawn?.child?.pid) {
+              writeJson(portOwnershipPath(ports.copilotBridge, homeDir), {
+                pid: copilotSpawn.child.pid, command: `${copilot.command} ${copilot.args.join(' ')}`,
+                cwd: process.cwd(), marker: 'construct', constructManaged: true,
+                startedAt: new Date().toISOString(),
+              });
+            }
+          } catch { /* ownership record is advisory */ }
           results.push({ name: 'Copilot Bridge', url: `http://127.0.0.1:${ports.copilotBridge}`, status: 'started' });
         } else {
           results.push({ name: 'Copilot Bridge', status: 'unavailable', note: 'copilot-proxy binary missing in lib/bridges/' });
@@ -476,16 +503,39 @@ async function emitServiceFailures(results) {
   } catch { /* best effort */ }
 }
 
-function killPortOwners(port, spawnSyncFn = spawnSync) {
+// Ownership record path for a port. startServices writes one when it spawns a service;
+// killPortOwners reads it before sending SIGTERM so a foreign process that happens to
+// occupy a configured port is never signalled.
+
+function portOwnershipPath(port, homeDir) {
+  return path.join(runtimeStateDir(homeDir), `port-${port}.json`);
+}
+
+// Predicate: does a process record represent a Construct-owned service? A record is
+// owned when it carries a Construct env/marker set at spawn time. A foreign process or
+// a record from before the ownership contract was introduced is not owned.
+
+export function isConstructOwnedPort(processRecord, { port } = {}) {
+  if (!processRecord || typeof processRecord !== 'object') return false;
+  return Boolean(processRecord.marker === 'construct' || processRecord.constructManaged === true);
+}
+
+function killPortOwners(port, spawnSyncFn = spawnSync, homeDir = os.homedir()) {
   if (!port || !Number.isInteger(port) || port <= 0) return false;
   try {
     const result = spawnSyncFn('lsof', ['-t', `-i:${port}`], { encoding: 'utf8' });
     const pids = (result.stdout || '').trim().split(/\s+/).filter(Boolean).map(Number).filter((n) => n > 0);
     if (pids.length === 0) return false;
+
+    // Only signal a PID if we have a durable Construct ownership record for this port
+    // AND it names this exact PID. A foreign owner gets reported, not killed.
+    const ownerRecord = readJson(portOwnershipPath(port, homeDir));
+    let killed = false;
     for (const pid of pids) {
-      try { process.kill(pid, 'SIGTERM'); } catch { /* already gone */ }
+      if (!ownerRecord || ownerRecord.pid !== pid || !isConstructOwnedPort(ownerRecord)) continue;
+      try { process.kill(pid, 'SIGTERM'); killed = true; } catch { /* already gone */ }
     }
-    return true;
+    return killed;
   } catch {
     return false;
   }
@@ -507,15 +557,15 @@ export async function stopServices({
   const envPath = getUserEnvPath(homeDir);
   const envValues = parseEnvFile(envPath);
   const memoryPort = Number(envValues.MEMORY_PORT) || derivedMemoryPort();
-  const cmKilled = killPortOwners(memoryPort, spawnSyncFn);
+  const cmKilled = killPortOwners(memoryPort, spawnSyncFn, homeDir);
   results.push({ name: 'Memory (cm)', status: cmKilled ? 'stopped' : 'not-running' });
 
   const bridgePort = Number(envValues.BRIDGE_PORT) || 5173;
-  const openCodeKilled = killPortOwners(bridgePort, spawnSyncFn);
+  const openCodeKilled = killPortOwners(bridgePort, spawnSyncFn, homeDir);
   results.push({ name: 'OpenCode', status: openCodeKilled ? 'stopped' : 'not-running' });
 
   const copilotBridgePort = Number(envValues.COPILOT_BRIDGE_PORT) || 5174;
-  const copilotBridgeKilled = killPortOwners(copilotBridgePort, spawnSyncFn);
+  const copilotBridgeKilled = killPortOwners(copilotBridgePort, spawnSyncFn, homeDir);
   results.push({ name: 'Copilot Bridge', status: copilotBridgeKilled ? 'stopped' : 'not-running' });
 
   const stopped = results.filter((r) => r.status === 'stopped' || r.status === 'cleaned').map((r) => r.name);

package/lib/storage/admin.mjs

@@ -3,6 +3,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { resolveWithinRoot } from '../path-policy.mjs';
 
 export function inferProjectName(cwd) {
   return path.basename(cwd) || 'construct';
@@ -54,8 +55,12 @@ export async function deleteIngestedArtifacts(rootDir, { files = [], confirm = f
   let deletedCount = 0;
   const internalDir = path.join(rootDir, '.cx', 'knowledge', 'internal');
   
-  for (const f of files) {
-    const p = path.join(internalDir, f);
+  // Resolve every model-supplied entry against the ingested root first; an escaping
+  // path throws before any deletion, so a ../ traversal can neither delete an out-of-root
+  // file nor partially delete the set.
+
+  const targets = files.map((f) => resolveWithinRoot(internalDir, f));
+  for (const p of targets) {
     if (fs.existsSync(p)) {
       fs.rmSync(p);
       deletedCount++;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "type": "module",
   "packageManager": "npm@11.5.1",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
@@ -26,6 +26,10 @@
     "platforms/**",
     "templates/**",
     "templates/distribution/**",
+    "schemas/**",
+    "registry/**",
+    "config/**",
+    "vendor/**",
     "scripts/sync-specialists.mjs",
     "README.md",
     ".env.example"
@@ -120,6 +124,7 @@
     "@eslint/js": "^9.39.4",
     "c8": "^11.0.0",
     "esbuild": "^0.28.1",
+    "postject": "1.0.0-alpha.6",
     "eslint": "^10.4.1",
     "globals": "^17.6.0",
     "ink-testing-library": "^4.0.0"

package/registry/agent-manifest.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "https://construct.dev/schemas/agent-manifest.v1.json",
+  "version": 1,
+  "kind": "agent-execution-manifest",
+  "description": "How an agent should reach Construct: MCP-first tool surface, with OpenCode as the primary human conversation surface. Source-of-truth values (core tool set, long-tail dispatcher) are verified against lib/mcp/server.mjs by tests/agent-manifest.test.mjs.",
+  "sources": {
+    "coreTools": "lib/mcp/server.mjs (CORE_TOOL_NAMES)",
+    "longTail": "lib/mcp/server.mjs (CONSTRUCT_CALL_TOOL)",
+    "surfaceTiers": "lib/registry/surface-map.mjs (SURFACE_TIERS, COMMAND_SURFACE)",
+    "capabilities": "registry/capabilities.json",
+    "credentials": "lib/mcp/server.mjs (config.env injection), lib/providers/secret-resolver.mjs"
+  },
+  "toolSurface": {
+    "model": "core-plus-long-tail",
+    "rationale": "ListTools front-loads a small core; everything else is reachable through the `call` gateway or discovered by intent via `find_tool`, so the schema stays small and small models stop hallucinating tool names. The long tail is reachable, just not front-loaded.",
+    "core": [
+      {
+        "name": "orchestration_policy",
+        "use": "Classify intent and get the specialist routing policy for a request."
+      },
+      {
+        "name": "orchestration_run",
+        "use": "Dispatch the routed specialist chain for a request after classifying it."
+      },
+      {
+        "name": "get_skill",
+        "use": "Fetch a role or domain skill playbook by id."
+      },
+      {
+        "name": "get_template",
+        "use": "Read a doc template (prd, adr, runbook, ...) by name before authoring an artifact."
+      },
+      {
+        "name": "search_skills",
+        "use": "Find relevant skills by query."
+      },
+      {
+        "name": "knowledge_search",
+        "use": "Search the project knowledge base."
+      },
+      {
+        "name": "memory_search",
+        "use": "Search durable cross-session memory."
+      },
+      {
+        "name": "project_context",
+        "use": "Read the active project context and working state."
+      },
+      {
+        "name": "summarize_diff",
+        "use": "Summarize a code diff for review or handoff."
+      },
+      {
+        "name": "find_tool",
+        "use": "Find tools by intent when you don't know the exact name; returns ranked tools with schemas."
+      },
+      {
+        "name": "author_artifact",
+        "use": "Materialize a typed artifact you drafted (PRD/ADR/RFC/…) and run the release gate."
+      },
+      {
+        "name": "document_export",
+        "use": "Convert a markdown file to PDF/DOCX/HTML/deck and write it to a path."
+      },
+      {
+        "name": "publish_run",
+        "use": "Run the publish pipeline to export an artifact (figures and demos optional)."
+      },
+      {
+        "name": "artifact_workflow",
+        "use": "Plan a manifest-backed artifact workflow; validate or export locally."
+      },
+      {
+        "name": "workflow_invoke",
+        "use": "Invoke an embedded Construct workflow (prd-draft, architecture-review, …)."
+      },
+      {
+        "name": "triage_recommend",
+        "use": "Recommend intake triage — type, owner, and routing — for a new signal."
+      },
+      {
+        "name": "orchestration_readiness",
+        "use": "Verify that the active MCP session has Construct orchestration tools attached; returns a typed failure reason and next step."
+      }
+    ],
+    "longTail": {
+      "tool": "call",
+      "use": "Invoke any non-core Construct tool by name: put the tool name in `tool` and its arguments in `args`. Call find_tool to discover the right tool by intent; the catalog of valid names is the `tool` enum.",
+      "rationale": "One dispatcher reuses the same handlers, so collapsing the surface costs no capability — every tool stays reachable by name. The manifest deliberately does not enumerate the full tool list; the live catalog is the `call` enum in lib/mcp/server.mjs, and find_tool ranks it by intent. The former gateway name `construct_call` is recovered tolerantly, so a stale name still resolves."
+    }
+  },
+  "humanEntry": {
+    "command": "opencode",
+    "subcommand": null,
+    "use": "A human uses OpenCode as the primary conversation surface after `construct sync` installs the Construct front-door agent, MCP wiring, and runtime plugin. The `construct` CLI remains setup/admin/headless infrastructure.",
+    "rationale": "Construct no longer ships a local conversation UI; OpenCode is primary and other public hosts use generated adapters or MCP.",
+    "surface": "opencode"
+  },
+  "credentials": {
+    "policy": "mcp-mediated",
+    "guidance": "Agents never resolve secrets themselves. The Construct MCP server applies config.env to its process environment at startup, so provider credentials are present for every tool call. The shared secret resolver walks the trusted sources (process env, config.env, ~/.env, project .env, shell rc) and resolves any 1Password reference internally.",
+    "doNot": "Do not instruct or run manual `op read` / `op://` lookups, and do not ask the user to paste keys. MCP tool outputs expose only env-key names and a configured boolean, never credential values.",
+    "source": "lib/mcp/server.mjs config.env injection; lib/providers/secret-resolver.mjs; lib/providers/credential-bootstrap.mjs"
+  },
+  "mcpGaps": {
+    "note": "True gaps only: capabilities that declare MCP unsupported. Flag variants of an MCP-backed capability and retired commands are not gaps.",
+    "gaps": [
+      {
+        "id": "oracle.meta-review",
+        "name": "Oracle Meta-Review",
+        "mcp": "unsupported",
+        "cliFallback": "construct oracle review",
+        "reason": "Declares surfaces.mcp.supported=false in registry/capabilities.json; reach it via the CLI --json twin."
+      }
+    ]
+  }
+}