agentic-workflow-manager 9.17.0 → 9.18.0

package/dist/src/commands/registry/scaffold.js

@@ -0,0 +1,140 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scaffoldRegistry = scaffoldRegistry;
+// cli/src/commands/registry/scaffold.ts
+// Logic for `awm registry scaffold`, separated from commander wiring.
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const types_1 = require("../../core/facts/types");
+function writeJson(write, file, value) {
+    write(file, JSON.stringify(value, null, 2) + '\n');
+}
+function handbookFor(name) {
+    return `# ${name}
+
+## Capabilities
+| id | status | notes |
+|----|--------|-------|
+| facts | active | see ## Capability: facts |
+
+## Capability: facts
+
+Declare operator/machine facts in \`facts.json\`. Skills may list \`needs\` in
+frontmatter; values live in the machine-local environment store
+(\`AWM_HOME/environments/\`), never in this registry tree.
+
+- Add fact definitions under \`facts\` in \`facts.json\` (\`schemaVersion: 1\`).
+- Keep \`minCliVersion\` in \`awm-registry.json\` at or above the CLI version that
+  understands facts.
+- Run \`awm registry doctor\` before publishing — structural failures block; advisories do not.
+`;
+}
+function writeScaffoldTree(root, name, write) {
+    writeJson(write, path_1.default.join(root, 'awm-registry.json'), {
+        overrides: [],
+        minCliVersion: types_1.FACTS_MIN_CLI_VERSION,
+    });
+    writeJson(write, path_1.default.join(root, 'catalog.json'), {
+        version: 1,
+        bundles: [],
+    });
+    const skillsDir = path_1.default.join(root, 'skills');
+    fs_1.default.mkdirSync(skillsDir, { recursive: true });
+    // Track skills/ in git — an empty dir is dropped on clone and then
+    // validateRegistryLayout / awm registry add reject the tree (RF-4.1).
+    write(path_1.default.join(skillsDir, '.gitkeep'), '');
+    writeJson(write, path_1.default.join(root, 'facts.json'), {
+        schemaVersion: 1,
+        facts: {},
+    });
+    write(path_1.default.join(root, 'REGISTRY.md'), handbookFor(name));
+}
+/**
+ * Create a minimal registry tree that passes structural `doctorRegistry`.
+ * Atomic (RF-4.3): write into a temp sibling, then rename into place; on
+ * failure remove only the staging dir so an empty preexisting target stays
+ * empty (retryable) and a missing target stays absent.
+ */
+function scaffoldRegistry(dir, opts = {}) {
+    if (typeof dir !== 'string' || dir.trim() === '') {
+        return { ok: false, error: 'scaffold target directory is required' };
+    }
+    const abs = path_1.default.resolve(dir);
+    const write = opts.writeFileSync ?? ((file, data) => fs_1.default.writeFileSync(file, data));
+    let targetExistsEmpty = false;
+    if (fs_1.default.existsSync(abs)) {
+        let stat;
+        try {
+            stat = fs_1.default.lstatSync(abs);
+        }
+        catch (e) {
+            return {
+                ok: false,
+                error: `Cannot inspect target ${abs}: ${e instanceof Error ? e.message : String(e)}`,
+            };
+        }
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            return { ok: false, error: `Target exists and is not a directory: ${abs}` };
+        }
+        if (fs_1.default.readdirSync(abs).length > 0) {
+            return {
+                ok: false,
+                error: `Target directory is not empty — refuse to overwrite: ${abs}`,
+            };
+        }
+        targetExistsEmpty = true;
+    }
+    const parent = path_1.default.dirname(abs);
+    let staging;
+    try {
+        fs_1.default.mkdirSync(parent, { recursive: true });
+        staging = fs_1.default.mkdtempSync(path_1.default.join(parent, '.awm-scaffold-'));
+        const name = path_1.default.basename(abs) || 'registry';
+        // Always stage first so mid-fail never leaves a partial target (RF-4.3).
+        writeScaffoldTree(staging, name, write);
+        if (targetExistsEmpty) {
+            // Never rmdir the empty shell before contents land. Write into abs
+            // directly from the validated staging pattern, then drop staging.
+            try {
+                writeScaffoldTree(abs, name, write);
+            }
+            catch (writeErr) {
+                // Best-effort: remove what we wrote into the preexisting empty
+                // dir without deleting the empty shell itself.
+                try {
+                    for (const entry of fs_1.default.readdirSync(abs)) {
+                        fs_1.default.rmSync(path_1.default.join(abs, entry), { recursive: true, force: true });
+                    }
+                }
+                catch {
+                    // best-effort
+                }
+                throw writeErr;
+            }
+            fs_1.default.rmSync(staging, { recursive: true, force: true });
+            staging = undefined;
+            return { ok: true, dir: abs };
+        }
+        // Target does not exist: atomic rename of staging into place.
+        fs_1.default.renameSync(staging, abs);
+        staging = undefined;
+        return { ok: true, dir: abs };
+    }
+    catch (e) {
+        if (staging) {
+            try {
+                fs_1.default.rmSync(staging, { recursive: true, force: true });
+            }
+            catch {
+                // best-effort cleanup; surface the original write error
+            }
+        }
+        return {
+            ok: false,
+            error: `Scaffold failed: ${e instanceof Error ? e.message : String(e)}`,
+        };
+    }
+}

