fraim-hub 2.0.346 → 2.0.348

package/dist/registry/scripts/learning/completion-state.js

@@ -4,10 +4,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.COMPLETION_END = exports.COMPLETION_START = exports.UnsupportedRunHistoryError = exports.sourcePathKey = void 0;
+exports.validateDeferredAttempt = validateDeferredAttempt;
+exports.validateDeferredWork = validateDeferredWork;
 exports.cycleRetrospectivePath = cycleRetrospectivePath;
 exports.validateProcessedSources = validateProcessedSources;
 exports.canonicalJournal = canonicalJournal;
 exports.readRunJournal = readRunJournal;
+exports.readRunReservations = readRunReservations;
 exports.readSourceReservations = readSourceReservations;
 exports.normalizeSourceParticipants = normalizeSourceParticipants;
 exports.sourceAuthorAllowed = sourceAuthorAllowed;
@@ -17,6 +20,33 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_crypto_1 = require("node:crypto");
 const artifact_paths_1 = require("../artifact-paths");
 const corpus_audit_1 = require("./corpus-audit");
+const outcome_types_1 = require("./outcome-types");
+function validateDeferredAttempt(value) {
+    if (!keys(value, ['at', 'evidenceHash', 'deferred', 'reason']) || !text(value.at) || !Number.isFinite(Date.parse(value.at)) || !hash(value.evidenceHash))
+        throw new Error('invalid-deferred-attempt');
+    // Older journals embedded the checkpoint snapshot; keep accepting those exact records.
+    if (value.deferred !== undefined && value.reason === undefined)
+        validateDeferredWork(value.deferred);
+    else if (value.deferred !== undefined || !text(value.reason))
+        throw new Error('invalid-deferred-attempt');
+}
+function validateDeferredWork(value) {
+    if (!keys(value, ['actions', 'sources', 'corpusComplete', 'corpusErrors']) || value.corpusComplete !== false || !Array.isArray(value.actions) || !Array.isArray(value.sources))
+        throw new Error('invalid-deferred-work');
+    if (value.corpusErrors !== undefined && (!Array.isArray(value.corpusErrors) || value.corpusErrors.some(item => !keys(item, ['path', 'reason']) || !text(item.path) || !node_path_1.default.isAbsolute(item.path) || !text(item.reason))))
+        throw new Error('invalid-deferred-work');
+    const actions = new Set(), sources = new Set();
+    for (const item of value.actions) {
+        if (!keys(item, ['actionId', 'revision', 'digest', 'reason']) || !text(item.actionId) || !Number.isInteger(item.revision) || item.revision < 1 || !hash(item.digest) || !text(item.reason) || actions.has(item.actionId))
+            throw new Error('invalid-deferred-work');
+        actions.add(item.actionId);
+    }
+    for (const item of value.sources) {
+        if (!keys(item, ['path', 'owner', 'reason', 'sha256']) || !text(item.path) || !node_path_1.default.isAbsolute(item.path) || /[\x00-\x1f]/.test(item.path) || !ownerValid(item.owner) || !text(item.reason) || (item.sha256 !== undefined && !hash(item.sha256)) || sources.has((0, exports.sourcePathKey)(item.path)))
+            throw new Error('invalid-deferred-work');
+        sources.add((0, exports.sourcePathKey)(item.path));
+    }
+}
 const sourcePathKey = (file) => {
     const value = node_path_1.default.resolve(file).replace(/\\/g, '/');
     return process.platform === 'win32' ? value.toLowerCase() : value;
@@ -145,9 +175,10 @@ function readRunJournal(file) {
     }
     return { events, lastHash, format: 'current' };
 }
