@vibesdotdev/plugins 0.0.0-stage → 1.0.0-rc.0

package/dist/cli/update.cli-command.impl.consumer.js

@@ -0,0 +1,750 @@
+import { resolveVibesAppOriginForEnvironment } from '@vibesdotdev/config/environment/resolve-app-origin';
+import { resolveFileSystemAdapter } from '@vibesdotdev/filesystem/client/resolve-adapter';
+import { getPathRoots } from '@vibesdotdev/paths';
+import { LoggedErrorSchema } from '@vibesdotdev/logging';
+import { CapabilityError, CaughtFailureSchema, composeChildEnv, getRuntimeHostIdentity, getRuntimePackagePlugins, isCapabilityError } from '@vibesdotdev/kernel';
+import { readWorkspacePluginSurfaces } from '@vibesdotdev/kernel/bootstrap';
+import { redactedExcerpt } from '@vibesdotdev/shared/utils';
+import { z } from 'zod/v4';
+import { unreadableSelectionsRefusal } from "./plugins.unlink.cli-command.impl.consumer.js";
+import { summarizeChildFailure } from "./child-failure.js";
+import { PluginsCLICommand } from "./context.js";
+import { resolveRuntimeExecution } from "./execution.js";
+import { planBun, readScopeDeclarations, runBunOrThrow } from "./package-manager.consumer.js";
+import { bodiesRunningReplacedExecutable, censusBodies, markReplacedExecutables, rollBodies } from "./roll.js";
+import { resolveScopes } from "./scopes.js";
+import { formatRepairReceipt, repairGlobalScope, seedGlobalScope, GLOBAL_MANIFEST_NAME, HOST_PACKAGE_NAME } from "./seed.js";
+import { runSelfUpdate, selfInstallTarget } from "./self-update.js";
+/**
+ * Prefix the release artifacts are published under, on the `assets` origin.
+ *
+ * MEASURED CORRECTION (WU-12, 2026-08-31): this used to read
+ * `https://vibes.dev/downloads/cli/latest.json`, which is not where anything
+ * is published. `vibes infra release cli` uploads to R2 bucket
+ * `vibes-public-downloads` under key prefix `downloads/cli/`, served from
+ * `https://assets.vibes.dev/`, and `home-web`'s `scripts/install.sh` has
+ * always downloaded from `${VIBES_MIRROR:-https://assets.vibes.dev/downloads/cli}`.
+ * `--self` pointing at a different origin than the installer is a split every
+ * mirror user would hit, so the ONE base is shared. The installer's
+ * `VIBES_MIRROR` is a shell variable; here the mirror is the command's own
+ * declared `--mirror <url>` option, never an environment read.
+ */
+const RELEASE_DOWNLOADS_PATH = 'downloads/cli';
+/** The deadline on the shipping-path verification boot. */
+const VERIFICATION_TIMEOUT_MS = 120_000;
+/** Whether a scope declares anything bun could install: a dependency or a `workspaces` glob. A scope with no manifest declares nothing. */
+function declaresAnything(declared) {
+    return declared !== null && (declared.dependencies.length > 0 || declared.workspaces.length > 0);
+}
+/**
+ * The published release base: the `assets` origin the production
+ * `config/environment` declares, under {@link RELEASE_DOWNLOADS_PATH}.
+ * Releases are published only to production, whatever environment this host
+ * calls (the desktop release reads its origin by the same rule), so this
+ * reads the production declaration rather than the active one; `--mirror`
+ * retargets. A runtime that declares no production `assets` origin refuses
+ * `release-origin-undeclared`.
+ */
+export async function publishedReleaseBase(runtime) {
+    const origin = await resolveVibesAppOriginForEnvironment('assets', 'production', runtime);
+    if (origin === null) {
+        throw new CapabilityError('No production assets origin is declared in this runtime.', 'NOT_FOUND', {
+            reason: 'release-origin-undeclared',
+            retryable: false,
+            recoveryHint: 'Pass --mirror <url> naming the release base that holds latest.json.'
+        });
+    }
+    return `${origin}/${RELEASE_DOWNLOADS_PATH}`;
+}
+/** `latest.json` under a release base (the declared `--mirror`, else the published base), trailing slashes trimmed. */
+export function latestManifestUrl(base) {
+    return `${base.replace(/\/+$/, '')}/latest.json`;
+}
+/**
+ * Which scope reports make `vibes update` FAIL.
+ *
+ * A command that reports `NOT VERIFIED` and exits 0 is the absence-looks-like-
+ * success defect: the shipped draft did exactly that, so a scope whose
+ * verification boot could not compose, and a `$VIBES_HOME` the command refused
+ * to touch at all, both read as "updated" to CI, to a script, and to the WU-07
+ * harness. Pure and exported so the rule is testable without booting a child.
+ *
+ * Not a failure: a benign skip (`no workspace plugin list to update`, a home
+ * delegated to a host workspace) — nothing was asked for and nothing broke.
+ *
+ * `--dry-run` suppresses only the VERIFICATION half: nothing was installed, so
+ * nothing was booted, so an unverified scope is not a defect. A REFUSAL is not
+ * suppressed — a foreign or fossil `$VIBES_HOME`, or a link glob whose parent
+ * is gone, is a fact about the scope as it stands, not about the install that
+ * did not run, and `vibes update --dry-run` in CI has to be able to see it.
+ */
+/** A surface omission is verified because the kernel refused to import the declared export. */
+export function isUnverifiedPluginRow(row) {
+    if (row.status === 'loaded' || row.status === 'deduped')
+        return false;
+    if (row.status === 'not-composed' && row.reason === 'surface-omitted')
+        return false;
+    return true;
+}
+export function collectUpdateFailures(reports, options) {
+    const failures = [];
+    for (const report of reports) {
+        // Deliberately BEFORE the dry-run short-circuit: a refusal happened
+        // whether or not anything was going to be installed.
+        if (report.failed === true) {
+            failures.push({
+                scope: report.scope,
+                root: report.root,
+                reason: report.skipped ?? 'refused'
+            });
+            continue;
+        }
+        if (report.skipped !== undefined)
+            continue;
+        // Nothing was installed, so nothing was booted: there is no verification
+        // to have failed.
+        if (options.dryRun)
+            continue;
+        if (!report.verified) {
+            failures.push({
+                scope: report.scope,
+                root: report.root,
+                reason: `NOT VERIFIED: ${report.verifyDetail ?? 'unknown'}`
+            });
+        }
+    }
+    return failures;
+}
+/** The first 12 hex digits of `bun.lock`'s sha256 under `root`, or `null` when the scope has no lock. */
+async function lockDigest(runtime, root) {
+    const filesystem = await resolveFileSystemAdapter(runtime, { binding: false });
+    const path = filesystem.join(root, 'bun.lock');
+    if (!(await filesystem.exists(path)))
+        return null;
+    const read = await filesystem.readFile(path);
+    const bytes = read instanceof Uint8Array ? read.slice() : new TextEncoder().encode(read);
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', bytes));
+    return Array.from(digest, (byte) => byte.toString(16).padStart(2, '0')).join('').slice(0, 12);
+}
+/**
+ * The command's inputs, each read on its own: a missing flag is off, a missing
+ * or non-text mirror is empty. commander maps `--no-roll` to `roll: false`, so
+ * only an explicit `false` turns the roll off.
+ */
+const UpdateInputSchema = z.object({
+    dryRun: z.boolean().catch(false),
+    roll: z.boolean().catch(true),
+    latest: z.boolean().catch(false),
+    repair: z.boolean().catch(false),
+    self: z.boolean().catch(false),
+    allowDowngrade: z.boolean().catch(false),
+    mirror: z.string().trim().catch('')
+});
+/** The schema of the verification boot's `plugins list --json` envelope, each field on its own. */
+const VerificationEnvelopeSchema = z.object({
+    plugins: z.array(z.object({ plugin: z.string(), status: z.string(), reason: z.literal('surface-omitted').optional() })).optional().catch(undefined),
+    resolutions: z
+        .array(z.object({ specifier: z.string(), linked: z.boolean().nullable(), realpath: z.string().nullable() }))
+        .optional()
+        .catch(undefined)
+});
+/** A failure as one bounded, credential-free line for a report. */
+function reportLine(failure) {
+    return redactedExcerpt(LoggedErrorSchema.parse(failure).message) || 'unknown failure';
+}
+/**
+ * `vibes update` — seed, install, verify, roll (plan §5).
+ *
+ * ### Ordering: self FIRST, then the graph, then ONE roll
+ *
+ * `--self` runs before any scope work and the census roll runs exactly once at
+ * the end. Rolling before the binary is replaced re-stales every body just
+ * rolled — the executable freshness nerve fires on the new inode — so the
+ * draft's "roll, then swap" order produced two rolls and a `pm status` Build
+ * column reading STALE immediately after a successful update.
+ *
+ * ### What triggers the roll: THREE reasons, one nerve each
+ *
+ * 1. the module graph moved (a scope's `bun.lock` digest changed);
+ * 2. `--self` installed a new release over this executable;
+ * 3. a body in the census is **already** executing a replaced file.
+ *
+ * The third one is not redundant. A local `bun run build:install` swaps
+ * `~/.local/bin/vibes` by atomic rename: no lock moves and `--self` downloaded
+ * nothing, so on reasons 1–2 alone `vibes update` reported "nothing changed, so
+ * no body was rolled" in the same minute `vibes pm status` reported "⚠ PM
+ * daemon (pid …) runs a replaced vibes executable". Two surfaces, one fact,
+ * and the surface that could FIX it held the weaker predicate. The census now
+ * consumes the same executable nerve `pm status` and PM's
+ * `ExecutableFreshnessReconciler` consume (`markReplacedExecutables`), so a
+ * body running a replaced executable is rolled and the receipt says why.
+ *
+ * ### Per scope
+ *
+ * preflight (schema, glob parents, foreign-owner refusal, `workspace:*`
+ * declarations) → `bun install` → a SCOPED `bun update <enabled registry
+ * packages> @vibesdotdev/plugins`, never a fleet-wide `bun update` at a
+ * 232-member root → verification by spawning the SHIPPING path
+ * (`vibes plugins list --json --scope <kind>` with `VIBES_HOST_ROOT` bound to
+ * the scope root), where every row must read `loaded`.
+ *
+ * The verification deliberately re-enters the real executable rather than
+ * inspecting the manifest we just wrote. A manifest is a claim; a boot is a
+ * measurement, and it is the only thing that proves the scope this command
+ * just changed can still compose.
+ *
+ * ### Exit code
+ *
+ * A scope that did not verify, and a scope the command REFUSED to touch, both
+ * make `vibes update` exit non-zero — after the full report (including the
+ * `--json` envelope) has been printed. The draft printed `NOT VERIFIED` and
+ * exited 0, so a refused `$VIBES_HOME` and a scope that cannot compose read as
+ * success to CI, to a script and to the WU-07 harness. Benign skips (a
+ * workspace with no plugin list, a home delegated to a host workspace) are not
+ * failures. `--dry-run` never fails a VERIFICATION — it installs nothing, so
+ * it boots nothing — but a REFUSED scope still exits non-zero under it: the
+ * refusal describes the scope as it stands, not the install that did not run.
+ * The rule lives in `collectUpdateFailures`.
+ *
+ * ### Foreign / fossil manifests
+ *
+ * A `$VIBES_HOME/package.json` whose name is not `vibes-global` is somebody
+ * else's file (or the 24-April fossil). We refuse it by name and print
+ * `vibes update --repair --global`; `--repair` then backs it up as
+ * `*.fossil-<stamp>` and prints kept|dropped. Nothing is merged silently and
+ * nothing is deleted without a backup line.
+ */
+export default class UpdateCLICommand extends PluginsCLICommand {
+    constructor(descriptor, context) {
+        super(descriptor, context);
+    }
+    async execute(args, options) {
+        const flags = { ...args, ...options };
+        const { dryRun, roll, latest, repair, ...input } = UpdateInputSchema.parse(flags);
+        const paths = getPathRoots(this.runtime);
+        const self = input.self ? await this.updateSelf(dryRun, input.mirror, input.allowDowngrade) : null;
+        const scopes = await resolveScopes(this.runtime, flags, { fallback: 'both' });
+        const scoped = [];
+        for (const scope of scopes) {
+            scoped.push(await this.updateScope(scope, { dryRun, latest, repair }));
+        }
+        const reports = scoped.map((outcome) => outcome.report);
+        const graphChanged = reports.some((report) => report.changed);
+        let outcomes = [];
+        let censusNote;
+        if (!roll) {
+            censusNote = '--no-roll: running bodies keep the previous graph until they restart.';
+        }
+        else {
+            // The census is taken BEFORE the trigger is decided, because one of the
+            // three reasons to roll is a fact about the bodies themselves.
+            const bodies = await markReplacedExecutables(await censusBodies({
+                runtime: this.runtime,
+                userHome: paths.userHome,
+                vibesHome: paths.vibesHome,
+                includePmDaemon: true
+            }), this.runtime);
+            // THE THIRD REASON. `--self` only reports a release this command
+            // downloaded, and the lock digest only reports the module graph; a local
+            // `bun run build:install` replaces the executable by atomic rename and
+            // moves neither. Gating on those two alone made `vibes update` print
+            // "nothing changed, so no body was rolled" while `vibes pm status`
+            // printed "runs a replaced vibes executable" about the same daemon.
+            // Same nerve, one decision.
+            const stale = bodiesRunningReplacedExecutable(bodies);
+            if (graphChanged || self?.replaced || stale.length > 0 || dryRun) {
+                const notes = [];
+                if (stale.length > 0 && !graphChanged && !self?.replaced) {
+                    notes.push(`the module graph is unchanged, but ${stale.length} running ` +
+                        `${stale.length === 1 ? 'body executes' : 'bodies execute'} a replaced vibes ` +
+                        `executable — ${stale.map((body) => `${body.id}: ${body.replacedReason}`).join('; ')}`);
+                }
+                if (!this.runtime.hasKind('hq/os-service')) {
+                    notes.push('hq/os-service is not composed into this host, so OS services were enumerated from ' +
+                        'the agent directory alone and cannot be restarted from here.');
+                }
+                if (notes.length)
+                    censusNote = notes.join(' ');
+                outcomes = await rollBodies({ runtime: this.runtime, bodies, dryRun });
+            }
+            else {
+                censusNote =
+                    'nothing changed and no running body executes a replaced vibes executable, ' +
+                        'so no body was rolled.';
+            }
+        }
+        this.emit({ self, reports, outcomes, censusNote, dryRun });
+        // The report is printed FIRST (including the whole `--json` envelope, so
+        // a machine caller still gets every row) and only then does the command
+        // fail. Silence plus exit 0 is what this replaces.
+        const failures = collectUpdateFailures(reports, { dryRun });
+        if (failures.length > 0)
+            throw updateIncomplete(failures, scoped);
+    }
+    /** Replace the running executable from the declared `--mirror`, else the published release base. */
+    async updateSelf(dryRun, mirror, allowDowngrade) {
+        const host = this.runtime.localEnvironment;
+        const platform = host.getPlatform?.();
+        const arch = host.getArch?.();
+        const home = host.accountHome?.();
+        if (!platform || !arch || !home) {
+            throw new CapabilityError('Host platform, architecture and account home are not captured.', 'UNAVAILABLE', {
+                recoveryHint: 'Run through a host that captures platform, architecture and account home (the vibes CLI host).'
+            });
+        }
+        const target = selfInstallTarget(platform, { LOCALAPPDATA: this.runtime.getEnv('LOCALAPPDATA') }, home);
+        const manifestUrl = latestManifestUrl(mirror || (await publishedReleaseBase(this.runtime)));
+        const result = await runSelfUpdate({
+            runtime: this.runtime,
+            manifestUrl,
+            currentVersion: this.hostVersion(),
+            target,
+            platform,
+            arch,
+            dryRun,
+            allowDowngrade
+        });
+        const report = {
+            replaced: result.replaced,
+            fromVersion: result.fromVersion,
+            toVersion: result.toVersion,
+            target: result.target.label,
+            manifestUrl
+        };
+        // THE DIGEST IS THE POINT OF A DRY RUN. `runSelfUpdate` already
+        // resolved the asset and its sha256; dropping it here left
+        // `--self --dry-run` announcing a download whose verification the
+        // operator could not check against SHA256SUMS.txt before running it
+        // for real. Reported on both surfaces (WU-12).
+        if (result.sha256)
+            report.sha256 = result.sha256;
+        if (result.note)
+            report.note = result.note;
+        return report;
+    }
+    /** Version of the running host: the host's own version fact, the one `--version` reports. */
+    hostVersion() {
+        // The shim's channel version, else the version the executable host
+        // declared; the environment captured both once.
+        return this.runtime.localEnvironment.hostVersion?.()?.trim() || 'unknown';
+    }
+    async updateScope(scope, options) {
+        const filesystem = await resolveFileSystemAdapter(this.runtime, { binding: false });
+        const plugins = await getRuntimePackagePlugins(this.runtime);
+        const manifestPath = filesystem.join(scope.root, 'package.json');
+        const base = {
+            scope: scope.kind,
+            root: scope.root,
+            manifestPath,
+            lockBefore: await lockDigest(this.runtime, scope.root),
+            lockAfter: null,
+            changed: false,
+            packages: [],
+            commands: [],
+            verified: false,
+            plugins: []
+        };
+        if (scope.kind === 'global') {
+            const repairReport = await this.prepareGlobal(plugins, scope.root, options);
+            if (repairReport.refusal)
+                return { report: { ...base, skipped: repairReport.refusal, failed: true } };
+            if (repairReport.lines.length)
+                base.repair = repairReport.lines;
+        }
+        const selected = await this.selectionsFor(scope);
+        const selections = selected.plugins;
+        if (selected.surface)
+            base.surface = selected.surface;
+        if (selections.length === 0 && scope.kind === 'workspace') {
+            const skipped = selected.surface
+                ? `${selected.surface} selects no plugins`
+                : `no workspace plugin list to update (looked for vibes.config.{ts,js,json}#plugins, then package.json#vibes.plugins in ${scope.root})`;
+            return { report: { ...base, skipped } };
+        }
+        // Preflight the on-disk rules before running bun: a glob whose parent is
+        // gone or a specifier nothing declares makes `bun install` succeed and the
+        // next boot fail, which is the worst possible ordering.
+        const preflight = this.preflight(plugins, scope);
+        if (preflight.issues.length) {
+            const skipped = { ...base, skipped: preflight.issues.join('; ') };
+            if (!preflight.benign)
+                skipped.failed = true;
+            return { report: skipped };
+        }
+        // The scope's install inputs, read once: an unreadable manifest refuses the scope (non-zero exit).
+        const declarations = await this.readDeclarations(scope.root);
+        if ('refused' in declarations) {
+            const refused = declarations.refused;
+            return { report: { ...base, skipped: `${refused.message} (${refused.reason})`, failed: true }, failure: refused };
+        }
+        const declared = declarations.declared;
+        // A scope that declares NOTHING — no plugins, no dependencies, no
+        // `workspaces` globs — has no install to run, and running one is not
+        // harmless: `bun install` on an empty manifest prints "No packages!
+        // Deleted empty lockfile" and still MATERIALIZES an empty
+        // `node_modules/` (measured, bun 1.4.0). Under `$VIBES_HOME` that
+        // directory is the one thing plan §8 item 3 says a delegated home must
+        // not have — an empty `node_modules` is where a later stray install
+        // silently lands and becomes a second graph. This is the exact shape
+        // `vibes update --repair --global` leaves behind on the migration path
+        // (plan §9 step 1 drops every fossil dependency and glob before step 2
+        // records `hostWorkspace`), so without this skip the documented
+        // migration cannot reach the documented end state.
+        if (selections.length === 0 && !declaresAnything(declared)) {
+            return { report: { ...base, skipped: 'nothing declared — no plugins, dependencies or workspaces globs to install' } };
+        }
+        const members = plugins.expandWorkspaceMembers(scope.root);
+        const registryPackages = [...new Set(selections.map((selection) => plugins.getPackageName(selection)))]
+            .filter((name) => !members.has(name))
+            .sort();
+        // The host package is always kept current; a scope that never names it
+        // still resolves its plugins through it.
+        const updateTargets = [...new Set([...registryPackages, HOST_PACKAGE_NAME])].filter((name) => declared?.dependencies.includes(name) === true);
+        base.packages = updateTargets;
+        const install = { action: 'install', cwd: scope.root };
+        const update = {
+            action: 'update',
+            cwd: scope.root,
+            args: [...updateTargets, ...(options.latest ? ['--latest'] : [])]
+        };
+        base.commands = [
+            await planBun({ runtime: this.runtime, ...install }),
+            ...(updateTargets.length ? [await planBun({ runtime: this.runtime, ...update })] : [])
+        ];
+        if (options.dryRun)
+            return { report: base };
+        // REGISTRY AUTH PREFLIGHT — the last thing checked before bun runs.
+        //
+        // Everything above this line preflights the on-disk shape. This one
+        // preflights the CREDENTIAL, because the failure it prevents is not a
+        // crash: packages.vibes.dev 404-hides a rejected or unresolved
+        // credential rather than returning 401, so `bun install` emits
+        // `error: GET https://packages.vibes.dev/@vibesdotdev%2fplugins - 404`
+        // and the user reasonably concludes the package was never published.
+        // Measured on a real machine 2026-08-31 — days were spent on a
+        // publication bug that did not exist. A refusal that NAMES the remedy
+        // is strictly better than a bare 404 trace.
+        // `runBunOrThrow` owns it (`registry-sign-in.consumer.ts`), so every
+        // install path — `update`, `plugins add|link|unlink|remove` — gets it.
+        await runBunOrThrow({ runtime: this.runtime, ...install });
+        // NEVER a bare `bun update` here: at a 232-member developer root that
+        // walks every workspace member and rewrites the whole lock.
+        if (updateTargets.length) {
+            await runBunOrThrow({ runtime: this.runtime, ...update });
+        }
+        base.lockAfter = await lockDigest(this.runtime, scope.root);
+        base.changed = base.lockAfter !== base.lockBefore;
+        const verification = await this.verifyScope(plugins, scope);
+        base.verified = verification.ok;
+        base.plugins = verification.rows;
+        if (!verification.ok)
+            base.verifyDetail = verification.detail;
+        return { report: base, failure: verification.failure };
+    }
+    /** Seed an absent home, repair a fossil one, or refuse a foreign one by name. */
+    async prepareGlobal(plugins, root, options) {
+        const scope = plugins.readGlobalPluginScope(root);
+        if (scope.absent) {
+            const seeded = await seedGlobalScope(this.runtime, { home: root, dryRun: options.dryRun });
+            const lines = [`seeded ${seeded.manifestPath}`];
+            if (seeded.wroteBunfig)
+                lines.push(`seeded ${seeded.bunfigPath}`);
+            if (seeded.migratedBunfig)
+                lines.push(`repaired the @vibesdotdev scope in ${seeded.bunfigPath} (backup beside it)`);
+            return { lines };
+        }
+        if (options.repair) {
+            const result = await repairGlobalScope(this.runtime, {
+                home: root,
+                dryRun: options.dryRun,
+                // The kernel is dependency-free by contract, so the glob expander
+                // is injected here: without it a `workspace:*` dependency whose
+                // supplying glob is gone would be KEPT and bun would fail the
+                // install again — the shape `vibes plugins unlink` used to leave
+                // behind, and the one `--repair` could not repair.
+                workspaceMembers: (scopeRoot, globs) => plugins.expandWorkspaceMembers(scopeRoot, [...globs]).keys()
+            });
+            return { lines: formatRepairReceipt(result) };
+        }
+        if (!scope.owned) {
+            return {
+                lines: [],
+                refusal: `${scope.manifestPath} is named '${scope.manifestName ?? '(unnamed)'}', not ` +
+                    `'${GLOBAL_MANIFEST_NAME}'. vibes will not rewrite a manifest it does not own. ` +
+                    'Run: vibes update --repair --global (it backs the file up first)'
+            };
+        }
+        return { lines: [] };
+    }
+    /**
+     * The specifiers a scope has ENABLED, read through the SAME resolution the
+     * bootstrap loader composes from.
+     *
+     * The workspace half used to call `resolveWorkspaceListTarget`, the WRITER's
+     * target resolver, which reports an empty list for a `vibes.config.ts`
+     * because it refuses to rewrite a module. `update --workspace` therefore saw
+     * nothing to update for plan §3's PRIMARY workspace surface — the file
+     * requirement #1 tells users to write — and skipped the scope with
+     * `no workspace plugin list to update`. It now reads Runtime's
+     * `readWorkspacePluginSurfaces` (`@vibesdotdev/kernel/bootstrap`, the
+     * owner of workspace composition formats) over the handed runtime's
+     * selected `runtime/loader`, the same reader the workspace composition and
+     * `plugins list` read: `vibes.config.{ts,js,json}#plugins` primary,
+     * `package.json#vibes.plugins` fallback.
+     *
+     * A SHADOWED fallback list is deliberately not included. `bun update` here
+     * targets the packages this scope composes; a specifier the effective surface
+     * overrides is not composed, and installing it would make `vibes update`
+     * disagree with the boot it uses to verify itself.
+     */
+    async selectionsFor(scope) {
+        if (scope.kind === 'global') {
+            return {
+                plugins: (await getRuntimePackagePlugins(this.runtime)).readGlobalPluginScope(scope.root).plugins,
+                surface: 'package.json#vibes.plugins'
+            };
+        }
+        const loader = await this.runtime
+            .query('runtime/loader')
+            .enabled()
+            .resolve();
+        const listing = await readWorkspacePluginSurfaces(scope.root, { loader });
+        // A declaration that failed to load leaves the list unknown: refuse
+        // rather than update the manifest's list or nothing.
+        if (listing.failures.length > 0)
+            throw unreadableSelectionsRefusal(listing);
+        return {
+            plugins: listing.effective?.plugins ?? [],
+            surface: listing.effective?.surface ?? null
+        };
+    }
+    /**
+     * The scope's install inputs. An unreadable or malformed manifest is the
+     * typed `plugin-scope-manifest-unreadable` refusal, carried into the report
+     * as a refused scope (SPEC: a refused scope exits non-zero) and kept whole
+     * as the command's cause; every other failure propagates.
+     */
+    async readDeclarations(root) {
+        try {
+            return { declared: await readScopeDeclarations(this.runtime, root) };
+        }
+        catch (error) {
+            const failure = CaughtFailureSchema.parse(error);
+            if (isCapabilityError(failure) && failure.reason === 'plugin-scope-manifest-unreadable')
+                return { refused: failure };
+            throw failure;
+        }
+    }
+    /**
+     * On-disk rules that decide whether bun may run at all.
+     *
+     * `benign` separates "there is nothing here to do" (a delegated home owns
+     * no packages — the update belongs to the host workspace) from "the request
+     * could not be carried out" (a link glob whose parent directory is gone).
+     * Only the second kind fails the command; conflating them would make
+     * `vibes update --global` on a delegated machine exit non-zero forever.
+     */
+    preflight(plugins, scope) {
+        if (scope.kind === 'global') {
+            const global = plugins.readGlobalPluginScope(scope.root);
+            if (global.hostWorkspace) {
+                return {
+                    issues: [
+                        `delegated to ${global.hostWorkspace} — update that workspace instead ` +
+                            '(the global home owns no packages)'
+                    ],
+                    benign: true
+                };
+            }
+            return {
+                issues: plugins.validatePluginScopeOnDisk(global)
+                    .filter((issue) => issue.code === 'workspace-parent-missing')
+                    .map((issue) => `${issue.message}. Remedy: ${issue.remedy}`),
+                benign: false
+            };
+        }
+        return { issues: [], benign: true };
+    }
+    /**
+     * Boot the SHIPPING path against the scope root and require every row to be
+     * composed. A manifest that parses is not a scope that composes.
+     *
+     * Two details that are easy to get wrong and were measured, not guessed:
+     *
+     * - The child's cwd is the scope root only for the WORKSPACE scope. Setting
+     *   it to `$VIBES_HOME` for the global scope made bootstrap read
+     *   `$VIBES_HOME/package.json#vibes.plugins` as the *workspace* fallback
+     *   list (there is no config there, so the cwd IS the workspace root), so
+     *   the workspace batch claimed every global specifier and the global batch
+     *   reported `deduped` for all of them.
+     * - `deduped` is therefore accepted alongside `loaded`: it means the very
+     *   same specifier was already selected by an earlier scope in that process,
+     *   so the plugin IS composed. `missing` and `failed` are the real failures,
+     *   and `shadowed` is reported as a warning detail because another plugin
+     *   owns the id.
+     */
+    async verifyScope(plugins, scope) {
+        let argv;
+        try {
+            argv = (await getRuntimeHostIdentity(this.runtime)).selfSpawnArgv('vibes update verification');
+        }
+        catch (error) {
+            const failure = CaughtFailureSchema.parse(error);
+            return { ok: false, rows: [], detail: reportLine(failure), failure };
+        }
+        const execution = await resolveRuntimeExecution(this.runtime, 'update verification boot');
+        const request = {
+            command: argv[0],
+            args: [...argv.slice(1), 'plugins', 'list', '--json', '--scope', scope.kind],
+            env: composeChildEnv(this.runtime, { env: { VIBES_HOST_ROOT: scope.root } }),
+            envMode: 'replace',
+            timeout: VERIFICATION_TIMEOUT_MS
+        };
+        if (scope.kind === 'workspace')
+            request.cwd = scope.root;
+        const result = await execution.execute(request);
+        if (result.exitCode !== 0 || result.timedOut) {
+            const summary = summarizeChildFailure({ stdout: result.stdout, stderr: result.stderr, max: 3 });
+            return {
+                ok: false,
+                rows: [],
+                detail: (summary && redactedExcerpt(summary, { maxChars: 1_000 })) ||
+                    `verification exited ${result.timedOut ? 'by timeout' : String(result.exitCode)} with no output`
+            };
+        }
+        const start = result.stdout.indexOf('{');
+        if (start < 0)
+            return { ok: false, rows: [], detail: 'verification produced no JSON envelope' };
+        let json;
+        try {
+            json = JSON.parse(result.stdout.slice(start));
+        }
+        catch (error) {
+            const failure = CaughtFailureSchema.parse(error);
+            return { ok: false, rows: [], detail: `verification produced malformed JSON: ${reportLine(failure)}`, failure };
+        }
+        const envelope = VerificationEnvelopeSchema.safeParse(json);
+        if (!envelope.success)
+            return { ok: false, rows: [], detail: 'verification produced a JSON envelope of the wrong shape' };
+        const linkage = new Map((envelope.data.resolutions ?? []).map((row) => [row.specifier, row]));
+        const rows = (envelope.data.plugins ?? []).map((row) => ({
+            plugin: row.plugin,
+            status: row.status,
+            reason: row.reason,
+            linked: linkage.get(row.plugin)?.linked ?? null,
+            realpath: linkage.get(row.plugin)?.realpath ?? null
+        }));
+        const bad = rows.filter((row) => isUnverifiedPluginRow(row));
+        if (bad.length) {
+            return { ok: false, rows, detail: bad.map((row) => `${row.plugin}: ${row.status}`).join(', ') };
+        }
+        return { ok: true, rows };
+    }
+    emit(payload) {
+        if (this.format === 'json') {
+            const roll = {
+                denominator: payload.outcomes.length,
+                rolled: payload.outcomes.filter((outcome) => outcome.rolled).length,
+                bodies: payload.outcomes.map(rollBodyRow)
+            };
+            if (payload.censusNote)
+                roll.note = payload.censusNote;
+            this.ui.json({ dryRun: payload.dryRun, self: payload.self, scopes: payload.reports, roll });
+            return;
+        }
+        if (payload.self) {
+            const self = payload.self;
+            // The sha256 is printed on BOTH surfaces. A dry run whose whole purpose
+            // is "tell me what you would do" that withholds the digest it would
+            // verify leaves the operator unable to compare it with SHA256SUMS.txt
+            // before authorising the real run.
+            const digest = self.sha256 ? ` sha256 ${self.sha256}` : '';
+            this.ui.info(self.replaced
+                ? `self ${self.fromVersion} → ${self.toVersion} installed at ${self.target}${digest}`
+                : `self ${self.fromVersion}: ${self.note ?? 'unchanged'}${digest}`);
+            this.ui.info(`  manifest ${self.manifestUrl}`);
+        }
+        for (const report of payload.reports) {
+            for (const line of report.repair ?? [])
+                this.ui.info(`  ${line}`);
+            if (report.skipped !== undefined) {
+                const line = `${report.scope} ${report.root}: ${report.skipped}`;
+                if (report.failed === true)
+                    this.ui.error(line);
+                else
+                    this.ui.warn(line);
+                continue;
+            }
+            const lock = report.changed
+                ? `lock ${report.lockBefore ?? 'none'} → ${report.lockAfter ?? 'none'}`
+                : `lock ${report.lockAfter ?? report.lockBefore ?? 'none'} (unchanged)`;
+            const failed = !payload.dryRun && !report.verified;
+            const verdict = payload.dryRun
+                ? 'dry run'
+                : report.verified
+                    ? 'verified'
+                    : `NOT VERIFIED: ${report.verifyDetail ?? 'unknown'}`;
+            const line = `${report.scope} ${report.root} — ${lock} — ${verdict}`;
+            if (failed)
+                this.ui.error(line);
+            else
+                this.ui.info(line);
+            for (const command of payload.dryRun ? report.commands : []) {
+                this.ui.info(`  would run: ${command.join(' ')}`);
+            }
+            for (const row of report.plugins) {
+                this.ui.info(`  ${row.plugin} ${row.status} ${row.linked === null ? '' : row.linked ? 'linked' : 'installed'}`.trimEnd());
+            }
+        }
+        if (payload.censusNote)
+            this.ui.warn(payload.censusNote);
+        for (const outcome of payload.outcomes) {
+            if (outcome.rolled)
+                this.ui.success(outcome.line);
+            else
+                this.ui.warn(outcome.line);
+        }
+        if (payload.outcomes.length) {
+            this.ui.info(`${payload.outcomes.filter((outcome) => outcome.rolled).length} of ` +
+                `${payload.outcomes.length} known bodies rolled`);
+        }
+    }
+}
+function rollBodyRow(outcome) {
+    const row = {
+        kind: outcome.body.kind,
+        id: outcome.body.id,
+        source: outcome.body.source,
+        shape: outcome.body.shape,
+        hqRegistered: outcome.body.hqRegistered,
+        // The census reports WHY a body was in scope, not only what happened to
+        // it: `replacedExecutable` is the nerve `vibes pm status` prints as
+        // `⚠ STALE`, and `null` means unanswerable.
+        replacedExecutable: outcome.body.replacedExecutable ?? null,
+        rolled: outcome.rolled
+    };
+    if (outcome.body.pid !== undefined)
+        row.runningPid = outcome.body.pid;
+    if (outcome.body.replacedReason)
+        row.replacedReason = outcome.body.replacedReason;
+    if (outcome.previousPid !== undefined)
+        row.previousPid = outcome.previousPid;
+    if (outcome.pid !== undefined)
+        row.pid = outcome.pid;
+    if (outcome.reason)
+        row.reason = outcome.reason;
+    return row;
+}
+/**
+ * `vibes update` did not complete: one line per failing scope, and the failure
+ * raised behind each refused or unverified scope kept as the cause for `-v`.
+ */
+function updateIncomplete(failures, scoped) {
+    const message = `vibes update did not complete (${failures.length} of ${scoped.length} scope(s)):\n` +
+        failures.map((failure) => `  ${failure.scope} ${failure.root}: ${failure.reason}`).join('\n');
+    const causes = scoped.flatMap((outcome) => (outcome.failure === undefined ? [] : [outcome.failure]));
+    if (causes.length === 0)
+        return new Error(message);
+    return new Error(message, { cause: new AggregateError(causes, 'The failure behind each refused or unverified scope') });
+}
+//# sourceMappingURL=update.cli-command.impl.consumer.js.map