fraim 2.0.351 → 2.0.353

package/dist/src/cli/mcp/fraim-mcp-latest-launcher.js

@@ -64,7 +64,7 @@ const launcherSource = `#!/usr/bin/env node
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
-const { spawnSync } = require('child_process');
+const { spawnSync, spawn } = require('child_process');
 
 const LAUNCHER_VERSION = ${LAUNCHER_VERSION};
 const STALENESS_WINDOW_MS = ${STALENESS_WINDOW_MS};
@@ -75,11 +75,15 @@ const USER_DIR = process.env.FRAIM_USER_DIR || path.join(os.homedir(), '.fraim')
 const STATE_DIR = path.join(USER_DIR, 'mcp-launcher');
 const STATE_PATH = path.join(STATE_DIR, 'latest.json');
 const CACHE_ROOT = path.join(USER_DIR, 'npm-cache', 'mcp');
+const REFRESH_LOCK = path.join(STATE_DIR, 'refresh.lock');
+const REFRESH_LOCK_STALE_MS = 10 * 60 * 1000;
+const launchStartedAt = Date.now();
 
 const commandName = (name) => process.platform === 'win32' ? name + '.cmd' : name;
 const npmCommand = commandName('npm');
 const npxCommand = commandName('npx');
 const rawArgs = process.argv.slice(2);
+const refreshMode = rawArgs[0] === '--refresh-cache';
 const cliMode = rawArgs[0] === '--fraim-cli';
 const cliArgs = cliMode ? rawArgs.slice(1) : (rawArgs.length > 0 ? rawArgs : ['mcp']);
 
@@ -172,6 +176,15 @@ function resolvePackage() {
     return { packageName: 'fraim', binName: 'fraim', version: cached.version, fromCache: true };
   }
 
+  if (isUsableState(cached)) {
+    const cachedDir = path.join(CACHE_ROOT, 'fraim-' + cached.version);
+    if (installedEntry(cached, cachedDir)) {
+      // The installed package is immediately usable. Refresh in a separate
+      // process so an npm outage cannot postpone this MCP connection.
+      return { packageName: 'fraim', binName: 'fraim', version: cached.version, fromCache: true, refresh: true };
+    }
+  }
+
   const fraimVersion = resolveLatest('fraim');
   if (fraimVersion) {
     const state = { packageName: 'fraim', binName: 'fraim', version: fraimVersion, fromCache: false };
@@ -219,19 +232,71 @@ function pruneCaches(keepDir, nowMs) {
   } catch (error) { /* nothing to prune */ }
 }
 
-function runPackage(plan, cacheDir) {
+function runPackage(plan, cacheDir, args = cliArgs) {
   ensureDir(cacheDir);
-  const env = { ...process.env, npm_config_cache: cacheDir };
-  const result = runCommand(npxCommand, ['--yes', '--package', plan.packageName + '@' + plan.version, plan.binName, ...cliArgs], {
+  const env = { ...process.env, npm_config_cache: cacheDir, FRAIM_MCP_LAUNCH_STARTED_AT: String(launchStartedAt) };
+  const result = runCommand(npxCommand, ['--yes', '--package', plan.packageName + '@' + plan.version, plan.binName, ...args], {
     stdio: 'inherit',
     env
   });
   return typeof result.status === 'number' ? result.status : 1;
 }
 
+function installedEntry(plan, cacheDir) {
+  try {
+    const npxDir = path.join(cacheDir, '_npx');
+    for (const hash of fs.readdirSync(npxDir)) {
+      try {
+        const packageDir = path.join(npxDir, hash, 'node_modules', plan.packageName);
+        const manifest = JSON.parse(fs.readFileSync(path.join(packageDir, 'package.json'), 'utf8'));
+        const entry = path.join(packageDir, 'bin', 'fraim.js');
+        if (manifest.name === plan.packageName && manifest.version === plan.version && fs.statSync(entry).isFile()) {
+          return entry;
+        }
+      } catch (error) { /* try another installed hash */ }
+    }
+  } catch (error) { /* no complete installed package */ }
+  return null;
+}
+
+function startBackgroundRefresh() {
+  try {
+    ensureDir(STATE_DIR);
+    try {
+      const age = Date.now() - fs.statSync(REFRESH_LOCK).mtimeMs;
+      if (age < REFRESH_LOCK_STALE_MS) return;
+      fs.rmSync(REFRESH_LOCK, { force: true });
+    } catch (error) { /* no lock */ }
+    const lock = fs.openSync(REFRESH_LOCK, 'wx');
+    fs.closeSync(lock);
+    const child = spawn(process.execPath, [__filename, '--refresh-cache'], {
+      detached: true, stdio: 'ignore', windowsHide: true, env: process.env
+    });
+    child.on('error', () => { try { fs.rmSync(REFRESH_LOCK, { force: true }); } catch (error) { /* best effort */ } });
+    child.unref();
+  } catch (error) { /* another launcher owns refresh */ }
+}
+
+if (refreshMode) {
+  try {
+    const latest = resolveLatest('fraim');
+    if (latest) {
+      const next = { packageName: 'fraim', binName: 'fraim', version: latest, fromCache: false };
+      const nextCache = path.join(CACHE_ROOT, 'fraim-' + latest);
+      if (installedEntry(next, nextCache) || (runPackage(next, nextCache, ['--version']) === 0 && installedEntry(next, nextCache))) {
+        writeState(next);
+      }
+    }
+  } finally {
+    try { fs.rmSync(REFRESH_LOCK, { force: true }); } catch (error) { /* best effort */ }
+  }
+  process.exit(0);
+}
+
 const plan = resolvePackage();
 const versionCacheDir = path.join(CACHE_ROOT, plan.packageName + '-' + plan.version.replace(/[^a-zA-Z0-9._-]/g, '_'));
 pruneCaches(versionCacheDir, Date.now());
+if (plan.refresh) startBackgroundRefresh();
 
 /**
  * True when npx materialized the package into this cache. A non-zero exit from a package
@@ -248,10 +313,19 @@ function packageMaterialized(cacheDir) {
   }
 }
 
-let status = runPackage(plan, versionCacheDir);
+const directEntry = installedEntry(plan, versionCacheDir);
+let status;
+if (directEntry) {
+  const result = spawnSync(process.execPath, [directEntry, ...cliArgs], {
+    stdio: 'inherit', env: { ...process.env, FRAIM_MCP_LAUNCH_STARTED_AT: String(launchStartedAt) }, windowsHide: true
+  });
+  status = typeof result.status === 'number' ? result.status : 1;
+} else {
+  status = runPackage(plan, versionCacheDir);
+}
 
 // Retry ONLY when npx could not materialize the package: the corrupt-cache case this exists for.
-if (status !== 0 && process.platform === 'win32' && !packageMaterialized(versionCacheDir)) {
+if (status !== 0 && !directEntry && process.platform === 'win32' && !packageMaterialized(versionCacheDir)) {
   const retryCache = path.join(CACHE_ROOT, 'retry-' + Date.now() + '-' + process.pid);
   console.error('[fraim-mcp-launcher] Package execution failed; retrying once with a fresh npm cache.');
   status = runPackage(plan, retryCache);
@@ -287,8 +361,9 @@ function getFraimMcpLauncherStatePath() {
  * MCP server spawn then uses immediately instead of waiting out the window.
  *
  * The semantics are "the version you just ran is the version recorded", which is why the caller
- * passes its own version rather than this function consulting the registry. A sync that ran an
- * older package must not claim to have recorded a newer one.
+ * passes its own version rather than this function consulting the registry. Automatic catalog
+ * sync is not a version selection: its running package may be older than the background updater's
+ * selection. It must leave this record alone regardless of which operation finishes first.
  *
  * The record's shape is duplicated from the generated launcher's `writeState`, deliberately and
  * unavoidably: that script executes standalone from `~/.fraim/bin` with only Node built-ins and
@@ -296,7 +371,9 @@ function getFraimMcpLauncherStatePath() {
  * `test-1354-mcp-launcher-freshness-window.ts` asserts that a record written here is accepted by
  * the launcher rather than merely that the fields look alike.
  */
-function recordFraimMcpLauncherVersion(version) {
+function recordFraimMcpLauncherVersion(version, source = 'explicit-sync') {
+    if (source === 'automatic-sync')
+        return false;
     if (!/^\d+\.\d+\.\d+/.test(version))
         return false;
     const statePath = getFraimMcpLauncherStatePath();

package/dist/src/cli/setup/user-level-sync.js

@@ -60,6 +60,52 @@ const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const chalk_1 = __importDefault(require("chalk"));
 const script_sync_utils_1 = require("../utils/script-sync-utils");
+/** Keep optional installation responsive and owned by the process that started it. */
+function installRuntimeDependencies(baseDir, env) {
+    return new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)('npm install --no-audit --no-fund --no-save --no-package-lock --omit=dev', {
+            cwd: baseDir,
+            env,
+            shell: true,
+            windowsHide: true,
+            // A private POSIX process group lets exit cleanup terminate npm and its
+            // descendants without asynchronous process enumeration after parent exit.
+            detached: process.platform !== 'win32',
+            stdio: ['ignore', 'ignore', 'pipe'],
+        });
+        let stderr = '';
+        child.stderr?.on('data', data => { stderr = (stderr + data.toString()).slice(-65536); });
+        const terminateInstaller = () => {
+            if (!child.pid || child.exitCode !== null || child.signalCode !== null)
+                return;
+            try {
+                if (process.platform === 'win32') {
+                    (0, child_process_1.execFileSync)('taskkill', ['/PID', String(child.pid), '/T', '/F'], {
+                        windowsHide: true, stdio: 'ignore', timeout: 5000,
+                    });
+                }
+                else {
+                    process.kill(-child.pid, 'SIGKILL');
+                }
+            }
+            catch { /* the owned child may have finished while shutdown began */ }
+        };
+        // STDIO closes with process.exit(), which does not wait for child handles.
+        // Terminate only this live install; ordinary CLI callers await completion.
+        process.once('exit', terminateInstaller);
+        child.once('error', error => {
+            process.removeListener('exit', terminateInstaller);
+            reject(error);
+        });
+        child.once('close', code => {
+            process.removeListener('exit', terminateInstaller);
+            if (code === 0)
+                resolve();
+            else
+                reject(Object.assign(new Error(`npm install exited with code ${code}`), { stderr }));
+        });
+    });
+}
 /**
  * Curated list of npm runtime dependencies that user-level scripts in
  * ~/.fraim/scripts/ require at runtime. Keep this list narrow — only add deps
@@ -101,7 +147,7 @@ function ensureUserLevelDirectories(userFraimDir) {
  * errors — setup must not break because a downstream script's dep couldn't
  * be installed.
  */
-function ensureUserLevelDependencies(userFraimDir) {
+async function ensureUserLevelDependencies(userFraimDir) {
     const baseDir = userFraimDir || (0, script_sync_utils_1.getUserFraimDir)();
     const pkgPath = path_1.default.join(baseDir, 'package.json');
     const nodeModulesDir = path_1.default.join(baseDir, 'node_modules');
@@ -133,11 +179,9 @@ function ensureUserLevelDependencies(userFraimDir) {
     }
     console.log(chalk_1.default.blue(`📦 Installing user-level runtime dependencies (${missing.join(', ')})...`));
     try {
-        (0, child_process_1.execSync)('npm install --no-audit --no-fund --no-save --no-package-lock --omit=dev', {
-            cwd: baseDir,
-            stdio: 'pipe',
-            env: childEnv,
-        });
+        // Catalog preparation also runs inside the MCP process. Await installation
+        // without blocking its event loop so local discovery can continue serving.
+        await installRuntimeDependencies(baseDir, childEnv);
         console.log(chalk_1.default.green(`✅ Installed: ${missing.join(', ')}`));
     }
     catch (error) {
@@ -158,7 +202,7 @@ async function syncUserLevelArtifacts(userFraimDir) {
     console.log(chalk_1.default.blue('📦 Setting up user-level FRAIM directory...'));
     console.log(chalk_1.default.gray(`   Target: ${baseDir}`));
     ensureUserLevelDirectories(baseDir);
-    ensureUserLevelDependencies(baseDir);
+    await ensureUserLevelDependencies(baseDir);
     // Issue #1201 (R4.2): repair global per-IDE FRAIM discovery artifacts
     // (e.g. ~/.codex/skills/fraim/SKILL.md) on every `npx fraim sync --global`
     // run, not only on `fraim add-ide` and first-run onboarding — closes the

package/dist/src/cli/utils/managed-agent-paths.js

@@ -227,6 +227,7 @@ function buildPathWithManagedAgentBins(basePath) {
 // launches already inherit the registry-composed PATH, so this returns null immediately on
 // win32 rather than attempting a login-shell equivalent that doesn't exist.
 const LOGIN_SHELL_PATH_TIMEOUT_MS = 3000;
+const LOGIN_SHELL_PATH_CACHE_TTL_MS = 60_000;
 function defaultResolveLoginShellPath() {
     if (process.platform === 'win32')
         return null;
@@ -279,18 +280,20 @@ let loginShellPathResolverOverride = null;
  */
 function __setLoginShellPathResolverForTests(resolver) {
     loginShellPathResolverOverride = resolver;
-    cachedLoginShellPath = undefined;
-    cachedNpmGlobalBinDirsForRecovery.clear();
+    __clearLoginShellPathCacheForTests();
 }
 let cachedLoginShellPath;
+let cachedLoginShellPathAtMs = 0;
 /**
- * Resolves and memoizes the PATH the user's own login shell would produce. Computed at most
- * once per process (AC-A5: bounded, fixed cost) — this feeds every agent-resolution call, so
- * recomputing per call would multiply one shell spawn by the number of agents probed.
+ * Resolves the user's login PATH at most once per minute, including failed reads. A
+ * running Hub can discover later installations without spawning a shell per agent probe.
  */
 function resolveLoginShellPathCached() {
-    if (cachedLoginShellPath !== undefined)
+    const nowMs = Date.now();
+    const ageMs = nowMs - cachedLoginShellPathAtMs;
+    if (cachedLoginShellPath !== undefined && ageMs >= 0 && ageMs < LOGIN_SHELL_PATH_CACHE_TTL_MS) {
         return cachedLoginShellPath;
+    }
     const resolver = loginShellPathResolverOverride ?? defaultResolveLoginShellPath;
     // AC-A5: a resolver failing must degrade to "no recovery", never propagate. The default
     // resolver already guards its own spawnSync internally; this also protects against an
@@ -301,13 +304,20 @@ function resolveLoginShellPathCached() {
     catch {
         cachedLoginShellPath = null;
     }
+    cachedLoginShellPathAtMs = nowMs;
+    // npm's configured global prefix can change even when the recovered PATH does not.
+    // Refresh both tiers together so an old prefix cannot outlive login-PATH recovery.
+    cachedNpmGlobalBinDirsForRecovery.clear();
     return cachedLoginShellPath;
 }
 /** Test seam only. Clears the memoized login-shell PATH so the next call recomputes. */
 function __clearLoginShellPathCacheForTests() {
     cachedLoginShellPath = undefined;
+    cachedLoginShellPathAtMs = 0;
+    cachedNpmGlobalBinDirsForRecovery.clear();
 }
 const cachedNpmGlobalBinDirsForRecovery = new Map();
+const NPM_GLOBAL_RECOVERY_CACHE_MAX_ENTRIES = 64;
 /**
  * Memoized wrapper around resolveNpmGlobalBinDirs(), scoped to buildRecoveredAgentPath()'s
  * own use only — NOT a change to resolveNpmGlobalBinDirs() itself, which fraim doctor and the
@@ -321,8 +331,8 @@ const cachedNpmGlobalBinDirsForRecovery = new Map();
  * and because each call sits inside a Promise executor that runs synchronously up to its own
  * spawnSync, the "concurrent" probes actually serialized behind it — up to 5 agents × 5s of
  * blocking spawnSync is exactly the event-loop-freezing regression issue #1010 eliminated,
- * reintroduced one layer deeper. Memoizing once per process (like resolveLoginShellPathCached
- * above) restores the bound this repo's own #1010 postmortem requires.
+ * reintroduced one layer deeper. Memoizing between login-PATH refreshes keeps repeated
+ * probes in the same round from duplicating that work.
  *
  * Keyed by `basePath` (not a single scalar): `resolveManagedCommand()` also routes through this
  * cache now, and unlike `detectEmployeesAsync()`'s repeated same-ambient-PATH probing, its
@@ -330,7 +340,8 @@ const cachedNpmGlobalBinDirsForRecovery = new Map();
  * isolated tests that swap `FRAIM_USER_DIR`/`PATH` per test case). A single scalar cache would
  * let the FIRST basePath's answer silently leak into every later, differently-scoped lookup —
  * concretely, a real machine's actual npm-global `codex` shadowing a test's own isolated managed
- * shim. Per-basePath keys keep the "once per distinct PATH" bound without that cross-contamination.
+ * shim. Per-basePath keys avoid that cross-contamination; a size limit bounds memory when
+ * callers supply many distinct PATHs before the next refresh.
  */
 function resolveNpmGlobalBinDirsCached(basePath) {
     const cached = cachedNpmGlobalBinDirsForRecovery.get(basePath);
@@ -343,6 +354,11 @@ function resolveNpmGlobalBinDirsCached(basePath) {
     catch {
         dirs = [];
     }
+    if (cachedNpmGlobalBinDirsForRecovery.size >= NPM_GLOBAL_RECOVERY_CACHE_MAX_ENTRIES) {
+        const oldestKey = cachedNpmGlobalBinDirsForRecovery.keys().next().value;
+        if (oldestKey !== undefined)
+            cachedNpmGlobalBinDirsForRecovery.delete(oldestKey);
+    }
     cachedNpmGlobalBinDirsForRecovery.set(basePath, dirs);
     return dirs;
 }

package/dist/src/core/handoff-contracts.js

@@ -680,10 +680,13 @@ const FIELD_SCHEMAS = {
         '  "runScope": "manager" | "project" | "org",',
         '  "proposals": [{',
         '    "proposalId": "<id the journal records against>",',
-        '    "claimKey": "<claim identity>", "family": "<learning family>", "revision": <int>,',
+        '    "claimKey": "<claim identity>", "revision": <int>,',
+        '    "type": "Job" | "Phase" | "Skill" | "Context" | "Rule" | "Learning" | "Template" | "Script" | "Config",',
         '    "changeType": "new" | "update" | "cold",',
         '    "title": "<reader title>", "takeaway": "<reader takeaway>", "example": "<optional>",',
-        '    "suggestedLevel": "manager" | "project" | "org", "recurrences": <int>,',
+        '    "suggestedLevel": "manager" | "project" | "org",',
+        '    // A Learning row adds its family and occurrence history:',
+        '    "family": "<learning family>", "recurrences": <int>,',
         '    "recurrencesAtLastReview": <int|null>, "domain": "<domain|null>",',
         '    "reopening": { "rejectedAt": "<date>", "reason": "<manager words>", "countAtRejection": <int> }',
         '  }],',
@@ -691,6 +694,9 @@ const FIELD_SCHEMAS = {
         '                   "kind": "refused" | "superseded", "reason": "...", "newSourceCount": <int> }]',
         '}',
         'Trace, sourceRefs and scores are audit metadata and must not be sent.',
+        'Types come from registry/rules/fraim/artifact-boundaries.md. A non-Learning row',
+        'omits family, recurrences, recurrencesAtLastReview, domain and reopening: a',
+        'capability change has no occurrence history and no learning family.',
     ].join(String.fromCharCode(10)),
     approved: ADDRESS_FEEDBACK_APPROVAL_SCHEMA,
     reviewHandoff: REVIEW_HANDOFF_SCHEMA,

package/dist/src/core/proposal-set-contract.js

@@ -32,7 +32,7 @@
  * from a payload that reached the Hub by some other path.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_SUPPRESSED_PER_SET = exports.MAX_PROPOSALS_PER_SET = exports.PROPOSAL_CHANGE_TYPES = exports.SUPPRESSION_KINDS = exports.PROPOSAL_RUN_SCOPES = void 0;
+exports.MAX_SUPPRESSED_PER_SET = exports.MAX_PROPOSALS_PER_SET = exports.LEARNING_ARTIFACT_TYPE = exports.PROPOSAL_ARTIFACT_TYPES = exports.PROPOSAL_CHANGE_TYPES = exports.SUPPRESSION_KINDS = exports.PROPOSAL_RUN_SCOPES = void 0;
 exports.rankProposals = rankProposals;
 exports.validateProposalSet = validateProposalSet;
 /** Scopes a run can be asked for. Decides which corpus an approval lands in. */
@@ -42,6 +42,35 @@ exports.PROPOSAL_RUN_SCOPES = ['manager', 'project', 'org'];
 exports.SUPPRESSION_KINDS = ['refused', 'superseded'];
 /** What kind of change a proposal makes to the corpus. */
 exports.PROPOSAL_CHANGE_TYPES = ['new', 'update', 'cold'];
+/**
+ * What kind of artifact a row proposes changing (Issue #2079).
+ *
+ * A learning run proposes more than one kind of thing. A lesson is a claim that
+ * has recurred, and the manager decides whether it is worth remembering. A
+ * capability change is a permanent change to a job, skill or rule, and the
+ * manager decides whether to make it. The run journal has always known the
+ * difference: every action it records is typed `kind: 'learning' | 'capability'`.
+ * This wire shape is where that fact used to be lost, so a job edit arrived with
+ * an occurrence count of 1 beside a lesson at 14 and a heading reading
+ * "New lesson".
+ *
+ * The vocabulary is not invented here. `registry/rules/fraim/artifact-boundaries.md`
+ * already defines these nine, each with the one-line responsibility that tells a
+ * reader what the type means, and instructs that the definition is kept there
+ * rather than copied into each job. `classify-instruction-placement` returns a
+ * family from exactly this set. Learning is one of the nine, so every row in a
+ * batch names its type from one list instead of lessons being described by
+ * `family` while everything else was described by a parallel vocabulary.
+ *
+ * This list carries the names only. The responsibility wording stays in the rule
+ * file, and `scripts/validate-artifact-type-contract.ts` fails the build if the
+ * two ever disagree.
+ */
+exports.PROPOSAL_ARTIFACT_TYPES = [
+    'Job', 'Phase', 'Skill', 'Context', 'Rule', 'Learning', 'Template', 'Script', 'Config',
+];
+/** The one type whose row carries recurrence evidence. */
+exports.LEARNING_ARTIFACT_TYPE = 'Learning';
 /**
  * Maximum proposals in one set. Derived from the measured envelope above, not
  * chosen: at roughly 700 bytes per proposal this keeps a full set inside twice
@@ -63,13 +92,28 @@ const isText = (v) => typeof v === 'string' && v.trim().length > 0;
  * boundary is cheaper than auditing every render site later.
  */
 const FORBIDDEN_PROPOSAL_FIELDS = ['trace', 'sourceRefs', 'sourceHashes', 'content', 'score'];
+/**
+ * Fields only a Learning row carries (Issue #2079).
+ *
+ * `recurrences` and `recurrencesAtLastReview` are the accumulated evidence
+ * behind a claim. `domain` is its subject matter, which
+ * `registry/rules/fraim/artifact-boundaries.md` keeps separate from reach.
+ * `family` is which family file it lands in, and it is the slot a capability
+ * change was being forced into because there was nowhere else to say what the
+ * row was. None of the four means anything for a capability change, and the
+ * count in particular invited the strength comparison that made a permanent job
+ * edit read as the weakest row in the batch. `reopening` goes with them: it
+ * quotes an earlier rejection and renders "it was at N then and is at M now",
+ * and M is the count this row does not have.
+ */
+const LEARNING_ONLY_FIELDS = ['family', 'recurrences', 'recurrencesAtLastReview', 'domain', 'reopening'];
 function validateEntry(entry, index, errors) {
     const at = `evidence.proposalSet.proposals[${index}]`;
     if (!isObject(entry)) {
         errors.push(`${at} must be an object`);
         return;
     }
-    for (const field of ['proposalId', 'claimKey', 'family']) {
+    for (const field of ['proposalId', 'claimKey']) {
         if (!isText(entry[field]))
             errors.push(`${at}.${field} must be a non-empty string`);
     }
@@ -101,32 +145,57 @@ function validateEntry(entry, index, errors) {
     if (!exports.PROPOSAL_CHANGE_TYPES.includes(entry.changeType)) {
         errors.push(`${at}.changeType must be one of ${exports.PROPOSAL_CHANGE_TYPES.join(', ')}`);
     }
-    if (!Number.isInteger(entry.recurrences) || entry.recurrences < 0) {
-        errors.push(`${at}.recurrences must be a non-negative integer`);
+    if (!exports.PROPOSAL_ARTIFACT_TYPES.includes(entry.type)) {
+        errors.push(`${at}.type must be one of ${exports.PROPOSAL_ARTIFACT_TYPES.join(', ')}, as defined in ` +
+            'registry/rules/fraim/artifact-boundaries.md; the row names what kind of artifact changes');
     }
     for (const field of FORBIDDEN_PROPOSAL_FIELDS) {
         if (entry[field] !== undefined) {
             errors.push(`${at}.${field} is audit metadata and must not be sent to the review surface`);
         }
     }
-    if (entry.reopening !== undefined) {
-        const r = entry.reopening;
-        const ra = `${at}.reopening`;
-        if (!isObject(r)) {
-            errors.push(`${ra} must be an object`);
-        }
-        else {
-            if (!isText(r.rejectedAt))
-                errors.push(`${ra}.rejectedAt must be a non-empty string`);
-            if (!isText(r.reason)) {
-                errors.push(`${ra}.reason must be a non-empty string; a reopening quotes the original decision`);
-            }
-            if (!Number.isInteger(r.countAtRejection) || r.countAtRejection < 0) {
-                errors.push(`${ra}.countAtRejection must be a non-negative integer`);
-            }
+    // Issue #2079. `type` decides which row this is, so each kind's fields are
+    // checked on its own terms instead of a capability change having to satisfy
+    // a Learning's.
+    if (entry.type === exports.LEARNING_ARTIFACT_TYPE)
+        validateLearningEntry(entry, at, errors);
+    else if (exports.PROPOSAL_ARTIFACT_TYPES.includes(entry.type))
+        validateCapabilityEntry(entry, at, errors);
+}
+/** A capability change: none of the evidence a claim accumulates. */
+function validateCapabilityEntry(entry, at, errors) {
+    for (const field of LEARNING_ONLY_FIELDS) {
+        if (entry[field] !== undefined) {
+            errors.push(`${at}.${field} belongs to a Learning row; a ${String(entry.type)} change has no ` +
+                'occurrence history, learning family or subject-matter domain to weigh');
         }
     }
 }
+/** A claim: its family, occurrence history, and the rejection it may return from. */
+function validateLearningEntry(entry, at, errors) {
+    if (!isText(entry.family)) {
+        errors.push(`${at}.family must be a non-empty string on a Learning row; it names the family file the entry lands in`);
+    }
+    if (!Number.isInteger(entry.recurrences) || entry.recurrences < 0) {
+        errors.push(`${at}.recurrences must be a non-negative integer`);
+    }
+    if (entry.reopening === undefined)
+        return;
+    const r = entry.reopening;
+    const ra = `${at}.reopening`;
+    if (!isObject(r)) {
+        errors.push(`${ra} must be an object`);
+        return;
+    }
+    if (!isText(r.rejectedAt))
+        errors.push(`${ra}.rejectedAt must be a non-empty string`);
+    if (!isText(r.reason)) {
+        errors.push(`${ra}.reason must be a non-empty string; a reopening quotes the original decision`);
+    }
+    if (!Number.isInteger(r.countAtRejection) || r.countAtRejection < 0) {
+        errors.push(`${ra}.countAtRejection must be a non-negative integer`);
+    }
+}
 function validateSuppressed(entry, index, errors) {
     const at = `evidence.proposalSet.suppressed[${index}]`;
     if (!isObject(entry)) {
@@ -171,10 +240,25 @@ function validateSuppressed(entry, index, errors) {
  *
  * Applied on the Hub's own read rather than trusted from the agent: the order the
  * manager sees should not depend on how a model happened to sort its output.
+ *
+ * Issue #2079 adds the partition above that. A capability change has no
+ * occurrence count, so ranking it against a Learning by one is the same category
+ * error the row made: `b.recurrences - a.recurrences` on a missing count is NaN,
+ * which is falsy, so the comparison fell straight through to the id tie-break
+ * and a permanent job edit landed wherever its id happened to put it.
+ *
+ * Capability rows lead as their own group, because a change to how the employee
+ * works from now on is decided before a batch of remembered lessons. Inside that
+ * group there is nothing to rank by and no claim that there is: every evidence
+ * comparison is zero and the order falls to `proposalId`, which is stable rather
+ * than meaningful. Learning rows keep the evidence ordering above.
  */
 function rankProposals(proposals) {
-    const growth = (p) => typeof p.recurrencesAtLastReview === 'number' ? p.recurrences - p.recurrencesAtLastReview : 0;
-    return [...proposals].sort((a, b) => b.recurrences - a.recurrences
+    const group = (p) => (p.type === exports.LEARNING_ARTIFACT_TYPE ? 1 : 0);
+    const count = (p) => (typeof p.recurrences === 'number' ? p.recurrences : 0);
+    const growth = (p) => typeof p.recurrencesAtLastReview === 'number' ? count(p) - p.recurrencesAtLastReview : 0;
+    return [...proposals].sort((a, b) => group(a) - group(b)
+        || count(b) - count(a)
         || growth(b) - growth(a)
         || a.proposalId.localeCompare(b.proposalId));
 }

package/dist/src/core/utils/server-startup.js

@@ -9,11 +9,11 @@ function createPortConflictError(port) {
     return error;
 }
 async function startListening(app, port, onListening) {
-    await new Promise((resolve, reject) => {
+    return new Promise((resolve, reject) => {
         const server = app.listen(port);
         server.once('listening', () => {
             onListening();
-            resolve();
+            resolve(server);
         });
         server.once('error', (error) => {
             if (error?.code === 'EADDRINUSE') {

package/dist/src/fraim/current-license.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sameLicenseScope = sameLicenseScope;
+exports.hasUsableLicense = hasUsableLicense;
+exports.effectiveLicenseExpiry = effectiveLicenseExpiry;
+exports.subscriptionAccessPatch = subscriptionAccessPatch;
+exports.selectCurrentLicense = selectCurrentLicense;
+function sameLicenseScope(a, b) {
+    return a.userId === b.userId && a.orgId === b.orgId
+        && (a.workspaceId || null) === (b.workspaceId || null);
+}
+function hasUsableLicense(key, now = Date.now()) {
+    const expiry = effectiveLicenseExpiry(key);
+    return key.isActive !== false && !key.revokedAt
+        && (key.status === 'active' || (!key.status && key.isActive === true))
+        && (expiry === null || expiry.getTime() > now);
+}
+/** No automatic grace. Explicit support grants are separate from payment proof. */
+function effectiveLicenseExpiry(key) {
+    if (!key.stripeSubscriptionId)
+        return key.expiresAt ? new Date(key.expiresAt) : null;
+    if (key.manualAccessOverride?.until === null)
+        return null;
+    let paid = key.paidThrough ? new Date(key.paidThrough).getTime() : 0;
+    if (key.stripeSubscriptionEndedAt)
+        paid = Math.min(paid, new Date(key.stripeSubscriptionEndedAt).getTime());
+    // A finite pre-migration deadline is retained until reconciliation classifies it.
+    const legacy = !key.billingReconciledAt && key.expiresAt ? new Date(key.expiresAt).getTime() : 0;
+    const manual = key.manualAccessOverride?.until ? new Date(key.manualAccessOverride.until).getTime() : 0;
+    return new Date(Math.max(paid, manual, legacy));
+}
+function subscriptionAccessPatch(key, now = new Date()) {
+    const expiresAt = effectiveLicenseExpiry(key);
+    const usable = expiresAt === null || expiresAt.getTime() > now.getTime();
+    const failed = ['past_due', 'unpaid', 'incomplete', 'paused'].includes(key.subscriptionStatus || '');
+    return {
+        expiresAt, status: usable ? 'active' : failed ? 'suspended' : 'expired',
+        suspendedAt: !usable && failed ? key.suspendedAt || now : null,
+        suspensionReason: !usable && failed ? 'payment_failed' : null
+    };
+}
+/** Paid lifecycle takes precedence over trials, including after suspension or cancellation. */
+function selectCurrentLicense(records, activeOnly = false) {
+    const now = Date.now();
+    const selected = records.filter(record => record.isActive !== false && !record.revokedAt).sort((a, b) => Number(b.tier === 'paid-subscription') - Number(a.tier === 'paid-subscription')
+        || Number(hasUsableLicense(b, now)) - Number(hasUsableLicense(a, now))
+        || Number(a.accessScope === 'persona') - Number(b.accessScope === 'persona')
+        || (new Date(b.createdAt).getTime() || 0) - (new Date(a.createdAt).getTime() || 0)
+        || a.key.localeCompare(b.key))[0] || null;
+    return selected && (!activeOnly || hasUsableLicense(selected, now)) ? selected : null;
+}