-/** Only exact, hash-chain-verified current archive plans reserve files. Older plans are outside this lifecycle. */
-function readSourceReservations(runDirectories, excludingRunFile) {
+/** Current archive plans and prepared assessments share one verified reservation inventory. */
+function readRunReservations(runDirectories, excludingRunFile) {
     const reserved = new Set();
+    const assessmentKeys = new Set();
     for (const directory of new Set(runDirectories.map(dir => node_path_1.default.resolve(dir)))) {
         let names;
         try {
@@ -168,6 +199,23 @@ function readSourceReservations(runDirectories, excludingRunFile) {
                 const journal = readRunJournal(file);
                 if (journal.format === 'historical')
                     continue;
+                const assessmentSources = new Map();
+                for (const event of journal.events) {
+                    if (event.payload.type === 'assessment-prepared') {
+                        const { record, sourcePaths } = event.payload.data;
+                        (0, outcome_types_1.validateOutcomeAssessmentRecord)(record);
+                        if (!Array.isArray(sourcePaths) || sourcePaths.length !== record.sourceRefs.length || sourcePaths.some(file => typeof file !== 'string' || !node_path_1.default.isAbsolute(file)))
+                            throw new Error('invalid-assessment-sources');
+                        assessmentSources.set(record.digest, { paths: sourcePaths, key: (0, outcome_types_1.assessmentKey)(record) });
+                    }
+                    else if (event.payload.type === 'assessment-committed')
+                        assessmentSources.delete(event.payload.data.digest);
+                }
+                for (const reservation of assessmentSources.values()) {
+                    assessmentKeys.add(reservation.key);
+                    for (const source of reservation.paths)
+                        reserved.add((0, exports.sourcePathKey)(source));
+                }
                 for (const event of journal.events)
                     if (event.payload.type === 'source-completion') {
                         for (const source of event.payload.data) {
@@ -183,7 +231,10 @@ function readSourceReservations(runDirectories, excludingRunFile) {
             }
         }
     }
-    return [...reserved].sort();
+    return { sources: [...reserved].sort(), assessmentKeys: [...assessmentKeys].sort() };
+}
+function readSourceReservations(runDirectories, excludingRunFile) {
+    return readRunReservations(runDirectories, excludingRunFile).sources;
 }
 exports.COMPLETION_START = '<!-- fraim-sleep-decisions:v1 -->';
 exports.COMPLETION_END = '<!-- /fraim-sleep-decisions -->';
@@ -234,7 +285,7 @@ function decodeCompletion(markdown, expected = {}) {
     catch {
         fail();
     }
-    if (!keys(state, ['schemaVersion', 'runId', 'owner', 'finalizationState', 'decisions', 'sourceDispositions', 'cleanup', 'reconciliations', 'retrospective', 'processedSources', 'sourceParticipants', 'corpusAudit', 'reconciliationHistory']) || state.schemaVersion !== 1 || !text(state.runId) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(state.runId) || !ownerValid(state.owner)
+    if (!keys(state, ['schemaVersion', 'runId', 'owner', 'finalizationState', 'decisions', 'sourceDispositions', 'cleanup', 'reconciliations', 'retrospective', 'processedSources', 'sourceParticipants', 'corpusAudit', 'reconciliationHistory', 'deferred', 'deferredHistory', 'deferredAttempts', 'outcomeAssessments']) || state.schemaVersion !== 1 || !text(state.runId) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(state.runId) || !ownerValid(state.owner)
         || !['pending', 'complete'].includes(state.finalizationState) || !Array.isArray(state.decisions) || !Array.isArray(state.sourceDispositions) || !Array.isArray(state.cleanup))
         fail();
     if ((expected.runId && expected.runId !== state.runId) || (expected.owner && !sameOwner(expected.owner, state.owner)))
@@ -249,8 +300,31 @@ function decodeCompletion(markdown, expected = {}) {
         fail();
     if (state.processedSources !== undefined)
         validateProcessedSources(state.processedSources);
+    if (state.outcomeAssessments !== undefined) {
+        if (!Array.isArray(state.outcomeAssessments))
+            fail();
+        const digests = new Set();
+        for (const assessment of state.outcomeAssessments) {
+            (0, outcome_types_1.validateOutcomeAssessmentRecord)(assessment);
+            if (assessment.runId !== state.runId || digests.has(assessment.digest))
+                fail();
+            digests.add(assessment.digest);
+        }
+    }
     if (state.sourceParticipants !== undefined)
         normalizeSourceParticipants(state.sourceParticipants, state.owner);
+    if (state.deferred !== undefined)
+        validateDeferredWork(state.deferred);
+    if (state.deferredHistory !== undefined) {
+        if (!Array.isArray(state.deferredHistory))
+            fail();
+        state.deferredHistory.forEach(validateDeferredWork);
+    }
+    if (state.deferredAttempts !== undefined) {
+        if (!Array.isArray(state.deferredAttempts))
+            fail();
+        state.deferredAttempts.forEach(validateDeferredAttempt);
+    }
     const ids = new Set();
     for (const item of state.decisions) {
         if (!keys(item, ['actionId', 'revision', 'digest', 'owner', 'claimKey', 'evidenceFingerprint', 'sourceRefs', 'decision', 'publicationRef', 'target', 'dependencies']) || !text(item.actionId) || ids.has(item.actionId) || !Number.isInteger(item.revision) || item.revision < 1 || !hash(item.digest) || !ownerValid(item.owner)
@@ -282,6 +356,8 @@ function decodeCompletion(markdown, expected = {}) {
             fail();
     }
     const decisions = new Map(state.decisions.map((item) => [item.actionId, item]));
+    if (state.deferred?.actions.some((item) => decisions.has(item.actionId)))
+        fail();
     if (state.corpusAudit !== undefined) {
         try {
             (0, corpus_audit_1.validateCorpusAudit)(state.corpusAudit);

package/dist/registry/scripts/learning/corpus-audit.js

@@ -10,7 +10,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_crypto_1 = require("node:crypto");
 const owner_identity_1 = require("./owner-identity");
-const { learningEntryBlocks } = require('./entry-format');
+const { learningEntryBlocks, learningEntryIdentity, isLearningEntryId } = require('./entry-format');
 const stable = (value) => JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
     ? Object.fromEntries(Object.keys(item).sort().map(key => [key, item[key]])) : item);
 const hash = (value) => (0, node_crypto_1.createHash)('sha256').update(value).digest('hex');
@@ -63,9 +63,8 @@ function collectLearningCorpus(homes, subjects, readerRoots = []) {
                         for (const block of blocks) {
                             // Match the runtime reader's handwritten identity contract.
                             // Approved mutations still use the author's narrower generated-ID schema.
-                            const declarations = block.text.split(/\r?\n/).map(line => line.trim()).filter(line => /^\*\*Id\*\*:/i.test(line));
-                            const id = declarations[0]?.match(/^\*\*Id\*\*:\s*(L-[0-9A-Za-z]{6,24})\s*$/)?.[1] ?? null;
-                            if ((declarations.length && (!id || declarations.length !== 1)) || (id && ids.has(id))
+                            const { id, ambiguous } = learningEntryIdentity(block.text);
+                            if (ambiguous || (id && ids.has(id))
                                 || !/^#{2,6}\s+\[P-(CRITICAL|HIGH|MED|LOW)\]\s+\S/.test(block.text)) {
                                 errors.push({ path: file.replace(/\\/g, '/'), reason: 'ambiguous-corpus-entry' });
                                 continue;
@@ -157,8 +156,9 @@ function collectLearningCorpus(homes, subjects, readerRoots = []) {
 /** Shared by journal replay and the strict compact receipt decoder. No filesystem access. */
 function validateCorpusAudit(audit, reviewer) {
     const fail = () => { throw new Error('invalid-corpus-audit'); };
-    if (!keys(audit, ['snapshot', 'reviewer', 'dispositions']) || typeof audit.reviewer !== 'string' || !audit.reviewer.trim() || (reviewer && audit.reviewer !== reviewer)
-        || !keys(audit.snapshot, ['schemaVersion', 'homes', 'entries', 'duplicates', 'fingerprint', 'complete', 'errors']) || audit.snapshot.schemaVersion !== 1 || audit.snapshot.complete !== true || !Array.isArray(audit.snapshot.errors) || audit.snapshot.errors.length
+    if (!keys(audit, ['snapshot', 'reviewer', 'dispositions', 'partial']) || typeof audit.reviewer !== 'string' || !audit.reviewer.trim() || (reviewer && audit.reviewer !== reviewer) || (audit.partial !== undefined && audit.partial !== true)
+        || !keys(audit.snapshot, ['schemaVersion', 'homes', 'entries', 'duplicates', 'fingerprint', 'complete', 'errors']) || audit.snapshot.schemaVersion !== 1 || typeof audit.snapshot.complete !== 'boolean' || (!audit.partial && !audit.snapshot.complete) || !Array.isArray(audit.snapshot.errors) || (!audit.partial && audit.snapshot.errors.length)
+        || audit.snapshot.errors.some(item => !keys(item, ['path', 'reason']) || typeof item.path !== 'string' || !node_path_1.default.isAbsolute(item.path) || typeof item.reason !== 'string' || !item.reason.trim())
         || !Array.isArray(audit.snapshot.homes) || !Array.isArray(audit.snapshot.entries) || !Array.isArray(audit.dispositions))
         fail();
     const snapshot = audit.snapshot;
@@ -172,7 +172,7 @@ function validateCorpusAudit(audit, reviewer) {
             fail();
         (0, owner_identity_1.validateOwner)(entry.ref?.owner);
         if (!snapshot.homes.some(owner => (0, owner_identity_1.ownerKey)(owner) === (0, owner_identity_1.ownerKey)(entry.ref.owner))
-            || (entry.ref.entryId === undefined ? !Number.isSafeInteger(entry.occurrence) || entry.occurrence < 0 : !/^L-[0-9A-Za-z]{6,24}$/.test(entry.ref.entryId) || entry.occurrence !== undefined)
+            || (entry.ref.entryId === undefined ? !Number.isSafeInteger(entry.occurrence) || entry.occurrence < 0 : !isLearningEntryId(entry.ref.entryId) || entry.occurrence !== undefined)
             || !/^learnings\//.test(entry.ref.relativePath) || /[\\:]/.test(entry.ref.relativePath) || entry.ref.relativePath.split('/').some(part => !part || part === '.' || part === '..')
             || !/^[a-f0-9]{64}$/.test(entry.sha256) || entries.has(corpusEntryKey(entry)))
             fail();

package/dist/registry/scripts/learning/entry-format.js

@@ -1,5 +1,14 @@
 'use strict';
 
+const LEARNING_ENTRY_ID_LINE = /^\*\*Id\*\*:\s*(L-[0-9A-Za-z]{6,24})\s*$/;
+function isLearningEntryId(value) { return typeof value === 'string' && /^L-[0-9A-Za-z]{6,24}$/.test(value); }
+/** Reader/corpus identity accepts stable handwritten IDs; approved mutation IDs remain narrower below. */
+function learningEntryIdentity(content) {
+    const declarations = content.split(/\r?\n/).map(line => line.trim()).filter(line => /^\*\*Id\*\*:/i.test(line));
+    const id = declarations[0]?.match(LEARNING_ENTRY_ID_LINE)?.[1] ?? null;
+    return { id: declarations.length === 1 ? id : null, ambiguous: declarations.length > 0 && (!id || declarations.length !== 1) };
+}
+
 // Read the shared author's current entry format for identity and update guards.
 function learningEntryBlocks(body) {
     const headings = [...body.matchAll(/^#{2,6}\s+\[P-[A-Z]+\].*$/gm)];
@@ -24,4 +33,4 @@ function learningEntryMetadata(content) {
     return metadata;
 }
 
-module.exports = { learningEntryMetadata, learningEntryBlocks };
+module.exports = { learningEntryMetadata, learningEntryBlocks, learningEntryIdentity, isLearningEntryId, LEARNING_ENTRY_ID_LINE };

package/dist/registry/scripts/learning/outcome-types.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchesOutcomeScope = matchesOutcomeScope;
+exports.assessmentKey = assessmentKey;
+exports.assessmentContent = assessmentContent;
+exports.outcomeAssessmentDigest = outcomeAssessmentDigest;
+exports.validateOutcomeAssessmentInput = validateOutcomeAssessmentInput;
+exports.validateOutcomeAssessmentRecord = validateOutcomeAssessmentRecord;
+exports.summarizeLearningOutcomes = summarizeLearningOutcomes;
+const node_crypto_1 = require("node:crypto");
+const owner_identity_1 = require("./owner-identity");
+const { isLearningEntryId } = require('./entry-format');
+function matchesOutcomeScope(record, scope) {
+    return (scope.key === undefined || assessmentKey(record) === scope.key)
+        && (scope.principal === undefined || record.learning.learningSubject === scope.principal)
+        && (scope.owners === undefined || scope.owners.some(owner => (0, owner_identity_1.ownerKey)(owner) === (0, owner_identity_1.ownerKey)(record.learning.owner)));
+}
+const canonical = (value) => JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
+    ? Object.fromEntries(Object.keys(item).sort().map(key => [key, item[key]])) : item);
+const text = (value) => typeof value === 'string' && !!value.trim() && !/[\x00-\x08\x0b\x0c\x0e-\x1f]/.test(value);
+const hash = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const relative = (value) => text(value) && !/[\\:\x00-\x1f]/.test(value) && value.split('/').every(part => !!part && part !== '.' && part !== '..');
+const date = (value) => typeof value === 'string' && /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z)?$/.test(value)
+    && Number.isFinite(Date.parse(value)) && new Date(value).toISOString().slice(0, 10) === value.slice(0, 10);
+/** Semantic identity comes from Sleep; paths are provenance, never a title or move-sensitive join. */
+function assessmentKey(input) {
+    return canonical([(0, owner_identity_1.ownerKey)(input.learning.owner), input.learning.learningSubject, input.learning.entryId, input.incidentId]);
+}
+function assessmentContent(input) {
+    return canonical({ learning: input.learning, incidentId: input.incidentId, observedAt: input.observedAt, outcome: input.outcome,
+        reportedHelp: input.reportedHelp, explicitlySkipped: input.explicitlySkipped,
+        sourceRefs: [...input.sourceRefs].sort((a, b) => canonical(a).localeCompare(canonical(b))), rationale: input.rationale,
+        guidanceExistedAt: input.guidanceExistedAt });
+}
+function outcomeAssessmentDigest(record) {
+    return (0, node_crypto_1.createHash)('sha256').update(canonical({ content: assessmentContent(record), revision: record.revision,
+        expectedPriorDigest: record.expectedPriorDigest, reviewer: record.reviewer })).digest('hex');
+}
+function validateOutcomeAssessmentInput(input) {
+    if (!input || !input.learning)
+        throw new Error('invalid-outcome-assessment');
+    (0, owner_identity_1.validateOwner)(input.learning.owner);
+    if (!relative(input.learning.relativePath) || !isLearningEntryId(input.learning.entryId)
+        || !text(input.learning.learningSubject) || !text(input.incidentId) || input.incidentId.length > 512
+        || !date(input.observedAt) || !date(input.guidanceExistedAt)
+        || !['success', 'miss', 'unknown'].includes(input.outcome) || typeof input.reportedHelp !== 'boolean'
+        || typeof input.explicitlySkipped !== 'boolean' || !text(input.rationale)
+        || (input.expectedPriorDigest !== null && !hash(input.expectedPriorDigest))
+        || !Array.isArray(input.sourceRefs) || !input.sourceRefs.length)
+        throw new Error('invalid-outcome-assessment');
+    if (input.reportedHelp && input.outcome !== 'success' || input.explicitlySkipped && input.outcome !== 'miss')
+        throw new Error('invalid-outcome-qualification');
+    if (Date.parse(input.guidanceExistedAt) > Date.parse(input.observedAt))
+        throw new Error('guidance-after-incident');
+    for (const source of input.sourceRefs) {
+        if (!source)
+            throw new Error('invalid-assessment-source');
+        (0, owner_identity_1.validateOwner)(source.owner);
+        if (!relative(source.relativePath) || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(source.sourceId)
+            || !hash(source.sha256))
+            throw new Error('invalid-assessment-source');
+    }
+    if (new Set(input.sourceRefs.map(source => canonical([(0, owner_identity_1.ownerKey)(source.owner), source.sourceId]))).size !== input.sourceRefs.length)
+        throw new Error('duplicate-assessment-source');
+}
+function validateOutcomeAssessmentRecord(record) {
+    validateOutcomeAssessmentInput(record);
+    if (!Number.isInteger(record.revision) || record.revision < 1 || !date(record.assessedAt)
+        || !text(record.reviewer) || !text(record.runId) || record.digest !== outcomeAssessmentDigest(record))
+        throw new Error('invalid-outcome-record');
+}
+function summarizeLearningOutcomes(records, learning) {
+    const selected = new Map();
+    for (const record of records) {
+        if ((0, owner_identity_1.ownerKey)(record.learning.owner) !== (0, owner_identity_1.ownerKey)(learning.owner) || record.learning.entryId !== learning.entryId
+            || record.learning.learningSubject !== learning.learningSubject)
+            continue;
+        validateOutcomeAssessmentRecord(record);
+        const key = assessmentKey(record), prior = selected.get(key);
+        if (!prior || record.revision > prior.revision)
+            selected.set(key, record);
+        else if (record.revision === prior.revision && record.digest !== prior.digest)
+            throw new Error('assessment-history-conflict');
+    }
+    if (!selected.size)
+        return undefined;
+    const current = [...selected.values()], observed = current.map(record => record.observedAt).sort();
+    return { success: current.filter(record => record.outcome === 'success').length,
+        reportedHelp: current.filter(record => record.outcome === 'success' && record.reportedHelp).length,
+        miss: current.filter(record => record.outcome === 'miss').length, unknown: current.filter(record => record.outcome === 'unknown').length,
+        firstObservedAt: observed[0], lastObservedAt: observed[observed.length - 1], assessedAt: current.map(record => record.assessedAt).sort().at(-1) };
+}

package/dist/registry/scripts/learning/owner-identity.js

@@ -8,6 +8,7 @@ exports.ownerPath = ownerPath;
 exports.validateOwner = validateOwner;
 exports.ownerKey = ownerKey;
 exports.assertSameOwner = assertSameOwner;
+exports.assertLearningTargetPath = assertLearningTargetPath;
 exports.resolveOwnerHome = resolveOwnerHome;
 exports.ownerArtifactPath = ownerArtifactPath;
 exports.configuredArtifactPath = configuredArtifactPath;
@@ -34,6 +35,16 @@ function assertSameOwner(expected, actual) {
     if (ownerKey(expected) !== ownerKey(actual))
         throw new Error('owner-path-conflict: the approved home differs from the configured path');
 }
+/** Shared authored-family identity check. Handwritten entries can omit Domain metadata. */
+function assertLearningTargetPath(ref, domain) {
+    const subject = ref.owner.level === 'Org' ? 'org' : ref.learningSubject;
+    if (!subject || !/^[a-zA-Z0-9@._+-]+$/.test(subject))
+        throw new Error('learning-subject-required');
+    const escaped = subject.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const match = ref.relativePath.match(new RegExp(`^learnings/${escaped}-((?:[a-z][a-z-]*-)?)(preferences|mistake-patterns|validated-patterns|manager-coaching)(\\.cold)?\\.md$`));
+    if (!match || (domain !== undefined && match[1] !== (domain === 'global' ? '' : domain + '-')))
+        throw new Error('domain-target-mismatch: learning subject, domain and family must match its file');
+}
 /** Pure read: resolve existing configured homes without migration or identity configuration. */
 function resolveOwnerHome(projectPath, level, options) {
     const load = (relative) => options.runtimeModule(projectPath, relative);

package/dist/registry/scripts/learning/proposal-queue.js

@@ -0,0 +1,81 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashContent = void 0;
+exports.atomicWrite = atomicWrite;
+exports.withFileLock = withFileLock;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const node_os_1 = require("node:os");
+const hashContent = (text) => (0, node_crypto_1.createHash)('sha256').update(text).digest('hex');
+exports.hashContent = hashContent;
+function atomicWrite(file, text) {
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
+    const temporary = file + '.' + (0, node_crypto_1.randomUUID)() + '.tmp';
+    try {
+        node_fs_1.default.writeFileSync(temporary, text, { encoding: 'utf8', flag: 'wx' });
+        const fd = node_fs_1.default.openSync(temporary, 'r+');
+        try {
+            node_fs_1.default.fsyncSync(fd);
+        }
+        finally {
+            node_fs_1.default.closeSync(fd);
+        }
+        node_fs_1.default.renameSync(temporary, file);
+    }
+    finally {
+        if (node_fs_1.default.existsSync(temporary))
+            node_fs_1.default.unlinkSync(temporary);
+    }
+}
+function withFileLock(file, fn) {
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
+    let fd;
+    try {
+        fd = node_fs_1.default.openSync(file + '.lock', 'wx');
+    }
+    catch {
+        // Serialize recovery so two contenders cannot unlink each other's new lock.
+        let recovery;
+        try {
+            recovery = node_fs_1.default.openSync(file + '.lock.recovery', 'wx');
+        }
+        catch {
+            throw new Error('busy: lock recovery is already in progress');
+        }
+        try {
+            const owner = JSON.parse(node_fs_1.default.readFileSync(file + '.lock', 'utf8'));
+            let stale = false;
+            if (owner.host === (0, node_os_1.hostname)() && Number.isInteger(owner.pid) && owner.pid > 0) {
+                try {
+                    process.kill(owner.pid, 0);
+                }
+                catch (error) {
+                    stale = error.code === 'ESRCH';
+                }
+            }
+            if (!stale)
+                throw new Error('busy');
+            node_fs_1.default.unlinkSync(file + '.lock');
+            fd = node_fs_1.default.openSync(file + '.lock', 'wx');
+        }
+        catch {
+            throw new Error('busy: reconcile outstanding lock before retry');
+        }
+        finally {
+            node_fs_1.default.closeSync(recovery);
+            node_fs_1.default.unlinkSync(file + '.lock.recovery');
+        }
+    }
+    node_fs_1.default.writeFileSync(fd, JSON.stringify({ pid: process.pid, host: (0, node_os_1.hostname)(), at: new Date().toISOString() }));
+    try {
+        return fn();
+    }
+    finally {
+        node_fs_1.default.closeSync(fd);
+        node_fs_1.default.unlinkSync(file + '.lock');
+    }
+}

package/dist/src/ai-hub/hosts.js

@@ -31,6 +31,7 @@ exports.buildDirectStartPlan = buildDirectStartPlan;
 exports.buildDirectContinuePlan = buildDirectContinuePlan;
 exports.parseHostLine = parseHostLine;
 exports.detectCodexCompactTaskFailure = detectCodexCompactTaskFailure;
+exports.wireHostProcess = wireHostProcess;
 exports.describeSpawnError = describeSpawnError;
 exports.hostDefaultUnsetEnv = hostDefaultUnsetEnv;
 exports.buildHostSpawnEnv = buildHostSpawnEnv;
@@ -2398,6 +2399,32 @@ function detectCodexCompactTaskFailure(line) {
     return null;
 }
 function wireHostProcess(hostId, child, handlers, spawnCwd) {
+    // Exec's JSON error has no auth code. Require independent provider stderr
+    // provenance AND the same terminal protocol error; never scan tool/prose text.
+    const codexRefreshFailure = 'Your access token could not be refreshed because your refresh token was already used. Please log out and sign in again.';
+    let codexAuthDiagnostic = false;
+    let codexTerminalAuthFailure = false;
+    const observeCodexAuth = (line, channel) => {
+        if (hostId !== 'codex')
+            return;
+        if (channel === 'stderr') {
+            const clean = line.replace(/\x1b\[[0-9;]*m/g, '').trim();
+            const diagnostic = clean.match(/^(?:\d{4}-\d{2}-\d{2}T[\d:.]+Z\s+)?ERROR\s+codex_login::auth::manager:\s+Failed to refresh token: (.+)$/);
+            if (diagnostic?.[1] === codexRefreshFailure)
+                codexAuthDiagnostic = true;
+            return;
+        }
+        try {
+            const event = JSON.parse(line);
+            if (event.type === 'turn.failed' || event.type === 'error') {
+                codexTerminalAuthFailure = (event.type === 'turn.failed' ? event.error?.message : event.message) === codexRefreshFailure;
+            }
+            else if (event.type === 'turn.started' || event.type === 'turn.completed') {
+                codexTerminalAuthFailure = false;
+            }
+        }
+        catch { /* Plain stdout cannot establish authentication failure. */ }
+    };
     const wire = (buffer, channel) => {
         let pending = '';
         let suppressCodexModelRefreshStderr = false;
@@ -2406,6 +2433,7 @@ function wireHostProcess(hostId, child, handlers, spawnCwd) {
             const lines = pending.split(/\r?\n/);
             pending = lines.pop() || '';
             for (const line of lines) {
+                observeCodexAuth(line, channel);
                 if (hostId === 'codex' && channel === 'stderr') {
                     if (line.includes('codex_models_manager::manager: failed to refresh available models:')) {
                         suppressCodexModelRefreshStderr = true;
@@ -2431,6 +2459,7 @@ function wireHostProcess(hostId, child, handlers, spawnCwd) {
         });
         buffer.on('end', () => {
             if (pending.trim().length > 0) {
+                observeCodexAuth(pending, channel);
                 const parsed = parseHostLine(hostId, pending);
                 if (parsed.message || parsed.sessionId || parsed.raw) {
                     handlers.onEvent(parsed, channel);
@@ -2444,7 +2473,12 @@ function wireHostProcess(hostId, child, handlers, spawnCwd) {
     // signal='SIGSEGV') are NOT treated as clean exits by classifyExit's
     // `exitCode ?? 0` guard. Pass -1 for any signal-terminated child so the
     // non-zero branch fires and recovery is attempted.
-    child.on('close', (code, signal) => handlers.onExit(signal ? -1 : code));
+    child.on('close', (code, signal) => {
+        if (!signal && code !== null && code !== 0 && codexAuthDiagnostic && codexTerminalAuthFailure) {
+            handlers.onEvent({ hostAuthenticationRequired: true, hostError: codexRefreshFailure, raw: codexRefreshFailure }, 'system');
+        }
+        handlers.onExit(signal ? -1 : code);
+    });
     // Issue #1327: without this listener, an OS-level spawn failure (EAGAIN,
     // ENOENT, EACCES) fires an 'error' event on the ChildProcess. An unhandled
     // EventEmitter 'error' throws synchronously and crashes the Hub process.

package/dist/src/ai-hub/hub-app-materializer.js

@@ -10,6 +10,7 @@ exports.resolveHubAppCacheDir = resolveHubAppCacheDir;
 exports.isHubAppCacheComplete = isHubAppCacheComplete;
 exports.listCachedHubAppVersions = listCachedHubAppVersions;
 exports.runNpmInstall = runNpmInstall;
+exports.pruneHubAppCache = pruneHubAppCache;
 exports.ensureMaterializedHubApp = ensureMaterializedHubApp;
 exports.resolveHubAppEntry = resolveHubAppEntry;
 const fs_1 = __importDefault(require("fs"));
@@ -209,6 +210,24 @@ const defaultInstallPackage = async (version, destDir) => {
     }
     fs_1.default.rmSync(installedRoot, { recursive: true, force: true });
 };
+const HUB_APP_CACHE_MAX_VERSIONS = 3;
+/** Prune the hub-app cache to at most HUB_APP_CACHE_MAX_VERSIONS entries, always preserving keepVersion. Non-fatal. */
+function pruneHubAppCache(fraimDir, keepVersion) {
+    try {
+        const all = listCachedHubAppVersions(fraimDir);
+        const sorted = all.map((e) => e.version).sort((a, b) => (semver_1.default.gt(a, b) ? -1 : 1));
+        const toKeep = new Set(sorted.slice(0, HUB_APP_CACHE_MAX_VERSIONS));
+        toKeep.add(keepVersion);
+        for (const v of sorted) {
+            if (!toKeep.has(v)) {
+                fs_1.default.rmSync(resolveHubAppCacheDir(v, fraimDir), { recursive: true, force: true });
+            }
+        }
+    }
+    catch {
+        // Prune failure must never break a launch.
+    }
+}
 /**
  * Return the entry path for `version`, materializing it first if it is not already a complete
  * cache entry. Returns immediately (no npm invocation) when a complete entry already exists.
@@ -248,6 +267,7 @@ async function ensureMaterializedHubApp(version, options = {}) {
     finally {
         fs_1.default.rmSync(stagingDir, { recursive: true, force: true });
     }
+    pruneHubAppCache(fraimDir, version);
     return entryPath;
 }
 /**

package/dist/src/ai-hub/server.js

@@ -2596,7 +2596,9 @@ function summarizeHostErrorForThread(error) {
 // noise that the system handled on its own.
 function pushTerminalFailureToThread(run, exitCode) {
     if (exitCode !== 0 && run.lastHostError) {
-        run.messages.push((0, hosts_1.createHubMessage)('system', `This run stopped: ${summarizeHostErrorForThread(run.lastHostError)}`));
+        const detail = detectLoginFailureSignature(run, exitCode)
+            ? run.lastHostError : summarizeHostErrorForThread(run.lastHostError);
+        run.messages.push((0, hosts_1.createHubMessage)('system', `This run stopped: ${detail}`));
     }
 }
 function createHubRecoveryEvent(run, exitCode, attempt) {
@@ -3017,6 +3019,7 @@ class AiHubServer {
         this.latestVersionPollTimer = null;
         this.catalogSyncChild = null;
         this.attachmentPolicy = (0, attachment_store_1.attachmentPolicy)();
+        this.configureAgentSurface = options.configureAgentSurface ?? configureFraimForHubAgent;
         this.openTerminal = options.openTerminal ?? hubOpenTerminal;
         this.preferencesStore = options.preferencesStore || new preferences_1.AiHubPreferencesStore();
         const launchResolution = options.projectPath
@@ -4254,7 +4257,10 @@ class AiHubServer {
                 const option = hubAgentOption(run.hostId);
                 run.status = 'failed';
                 run.pauseReason = 'awaiting_user';
-                run.loginRequired = option ? { agentLabel: option.label } : undefined;
+                run.loginRequired = option ? {
+                    agentLabel: option.label,
+                    ...(run.hostId === 'codex' && run.lastHostError ? { remediation: run.lastHostError } : {}),
+                } : undefined;
             }
             if (run.status !== 'running') {
                 run.eventLogRefs = (run.eventLogRefs || []).map((ref) => {
@@ -7013,7 +7019,7 @@ class AiHubServer {
                 return res.json({ ok: true, configured: [], message: 'No ready CLI agents to configure.' });
             }
             const results = await Promise.all(readyIds.map(async (hubId) => {
-                const result = await configureFraimForHubAgent(hubId);
+                const result = await this.configureAgentSurface(hubId);
                 return { hubId, ...result };
             }));
             const failed = results.filter((r) => !r.configured);