package/dist/src/commands/watch/index.js

@@ -160,6 +160,9 @@ function registerWatchCommand(program) {
         }
         else {
             process.stdout.write(`awm watch: ${outcome === 'stopped' ? 'detenido' : 'track congelado'}; ciclo ${final.cycleState ?? final.state} — sin certificacion de cierre\n`);
+            // exitCode only — never process.exit here: in-process tests call parseAsync
+            // inside Jest; a hard exit kills the worker (CI exit 130 on every OS).
+            // exitCode=130 is intentional Darwin CI flake harden (reopened-196), not operator-environments scope.
             if (outcome === 'stopped')
                 process.exitCode = 130;
             else if (outcome === 'complete' || final.state !== 'present')

package/dist/src/core/environments/resolve.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTEXT_INJECT_MAX_CHARS = void 0;
+exports.statusFor = statusFor;
+exports.buildInjection = buildInjection;
+/** Fixed budget for `inject: context` fresh values (RF-3.2). */
+exports.CONTEXT_INJECT_MAX_CHARS = 2048;
+function assertValidNow(now) {
+    if (!(now instanceof Date) || !Number.isFinite(now.getTime())) {
+        throw new Error('now must be a Date with a finite getTime()');
+    }
+}
+function effectiveStatus(definitionDurability, stored, now) {
+    if (!stored)
+        return 'missing';
+    if (stored.status === 'missing')
+        return 'missing';
+    if (stored.status === 'stale')
+        return 'stale';
+    // Durable never time-stales (RF-2.3).
+    if (definitionDurability === 'durable') {
+        return stored.status === 'fresh' ? 'fresh' : stored.status;
+    }
+    // Volatile: fail closed — missing/invalid expiresAt or now >= expiresAt → stale (RF-2.4).
+    if (typeof stored.expiresAt !== 'string' || stored.expiresAt.trim() === '') {
+        return 'stale';
+    }
+    const expiresMs = Date.parse(stored.expiresAt);
+    if (!Number.isFinite(expiresMs) || now.getTime() >= expiresMs) {
+        return 'stale';
+    }
+    return stored.status === 'fresh' ? 'fresh' : stored.status;
+}
+/**
+ * Per-catalog-id status against the store. Missing → `missing` with no default (RF-2.5).
+ */
+function statusFor(catalog, store, now = new Date()) {
+    if (!catalog || typeof catalog !== 'object' || !catalog.facts) {
+        throw new Error('statusFor: catalog with facts is required');
+    }
+    if (!store || typeof store !== 'object') {
+        throw new Error('statusFor: store must be an object');
+    }
+    assertValidNow(now);
+    const out = {};
+    for (const [id, def] of Object.entries(catalog.facts)) {
+        out[id] = effectiveStatus(def.durability, store[id], now);
+    }
+    return out;
+}
+/**
+ * Build injection payload. Default / explicit `reference` exposes path + ids only (RF-3.1).
+ * `context` includes fresh `inject: context` values under budget; overflow degrades (RF-3.2).
+ */
+function buildInjection(opts) {
+    if (!opts || typeof opts !== 'object') {
+        throw new Error('buildInjection: options object is required');
+    }
+    if (!opts.catalog?.facts) {
+        throw new Error('buildInjection: catalog with facts is required');
+    }
+    if (typeof opts.storePath !== 'string' || opts.storePath.trim() === '') {
+        throw new Error('buildInjection: storePath must be a non-empty string');
+    }
+    if (!opts.store || typeof opts.store !== 'object') {
+        throw new Error('buildInjection: store must be an object');
+    }
+    const rawInject = opts.inject ?? 'reference';
+    // Unknown/typo must not fall through into context (fail-open). Prefer reference (RNF-2).
+    const inject = rawInject === 'reference' || rawInject === 'context' ? rawInject : 'reference';
+    const maxChars = opts.maxChars ?? exports.CONTEXT_INJECT_MAX_CHARS;
+    if (typeof maxChars !== 'number' || !Number.isFinite(maxChars) || maxChars < 0) {
+        throw new Error('buildInjection: maxChars must be a non-negative finite number');
+    }
+    const now = opts.now ?? new Date();
+    assertValidNow(now);
+    if (opts.factIds !== undefined) {
+        if (!Array.isArray(opts.factIds) || opts.factIds.some((id) => typeof id !== 'string' || id === '')) {
+            throw new Error('buildInjection: factIds must be an array of non-empty strings');
+        }
+    }
+    const factIds = opts.factIds ?? Object.keys(opts.catalog.facts);
+    const statuses = statusFor(opts.catalog, opts.store, now);
+    const referenceResult = () => ({
+        mode: 'reference',
+        storePath: opts.storePath,
+        factIds: [...factIds],
+    });
+    if (inject !== 'context') {
+        return referenceResult();
+    }
+    // Context mode: only fresh values whose catalog inject is `context` (RF-3.2).
+    const contextValues = {};
+    let totalChars = 0;
+    for (const id of factIds) {
+        const def = opts.catalog.facts[id];
+        if (!def || def.inject !== 'context')
+            continue;
+        if (statuses[id] !== 'fresh')
+            continue;
+        const stored = opts.store[id];
+        if (!stored || typeof stored.value !== 'string')
+            continue;
+        totalChars += stored.value.length;
+        contextValues[id] = stored.value;
+    }
+    if (Object.keys(contextValues).length === 0) {
+        return referenceResult();
+    }
+    if (totalChars > maxChars) {
+        return {
+            ...referenceResult(),
+            warning: `Context inject budget exceeded (${totalChars} > ${maxChars} chars); degraded to reference`,
+        };
+    }
+    return {
+        mode: 'context',
+        storePath: opts.storePath,
+        factIds: [...factIds],
+        values: contextValues,
+    };
+}

package/dist/src/core/environments/store.js

@@ -0,0 +1,323 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvironmentStoreError = void 0;
+exports.environmentsRoot = environmentsRoot;
+exports.envDir = envDir;
+exports.valuesPath = valuesPath;
+exports.getActiveEnvironmentName = getActiveEnvironmentName;
+exports.setActiveEnvironmentName = setActiveEnvironmentName;
+exports.readValues = readValues;
+exports.isInsideRegistryTree = isInsideRegistryTree;
+exports.assertNotInsideRegistryTree = assertNotInsideRegistryTree;
+exports.writeEnvValue = writeEnvValue;
+exports.writeFact = writeFact;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const atomic_file_1 = require("../atomic-file");
+const paths_1 = require("../paths");
+const registries_1 = require("../registries");
+class EnvironmentStoreError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EnvironmentStoreError';
+    }
+}
+exports.EnvironmentStoreError = EnvironmentStoreError;
+const DEFAULT_ENV_NAME = 'default';
+const META_FILE = 'meta.json';
+const VALUES_FILE = 'values.json';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Root of machine-local environment stores: `AWM_HOME/environments`. */
+function environmentsRoot() {
+    return path_1.default.join((0, paths_1.awmHome)(), 'environments');
+}
+function envDir(name) {
+    assertEnvName(name);
+    return path_1.default.join(environmentsRoot(), name);
+}
+function valuesPath(name) {
+    return path_1.default.join(envDir(name), VALUES_FILE);
+}
+function metaPath() {
+    return path_1.default.join(environmentsRoot(), META_FILE);
+}
+function assertEnvName(name) {
+    if (typeof name !== 'string' || name.trim() === '') {
+        throw new EnvironmentStoreError('environment name must be a non-empty string');
+    }
+    if (name.includes('\0')) {
+        throw new EnvironmentStoreError(`Invalid environment name ${JSON.stringify(name)}: NUL byte`);
+    }
+    const lower = name.toLowerCase();
+    if (lower === META_FILE.toLowerCase() || lower === VALUES_FILE.toLowerCase()) {
+        throw new EnvironmentStoreError(`Invalid environment name ${JSON.stringify(name)}: reserved store filename`);
+    }
+    if (name.includes('/') || name.includes('\\') || name.includes('..') || name === '.' || name === '..') {
+        throw new EnvironmentStoreError(`Invalid environment name ${JSON.stringify(name)}`);
+    }
+}
+function readMeta() {
+    const file = metaPath();
+    if (!fs_1.default.existsSync(file))
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(fs_1.default.readFileSync(file, 'utf-8'));
+    }
+    catch (e) {
+        throw new EnvironmentStoreError(`Invalid environments meta at ${file}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!isRecord(raw) || typeof raw.active !== 'string' || raw.active.trim() === '') {
+        throw new EnvironmentStoreError(`Invalid environments meta at ${file}: expected { active: string }`);
+    }
+    return { active: raw.active };
+}
+function writeMeta(meta) {
+    const file = metaPath();
+    assertNotInsideRegistryTree(file);
+    (0, atomic_file_1.writeFileAtomic)(file, JSON.stringify(meta, null, 2) + '\n');
+}
+/** Exactly one active environment per machine; default name `default` (RF-2.2). */
+function getActiveEnvironmentName() {
+    const meta = readMeta();
+    if (!meta)
+        return DEFAULT_ENV_NAME;
+    assertEnvName(meta.active);
+    return meta.active;
+}
+function setActiveEnvironmentName(name) {
+    assertEnvName(name);
+    writeMeta({ active: name });
+}
+function parseStoredEntry(id, raw) {
+    if (!isRecord(raw)) {
+        throw new EnvironmentStoreError(`values.${id} must be an object`);
+    }
+    if (typeof raw.value !== 'string') {
+        throw new EnvironmentStoreError(`values.${id}.value must be a string`);
+    }
+    if (raw.status !== 'fresh' && raw.status !== 'stale' && raw.status !== 'missing') {
+        throw new EnvironmentStoreError(`values.${id}.status must be fresh|stale|missing`);
+    }
+    if (typeof raw.updatedAt !== 'string') {
+        throw new EnvironmentStoreError(`values.${id}.updatedAt must be a string`);
+    }
+    const entry = {
+        value: raw.value,
+        status: raw.status,
+        updatedAt: raw.updatedAt,
+    };
+    if (raw.expiresAt !== undefined) {
+        if (typeof raw.expiresAt !== 'string') {
+            throw new EnvironmentStoreError(`values.${id}.expiresAt must be a string`);
+        }
+        entry.expiresAt = raw.expiresAt;
+    }
+    return entry;
+}
+function readValues(name) {
+    const file = valuesPath(name);
+    if (!fs_1.default.existsSync(file))
+        return {};
+    let raw;
+    try {
+        raw = JSON.parse(fs_1.default.readFileSync(file, 'utf-8'));
+    }
+    catch (e) {
+        throw new EnvironmentStoreError(`Invalid values.json at ${file}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!isRecord(raw)) {
+        throw new EnvironmentStoreError(`values.json at ${file} must be a JSON object`);
+    }
+    const out = Object.create(null);
+    for (const [id, entry] of Object.entries(raw)) {
+        if (id === '__proto__' || id === 'constructor' || id === 'prototype') {
+            throw new EnvironmentStoreError(`values.json at ${file}: forbidden fact id ${JSON.stringify(id)}`);
+        }
+        out[id] = parseStoredEntry(id, entry);
+    }
+    return out;
+}
+/**
+ * Resolve a path through any intermediate symlinks (including when the leaf does
+ * not exist yet). Walks up to the nearest existing ancestor, realpaths it, then
+ * re-appends missing segments — same spirit as sensors/ledger realpath containment.
+ */
+function resolvePathForContainment(targetPath) {
+    const absolute = path_1.default.resolve(targetPath);
+    const missing = [];
+    let cursor = absolute;
+    while (!fs_1.default.existsSync(cursor)) {
+        const parent = path_1.default.dirname(cursor);
+        if (parent === cursor)
+            break;
+        missing.unshift(path_1.default.basename(cursor));
+        cursor = parent;
+    }
+    let realBase;
+    try {
+        realBase = fs_1.default.realpathSync.native(cursor);
+    }
+    catch {
+        realBase = cursor;
+    }
+    return missing.length === 0 ? realBase : path_1.default.join(realBase, ...missing);
+}
+function isPathInsideRoot(candidate, root) {
+    if ((0, paths_1.sameExistingPath)(candidate, root))
+        return true;
+    const rel = path_1.default.relative(root, candidate);
+    if (rel === '')
+        return true;
+    if (rel === '..')
+        return false;
+    if (!rel.startsWith(`..${path_1.default.sep}`) && !rel.startsWith('..') && !path_1.default.isAbsolute(rel))
+        return true;
+    const prefix = root.endsWith(path_1.default.sep) ? root : root + path_1.default.sep;
+    return candidate === root || candidate.startsWith(prefix);
+}
+/**
+ * True when `targetPath` (after resolving symlinks) is the same as or nested under
+ * any registry content root. Catches AWM_HOME/environments → registry symlink (RNF-1).
+ *
+ * Always unions `contentRoots()` with any explicit `registryRoots`. An empty
+ * explicit array no longer disables checks — callers that need extra roots pass
+ * them; they cannot opt out of installed content roots.
+ */
+function isInsideRegistryTree(targetPath, registryRoots) {
+    if (typeof targetPath !== 'string' || targetPath.trim() === '') {
+        throw new EnvironmentStoreError('target path must be a non-empty string');
+    }
+    const lexicalTarget = path_1.default.resolve(targetPath);
+    const realTarget = resolvePathForContainment(targetPath);
+    const roots = [...(0, registries_1.contentRoots)(), ...(registryRoots ?? [])];
+    for (const root of roots) {
+        if (typeof root !== 'string' || root.trim() === '')
+            continue;
+        const lexicalRoot = path_1.default.resolve(root);
+        const realRoot = resolvePathForContainment(root);
+        if (isPathInsideRoot(realTarget, realRoot))
+            return true;
+        // Also check lexical forms so non-existent trees still refuse obvious nesting.
+        if (isPathInsideRoot(lexicalTarget, lexicalRoot))
+            return true;
+    }
+    return false;
+}
+function assertNotInsideRegistryTree(targetPath, registryRoots) {
+    if (isInsideRegistryTree(targetPath, registryRoots)) {
+        throw new EnvironmentStoreError(`Refusing to write environment store inside a registry tree: ${targetPath} (RNF-1)`);
+    }
+}
+/**
+ * Atomic write of a values.json document. Refuses targets under registry roots (RNF-1).
+ */
+function writeEnvValue(targetPath, values, opts = {}) {
+    if (typeof targetPath !== 'string' || targetPath.trim() === '') {
+        throw new EnvironmentStoreError('target path must be a non-empty string');
+    }
+    if (!isRecord(values)) {
+        throw new EnvironmentStoreError('values must be an object');
+    }
+    for (const [id, entry] of Object.entries(values)) {
+        parseStoredEntry(id, entry);
+    }
+    // RNF-1: refuse registry-tree targets. Callers that need environmentsRoot placement
+    // (writeFact) pass valuesPath(name); this helper does not re-check environmentsRoot.
+    assertNotInsideRegistryTree(targetPath, opts.registryRoots);
+    (0, atomic_file_1.writeFileAtomic)(targetPath, JSON.stringify(values, null, 2) + '\n');
+}
+function validateValue(definition, value) {
+    if (definition.valueType === 'path') {
+        if (value.trim() === '') {
+            throw new EnvironmentStoreError('path value must be a non-empty string');
+        }
+    }
+    if (definition.valueType === 'enum') {
+        const allowed = definition.values ?? [];
+        if (!allowed.includes(value)) {
+            throw new EnvironmentStoreError(`enum value ${JSON.stringify(value)} is not one of: ${allowed.join(', ')}`);
+        }
+    }
+}
+function withExpiresAt(entry, definition) {
+    if (!definition || definition.durability !== 'volatile') {
+        return {
+            value: entry.value,
+            status: entry.status,
+            updatedAt: entry.updatedAt,
+        };
+    }
+    if (typeof definition.ttl !== 'number' || !Number.isFinite(definition.ttl) || definition.ttl <= 0) {
+        throw new EnvironmentStoreError('volatile fact definition requires a finite ttl > 0');
+    }
+    const ttlSeconds = definition.ttl;
+    const updatedMs = Date.parse(entry.updatedAt);
+    if (!Number.isFinite(updatedMs)) {
+        throw new EnvironmentStoreError(`updatedAt must be a valid ISO timestamp, got ${JSON.stringify(entry.updatedAt)}`);
+    }
+    let expiresAt;
+    try {
+        expiresAt = new Date(updatedMs + ttlSeconds * 1000).toISOString();
+    }
+    catch (e) {
+        if (e instanceof RangeError) {
+            throw new EnvironmentStoreError(`volatile expiresAt out of range for updatedAt=${JSON.stringify(entry.updatedAt)} ttl=${ttlSeconds}`);
+        }
+        throw e;
+    }
+    return { ...entry, expiresAt };
+}
+/**
+ * Write one fact into `environments/<name>/values.json` (RF-2.1). Atomic rename.
+ * When `catalog` is provided, unknown ids error and list `consultedRoots`.
+ */
+function writeFact(name, id, entry, opts = {}) {
+    assertEnvName(name);
+    if (typeof id !== 'string' || id.trim() === '') {
+        throw new EnvironmentStoreError('fact id must be a non-empty string');
+    }
+    if (!isRecord(entry) || typeof entry.value !== 'string') {
+        throw new EnvironmentStoreError('fact entry.value must be a string');
+    }
+    if (entry.status !== 'fresh' && entry.status !== 'stale' && entry.status !== 'missing') {
+        throw new EnvironmentStoreError('fact entry.status must be fresh|stale|missing');
+    }
+    if (typeof entry.updatedAt !== 'string') {
+        throw new EnvironmentStoreError('fact entry.updatedAt must be a string');
+    }
+    let definition = opts.definition;
+    if (opts.catalog) {
+        // Own keys only — prototype members (toString, …) are not catalog facts.
+        if (!Object.hasOwn(opts.catalog.facts, id)) {
+            const roots = opts.consultedRoots?.length
+                ? opts.consultedRoots.join(', ')
+                : '(no catalog roots)';
+            throw new EnvironmentStoreError(`Unknown fact id ${JSON.stringify(id)}; consulted: ${roots}`);
+        }
+        definition = definition ?? opts.catalog.facts[id];
+    }
+    if (definition) {
+        validateValue(definition, entry.value);
+    }
+    const nextEntry = withExpiresAt({
+        value: entry.value,
+        status: entry.status,
+        updatedAt: entry.updatedAt,
+        ...(entry.expiresAt !== undefined ? { expiresAt: entry.expiresAt } : {}),
+    }, definition);
+    const file = valuesPath(name);
+    assertNotInsideRegistryTree(file, opts.registryRoots);
+    const current = readValues(name);
+    const next = { ...current, [id]: nextEntry };
+    writeEnvValue(file, next, { registryRoots: opts.registryRoots });
+    // First write materializes the single active env as the env being written (RF-2.2).
+    if (!readMeta()) {
+        writeMeta({ active: name });
+    }
+}