@prodero/curator 0.1.0 → 0.2.0

package/dist/core/npm-update.js

@@ -0,0 +1,289 @@
+/** Terminal-owned npm update. Every controller import is a Node builtin and is
+ * loaded before npm may replace this package; no project or host writers. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { gunzip } from 'node:zlib';
+import { promisify } from 'node:util';
+const unzip = promisify(gunzip);
+const NAME = '@prodero/curator', REGISTRY = 'https://registry.npmjs.org/';
+const stable = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const MAX_TARBALL = 32 * 1024 * 1024, MAX_UNPACKED = 128 * 1024 * 1024;
+export class NpmUpdateError extends Error {
+    code;
+    exitCode;
+    constructor(code, message, exitCode = 1) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+    }
+}
+function fail(code, message) { throw new NpmUpdateError(code, message); }
+// The registry normalizes away ./; allow only these equivalent exact paths.
+const supportedBin = (value) => !!value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 1 && Object.hasOwn(value, 'prodero') && ['bin/prodero', './bin/prodero'].includes(value.prodero);
+const comparison = (a, b) => { const x = a.split('.').map(Number), y = b.split('.').map(Number); return x[0] - y[0] || x[1] - y[1] || x[2] - y[2]; };
+const supportedEngine = (engine, node) => {
+    // The initial allowlist intentionally accepts only the project's published
+    // engine contract. Unknown range syntax is unsupported, never guessed.
+    return engine === '>=22.14.0 <23' && stable.test(node) && comparison(node, '22.14.0') >= 0 && comparison(node, '23.0.0') < 0;
+};
+async function bounded(response, max) {
+    if (!response.ok || !response.body)
+        fail('NPM_UPDATE_REGISTRY', 'The public npm artifact or metadata is unavailable. No install started.');
+    const length = Number(response.headers.get('content-length'));
+    if (length > max)
+        fail('NPM_UPDATE_ARTIFACT', 'The npm response exceeds the supported size.');
+    const reader = response.body.getReader(), parts = [];
+    let bytes = 0;
+    try {
+        while (true) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            bytes += chunk.value.length;
+            if (bytes > max)
+                fail('NPM_UPDATE_ARTIFACT', 'The npm response exceeds the supported size.');
+            parts.push(Buffer.from(chunk.value));
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+    return Buffer.concat(parts);
+}
+function childEnv(temp, node) {
+    return { HOME: path.join(temp, 'home'), TMPDIR: path.join(temp, 'tmp'), PATH: path.dirname(node), LANG: 'C', LC_ALL: 'C', NO_COLOR: '1', npm_config_update_notifier: 'false' };
+}
+/** Wait for actual exit, but never wait indefinitely for descendants holding
+ * inherited output pipes. Only this command's direct child is signalled. */
+export async function runNpmCommand(node, args, options) {
+    return new Promise(resolve => {
+        let stdout = '', stderr = '', timedOut = false, done = false, exited = false, code = null, signal = null;
+        const child = spawn(node, args, { cwd: options.cwd, env: options.env, shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
+        let hardTimer, drainTimer, finalTimer;
+        const finish = (outputIncomplete) => { if (done)
+            return; done = true; clearTimeout(deadline); clearTimeout(hardTimer); clearTimeout(drainTimer); clearTimeout(finalTimer); child.stdout.destroy(); child.stderr.destroy(); child.unref(); resolve({ code, stdout, stderr, timedOut, exited, outputIncomplete, signal }); };
+        child.stdout.on('data', data => { stdout = (stdout + String(data)).slice(-65536); });
+        child.stderr.on('data', data => { stderr = (stderr + String(data)).slice(-65536); });
+        const deadline = setTimeout(() => { timedOut = true; child.kill('SIGTERM'); hardTimer = setTimeout(() => { child.kill('SIGKILL'); finalTimer = setTimeout(() => finish(true), 250); }, 5000); }, options.timeout);
+        child.once('error', () => finish(true));
+        child.once('exit', (exitCode, exitSignal) => { exited = true; code = exitCode; signal = exitSignal; clearTimeout(deadline); clearTimeout(hardTimer); drainTimer = setTimeout(() => finish(true), 250); });
+        child.once('close', () => finish(false));
+    });
+}
+function flags(temp, prefix) { return ['--prefix', prefix, '--userconfig', path.join(temp, 'user.npmrc'), '--globalconfig', path.join(temp, 'global.npmrc'), '--cache', path.join(temp, 'cache'), '--registry', REGISTRY]; }
+async function owned(target, directory = false) {
+    const stat = await fs.lstat(target);
+    if (stat.isSymbolicLink() || (directory ? !stat.isDirectory() : !stat.isFile()) || (process.getuid && stat.uid !== process.getuid()) || (stat.mode & 0o022))
+        fail('NPM_UPDATE_LAYOUT', 'This updater requires an ordinary same-user npm installation without writable shared paths. Use your package manager for this layout.');
+    if (directory && !(stat.mode & 0o200))
+        fail('NPM_UPDATE_PERMISSION', 'This npm installation is not writable. Repair permissions with its package manager; this updater does not use sudo.');
+    if (directory)
+        await fs.access(target, fs.constants.W_OK).catch(() => fail('NPM_UPDATE_PERMISSION', 'This npm installation is not writable. Repair permissions with its package manager; this updater does not use sudo.'));
+    return stat;
+}
+async function layout(deps, temp) {
+    const selectedRoot = path.resolve(deps.packageRoot ?? fileURLToPath(new URL('../..', import.meta.url))), root = await fs.realpath(selectedRoot), prefix = path.resolve(root, '../../../..');
+    if (selectedRoot !== root)
+        fail('NPM_UPDATE_LAYOUT', 'Linked package roots are unsupported. Invoke this installation’s own public executable.');
+    const entry = path.resolve(deps.entryPath ?? process.argv[1] ?? '');
+    const publicEntries = [path.join(prefix, 'bin/prodero'), path.join(root, 'bin/prodero')], internalCli = path.join(root, 'dist/cli.js');
+    if (!publicEntries.includes(entry) && entry !== internalCli || await fs.realpath(entry) !== (entry === internalCli ? internalCli : path.join(root, 'bin/prodero')))
+        fail('NPM_UPDATE_LAYOUT', 'The invoked executable does not belong to this exact npm installation. Linked aliases cannot select a different prefix.');
+    if (root !== path.join(prefix, 'lib/node_modules/@prodero/curator') || await fs.stat(path.join(root, 'src/cli.ts')).catch(() => null))
+        fail('NPM_UPDATE_LAYOUT', 'Only an installed global npm @prodero/curator package is supported. Linked packages and source checkouts need their package manager.');
+    for (const dir of [prefix, path.join(prefix, 'bin'), path.join(prefix, 'lib'), path.join(prefix, 'lib/node_modules'), path.join(prefix, 'lib/node_modules/@prodero'), root])
+        await owned(dir, true);
+    await owned(path.join(root, 'package.json'));
+    await owned(path.join(root, 'bin/prodero'));
+    const pkg = JSON.parse(await fs.readFile(path.join(root, 'package.json'), 'utf8'));
+    if (pkg.name !== NAME || !stable.test(pkg.version) || !supportedBin(pkg.bin))
+        fail('NPM_UPDATE_LAYOUT', 'The installed package identity or public executable is unsupported.');
+    const publicBin = path.join(prefix, 'bin/prodero');
+    const bin = await fs.lstat(publicBin);
+    if (!bin.isSymbolicLink() || process.getuid && bin.uid !== process.getuid() || await fs.realpath(publicBin) !== path.join(root, 'bin/prodero'))
+        fail('NPM_UPDATE_LAYOUT', 'The public executable does not belong to this npm package. No other installation will be changed.');
+    const node = await fs.realpath(deps.nodePath ?? process.execPath);
+    await fs.access(node, fs.constants.X_OK);
+    const npm = await fs.realpath(path.join(path.dirname(node), 'npm')).catch(() => fail('NPM_UPDATE_TOOLCHAIN', 'Cannot find npm beside the current Node executable. Use this installation’s package manager.'));
+    const npmRoot = path.resolve(path.dirname(npm), '..'), npmPkg = JSON.parse(await fs.readFile(path.join(npmRoot, 'package.json'), 'utf8'));
+    if (npm !== path.join(npmRoot, 'bin/npm-cli.js') || npmPkg.name !== 'npm' || npmPkg.bin?.npm !== 'bin/npm-cli.js' || !/^10\.9\.\d+$/.test(npmPkg.version))
+        fail('NPM_UPDATE_TOOLCHAIN', 'This updater supports npm 10.9.x with Node 22.14–22.x. Other toolchains need their package manager.');
+    if (!supportedEngine('>=22.14.0 <23', process.versions.node))
+        fail('NPM_UPDATE_TOOLCHAIN', 'This updater requires Node 22.14–22.x.');
+    for (const file of [node, npm, path.join(npmRoot, 'package.json')]) {
+        const s = await fs.lstat(file);
+        if (!s.isFile() || s.mode & 0o022 || process.getuid && s.uid !== process.getuid() && s.uid !== 0)
+            fail('NPM_UPDATE_TOOLCHAIN', 'The Node/npm toolchain ownership or permissions are unsupported.');
+    }
+    if (node.startsWith(root + path.sep) || npm.startsWith(root + path.sep))
+        fail('NPM_UPDATE_TOOLCHAIN', 'Node and npm must be outside the package being replaced.');
+    const run = deps.run ?? runNpmCommand, options = { cwd: temp, env: childEnv(temp, node), timeout: 15000 }, fixed = flags(temp, prefix);
+    const npmRootResult = await run(node, [npm, 'root', '--global', ...fixed], options), listing = await run(node, [npm, 'ls', '--global', '--parseable', '--depth=0', NAME, ...fixed], options);
+    if (npmRootResult.code !== 0 || npmRootResult.timedOut || npmRootResult.outputIncomplete || npmRootResult.exited === false || npmRootResult.stdout.trim() !== path.join(prefix, 'lib/node_modules') || listing.code !== 0 || listing.timedOut || listing.outputIncomplete || listing.exited === false || !listing.stdout.trim().split(/\r?\n/).includes(root))
+        fail('NPM_UPDATE_LAYOUT', 'The verified npm does not recognize this exact global installation. No package was changed.');
+    const identities = await Promise.all([entry, node, npm, path.join(npmRoot, 'package.json'), path.join(root, 'package.json'), path.join(root, 'bin/prodero')].map(async (file) => { const s = await fs.stat(file); return [file, s.dev, s.ino, s.size, s.mtimeMs, s.uid, s.mode]; }));
+    return { root, prefix, node, npm, version: pkg.version, identity: JSON.stringify(identities) };
+}
+function manifest(value, version) {
+    const v = value;
+    if (!v || v.name !== NAME || !stable.test(v.version) || version && v.version !== version || !supportedBin(v.bin) || !supportedEngine(v.engines?.node, process.versions.node))
+        fail('NPM_UPDATE_TARGET', 'The npm target identity, executable or Node engine contract is unsupported.');
+    if (v.scripts && (typeof v.scripts !== 'object' || Array.isArray(v.scripts)))
+        fail('NPM_UPDATE_TARGET', 'Invalid npm target script metadata.');
+    if (v.scripts && ['preinstall', 'install', 'postinstall'].some(k => v.scripts[k]))
+        fail('NPM_UPDATE_SCRIPTS', 'The target requires install lifecycle hooks, which this updater does not run.');
+    return v;
+}
+/** Inspect the verified archive before npm can create bins or install anything.
+ * Normal ustar and npm PAX headers are supported; links/escaping paths are not. */
+async function archiveManifest(compressed) {
+    const tar = await unzip(compressed, { maxOutputLength: MAX_UNPACKED }), files = new Set();
+    let pkg, paxPath;
+    for (let offset = 0; offset + 512 <= tar.length;) {
+        const h = tar.subarray(offset, offset + 512);
+        if (h.every(b => b === 0))
+            break;
+        const field = (start, size) => h.subarray(start, start + size).toString('utf8').replace(/\0.*$/s, '');
+        const sizeText = field(124, 12).trim();
+        if (!/^[0-7]+$/.test(sizeText))
+            fail('NPM_UPDATE_ARTIFACT', 'Unsupported npm archive size field.');
+        const size = parseInt(sizeText, 8), end = offset + 512 + size;
+        if (!Number.isSafeInteger(size) || end > tar.length)
+            fail('NPM_UPDATE_ARTIFACT', 'Incomplete npm archive.');
+        const checksum = parseInt(field(148, 8).trim(), 8), sum = h.reduce((a, b, i) => a + (i >= 148 && i < 156 ? 32 : b), 0);
+        if (checksum !== sum)
+            fail('NPM_UPDATE_ARTIFACT', 'Invalid npm archive header.');
+        const type = field(156, 1), body = tar.subarray(offset + 512, end);
+        offset += 512 + Math.ceil(size / 512) * 512;
+        if (type === 'x' || type === 'g') {
+            let at = 0;
+            while (at < body.length) {
+                const space = body.indexOf(32, at), length = Number(body.subarray(at, space).toString());
+                if (space < at || !Number.isSafeInteger(length) || length <= space - at + 1 || at + length > body.length)
+                    fail('NPM_UPDATE_ARTIFACT', 'Invalid npm archive metadata.');
+                const record = body.subarray(space + 1, at + length - 1).toString(), equal = record.indexOf('=');
+                if (record.slice(0, equal) === 'path')
+                    paxPath = record.slice(equal + 1);
+                if (['linkpath', 'size'].includes(record.slice(0, equal)))
+                    fail('NPM_UPDATE_ARTIFACT', 'Unsupported npm archive metadata.');
+                at += length;
+            }
+            continue;
+        }
+        const name = paxPath ?? [field(345, 155), field(0, 100)].filter(Boolean).join('/');
+        paxPath = undefined;
+        if (!name.startsWith('package/') || name.includes('\\') || name.split('/').includes('..') || path.posix.normalize(name).replace(/\/$/, '') !== name.replace(/\/$/, ''))
+            fail('NPM_UPDATE_ARTIFACT', 'Unsafe npm archive path.');
+        if (type === '5')
+            continue;
+        if (type !== '' && type !== '0')
+            fail('NPM_UPDATE_ARTIFACT', 'Linked or unsupported npm archive entries are not supported.');
+        const relative = name.slice(8);
+        if (files.has(relative))
+            fail('NPM_UPDATE_ARTIFACT', 'Duplicate npm archive entry.');
+        files.add(relative);
+        if (relative.endsWith('.node') || path.posix.basename(relative) === 'binding.gyp')
+            fail('NPM_UPDATE_SCRIPTS', 'A target native build is unsupported with install scripts disabled.');
+        if (relative === 'package.json') {
+            if (size > 1024 * 1024)
+                fail('NPM_UPDATE_ARTIFACT', 'The package manifest is too large.');
+            try {
+                pkg = JSON.parse(body.toString('utf8'));
+            }
+            catch {
+                fail('NPM_UPDATE_ARTIFACT', 'Invalid package manifest in npm archive.');
+            }
+        }
+    }
+    if (!pkg || !files.has('bin/prodero') || !files.has('dist/cli.js'))
+        fail('NPM_UPDATE_ARTIFACT', 'The target is missing its prebuilt public executable or CLI.');
+    return { pkg, files };
+}
+export async function runNpmUpdate(options = {}, deps = {}) {
+    if (options.targetVersion && !stable.test(options.targetVersion))
+        fail('NPM_UPDATE_VERSION', 'Use one exact stable version (for example 0.2.0), without ranges, tags or URLs.');
+    if (!deps.interactive && !(options.yes && options.targetVersion))
+        fail('NPM_UPDATE_CONFIRMATION', 'Use an interactive terminal, or explicitly run prodero update <exact-version> --yes after ending work and closing Codex and Claude.');
+    const write = deps.write ?? console.log, temp = await fs.mkdtemp(path.join(os.tmpdir(), 'prodero-npm-update-'));
+    let started = false;
+    try {
+        await Promise.all(['home', 'tmp', 'cache'].map(dir => fs.mkdir(path.join(temp, dir), { mode: 0o700 })));
+        await Promise.all(['user.npmrc', 'global.npmrc'].map(file => fs.writeFile(path.join(temp, file), '', { mode: 0o600 })));
+        const current = await layout(deps, temp), request = deps.request ?? fetch;
+        let target;
+        try {
+            const data = await bounded(await request(`${REGISTRY}@prodero%2fcurator/${options.targetVersion ?? 'latest'}`, { signal: AbortSignal.timeout(15000), redirect: 'error' }), 1024 * 1024);
+            target = manifest(JSON.parse(data.toString()), options.targetVersion);
+        }
+        catch (error) {
+            if (error instanceof NpmUpdateError)
+                throw error;
+            fail('NPM_UPDATE_REGISTRY', 'Cannot verify the public npm target. No install started.');
+        }
+        if (comparison(target.version, current.version) < 0)
+            fail('NPM_UPDATE_VERSION', 'Downgrades are not supported. No package was changed.');
+        if (target.version === current.version)
+            return { ok: true, status: 'current', installedVersion: current.version, targetVersion: target.version, prefix: current.prefix, restartRequired: false, message: 'This exact npm version is already installed. No package was changed.', exitCode: 0 };
+        let url;
+        try {
+            url = new URL(target.dist.tarball);
+        }
+        catch {
+            fail('NPM_UPDATE_TARGET', 'The npm artifact URL is missing or invalid.');
+        }
+        if (url.protocol !== 'https:' || url.hostname !== 'registry.npmjs.org' || url.port || url.username || url.password || url.search || url.hash || url.pathname !== `/@prodero/curator/-/curator-${target.version}.tgz` || !/^sha512-[A-Za-z0-9+/]{86}==$/.test(target.dist.integrity))
+            fail('NPM_UPDATE_TARGET', 'Only a verified standard npm registry artifact is supported.');
+        let tarball;
+        try {
+            tarball = await bounded(await request(url.href, { signal: AbortSignal.timeout(30000), redirect: 'error' }), MAX_TARBALL);
+        }
+        catch (error) {
+            if (error instanceof NpmUpdateError)
+                throw error;
+            fail('NPM_UPDATE_REGISTRY', 'Cannot download the verified npm artifact. No install started.');
+        }
+        if (`sha512-${crypto.createHash('sha512').update(tarball).digest('base64')}` !== target.dist.integrity)
+            fail('NPM_UPDATE_INTEGRITY', 'The downloaded npm artifact does not match its approved integrity. No install started.');
+        const archived = manifest((await archiveManifest(tarball)).pkg, target.version);
+        if (archived.engines.node !== target.engines.node)
+            fail('NPM_UPDATE_TARGET', 'The artifact engine metadata differs from the registry.');
+        write(`Update ${NAME}: ${current.version} → ${target.version}\nDestination: ${current.prefix}\nInstall scripts are disabled. Standard npm production dependencies will be resolved from the public registry.\nFinish work and close Codex and Claude before continuing. This command does not detect or close running applications.`);
+        if (options.yes)
+            write('--yes confirms that you have finished work and closed Codex and Claude.');
+        if (!options.yes && !await deps.confirm?.('Have you finished work and closed Codex and Claude? Continue with this update? [y/N] '))
+            return { ok: false, status: 'cancelled', installedVersion: current.version, targetVersion: target.version, prefix: current.prefix, restartRequired: false, message: 'Update cancelled. No package was changed.', exitCode: 1 };
+        if ((await layout(deps, temp)).identity !== current.identity)
+            fail('NPM_UPDATE_CHANGED', 'The installation or toolchain changed during confirmation. Run the update again to review it.');
+        const artifact = path.join(temp, 'curator.tgz');
+        await fs.writeFile(artifact, tarball, { mode: 0o600 });
+        write('Installing the checked npm artifact. Keep Codex and Claude closed until verification finishes.');
+        const run = deps.run ?? runNpmCommand, execOptions = { cwd: temp, env: childEnv(temp, current.node), timeout: 180000 };
+        started = true;
+        const installed = await run(current.node, [current.npm, 'install', '--global', ...flags(temp, current.prefix), '--ignore-scripts', '--engine-strict', '--omit=dev', '--no-audit', '--no-fund', artifact], execOptions);
+        if (installed.code !== 0 || installed.timedOut || installed.outputIncomplete || installed.exited === false)
+            return { ok: false, status: 'failed', installedVersion: null, targetVersion: target.version, prefix: current.prefix, restartRequired: true, message: 'npm did not complete successfully. The installation may be partial; keep applications closed and inspect/repair this npm installation before retrying. No rollback is claimed.', exitCode: installed.code && installed.code > 0 ? installed.code : 1 };
+        // From this boundary onward use only builtin readers/child-process code already
+        // loaded above. Never import new helpers from the replaced installation.
+        const pkg = JSON.parse(await fs.readFile(path.join(current.root, 'package.json'), 'utf8'));
+        if (pkg.name !== NAME || pkg.version !== target.version || !supportedBin(pkg.bin) || await fs.realpath(path.join(current.prefix, 'bin/prodero')) !== path.join(current.root, 'bin/prodero'))
+            fail('NPM_UPDATE_VERIFY', 'npm finished, but the installed package or public executable does not match the target. Keep applications closed and repair the npm installation.');
+        await fs.access(path.join(current.prefix, 'bin/prodero'), fs.constants.X_OK);
+        const version = await run(current.node, [path.join(current.root, 'bin/prodero'), '--version'], { ...execOptions, timeout: 15000 }), help = await run(current.node, [path.join(current.root, 'bin/prodero'), '--help'], { ...execOptions, timeout: 15000 });
+        if (version.outputIncomplete || help.outputIncomplete || version.exited === false || help.exited === false || version.timedOut || help.timedOut || version.code !== 0 || version.stdout.trim() !== target.version || help.code !== 0 || !help.stdout.includes('Usage: prodero'))
+            fail('NPM_UPDATE_VERIFY', 'The installed target failed its CLI smoke checks. Keep applications closed and repair the npm installation.');
+        return { ok: true, status: 'updated', installedVersion: target.version, targetVersion: target.version, prefix: current.prefix, restartRequired: true, message: `Installed ${NAME}@${target.version} and verified its public CLI. Reopen Codex or Claude and reconnect MCP to load the new runtime. Project data and saved host/dev selections were not changed by this updater.`, exitCode: 0 };
+    }
+    catch (error) {
+        if (error instanceof NpmUpdateError)
+            throw error;
+        throw new NpmUpdateError(started ? 'NPM_UPDATE_VERIFY' : 'NPM_UPDATE_FAILED', started ? 'The update outcome could not be verified. Keep applications closed and inspect/repair the npm installation before retrying.' : 'The npm installation or target could not be verified. No install started.');
+    }
+    finally {
+        await fs.rm(temp, { recursive: true, force: true }).catch(() => { });
+    }
+}
+//# sourceMappingURL=npm-update.js.map

package/dist/core/project.js

@@ -33,7 +33,7 @@ import { discoverSessions } from "./session-index.js";
 import { closeSession, createSession, readSession, recordSessionObservations, updateSessionTaskContext } from "./sessions.js";
 import { DEFAULT_CONTEXT_BUDGET_TOKENS, DEFAULT_REQUIRED_CONTEXT_BUDGET_TOKENS, memoryCompression, summarizeSessionMemory, TOKEN_COUNT_METHOD } from "./telemetry.js";
 import { INDEX_TEMPLATE } from "./templates.js";
-import { ensureDerivedStateRoot, checkedDataPath, ensureProjectDirectories, ensureRuntimeDirectories, ensureLocalStateIgnored, exists, projectDataPath, readConfig, sha256, writeFileAtomic, writeConfig, } from "./storage.js";
+import { CANONICAL_ID_PATTERN, ensureDerivedStateRoot, checkedDataPath, ensureProjectDirectories, ensureRuntimeDirectories, ensureLocalStateIgnored, exists, projectDataPath, readConfig, sha256, writeFileAtomic, writeConfig, } from "./storage.js";
 export { PRODERO_SCHEMA_VERSION, PRODERO_VERSION } from "./constants.js";
 export { createSession, parseSession, SESSION_SECTIONS } from "./sessions.js";
 export { getContext } from "./context.js";
@@ -102,13 +102,13 @@ export async function getDetailedProjectStatus(start = process.cwd(), options =
         const statusReads = [
             config ? (async () => {
                 const phaseStarted = performance.now();
-                const result = await discoverSessions(root);
+                const result = await discoverSessions(root, { persistCache: options.persistCache });
                 options.instrument?.({ phase: "session-index", durationMs: performance.now() - phaseStarted, cache: result.cacheState, filesScanned: result.sessionFilesScanned, bodiesRead: result.sessionBodiesRead });
                 return result;
             })() : null,
             config ? (async () => {
                 const phaseStarted = performance.now();
-                const result = await loadMemoryCatalog(root);
+                const result = await loadMemoryCatalog(root, { persistCache: options.persistCache });
                 options.instrument?.({ phase: "memory-index", durationMs: performance.now() - phaseStarted, cache: result.cacheState, filesScanned: result.filesScanned, bodiesRead: result.bodiesIndexed });
                 return result;
             })() : null,
@@ -128,7 +128,7 @@ export async function getDetailedProjectStatus(start = process.cwd(), options =
         const [discovery, catalog, fast, skills] = statusResults;
         const telemetryStarted = performance.now();
         const knowledge = catalog?.summaries ?? [];
-        const graph = config && catalog ? await loadKnowledgeGraph(root, catalog) : null;
+        const graph = config && catalog ? await loadKnowledgeGraph(root, catalog, { persistCache: options.persistCache }) : null;
         const disputedIds = new Set(knowledge.filter((item) => item.status === "disputed").map((item) => item.id));
         const conflictPairs = new Set();
         for (const item of knowledge.filter((candidate) => candidate.status === "disputed")) {
@@ -138,7 +138,7 @@ export async function getDetailedProjectStatus(start = process.cwd(), options =
                 conflictPairs.add(item.id);
         }
         const counts = skillCounts(skills);
-        const recommendations = config ? await promotionRecommendations(root) : [];
+        const recommendations = config ? await promotionRecommendations(root, { persistCache: options.persistCache }) : [];
         const status = {
             ...fast,
             knowledgeCount: knowledge.filter((item) => item.status === "active" || item.status === "disputed").length,
@@ -165,8 +165,8 @@ export async function getDetailedProjectStatus(start = process.cwd(), options =
     }
 }
 /** Complete status remains the compatibility API for correctness-oriented callers. */
-export async function getProjectStatus(start = process.cwd()) {
-    return getDetailedProjectStatus(start);
+export async function getProjectStatus(start = process.cwd(), options = {}) {
+    return getDetailedProjectStatus(start, options);
 }
 export async function initializeProject(start = process.cwd()) {
     const root = await findProjectRoot(start);
@@ -510,7 +510,7 @@ export async function rememberProjectKnowledge(start, input, provider) {
     if (relationships.length > 12)
         throw new Error("Remember supports at most 12 explicit relationships.");
     for (const relation of relationships) {
-        if (!["related_to", "depends_on", "implements"].includes(relation.type) || !/^mem_[a-zA-Z0-9_]+$/.test(relation.target))
+        if (!["related_to", "depends_on", "implements"].includes(relation.type) || !CANONICAL_ID_PATTERN.test(relation.target))
             throw new Error("Remember relationship is malformed.");
         const target = beforeKnowledge.find((item) => item.id === relation.target);
         if (!target || (target.status !== "active" && target.status !== "disputed"))

package/dist/core/session-index.js

@@ -13,8 +13,9 @@ const cacheSchema = z.object({
     checkpoints: z.record(stampSchema.extend({ id: z.string(), createdAt: z.string(), processedKeys: z.array(z.string()), observationHashes: z.array(z.string()).optional() })),
     sessions: z.record(stampSchema.extend({ id: z.string(), parentSessionId: z.string().regex(/^sess_[a-zA-Z0-9_]+$/).optional(), sha256: z.string().regex(/^[a-f0-9]{64}$/), status: z.enum(["active", "open", "closed"]), hasObservations: z.boolean() })),
 });
-async function readCache(root) {
-    await ensureDerivedStateRoot(root);
+async function readCache(root, persistCache) {
+    if (persistCache)
+        await ensureDerivedStateRoot(root);
     const target = await checkedDataPath(root, ".cache", "session-index.json");
     if (!(await exists(target)))
         return { cache: structuredClone(EMPTY_CACHE), state: "missing" };
@@ -25,7 +26,8 @@ async function readCache(root) {
     catch {
         // Disposable derived JSON is rebuilt below; canonical sessions/checkpoints remain authoritative.
     }
-    await fs.rm(target, { force: true });
+    if (persistCache)
+        await fs.rm(target, { force: true });
     return { cache: structuredClone(EMPTY_CACHE), state: "invalid" };
 }
 function parseCheckpoint(content, filename) {
@@ -33,7 +35,7 @@ function parseCheckpoint(content, filename) {
     return { observationHashes: checkpoint.observationHashes ?? [], id: checkpoint.id, createdAt: checkpoint.createdAt, processedKeys: checkpoint.sessions.map((session) => `${session.path}:${session.sha256}`), size: 0, mtimeMs: 0, ctimeMs: 0 };
 }
 export async function discoverSessions(root, options = {}) {
-    const { cache, state } = await readCache(root);
+    const { cache, state } = await readCache(root, options.persistCache !== false);
     const nextCheckpoints = {};
     const processed = new Set();
     const processedObservations = new Set();
@@ -93,8 +95,10 @@ export async function discoverSessions(root, options = {}) {
         sessions.push({ id: cached.id, parentSessionId: cached.parentSessionId, path: name, sha256: cached.sha256, status: cached.status, hasObservations: cached.hasObservations, pending, session: parsed });
     }
     const nextCache = { version: 3, checkpoints: nextCheckpoints, sessions: nextSessions };
-    await ensureDerivedStateRoot(root);
-    await writeFileAtomic(projectDataPath(root, ".cache", "session-index.json"), `${JSON.stringify(nextCache)}\n`);
+    if (options.persistCache !== false) {
+        await ensureDerivedStateRoot(root);
+        await writeFileAtomic(projectDataPath(root, ".cache", "session-index.json"), `${JSON.stringify(nextCache)}\n`);
+    }
     const checkpointEntries = Object.values(nextCheckpoints).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
     return {
         processedObservations,

package/dist/core/sessions.js

@@ -1,4 +1,4 @@
-import { writeFileExclusive } from "./storage.js";
+import { writeFileExclusive, CANONICAL_ID_PATTERN } from "./storage.js";
 import { validateApplicability, inferApplicability, buildTaskContext } from "./applicability.js";
 import { assertPathScope } from "./path-scope.js";
 import { assertNoSecrets } from "./secrets.js";
@@ -218,9 +218,9 @@ export function validateEntries(entries) {
             if (entry.proposedReason && entry.proposedReason.length > 1_000)
                 throw new Error("Skill proposal reasons may not exceed 1,000 characters.");
         }
-        if (entry.supersedes?.some((id) => !/^mem_[a-zA-Z0-9_]+$/.test(id)))
+        if (entry.supersedes?.some((id) => !CANONICAL_ID_PATTERN.test(id)))
             throw new Error("Superseded Prodero memory ids are malformed.");
-        if (entry.relations?.some((relation) => !["related_to", "depends_on", "implements"].includes(relation.type) || !/^mem_[a-zA-Z0-9_]+$/.test(relation.target)))
+        if (entry.relations?.some((relation) => !["related_to", "depends_on", "implements"].includes(relation.type) || !CANONICAL_ID_PATTERN.test(relation.target)))
             throw new Error("Prodero memory relationships are malformed.");
         if (content.length > 10_000)
             throw new Error("A Prodero session observation may not exceed 10,000 characters.");

package/dist/core/settings.js

@@ -1,23 +1,34 @@
 import { SETTINGS, settingKeySchema } from '../settings-definition.js';
 import fs from 'node:fs/promises';
 import { presentationConfigSchema } from '../settings-definition.js';
-import { readConfig, writeConfig, projectDataPath, assertSafePath, exists } from './storage.js';
+import { readConfig, writeConfig, projectDataPath, assertSafePath, exists, assertSupportedSchema, assertSupportedKnowledgeSchema } from './storage.js';
 import { withSyncLock } from './sync-transaction.js';
-export function effectiveSettings(config) {
-    const values = { 'presentation.mode': config?.presentation?.mode, 'presentation.theme': config?.presentation?.theme, 'context.max_tokens': config?.context?.max_tokens ?? config?.context?.budgetTokens };
+import { readLocalPreferences, saveLocalPreference } from './local-preferences.js';
+async function supportedConfig(root) {
+    const config = await readConfig(root);
+    if (config) {
+        assertSupportedSchema(config.schemaVersion);
+        assertSupportedKnowledgeSchema(config.knowledgeSchemaVersion);
+    }
+    return config;
+}
+export function effectiveSettings(config, local = {}) {
+    const legacy = { 'presentation.mode': config?.presentation?.mode, 'presentation.theme': config?.presentation?.theme, 'context.max_tokens': config?.context?.max_tokens ?? config?.context?.budgetTokens };
+    const overrides = { 'presentation.mode': local.mode, 'presentation.theme': local.theme, 'context.max_tokens': undefined };
+    const values = { ...legacy, 'presentation.mode': local.mode ?? legacy['presentation.mode'], 'presentation.theme': local.theme ?? legacy['presentation.theme'] };
     return SETTINGS.map(def => {
         const value = values[def.key] ?? def.defaultValue;
         const option = 'options' in def ? def.options.find(o => o.id === value) : undefined;
         return { key: def.key, group: def.group, label: def.label, description: option && 'description' in option ? option.description : def.description, type: def.type, value,
             displayValue: option?.label ?? (typeof value === 'number' ? `${value.toLocaleString('en-US')} ${'unit' in def ? def.unit : ''}`.trim() : String(value)),
-            source: values[def.key] === undefined ? 'default' : 'project override',
+            source: overrides[def.key] !== undefined ? 'local override' : legacy[def.key] === undefined ? 'default' : def.group === 'Presentation' ? 'legacy project default' : 'project override',
             defaultValue: def.defaultValue, ...('options' in def ? { options: def.options } : {}), ...('min' in def ? { min: def.min, max: def.max } : {}) };
     });
 }
 export async function projectSettings(root) {
     let config;
     try {
-        config = await readConfig(root);
+        config = await supportedConfig(root);
     }
     catch (error) {
         // Presentation preferences are metadata, never a permission to read/write newer knowledge.
@@ -37,8 +48,9 @@ export async function projectSettings(root) {
         const presentation = presentationConfigSchema.safeParse(raw?.presentation);
         config = { presentation: presentation.success ? presentation.data : undefined };
     }
-    const settings = effectiveSettings(config);
-    return { root, initialized: config !== null, settings, presentation: { mode: config?.presentation?.mode ?? SETTINGS[0].defaultValue, theme: config?.presentation?.theme ?? SETTINGS[1].defaultValue } };
+    const local = await readLocalPreferences(root), settings = effectiveSettings(config, local.presentation);
+    return { root, initialized: config !== null, settings, presentation: { mode: local.presentation.mode ?? config?.presentation?.mode ?? SETTINGS[0].defaultValue, theme: local.presentation.theme ?? config?.presentation?.theme ?? SETTINGS[1].defaultValue },
+        presentationSources: { mode: settings[0].source, theme: settings[1].source }, diagnostics: local.diagnostics };
 }
 export function renderSettings(view) {
     const lines = ['Prodero · Project Settings'];
@@ -47,30 +59,36 @@ export function renderSettings(view) {
         for (const s of view.settings.filter(s => s.group === group))
             lines.push(`${s.label}: ${s.displayValue} (${s.source})`, s.description);
     }
+    lines.push('Display mode and theme are saved on this checkout. Context budget is shared project configuration.');
+    for (const diagnostic of view.diagnostics)
+        lines.push(`${diagnostic.code}: ${diagnostic.cause}`, diagnostic.recovery);
     if (!view.initialized)
         lines.push('Project is not initialized. Defaults are shown; initialize Prodero before saving settings.');
     return lines.join('\n\n');
 }
-export async function setProjectSetting(root, key, value) {
+export async function setProjectSetting(root, key, value, options = {}) {
     const name = settingKeySchema.parse(key), def = SETTINGS.find(s => s.key === name);
-    const parsed = def.validation.parse(value);
-    if (!await readConfig(root))
+    const reset = options.reset === true;
+    if (reset && (value !== undefined || name === 'context.max_tokens'))
+        throw new Error('Reset requires a presentation key and no value.');
+    const parsed = reset ? undefined : def.validation.parse(value);
+    if (!await supportedConfig(root))
         throw new Error('Initialize Prodero before changing project settings.');
     return withSyncLock(root, async () => {
-        const config = (await readConfig(root));
+        const config = await supportedConfig(root);
+        if (!config)
+            throw new Error('Initialize Prodero before changing project settings.');
         switch (name) {
             case 'presentation.mode':
-                config.presentation = { ...config.presentation, mode: parsed };
-                break;
             case 'presentation.theme':
-                config.presentation = { ...config.presentation, theme: parsed };
-                break;
+                await saveLocalPreference(root, name === 'presentation.mode' ? 'mode' : 'theme', parsed, reset);
+                return projectSettings(root);
             case 'context.max_tokens':
                 config.context = { ...config.context, max_tokens: parsed };
                 break;
         }
         await writeConfig(root, config);
         return projectSettings(root);
-    }, { waitMs: 5000 });
+    }, { waitMs: 5000, ...(name === 'context.max_tokens' ? {} : { recoverLifecycle: false, maintainIntegration: false }) });
 }
 //# sourceMappingURL=settings.js.map

package/dist/core/skills.js

@@ -5,7 +5,7 @@ import path from "node:path";
 import { z } from "zod";
 import { frontmatter, parseFrontmatter } from "./format.js";
 import { sortableId } from "./ids.js";
-import { tokens } from "./matching.js";
+import { tokens, normalized } from "./matching.js";
 import { exists, checkedDataPath, ensureDataDirectory, readConfig, sha256, writeFileAtomic } from "./storage.js";
 import { withSyncLock, recoverSyncTransaction, safeProjectPath, commitSyncTransaction, fileHash } from "./sync-transaction.js";
 import { estimateTokens } from "./telemetry.js";
@@ -284,7 +284,26 @@ export function scoreSkill(query, skill) {
     const matched = new Set(signals.flatMap(s => s.matches));
     const domainMatch = [...matched].some(t => !ambiguous.has(t));
     const enoughContext = matched.size >= 2;
-    return { score: domainMatch || enoughContext ? signals.reduce((sum, signal) => sum + signal.score, 0) : 0, signals };
+    // Topic overlap (even several nouns) is not a request to execute a procedure.
+    // Match a small action family in both the task and skill metadata. Installation
+    // as an audit subject deliberately does not imply an install request.
+    const intentFamilies = [
+        ['build', 'building', 'rebuild', 'rebuilding'],
+        ['install', 'installing', 'uninstall', 'uninstalling'],
+        ['switch', 'switching', 'enable', 'enabling', 'disable', 'disabling'],
+        ['test', 'tests', 'testing', 'verify', 'verification', 'validate', 'validation', 'check', 'checks'],
+        ['recover', 'recovery', 'restore', 'restoring'],
+        ['debug', 'debugging', 'diagnose', 'diagnosing', 'inspect', 'inspection', 'troubleshoot', 'troubleshooting'],
+        ['change', 'changes', 'changing', 'edit', 'editing', 'fix', 'fixing', 'implement', 'update'],
+    ];
+    const rawQuery = tokenize(query), metadata = tokenize(fields.map(([, value]) => value).join(' '));
+    const sharedIntent = intentFamilies.find(family => family.some(t => rawQuery.has(t)) && family.some(t => metadata.has(t)));
+    const directionalMode = rawQuery.has('dev') && rawQuery.has('npm') && /(?:↔|→|←|->|<-|\bto\b)/i.test(query)
+        && metadata.has('dev') && (metadata.has('npm') || metadata.has('package'));
+    const evidence = new Set([...matched, ...(sharedIntent ? ['procedural-intent'] : [])]);
+    const named = normalized(query) === normalized(skill.title) && normalized(query).length > 0;
+    const eligible = named || ((sharedIntent || directionalMode) && (domainMatch || enoughContext) && evidence.size >= 2);
+    return { score: eligible ? Math.max(named ? 1 : 0, signals.reduce((sum, signal) => sum + signal.score, 0)) : 0, signals };
 }
 export async function projectSkillsView(root, options = {}) {
     await requireProject(root);

package/dist/core/storage.js

@@ -70,6 +70,59 @@ export async function ensureStorageDirectory(target, forcePrivate = false) {
     if (forcePrivate)
         await tightenPrivateMode(target);
 }
+const privateIgnoreUpdates = new Map();
+/** Preference writes must not repair shared integration. Private self-exclusion
+ * protects files even when root ignore rules are absent; custom rules are never edited.
+ */
+export async function ensureSelfIgnoredPrivateDirectory(root, directory) {
+    const key = projectDataPath(root, directory), pending = privateIgnoreUpdates.get(key);
+    if (pending)
+        return pending;
+    const failure = () => new Error('PRODERO_LOCAL_IGNORE_UNAVAILABLE: Private ignore protection is unavailable. Preserve the existing local state and restore a safe self-excluding .gitignore containing only * in the private directory before retrying; shared project ignore rules were not changed.');
+    const update = (async () => {
+        try {
+            const target = await checkedDataPath(root, directory);
+            const ignore = await checkedDataPath(root, directory, '.gitignore');
+            const read = () => fs.readFile(ignore, 'utf8').catch(error => { if (error.code === 'ENOENT')
+                return null; throw error; });
+            const validate = (text) => {
+                const rules = text.split(/\r?\n/).filter(line => line !== '' && !line.startsWith('#'));
+                if (rules.length !== 1 || rules[0] !== '*')
+                    throw failure();
+            };
+            const readReady = async () => {
+                let current = await read();
+                // Another process may have opened the exclusive marker but not written its
+                // one rule yet. Wait briefly; never overwrite an existing empty/custom file.
+                for (let attempt = 0; current === '' && attempt < 3; attempt++) {
+                    await new Promise(resolve => setTimeout(resolve, 10));
+                    current = await read();
+                }
+                return current;
+            };
+            const current = await readReady();
+            if (current !== null)
+                validate(current);
+            else {
+                await ensureStorageDirectory(target);
+                await writeFileExclusive(ignore, '*\n').catch(error => { if (error.code !== 'EEXIST')
+                    throw error; });
+                validate((await readReady()) ?? '');
+            }
+            return target;
+        }
+        catch {
+            throw failure();
+        }
+    })();
+    privateIgnoreUpdates.set(key, update);
+    try {
+        return await update;
+    }
+    finally {
+        privateIgnoreUpdates.delete(key);
+    }
+}
 export async function writeFileExclusive(target, content) {
     await assertSafePath(target);
     await protectPrivatePath(target);
@@ -209,8 +262,9 @@ export async function ensureDataDirectory(root, relative) {
     await ensureStorageDirectory(target);
     return target;
 }
+export const CANONICAL_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
 export function canonicalId(value, filename) {
-    if (typeof value !== "string" || !/^[a-zA-Z0-9_-]+$/.test(value))
+    if (typeof value !== "string" || !CANONICAL_ID_PATTERN.test(value))
         throw new Error(`Invalid canonical ID: ${filename}`);
 }
 const positive = z.number().int().positive();