@mc-and-his-agents/loom-installer 0.1.79 → 0.1.81

package/README.md

@@ -20,6 +20,13 @@ npx @mc-and-his-agents/loom-installer add skill <skill-id> --host codex
 npx @mc-and-his-agents/loom-installer add skill <skill-id> --host claude
 ```
 
+Read-only upgrade rehearsal and verification:
+
+```bash
+npx @mc-and-his-agents/loom-installer upgrade-plan plugin --host codex --json
+npx @mc-and-his-agents/loom-installer verify-upgrade plugin --host codex --json
+```
+
 You can also pin the installer first:
 
 ```bash
@@ -47,6 +54,8 @@ Generated payload directories are not committed to git. The build step recreates
 
 Installer JSON output reports `distribution_layer`, `version_context`, and `failed_layer` so callers can distinguish host adapter plugin installs from generated single-skill installs.
 
+Installer-managed layers also write `loom-installed-surface-status/v1` metadata. `upgrade-plan` and `verify-upgrade` read that metadata, compare it to the package payload, and report `upgrade_eligibility`, `changed_paths`, `drift`, `rollback_path`, and fail-closed reasons without mutating the target repository. See `docs/adoption/installed-loom-status.md` for the status contract.
+
 ## Release Notes
 
 Publishing only happens from `main`.

package/README.zh-CN.md

@@ -20,6 +20,13 @@ npx @mc-and-his-agents/loom-installer add skill <skill-id> --host codex
 npx @mc-and-his-agents/loom-installer add skill <skill-id> --host claude
 ```
 
+只读升级演练与验证：
+
+```bash
+npx @mc-and-his-agents/loom-installer upgrade-plan plugin --host codex --json
+npx @mc-and-his-agents/loom-installer verify-upgrade plugin --host codex --json
+```
+
 也可以先固定 installer 版本：
 
 ```bash
@@ -47,6 +54,8 @@ Options：
 
 Installer JSON output 会报告 `distribution_layer`、`version_context` 和 `failed_layer`，让调用方区分 host adapter plugin install 与 generated single-skill install。
 
+Installer 管理的 layer 也会写入 `loom-installed-surface-status/v1` metadata。`upgrade-plan` 和 `verify-upgrade` 只读取该 metadata，并与 package payload 比对，报告 `upgrade_eligibility`、`changed_paths`、`drift`、`rollback_path` 和 fail-closed reason；它们不会修改目标仓库。状态合同见 `docs/adoption/installed-loom-status.md`。
+
 ## Release Notes
 
 发布只会从 `main` 进行。

package/dist/src/cli.js

