total-recall-brain 3.31.2 → 3.32.0

package/src/core/daemon-control.mjs

@@ -9,7 +9,11 @@ import { agentDir, brainDir } from './config.mjs';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.join(__dirname, '..', '..');
 
-const PID_FILE = path.join(brainDir, 'logs', 'daemon.pid');
+// The daemon's own lockfile (daemon-loop acquirePidLock). start/stop/status read the
+// same file: a separate logs/daemon.pid let `daemon stop` miss the live daemon and
+// leave it running old code alongside a newly started one.
+export const DAEMON_PID_FILE = path.join(brainDir, 'daemon.pid');
+const PID_FILE = DAEMON_PID_FILE;
 const LOG_FILE = path.join(brainDir, 'logs', 'daemon.log');
 
 /**
@@ -104,8 +108,8 @@ export function startDaemon() {
 
   child.unref();
   
-  // Write the PID file
-  fs.writeFileSync(PID_FILE, String(child.pid), 'utf8');
+  // The daemon writes DAEMON_PID_FILE itself when it acquires its lock;
+  // pre-writing the child's pid here made the child see a live lock and exit.
   fs.closeSync(logFd);
 
   logger.info('daemon-control', `Active Intelligence Daemon started detached (PID ${child.pid}).`);
@@ -113,10 +117,13 @@ export function startDaemon() {
 }
 
 /**
- * Stops the running background daemon.
- * @returns {boolean} True if successfully stopped, false otherwise.
+ * Stops the running background daemon and waits for the process to exit.
+ * The daemon owns its lockfile and removes it on exit, so a start issued right
+ * after stop can never run alongside a daemon that is still finishing work.
+ * @param {{ graceMs?: number, pollMs?: number }} [opts]
+ * @returns {Promise<boolean>} True if a daemon was running and has exited.
  */