@@ -3,10 +3,12 @@ import { formatResult, parseCli, runInstaller } from './index.js';
 import { InstallerError } from './utils.js';
 function errorResult(message) {
     return {
+        schema_version: 'loom-installer-result/v1',
+        operation: 'add',
         mode: 'plugin',
         host: 'codex',
         distribution_layer: 'host-adapter-plugin',
-        status: 'installed',
+        status: 'blocked',
         installed_paths: [],
         verification: [],
         warnings: [],

package/dist/src/index.js

@@ -1,6 +1,6 @@
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { InstallerError, assert, dirExists, ensureTargetWritable, runCommand } from './utils.js';
+import { InstallerError, assert, dirExists, ensureTargetExists, ensureTargetWritable, fileExists, readJson, runCommand, sha256, writeJson } from './utils.js';
 import { loadPayloadManifest, resolveSkillRecord, verifyPayload } from './payload.js';
 import { installCodexPlugin, installCodexSkill } from './codex.js';
 import { installClaudePlugin, installClaudeSkill } from './claude.js';
@@ -52,8 +52,8 @@ export function parseCli(argv) {
     const subject = argv[1];
     const third = argv[2];
     const rest = subject === 'plugin' ? argv.slice(2) : argv.slice(3);
-    if (command !== 'add') {
-        throw new InstallerError('usage: loom-installer add plugin|skill <skill-id> [--host ...] [--target ...] [--force] [--json]');
+    if (command !== 'add' && command !== 'upgrade-plan' && command !== 'verify-upgrade') {
+        throw new InstallerError('usage: loom-installer add|upgrade-plan|verify-upgrade plugin|skill <skill-id> [--host ...] [--target ...] [--force] [--json]');
     }
     const options = { ...DEFAULT_OPTIONS };
     for (let index = 0; index < rest.length; index += 1) {
@@ -88,21 +88,23 @@ export function parseCli(argv) {
     }
     if (subject === 'plugin') {
         return {
+            operation: command,
             mode: 'plugin',
             options,
         };
     }
     if (subject === 'skill') {
         if (!third) {
-            throw new InstallerError('usage: loom-installer add skill <skill-id>');
+            throw new InstallerError(`usage: loom-installer ${command} skill <skill-id>`);
         }
         return {
+            operation: command,
             mode: 'skill',
             skillId: third,
             options,
         };
     }
-    throw new InstallerError(`unknown add target: ${String(subject)}`);
+    throw new InstallerError(`unknown ${command} target: ${String(subject)}`);
 }
 export function checkPython(env) {
     const result = runCommand(env.pythonBin, ['-c', 'import sys; print(f"{sys.version_info[0]}.{sys.version_info[1]}.{sys.version_info[2]}")'], process.env);
@@ -124,8 +126,8 @@ export function checkPython(env) {
     }
     return warnings;
 }
-export function ensureClaudeCliWhenNeeded(host, mode, env) {
-    if (host !== 'claude' || mode !== 'plugin') {
+export function ensureClaudeCliWhenNeeded(host, mode, operation, env) {
+    if (operation !== 'add' || host !== 'claude' || mode !== 'plugin') {
         return;
     }
     const result = runCommand(env.claudeBin, ['--version'], process.env);
@@ -136,8 +138,17 @@ export function ensureClaudeCliWhenNeeded(host, mode, env) {
 export function formatResult(result) {
     const version = result.version_context;
     return [
-        `${result.host} ${result.mode}: ${result.status}`,
+        `${result.host} ${result.mode} ${result.operation ?? 'add'}: ${result.status}`,
         `layer: ${result.distribution_layer}`,
+        ...(result.installed_status
+            ? [
+                `runtime_state: ${result.installed_status.runtime_state}`,
+                `upgrade_eligibility: ${result.installed_status.upgrade_eligibility}`,
+            ]
+            : []),
+        ...(result.changed_paths?.length ? [`changed_paths: ${result.changed_paths.length}`] : []),
+        ...(result.drift?.length ? [`drift: ${result.drift.length}`] : []),
+        ...(result.rollback_path ? [`rollback_path: ${result.rollback_path}`] : []),
         ...(version
             ? [
                 `versions: repo=${version.repo_version} installer=${version.installer_package_version} plugin=${version.plugin_surface_version} registry=${version.skills_registry_version}`,
@@ -150,13 +161,33 @@ export function formatResult(result) {
 export function runInstaller(parsed, envSource = process.env, packageRoot) {
     const resolvedEnv = resolveEnvironment(envSource);
     const host = selectHost(parsed.options.host, resolvedEnv);
+    const operation = parsed.operation ?? 'add';
     const resolvedPackageRoot = packageRoot ?? packageRootFromUrl(import.meta.url);
     const targetRoot = resolve(parsed.options.target);
-    ensureTargetWritable(targetRoot);
+    if (operation === 'add') {
+        ensureTargetWritable(targetRoot);
+    }
+    else {
+        ensureTargetExists(targetRoot);
+    }
     const manifest = loadPayloadManifest(resolvedPackageRoot);
     verifyPayload(resolvedPackageRoot, manifest);
     const warnings = checkPython(resolvedEnv);
-    ensureClaudeCliWhenNeeded(host, parsed.mode, resolvedEnv);
+    ensureClaudeCliWhenNeeded(host, parsed.mode, operation, resolvedEnv);
+    const skill = parsed.mode === 'skill' ? resolveSkillRecord(manifest, parsed.skillId ?? '') : undefined;
+    if (operation !== 'add') {
+        const result = inspectInstalledSurface({
+            operation,
+            host,
+            parsed,
+            packageRoot: resolvedPackageRoot,
+            targetRoot,
+            manifest,
+            skill,
+        });
+        result.warnings.unshift(...warnings);
+        return result;
+    }
     const result = installForHost({
         host,
         parsed,
@@ -166,7 +197,15 @@ export function runInstaller(parsed, envSource = process.env, packageRoot) {
         manifest,
     });
     result.warnings.unshift(...warnings);
-    return withVersionContext(result, manifest, parsed.mode === 'skill' ? resolveSkillRecord(manifest, parsed.skillId ?? '') : undefined);
+    const withContext = withVersionContext(result, manifest, skill);
+    writeInstalledSurfaceStatus({
+        result: withContext,
+        host,
+        mode: parsed.mode,
+        skill,
+        targetRoot,
+    });
+    return withContext;
 }
 function payloadVersionContext(manifest, skill) {
     return {
@@ -186,10 +225,248 @@ function payloadVersionContext(manifest, skill) {
 }
 function withVersionContext(result, manifest, skill) {
     return {
+        schema_version: 'loom-installer-result/v1',
+        operation: 'add',
         ...result,
         version_context: payloadVersionContext(manifest, skill),
     };
 }
+function distributionLayer(mode) {
+    return mode === 'plugin' ? 'host-adapter-plugin' : 'generated-single-skill';
+}
+function skillDirName(host, skillId) {
+    if (host === 'codex') {
+        return skillId.startsWith('loom-') ? skillId : `loom-${skillId}`;
+    }
+    return skillId;
+}
+function installedRoot(targetRoot, host, mode, skill) {
+    if (mode === 'plugin') {
+        return host === 'codex'
+            ? join(targetRoot, 'plugins', 'loom')
+            : join(targetRoot, '.claude', 'marketplaces', 'loom-local', 'plugins', 'loom');
+    }
+    assert(skill, 'skill install requires a skill record');
+    return host === 'codex'
+        ? join(targetRoot, '.agents', 'skills', skillDirName(host, skill.id))
+        : join(targetRoot, '.claude', 'skills', skillDirName(host, skill.id));
+}
+function installedStatusPath(root) {
+    return join(root, '.loom-install-status.json');
+}
+function writeInstalledSurfaceStatus(input) {
+    const root = installedRoot(input.targetRoot, input.host, input.mode, input.skill);
+    const statusPath = installedStatusPath(root);
+    const status = {
+        schema_version: 'loom-installed-surface-status/v1',
+        installed_layer: input.result.distribution_layer,
+        host_adapter: input.host,
+        mode: input.mode,
+        ...(input.skill ? { skill_id: input.skill.id } : {}),
+        version_context: input.result.version_context,
+        runtime_state: 'ready',
+        upgrade_eligibility: 'current',
+        evidence: [`installed surface metadata at ${statusPath}`],
+        failed_layer: null,
+        fail_closed_reason: null,
+    };
+    writeJson(statusPath, status);
+    input.result.installed_paths.push(statusPath);
+    input.result.installed_status = status;
+}
+function sourcePrefix(mode, manifest, skill) {
+    if (mode === 'plugin') {
+        return manifest.plugin.relative_path.replace(/\/$/, '');
+    }
+    assert(skill, 'skill install requires a skill record');
+    return skill.relative_path.replace(/\/$/, '');
+}
+function targetRelativePath(mode, host, sourcePath, manifest, skill) {
+    const prefix = sourcePrefix(mode, manifest, skill);
+    const suffix = sourcePath.slice(prefix.length).replace(/^\//, '');
+    if (mode === 'plugin') {
+        return host === 'codex'
+            ? join('plugins', 'loom', suffix)
+            : join('.claude', 'marketplaces', 'loom-local', 'plugins', 'loom', suffix);
+    }
+    assert(skill, 'skill install requires a skill record');
+    return host === 'codex'
+        ? join('.agents', 'skills', skillDirName(host, skill.id), suffix)
+        : join('.claude', 'skills', skillDirName(host, skill.id), suffix);
+}
+function compareInstalledPayload(input) {
+    const prefix = `${sourcePrefix(input.mode, input.manifest, input.skill)}/`;
+    const changed = [];
+    for (const file of input.manifest.files) {
+        if (!file.path.startsWith(prefix)) {
+            continue;
+        }
+        const source = join(input.packageRoot, 'payload', file.path);
+        const targetRelative = targetRelativePath(input.mode, input.host, file.path, input.manifest, input.skill);
+        const target = join(input.targetRoot, targetRelative);
+        if (!fileExists(target) || sha256(source) !== sha256(target)) {
+            changed.push(targetRelative);
+        }
+    }
+    return changed.sort();
+}
+function statusFailureResult(input) {
+    const available = payloadVersionContext(input.manifest, input.skill);
+    const rollbackPath = input.rollbackPath ?? null;
+    const installedStatus = {
+        schema_version: 'loom-installed-surface-status/v1',
+        installed_layer: distributionLayer(input.mode),
+        host_adapter: input.host,
+        mode: input.mode,
+        ...(input.skill ? { skill_id: input.skill.id } : {}),
+        version_context: null,
+        runtime_state: 'blocked',
+        upgrade_eligibility: 'incompatible',
+        evidence: input.evidence,
+        failed_layer: 'installed-surface',
+        fail_closed_reason: input.reason,
+    };
+    return {
+        schema_version: 'loom-installer-result/v1',
+        operation: input.operation,
+        mode: input.mode,
+        host: input.host,
+        distribution_layer: distributionLayer(input.mode),
+        status: 'blocked',
+        installed_paths: rollbackPath ? [rollbackPath] : [],
+        verification: input.evidence,
+        warnings: [],
+        version_context: null,
+        installed_status: installedStatus,
+        available_version_context: available,
+        changed_paths: [],
+        drift: [],
+        rollback_path: rollbackPath,
+        rehearsal: {
+            schema_version: 'loom-upgrade-rehearsal/v1',
+            mutates_target: false,
+            changed_paths: [],
+            drift: [],
+            rollback_path: rollbackPath,
+        },
+        failed_layer: 'installed-surface',
+        fail_closed_reason: input.reason,
+    };
+}
+function sameVersionContext(left, right) {
+    if (!left) {
+        return false;
+    }
+    const keys = [
+        'repo_version',
+        'installer_package_version',
+        'plugin_surface_version',
+        'host_adapter_version',
+        'skills_registry_version',
+        'runtime_core_version',
+        'skill_package_version',
+        'skill_contract_version',
+        'skill_package_id',
+    ];
+    return keys.every((key) => left[key] === right[key]);
+}
+function inspectInstalledSurface(input) {
+    const root = installedRoot(input.targetRoot, input.host, input.parsed.mode, input.skill);
+    const statusPath = installedStatusPath(root);
+    const available = payloadVersionContext(input.manifest, input.skill);
+    if (!fileExists(statusPath)) {
+        return statusFailureResult({
+            operation: input.operation,
+            host: input.host,
+            mode: input.parsed.mode,
+            skill: input.skill,
+            manifest: input.manifest,
+            rollbackPath: root,
+            reason: `installed Loom status metadata is missing: ${relative(input.targetRoot, statusPath)}`,
+            evidence: [`missing installed status metadata at ${statusPath}`],
+        });
+    }
+    let installedStatus = readJson(statusPath);
+    if (installedStatus.schema_version !== 'loom-installed-surface-status/v1' ||
+        installedStatus.host_adapter !== input.host ||
+        installedStatus.mode !== input.parsed.mode ||
+        installedStatus.installed_layer !== distributionLayer(input.parsed.mode) ||
+        !installedStatus.version_context) {
+        return statusFailureResult({
+            operation: input.operation,
+            host: input.host,
+            mode: input.parsed.mode,
+            skill: input.skill,
+            manifest: input.manifest,
+            rollbackPath: root,
+            reason: `installed Loom status metadata is inconsistent: ${relative(input.targetRoot, statusPath)}`,
+            evidence: [`inconsistent installed status metadata at ${statusPath}`],
+        });
+    }
+    if (input.skill && installedStatus.skill_id !== input.skill.id) {
+        return statusFailureResult({
+            operation: input.operation,
+            host: input.host,
+            mode: input.parsed.mode,
+            skill: input.skill,
+            manifest: input.manifest,
+            rollbackPath: root,
+            reason: `installed Loom skill metadata does not match ${input.skill.id}`,
+            evidence: [`skill metadata mismatch at ${statusPath}`],
+        });
+    }
+    const changedPaths = compareInstalledPayload({
+        host: input.host,
+        mode: input.parsed.mode,
+        packageRoot: input.packageRoot,
+        targetRoot: input.targetRoot,
+        manifest: input.manifest,
+        skill: input.skill,
+    });
+    const versionMatches = sameVersionContext(installedStatus.version_context, available);
+    const eligibility = changedPaths.length === 0 && versionMatches ? 'current' : versionMatches ? 'drift' : 'upgrade-available';
+    const drift = eligibility === 'drift' ? changedPaths : [];
+    const runtimeState = eligibility === 'drift' ? 'blocked' : 'ready';
+    const rollbackPath = changedPaths.length > 0 ? root : null;
+    const failClosedReason = eligibility === 'drift' ? 'installed Loom payload drifted from its recorded version context' : null;
+    installedStatus = {
+        ...installedStatus,
+        runtime_state: runtimeState,
+        upgrade_eligibility: eligibility,
+        evidence: [`read installed status metadata at ${statusPath}`, `compared installed payload under ${root}`],
+        failed_layer: failClosedReason ? 'installed-surface' : null,
+        fail_closed_reason: failClosedReason,
+    };
+    return {
+        schema_version: 'loom-installer-result/v1',
+        operation: input.operation,
+        mode: input.parsed.mode,
+        host: input.host,
+        distribution_layer: distributionLayer(input.parsed.mode),
+        status: input.operation === 'verify-upgrade' ? (failClosedReason ? 'blocked' : 'verified') : failClosedReason ? 'blocked' : 'planned',
+        installed_paths: [root, statusPath],
+        verification: [
+            `read installed status metadata at ${statusPath}`,
+            `compared ${changedPaths.length} changed path(s) without mutating target`,
+        ],
+        warnings: [],
+        version_context: installedStatus.version_context,
+        installed_status: installedStatus,
+        available_version_context: available,
+        changed_paths: changedPaths,
+        drift,
+        rollback_path: rollbackPath,
+        rehearsal: {
+            schema_version: 'loom-upgrade-rehearsal/v1',
+            mutates_target: false,
+            changed_paths: changedPaths,
+            drift,
+            rollback_path: rollbackPath,
+        },
+        failed_layer: failClosedReason ? 'installed-surface' : null,
+        fail_closed_reason: failClosedReason,
+    };
+}
 function installForHost(input) {
     const { host, parsed, env, packageRoot, targetRoot, manifest } = input;
     if (parsed.mode === 'plugin') {

package/dist/src/utils.js

@@ -37,6 +37,11 @@ export function ensureTargetWritable(path) {
         throw new InstallerError(`target path is not writable: ${path}`);
     }
 }
+export function ensureTargetExists(path) {
+    if (!existsSync(path)) {
+        throw new InstallerError(`target path does not exist: ${path}`);
+    }
+}
 export function copyTree(source, target, force) {
     if (existsSync(target)) {
         if (!force) {

package/dist/test/installer.test.js

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { existsSync, mkdtempSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { execFileSync, spawnSync } from 'node:child_process';
@@ -56,13 +56,22 @@ test('detectHosts and selectHost fail closed on conflicts', () => {
 });
 test('parseCli supports plugin and skill flows', () => {
     const plugin = parseCli(['add', 'plugin', '--host', 'codex', '--json']);
+    assert.equal(plugin.operation, 'add');
     assert.equal(plugin.mode, 'plugin');
     assert.equal(plugin.options.host, 'codex');
     assert.equal(plugin.options.json, true);
     const skill = parseCli(['add', 'skill', 'loom-review', '--target', '/tmp/repo']);
+    assert.equal(skill.operation, 'add');
     assert.equal(skill.mode, 'skill');
     assert.equal(skill.skillId, 'loom-review');
     assert.equal(skill.options.target, '/tmp/repo');
+    const plan = parseCli(['upgrade-plan', 'plugin', '--host', 'codex', '--target', '/tmp/repo', '--json']);
+    assert.equal(plan.operation, 'upgrade-plan');
+    assert.equal(plan.mode, 'plugin');
+    const verify = parseCli(['verify-upgrade', 'skill', 'loom-init', '--host', 'claude']);
+    assert.equal(verify.operation, 'verify-upgrade');
+    assert.equal(verify.mode, 'skill');
+    assert.equal(verify.skillId, 'loom-init');
 });
 test('payload manifest excludes python cache artifacts', () => {
     const manifest = JSON.parse(readFileSync(join(packageRoot(), 'payload', 'manifest.json'), 'utf8'));
@@ -119,9 +128,145 @@ test('codex plugin install writes marketplace entry', () => {
     assert.equal(result.host, 'codex');
     assert.equal(result.distribution_layer, 'host-adapter-plugin');
     assert.equal(result.version_context?.plugin_surface_version, '0.4.0');
+    assert.equal(result.installed_status?.schema_version, 'loom-installed-surface-status/v1');
+    assert.equal(result.installed_status?.runtime_state, 'ready');
     assert.equal(marketplace.plugins[0].name, 'loom');
     assert.equal(marketplace.plugins[0].source.path, './plugins/loom');
 });
+test('upgrade-plan reports current installed plugin without mutating target', () => {
+    const base = fixtureRoot();
+    const envSource = prepareEnv(base);
+    mkdirSync(envSource.CODEX_HOME, { recursive: true });
+    const repoRoot = join(base, 'repo');
+    mkdirSync(repoRoot, { recursive: true });
+    runInstaller({
+        mode: 'plugin',
+        options: {
+            host: 'codex',
+            target: repoRoot,
+            force: false,
+            json: false,
+        },
+    }, envSource, packageRoot());
+    const plan = runInstaller({
+        operation: 'upgrade-plan',
+        mode: 'plugin',
+        options: {
+            host: 'codex',
+            target: repoRoot,
+            force: false,
+            json: false,
+        },
+    }, envSource, packageRoot());
+    assert.equal(plan.operation, 'upgrade-plan');
+    assert.equal(plan.status, 'planned');
+    assert.equal(plan.installed_status?.upgrade_eligibility, 'current');
+    assert.deepEqual(plan.changed_paths, []);
+    assert.deepEqual(plan.drift, []);
+    assert.equal(plan.rehearsal?.mutates_target, false);
+    assert.equal(plan.rollback_path, null);
+});
+test('upgrade-plan reports available payload and changed paths', () => {
+    const base = fixtureRoot();
+    const envSource = prepareEnv(base);
+    mkdirSync(envSource.CODEX_HOME, { recursive: true });
+    const repoRoot = join(base, 'repo');
+    mkdirSync(repoRoot, { recursive: true });
+    runInstaller({
+        mode: 'plugin',
+        options: {
+            host: 'codex',
+            target: repoRoot,
+            force: false,
+            json: false,
+        },
+    }, envSource, packageRoot());
+    const statusPath = join(repoRoot, 'plugins', 'loom', '.loom-install-status.json');
+    const status = JSON.parse(readFileSync(statusPath, 'utf8'));
+    status.version_context.installer_package_version = '0.0.0';
+    writeFileSync(statusPath, `${JSON.stringify(status, null, 2)}\n`, 'utf8');
+    writeFileSync(join(repoRoot, 'plugins', 'loom', 'skills', 'registry.json'), '{"registry_version":"0.0.0"}\n', 'utf8');
+    const plan = runInstaller({
+        operation: 'upgrade-plan',
+        mode: 'plugin',
+        options: {
+            host: 'codex',
+            target: repoRoot,
+            force: false,
+            json: false,
+        },
+    }, envSource, packageRoot());
+    assert.equal(plan.status, 'planned');
+    assert.equal(plan.installed_status?.upgrade_eligibility, 'upgrade-available');
+    assert.equal(plan.changed_paths?.includes(join('plugins', 'loom', 'skills', 'registry.json')), true);
+    assert.equal(plan.rollback_path, join(repoRoot, 'plugins', 'loom'));
+});
+test('verify-upgrade fails closed when installed payload drifts from recorded metadata', () => {
+    const base = fixtureRoot();
+    const envSource = prepareEnv(base);
+    mkdirSync(envSource.CODEX_HOME, { recursive: true });
+    const repoRoot = join(base, 'repo');
+    mkdirSync(repoRoot, { recursive: true });
+    runInstaller({
+        mode: 'plugin',
+        options: {
+            host: 'codex',
+            target: repoRoot,
+            force: false,
+            json: false,
+        },
+    }, envSource, packageRoot());
+    writeFileSync(join(repoRoot, 'plugins', 'loom', 'skills', 'registry.json'), '{"registry_version":"drift"}\n', 'utf8');
+    const verify = runInstaller({
+        operation: 'verify-upgrade',
+        mode: 'plugin',
+        options: {
+            host: 'codex',
+            target: repoRoot,
+            force: false,
+            json: false,
+        },
+    }, envSource, packageRoot());
+    assert.equal(verify.status, 'blocked');
+    assert.equal(verify.installed_status?.runtime_state, 'blocked');
+    assert.equal(verify.installed_status?.upgrade_eligibility, 'drift');
+    assert.equal(verify.drift?.includes(join('plugins', 'loom', 'skills', 'registry.json')), true);
+    assert.equal(verify.failed_layer, 'installed-surface');
+    assert.match(verify.fail_closed_reason ?? '', /drifted/);
+    assert.equal(verify.rollback_path, join(repoRoot, 'plugins', 'loom'));
+});
+test('verify-upgrade fails closed when installed version metadata is missing', () => {
+    const base = fixtureRoot();
+    const envSource = prepareEnv(base);
+    mkdirSync(envSource.CODEX_HOME, { recursive: true });
+    const repoRoot = join(base, 'repo');
+    mkdirSync(repoRoot, { recursive: true });
+    runInstaller({
+        mode: 'plugin',
+        options: {
+            host: 'codex',
+            target: repoRoot,
+            force: false,
+            json: false,
+        },
+    }, envSource, packageRoot());
+    rmSync(join(repoRoot, 'plugins', 'loom', '.loom-install-status.json'));
+    const verify = runInstaller({
+        operation: 'verify-upgrade',
+        mode: 'plugin',
+        options: {
+            host: 'codex',
+            target: repoRoot,
+            force: false,
+            json: false,
+        },
+    }, envSource, packageRoot());
+    assert.equal(verify.status, 'blocked');
+    assert.equal(verify.installed_status?.upgrade_eligibility, 'incompatible');
+    assert.equal(verify.failed_layer, 'installed-surface');
+    assert.match(verify.fail_closed_reason ?? '', /metadata is missing/);
+    assert.equal(verify.rollback_path, join(repoRoot, 'plugins', 'loom'));
+});
 test('codex plugin install fails closed on marketplace conflicts without force', () => {
     const base = fixtureRoot();
     const envSource = prepareEnv(base);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mc-and-his-agents/loom-installer",
-  "version": "0.1.79",
+  "version": "0.1.81",
   "description": "Node installer for Loom plugin and single-skill installation surfaces.",
   "type": "module",
   "bin": {