-export function stopDaemon() {
+export async function stopDaemon({ graceMs = 35_000, pollMs = 250 } = {}) {
   const pid = readPid();
   if (!pid) {
     // Clear PID file in case it was a stale/dead record
@@ -126,19 +133,31 @@ export function stopDaemon() {
     return false;
   }
 
+  const alive = () => { try { process.kill(pid, 0); return true; } catch { return false; } };
   try {
     process.kill(pid, 'SIGTERM');
     logger.info('daemon-control', `Sent SIGTERM to daemon PID ${pid}.`);
-    
-    // Wait briefly and verify cleanup
-    try {
-      if (fs.existsSync(PID_FILE)) fs.unlinkSync(PID_FILE);
-    } catch {}
-    return true;
   } catch (err) {
     logger.error('daemon-control', `Failed to terminate daemon PID ${pid}: ${err.message}`);
     return false;
   }
+
+  const deadline = Date.now() + graceMs;
+  while (alive() && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+  if (alive()) {
+    logger.warn('daemon-control', `Daemon PID ${pid} still running after ${graceMs}ms — sending SIGKILL.`);
+    try { process.kill(pid, 'SIGKILL'); } catch {}
+  }
+
+  // A SIGKILLed daemon cannot run its exit handler; drop its lock if still ours.
+  try {
+    if (fs.existsSync(PID_FILE) && parseInt(fs.readFileSync(PID_FILE, 'utf8').trim(), 10) === pid) {
+      fs.unlinkSync(PID_FILE);
+    }
+  } catch {}
+  return true;
 }
 
 /**

package/src/core/daemon-loop.mjs

@@ -12,6 +12,7 @@
  */
 
 import path from 'path';
+import { DAEMON_PID_FILE } from './daemon-control.mjs';
 import fs from 'fs';
 import { fileURLToPath } from 'node:url';
 import { readProcessCommand, entryPathHint, shouldHonorPidLock } from './pid-lock.mjs';
@@ -102,7 +103,7 @@ export function writeInterrupt(message) {
 
 // ─── PID Lockfile ───────────────────────────────────────────────────────────────
 
-const PID_FILE = path.join(BRAIN_DIR, 'daemon.pid');
+const PID_FILE = DAEMON_PID_FILE;
 
 /**
  * Attempt to acquire the PID lockfile. If another daemon is alive, exit.
@@ -112,7 +113,7 @@ export function acquirePidLock() {
   try {
     if (fs.existsSync(PID_FILE)) {
       const existingPid = parseInt(fs.readFileSync(PID_FILE, 'utf8').trim(), 10);
-      if (existingPid && !isNaN(existingPid)) {
+      if (existingPid && !isNaN(existingPid) && existingPid !== process.pid) {
         // Liveness alone cannot tell our daemon from whatever else inherited
         // the number after a reboot — observed here holding a PID that had
         // since been handed to an unrelated desktop app, which would refuse
@@ -218,14 +219,20 @@ function shutdown(signal) {
       });
     })
     .finally(() => {
-      try {
-        releasePidLock();
-      } catch {
-        // Lock already gone — nothing to release.
-      }
+      // Keep the PID lock until the process really exits (see the 'exit'
+      // handler): releasing it here let a new daemon start while this one was
+      // still finishing its current task.
     });
 }
 
+process.on('exit', () => {
+  try {
+    releasePidLock();
+  } catch {
+    // Lock already gone — nothing to release.
+  }
+});
+
 process.on('SIGTERM', () => shutdown('SIGTERM'));
 process.on('SIGINT', () => shutdown('SIGINT'));
 

package/src/core/plugin-loader.mjs

@@ -2,6 +2,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { fileURLToPath } from 'node:url';
+import { validateAppCliSpec } from './app-deploy/runtime-cli.mjs';
+import { validateUiSpec } from './app-deploy/ui-elements.mjs';
 
 const ID_PATTERN = /^[a-z][a-z0-9-]{1,63}$/;
 const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
@@ -226,27 +228,25 @@ export function validatePluginManifest(manifest) {
           errors.push("Each entry in 'commands' must be an object");
           continue;
         }
-        if (!c.name || typeof c.name !== 'string') {
-          errors.push("Each command entry must have a string 'name'");
+        if (typeof c.name !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(c.name)) {
+          errors.push("Each command entry must have a safe lowercase kebab-case 'name'");
         }
         if (!c.handler || !isSafeRelativePath(c.handler)) {
           errors.push(`Command '${c.name || 'unknown'}' has invalid or unsafe 'handler': must be safe relative path`);
         }
+        if (c.background !== undefined && typeof c.background !== 'boolean') {
+          errors.push(`Command '${c.name || 'unknown'}' background must be boolean`);
+        }
       }
     }
   }
 
   if (manifest.ui !== undefined) {
-    if (typeof manifest.ui !== 'object' || manifest.ui === null) {
-      errors.push("'ui' must be an object");
-    } else {
-      if (manifest.ui.design_tokens !== undefined && !isSafeRelativePath(manifest.ui.design_tokens)) {
-        errors.push("'ui.design_tokens' must be a safe relative path");
-      }
-      if (manifest.ui.elements !== undefined && !Array.isArray(manifest.ui.elements)) {
-        errors.push("'ui.elements' must be an array");
-      }
-    }
+    errors.push(...validateUiSpec(manifest.ui));
+  }
+
+  if (manifest.app_cli !== undefined) {
+    errors.push(...validateAppCliSpec(manifest.app_cli));
   }
 
   if (manifest.openwiki_hubs !== undefined) {

package/src/core/schema.mjs

@@ -231,6 +231,63 @@ export const ConversationSchema = z.object({
   created_at: ssssDatetime().optional(),
 });
 
+// SSSS 0.10 core primitives (spec §5.4). `role` and `thread` are the canonical
+// forms of `security_role` and `conversation`, which stay for existing vaults.
+export const AssetSchema = z.object({
+  type: z.literal('asset'),
+  name: z.string(),
+  mime_type: z.string(),
+  encoding: z.enum(['base64', 'utf-8', 'none']),
+  slug: z.string().optional(),
+  hash: z.string().optional(),
+  size_bytes: z.number().int().nonnegative().optional(),
+  description: z.string().optional(),
+});
+
+export const ResourceSchema = z.object({
+  type: z.literal('resource'),
+  name: z.string(),
+  kind: z.string(),
+  status: z.enum(['bound', 'unbound', 'pending', 'error']),
+  slug: z.string().optional(),
+  description: z.string().optional(),
+  binds: z.unknown().optional(),
+  provisioning: z.unknown().optional(),
+});
+
+export const RoleSchema = z.object({
+  type: z.literal('role'),
+  name: z.string(),
+  permissions: z.array(z.string()),
+  description: z.string().optional(),
+});
+
+export const TriggerSchema = z.object({
+  type: z.literal('trigger'),
+  name: z.string(),
+  source: z.enum(['cron', 'interval', 'webhook', 'event', 'file_change', 'condition', 'manual']),
+  status: z.enum(['active', 'paused', 'disabled']),
+  slug: z.string().optional(),
+  description: z.string().optional(),
+  cron: z.string().optional(),
+  interval: z.union([z.string(), z.number()]).optional(),
+  timezone: z.string().optional(),
+  target_workflow: z.string().optional(),
+  target_params: z.record(z.unknown()).optional(),
+  concurrency: z.enum(['allow_parallel', 'skip_if_running', 'enqueue', 'replace']).optional(),
+  misfire_policy: z.enum(['skip', 'run_once', 'catch_up']).optional(),
+});
+
+export const ThreadSchema = z.object({
+  type: z.literal('thread'),
+  thread_id: z.string(),
+  workspace_id: z.string().optional(),
+  user_id: z.string().optional(),
+  status: z.enum(['active', 'archived', 'closed']).optional(),
+  turn_count: z.number().int().optional(),
+  created_at: ssssDatetime().optional(),
+});
+
 export const RunSchema = z.object({
   type: z.literal('run'),
   run_id: z.string(),
@@ -1162,25 +1219,22 @@ export const AccessGrantSchema = z.object({
 }).passthrough();
 
 /**
- * Canonical repo-layer skill configuration record.
- * Persisted as an SSSS document in the project vault (e.g. `system/skills/<id>.md`).
- * Controls gate commands, tier rules, and repo customizations.
- * Projected into `config.json` for skill scripts to read.
+ * Canonical repo-layer configuration for a layered skill, stored in the repo's
+ * project vault at `system/skills/<skill_id>.md` and written only through the
+ * operation service (`src/core/skill-config.mjs`). The shape of `config` is the
+ * skill core's contract (`core/config.schema.json`), not this host type, so no
+ * skill-specific fields belong here. `config.json` beside the skill is a
+ * projection of `config`, rebuilt after every write.
  */
 export const SkillConfigSchema = z.object({
   type: z.literal('skill_config'),
   title: z.string().min(1),
   description: z.string().min(1),
   timestamp: ssssDatetime(),
-  skill_id: z.string().regex(/^[a-z][a-z0-9-]{1,63}$/),
-  version: z.string().min(1),
-  config: z.record(z.any()).default({}),
-  tiers: z.record(z.any()).optional().default({}),
-  gates: z.array(z.object({
-    name: z.string(),
-    command: z.string(),
-    tier: z.string().optional()
-  })).optional().default([]),
+  skill_id: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/),
+  config: z.record(z.string(), z.any()),
+  /** SHA-256 of the core/config.schema.json the config was validated against. */
+  schema_sha256: z.string().regex(/^[0-9a-f]{64}$/),
   created_at: ssssDatetime(),
   updated_at: ssssDatetime().optional()
 }).passthrough();
@@ -1221,6 +1275,11 @@ export const SSSS_SCHEMAS = {
   security_role: SecurityRoleSchema,
   model: ModelSchema,
   conversation: ConversationSchema,
+  asset: AssetSchema,
+  resource: ResourceSchema,
+  role: RoleSchema,
+  trigger: TriggerSchema,
+  thread: ThreadSchema,
   run: RunSchema,
   primitive: PrimitiveSchema,
   proposal: ProposalSchema,

package/src/core/skill-config.mjs

@@ -0,0 +1,376 @@
+/**
+ * Repo-layer configuration for layered skills.
+ *
+ * A layered skill's plugin-owned core ships the layer contract as
+ * `core/config.schema.json` (JSON Schema, root type object) and may ship
+ * `core/detect.mjs`. The canonical repo config is a `skill_config` SSSS
+ * document in the repo's project vault (`system/skills/<id>.md`), written
+ * through the operation service after the whole config validates against the
+ * contract. `config.json` next to `core/` is a projection of that record for
+ * the core scripts to read; it is rebuilt after every write.
+ *
+ * Collections: an array property annotated with `"x-collection": "<noun>"`
+ * gets `<noun> list|add|remove` verbs; items are keyed by `"x-key"` (default
+ * `name`).
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { pathToFileURL } from 'node:url';
+import { z } from 'zod';
+import { writeVfsDocument } from './ssss-operation-service.mjs';
+import { findVfsDocumentByPath } from './vfs-documents.mjs';
+
+const SKILL_ID = /^[a-z][a-z0-9-]{0,63}$/;
+const FORBIDDEN_SEGMENTS = new Set(['__proto__', 'prototype', 'constructor']);
+
+export class SkillConfigError extends Error {
+  constructor(message, { exitCode = 2, issues = [] } = {}) {
+    super(message);
+    this.exitCode = exitCode;
+    this.issues = issues;
+  }
+}
+
+function regularFile(file) {
+  return fs.existsSync(file) && !fs.lstatSync(file).isSymbolicLink() && fs.statSync(file).isFile();
+}
+
+/** Locate a deployed layered skill inside a repository. */
+export function resolveSkillDir(repoRoot, skillId) {
+  if (!SKILL_ID.test(skillId || '')) throw new SkillConfigError('Skill id must be lowercase kebab-case');
+  const skillDir = path.join(path.resolve(repoRoot), '.agent', 'skills', skillId);
+  if (!fs.existsSync(skillDir)) throw new SkillConfigError(`Skill '${skillId}' is not deployed in ${repoRoot}`, { exitCode: 1 });
+  if (fs.lstatSync(skillDir).isSymbolicLink()) throw new SkillConfigError(`Refusing symlinked skill directory: ${skillDir}`, { exitCode: 1 });
+  return skillDir;
+}
+
+/** Load and compile the core-owned layer contract. */
+export function loadConfigSchema(skillDir) {
+  const coreDir = path.join(skillDir, 'core');
+  if (fs.existsSync(coreDir) && fs.lstatSync(coreDir).isSymbolicLink()) {
+    throw new SkillConfigError(`Refusing symlinked skill core: ${coreDir}`, { exitCode: 1 });
+  }
+  const schemaPath = path.join(coreDir, 'config.schema.json');
+  if (!regularFile(schemaPath)) {
+    throw new SkillConfigError(`Skill has no config contract (expected core/config.schema.json)`, { exitCode: 1 });
+  }
+  const raw = fs.readFileSync(schemaPath);
+  let schema;
+  try { schema = JSON.parse(raw.toString('utf8')); }
+  catch (error) { throw new SkillConfigError(`core/config.schema.json is not valid JSON: ${error.message}`, { exitCode: 1 }); }
+  if (schema?.type !== 'object') throw new SkillConfigError('core/config.schema.json must describe an object', { exitCode: 1 });
+  let validator;
+  try { validator = z.fromJSONSchema(schema); }
+  catch (error) { throw new SkillConfigError(`core/config.schema.json is not a supported JSON Schema: ${error.message}`, { exitCode: 1 }); }
+  return { schema, validator, schemaPath, sha256: crypto.createHash('sha256').update(raw).digest('hex') };
+}
+
+function formatIssues(issues) {
+  return issues.map((issue) => `${issue.path.length ? issue.path.join('.') : '(root)'}: ${issue.message}`);
+}
+
+/** Validate a whole config document; returns the normalized value (defaults applied). */
+export function validateSkillConfig(contract, value) {
+  const result = contract.validator.safeParse(value);
+  if (result.success) return { valid: true, value: result.data, errors: [] };
+  return { valid: false, value: null, errors: formatIssues(result.error.issues) };
+}
+
+export function configPath(skillDir) {
+  return path.join(skillDir, 'config.json');
+}
+
+export function recordPath(skillId) {
+  return `system/skills/${skillId}.md`;
+}
+
+/** The repo's own project vault. Never walks up into a parent project's brain. */
+export function projectVaultFor(skillDir) {
+  const repoRoot = path.resolve(skillDir, '..', '..', '..');
+  const brain = path.join(repoRoot, '.agent', 'skills', 'total-recall');
+  if (!regularFile(path.join(brain, 'SKILL.md'))) {
+    throw new SkillConfigError(`No project brain in ${repoRoot}; run 'total-recall init --project' there first`, { exitCode: 1 });
+  }
+  return path.join(brain, 'memory-vault');
+}
+
+function readProjection(skillDir) {
+  const file = configPath(skillDir);
+  if (!fs.existsSync(file)) return null;
+  if (!regularFile(file)) throw new SkillConfigError(`Refusing non-regular config file: ${file}`, { exitCode: 1 });
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (error) { throw new SkillConfigError(`config.json is not valid JSON: ${error.message}`, { exitCode: 1 }); }
+}
+
+/**
+ * Current repo config. `source` is 'record' (canonical), 'projection' (a
+ * config.json with no record yet, e.g. a repo skill awaiting import), or null.
+ */
+export function readSkillConfigState(skillDir) {
+  const skillId = path.basename(skillDir);
+  const record = findVfsDocumentByPath(recordPath(skillId), projectVaultFor(skillDir));
+  const projection = readProjection(skillDir);
+  if (record) {
+    if (record.type !== 'skill_config' || !record.config || typeof record.config !== 'object') {
+      throw new SkillConfigError(`${recordPath(skillId)} is not a skill_config record`, { exitCode: 1 });
+    }
+    return { config: record.config, source: 'record', record, projection, inSync: isDeepStrictEqual(projection, record.config) };
+  }
+  return { config: projection, source: projection === null ? null : 'projection', record: null, projection, inSync: projection === null };
+}
+
+export function readSkillConfig(skillDir) {
+  return readSkillConfigState(skillDir).config;
+}
+
+/** Rebuild config.json from the canonical record (atomic replace). */
+export function projectSkillConfig(skillDir, config) {
+  const file = configPath(skillDir);
+  if (fs.existsSync(file) && !regularFile(file)) throw new SkillConfigError(`Refusing non-regular config file: ${file}`, { exitCode: 1 });
+  const temp = path.join(skillDir, `.config.json.${process.pid}.${Date.now()}.tmp`);
+  fs.writeFileSync(temp, `${JSON.stringify(config, null, 2)}\n`, { encoding: 'utf8', flag: 'wx', mode: 0o644 });
+  try { fs.renameSync(temp, file); }
+  catch (error) { fs.rmSync(temp, { force: true }); throw error; }
+}
+
+/**
+ * The single write path for repo-layer config: validate against the core
+ * contract, commit the skill_config record through the SSSS operation service,
+ * then rebuild the config.json projection.
+ */
+export async function writeSkillConfig(skillDir, contract, value) {
+  const checked = validateSkillConfig(contract, value);
+  if (!checked.valid) {
+    throw new SkillConfigError(`Config does not satisfy core/config.schema.json:\n  ${checked.errors.join('\n  ')}`, { issues: checked.errors });
+  }
+  const file = configPath(skillDir);
+  if (fs.existsSync(file) && !regularFile(file)) throw new SkillConfigError(`Refusing non-regular config file: ${file}`, { exitCode: 1 });
+  const skillId = path.basename(skillDir);
+  const vaultRoot = projectVaultFor(skillDir);
+  const existing = findVfsDocumentByPath(recordPath(skillId), vaultRoot);
+  const now = new Date().toISOString();
+  const createdAt = existing?.created_at ? new Date(existing.created_at).toISOString() : now;
+  await writeVfsDocument(recordPath(skillId), {
+    type: 'skill_config',
+    title: `Skill config: ${skillId}`,
+    description: `Repo-layer configuration for the ${skillId} skill.`,
+    timestamp: now,
+    skill_id: skillId,
+    config: checked.value,
+    schema_sha256: contract.sha256,
+    created_at: createdAt,
+    ...(existing ? { updated_at: now } : {}),
+  }, '', { actorRole: 'system', intent: `Update repo config for skill ${skillId}`, vaultRoot });
+  projectSkillConfig(skillDir, checked.value);
+  return checked.value;
+}
+
+function splitPath(dotted) {
+  if (!dotted) return [];
+  const segments = String(dotted).split('.');
+  for (const segment of segments) {
+    if (!segment || FORBIDDEN_SEGMENTS.has(segment)) throw new SkillConfigError(`Invalid config path '${dotted}'`);
+  }
+  return segments;
+}
+
+export function getConfigValue(config, dotted) {
+  let node = config;
+  for (const segment of splitPath(dotted)) {
+    if (node === null || typeof node !== 'object' || !Object.hasOwn(node, segment)) return undefined;
+    node = node[segment];
+  }
+  return node;
+}
+
+/** Return a copy of `config` with `dotted` set (or removed when `value` is undefined). */
+export function setConfigValue(config, dotted, value) {
+  const segments = splitPath(dotted);
+  if (segments.length === 0) throw new SkillConfigError('A config path is required');
+  const root = structuredClone(config ?? {});
+  let node = root;
+  for (const segment of segments.slice(0, -1)) {
+    if (node[segment] === undefined) node[segment] = {};
+    if (node[segment] === null || typeof node[segment] !== 'object') {
+      throw new SkillConfigError(`Config path '${dotted}' crosses a non-object value at '${segment}'`);
+    }
+    node = node[segment];
+  }
+  const last = segments.at(-1);
+  if (value === undefined) delete node[last];
+  else node[last] = value;
+  return root;
+}
+
+/** CLI values: JSON when it parses (numbers, booleans, arrays, objects), otherwise a string. */
+export function parseCliValue(raw) {
+  try { return JSON.parse(raw); } catch { return raw; }
+}
+
+/** Array properties exposed as collection verbs, keyed by noun. */
+export function listCollections(schema) {
+  const collections = {};
+  for (const [property, definition] of Object.entries(schema.properties || {})) {
+    const noun = definition?.['x-collection'];
+    if (definition?.type === 'array' && typeof noun === 'string' && SKILL_ID.test(noun)) {
+      collections[noun] = { property, key: definition['x-key'] || 'name' };
+    }
+  }
+  return collections;
+}
+
+/** Parse `key=value` pairs (or one JSON object) into a collection item. */
+export function parseCollectionItem(args) {
+  if (args.length === 1 && args[0].trim().startsWith('{')) {
+    const item = parseCliValue(args[0]);
+    if (item && typeof item === 'object' && !Array.isArray(item)) return item;
+    throw new SkillConfigError('Collection item must be a JSON object');
+  }
+  if (args.length === 0) throw new SkillConfigError('Collection item needs key=value fields or a JSON object');
+  let item = {};
+  for (const arg of args) {
+    const at = arg.indexOf('=');
+    if (at <= 0) throw new SkillConfigError(`Expected key=value, got '${arg}'`);
+    item = setConfigValue(item, arg.slice(0, at), parseCliValue(arg.slice(at + 1)));
+  }
+  return item;
+}
+
+export function addCollectionItem(config, collection, item) {
+  const current = getConfigValue(config, collection.property) ?? [];
+  if (!Array.isArray(current)) throw new SkillConfigError(`'${collection.property}' is not an array`);
+  const key = item?.[collection.key];
+  if (key === undefined || key === '') throw new SkillConfigError(`Item needs a '${collection.key}' field`);
+  if (current.some((entry) => entry?.[collection.key] === key)) {
+    throw new SkillConfigError(`${collection.property} already has ${collection.key} '${key}'`);
+  }
+  return setConfigValue(config, collection.property, [...current, item]);
+}
+
+export function removeCollectionItem(config, collection, key) {
+  const current = getConfigValue(config, collection.property) ?? [];
+  if (!Array.isArray(current)) throw new SkillConfigError(`'${collection.property}' is not an array`);
+  const next = current.filter((entry) => String(entry?.[collection.key]) !== String(key));
+  if (next.length === current.length) throw new SkillConfigError(`${collection.property} has no ${collection.key} '${key}'`, { exitCode: 1 });
+  return setConfigValue(config, collection.property, next);
+}
+
+/** Run the core's detector. It proposes a config; nothing is written here. */
+export async function detectSkillConfig(skillDir, repoRoot) {
+  const detector = path.join(skillDir, 'core', 'detect.mjs');
+  if (!regularFile(detector)) throw new SkillConfigError('Skill core has no detector (expected core/detect.mjs)', { exitCode: 1 });
+  const mod = await import(`${pathToFileURL(detector).href}?t=${fs.statSync(detector).mtimeMs}`);
+  const detect = mod.detect || mod.default;
+  if (typeof detect !== 'function') throw new SkillConfigError('core/detect.mjs must export detect()', { exitCode: 1 });
+  const proposal = await detect({ repoRoot: path.resolve(repoRoot), skillDir });
+  if (!proposal || typeof proposal !== 'object' || Array.isArray(proposal)) {
+    throw new SkillConfigError('detect() must return a config object', { exitCode: 1 });
+  }
+  return proposal;
+}
+
+/** Required top-level properties still absent from `config`. */
+export function missingRequired(schema, config) {
+  return (schema.required || []).filter((key) => config?.[key] === undefined);
+}
+
+/**
+ * Values at schema locations annotated `"x-command": true`, with their config
+ * paths. A command is a shell-style string or an argv array of strings.
+ */
+export function collectCommandValues(schema, value, at = []) {
+  if (!schema || value === undefined || value === null) return [];
+  if (schema['x-command'] === true && (typeof value === 'string'
+      || (Array.isArray(value) && value.length && value.every((part) => typeof part === 'string')))) {
+    return [{ path: at.join('.'), command: value }];
+  }
+  const found = [];
+  if (schema.type === 'array' && Array.isArray(value) && schema.items) {
+    value.forEach((item, i) => found.push(...collectCommandValues(schema.items, item, [...at, String(i)])));
+  }
+  if (schema.properties && typeof value === 'object' && !Array.isArray(value)) {
+    for (const [key, child] of Object.entries(schema.properties)) {
+      found.push(...collectCommandValues(child, value[key], [...at, key]));
+    }
+  }
+  return found;
+}
+
+function onPath(binary) {
+  for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, binary);
+    try {
+      if (fs.statSync(candidate).isFile()) { fs.accessSync(candidate, fs.constants.X_OK); return true; }
+    } catch { /* keep looking */ }
+  }
+  return false;
+}
+
+/** Whether a gate command's program exists; does not run it. */
+export function resolveCommand(command, repoRoot) {
+  const tokens = Array.isArray(command) ? [...command] : String(command).trim().split(/\s+/).filter(Boolean);
+  while (tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[0])) tokens.shift();
+  const program = tokens[0];
+  if (!program) return { ok: false, reason: 'empty command' };
+  if (path.isAbsolute(program)) {
+    return fs.existsSync(program) ? { ok: true } : { ok: false, reason: `${program} does not exist` };
+  }
+  if (program.includes('/')) {
+    const file = path.resolve(repoRoot, program);
+    const inside = !path.relative(repoRoot, file).startsWith('..');
+    return inside && fs.existsSync(file) ? { ok: true } : { ok: false, reason: `${program} does not exist in the repo` };
+  }
+  if (['npm', 'pnpm', 'yarn', 'bun'].includes(program) && tokens[1] === 'run' && tokens[2]) {
+    let scripts = {};
+    try { scripts = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8')).scripts || {}; } catch { /* no package.json */ }
+    return Object.hasOwn(scripts, tokens[2]) ? { ok: true } : { ok: false, reason: `package.json has no '${tokens[2]}' script` };
+  }
+  return onPath(program) ? { ok: true } : { ok: false, reason: `'${program}' is not on PATH` };
+}
+
+/**
+ * Check a deployed layered skill's repo layer against its core contract.
+ * Shared by `skill status`, `skill config <id> check`, and `app verify`.
+ * Each check is { id, level: 'error'|'warn', ok, message }; `ok` is false when
+ * any error-level check fails.
+ */
+export function checkSkillLayerContract(skillDir) {
+  const skillId = path.basename(skillDir);
+  const repoRoot = path.resolve(skillDir, '..', '..', '..');
+  const checks = [];
+  const add = (id, ok, message, level = 'error') => checks.push({ id, level, ok, message });
+  const result = () => ({ skill_id: skillId, path: skillDir, ok: checks.every((c) => c.ok || c.level !== 'error'), checks });
+
+  let contract;
+  try { contract = loadConfigSchema(skillDir); add('contract', true, 'core/config.schema.json loads'); }
+  catch (error) { add('contract', false, error.message); return result(); }
+
+  let state;
+  try { state = readSkillConfigState(skillDir); }
+  catch (error) { add('record', false, error.message); return result(); }
+  if (state.source === null) { add('record', false, `Not configured; run 'total-recall skill config ${skillId} init'`); return result(); }
+  if (state.source === 'projection') {
+    add('record', false, `config.json is not recorded in SSSS; run 'total-recall skill config ${skillId} import'`);
+  } else {
+    add('record', true, `Recorded at ${recordPath(skillId)}`);
+  }
+
+  const checked = validateSkillConfig(contract, state.config);
+  add('config', checked.valid, checked.valid ? 'Config satisfies the contract' : `Config violates the contract: ${checked.errors.join('; ')}`);
+  if (state.source === 'record') {
+    const current = state.record.schema_sha256 === contract.sha256;
+    add('contract-version', current, current ? 'Validated against the current core contract'
+      : 'The core contract changed since this config was recorded; re-save it to re-validate', 'warn');
+    add('projection', state.inSync, state.inSync ? 'config.json matches the record'
+      : `config.json has drifted from the record; run 'total-recall skill config ${skillId} rebuild'`);
+  }
+  for (const { path: at, command } of collectCommandValues(contract.schema, state.config)) {
+    const resolved = resolveCommand(command, repoRoot);
+    const shown = Array.isArray(command) ? command.join(' ') : command;
+    add(`command:${at}`, resolved.ok, resolved.ok ? `${at}: '${shown}' resolves` : `${at}: ${resolved.reason}`);
+  }
+  return result();
+}