@jini-ai/agent-plugins 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.4.1 — 2026-10-04
+
+- Layout B per-plugin state with a build-free `@jini-ai/agent-plugins/persistent-state` entry; migration completes after quarantining rejected entries.
+- A directory-shaped ZIP entry with a symlink mode is still treated as a symlink.
+
 ## Unreleased — lifecycle consumer adoption
 
 - Expose narrow `createAgentPluginActivations(required, optional)` composition without

package/README.md

@@ -259,3 +259,22 @@ For a host that needs only activation, use `createAgentPluginActivations` with
 `createNodeAgentPluginEffects({})` instead of supplying unused network/provisioning
 ports. Retain one returned object for the process lifetime. See `API.md` for the
 object-shaped reads, filters and optional legacy metadata reader.
+
+### Persistent plugin state (Layout B)
+
+`@jini-ai/agent-plugins/persistent-state` is a build-free Node entry with declarations.
+`pluginStatePaths({ workspaceRoot, pluginId })` gives one plugin's `package/sha256/`,
+`memory/learned/`, `memory/notes/` and `data/` paths. `createPluginMemory` injects the
+filesystem, the package containment primitive and a cross-process lock. Its plugin-facing
+`learned` capability cannot select another id or write user notes. Defaults: 1 MiB learned,
+16 KiB notes, 128 files per tier; callers may lower these caps.
+
+`migratePluginLayout` moves legacy packages, memory and PLUGIN_DATA, preserving conflicts
+and malformed installs for human repair. It records version 2 only after success and repairs
+frozen package roots after interrupted moves. Lock files use workspace staging scratch.
+Uninstall keeps persistent state by default; deleting it requires a matching confirmed preview.
+The reserved workspace directory ids `staging`, `packages`, `memory`, and `data` are refused
+as plugin ids so package state cannot overlap migration inputs or installation scratch.
+
+The `dev.tovu.memory` proposal is consumer policy and is not implemented by this neutral entry.
+No version bump or publishing accompanies this workspace implementation.

package/dist/lifecycle/index.d.ts

@@ -137,8 +137,18 @@ export declare function createAgentPluginLifecycle(required: AgentPluginLifecycl
     }, optional?: {
         readonly deliveryMode?: AgentPluginDeliveryMode;
     }) => Promise<import("./resolve-agent-plugin-refs.js").ResolveAgentPluginRefsResult>;
+    pluginMemory: (input: {
+        readonly workspaceId: string;
+        readonly pluginId: string;
+    }) => import("../../persistent-state.js").PluginMemory;
+    migratePluginLayout: (input: {
+        readonly workspaceId: string;
+    }) => Promise<{
+        complete: boolean;
+        moved: number;
+    }>;
     listInstalledPlugins: (input: {
-        readonly packagesDir: string;
+        readonly workspaceRoot: string;
     }) => Promise<readonly import("./types.js").InstalledAgentPlugin[]>;
     isInstalledDigestPresent: (input: {
         readonly packagesDir: string;

package/dist/lifecycle/index.js

@@ -1,3 +1,4 @@
+import { createPersistentStateModule } from "./persistent-state.js";
 import { fetchAgentPluginArchive, maxAgentPluginArchiveBytes } from './fetch-archive.js';
 import { createSeedBundledModule } from './seed-bundled.js';
 import { createRetireBundledModule } from './retire-bundled.js';
@@ -80,7 +81,13 @@ export function createAgentPluginLifecycle(required, optional = {}) {
         readInstalledMcpServerIds: (input) => capabilities.readInstalledMcpServerIds(input.packageRoot),
         readInstalledMcpServers: (input) => capabilities.readInstalledMcpServers(input.packageRoot),
         resolveAgentPluginRefs: (input, optional = {}) => refs.resolveAgentPluginRefs(input.pluginRefIds, input.workspaceLayout, optional.deliveryMode ?? context.deliveryMode),
-        listInstalledPlugins: (input) => refs.listInstalledPlugins(input.packagesDir),
+        pluginMemory: (input) => createPersistentStateModule(context).memory({
+            workspaceRoot: context.layout.forWorkspace({ workspaceId: input.workspaceId }).root, pluginId: input.pluginId,
+        }),
+        migratePluginLayout: (input) => createPersistentStateModule(context).migrate({
+            workspaceRoot: context.layout.forWorkspace({ workspaceId: input.workspaceId }).root,
+        }),
+        listInstalledPlugins: (input) => refs.listInstalledPlugins(input.workspaceRoot),
         isInstalledDigestPresent: (input) => refs.isInstalledDigestPresent(input.packagesDir, input.archiveDigest),
         rankInstalledAgentPlugins: (input) => search.rankInstalledAgentPlugins(input.query, input.candidates, input.limit),
         readTrustedPluginFile: (input) => trusted.readTrustedPluginFile(input.plugin, input.filename),

package/dist/lifecycle/install.js

@@ -1,3 +1,4 @@
+import { createPersistentStateModule } from "./persistent-state.js";
 /** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
 import { createHash } from "node:crypto";
 import { constants } from "node:fs";
@@ -14,6 +15,7 @@ export class AgentPluginInstallError extends Error {
     }
 }
 function buildModule(ports) {
+    const persistentState = createPersistentStateModule(ports);
     const chmod = ports.filesystem.chmod.bind(ports.filesystem);
     const mkdir = ports.filesystem.mkdir.bind(ports.filesystem);
     const mkdtemp = ports.filesystem.mkdtemp.bind(ports.filesystem);
@@ -45,12 +47,8 @@ function buildModule(ports) {
         if (!SHA256_HEX_PATTERN.test(expectedSha256) || digest !== expectedSha256.toLowerCase()) {
             throw new AgentPluginInstallError({ code: "DIGEST_MISMATCH", message: `archive SHA-256 '${digest}' does not match the expected '${expectedSha256}' — refusing to extract unverified bytes` });
         }
-        await mkdir(workspaceLayout.packages, { recursive: true, mode: 0o700 });
-        const finalRoot = path.join(workspaceLayout.packages, digest);
-        const alreadyPublished = await isRealDirectory(finalRoot);
-        if (alreadyPublished) {
-            return indexInstalledRoot(finalRoot, digest);
-        }
+        await mkdir(workspaceLayout.root, { recursive: true, mode: 0o700 });
+        await persistentState.assertOwnedPath({ workspaceRoot: workspaceLayout.root, entryPath: "staging" });
         await mkdir(workspaceLayout.staging, { recursive: true, mode: 0o700 });
         await assertEntryCountWithinCap(archiveReader.entries({ archive }));
         const transactionRoot = await mkdtemp(path.join(workspaceLayout.staging, "install-"));
@@ -59,9 +57,25 @@ function buildModule(ports) {
         try {
             const executablePaths = await extractEntries(archiveReader.entries({ archive }), extractionRoot);
             const indexed = await indexInstalledRoot(extractionRoot, digest);
-            await publish(extractionRoot, finalRoot);
-            await freezeTree(finalRoot, executablePaths);
-            return { ...indexed, packageRoot: finalRoot };
+            return await persistentState.withPluginLock({ workspaceRoot: workspaceLayout.root, pluginId: indexed.pluginId, run: async () => {
+                    // The manifest identifies the plugin only after bounded staging extraction (Layout B).
+                    const pluginId = indexed.pluginId;
+                    const packagesDir = workspaceLayout.pluginPackagesDir({ pluginId });
+                    await persistentState.assertOwnedPath({ workspaceRoot: workspaceLayout.root, entryPath: path.relative(workspaceLayout.root, packagesDir) });
+                    await mkdir(packagesDir, { recursive: true, mode: 0o700 });
+                    const finalRoot = await assertContainedOnDisk(packagesDir, digest);
+                    for (const directory of [workspaceLayout.pluginDataDir({ pluginId }),
+                        workspaceLayout.pluginMemoryDir({ pluginId, kind: 'learned' }),
+                        workspaceLayout.pluginMemoryDir({ pluginId, kind: 'notes' })]) {
+                        await persistentState.assertOwnedPath({ workspaceRoot: workspaceLayout.root, entryPath: path.relative(workspaceLayout.root, directory) });
+                        await mkdir(directory, { recursive: true, mode: 0o700 });
+                    }
+                    if (await isRealDirectory(finalRoot))
+                        return indexInstalledRoot(finalRoot, digest);
+                    await publish(extractionRoot, finalRoot);
+                    await freezeTree(finalRoot, executablePaths);
+                    return { ...indexed, packageRoot: finalRoot };
+                } });
         }
         finally {
             await rm(transactionRoot, { recursive: true, force: true });

package/dist/lifecycle/layout.d.ts

@@ -2,6 +2,16 @@ export interface AgentPluginWorkspaceLayout {
     readonly root: string;
     readonly packages: string;
     readonly staging: string;
+    pluginRootDir(required: {
+        readonly pluginId: string;
+    }, optional?: Record<string, never>): string;
+    pluginPackagesDir(required: {
+        readonly pluginId: string;
+    }, optional?: Record<string, never>): string;
+    pluginMemoryDir(required: {
+        readonly pluginId: string;
+        readonly kind: 'learned' | 'notes';
+    }, optional?: Record<string, never>): string;
     pluginDataDir(required: {
         readonly pluginId: string;
     }): string;

package/dist/lifecycle/layout.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { pluginStatePaths } from '../../persistent-state.js';
 /** Explicit root only; site-root and environment resolution belong to the consumer. */
 export function createAgentPluginLayout(required) {
     if (!path.isAbsolute(required.root))
@@ -14,9 +15,16 @@ export function createAgentPluginLayout(required) {
                 root: workspaceRoot,
                 packages: path.join(workspaceRoot, 'packages', 'sha256'),
                 staging: path.join(workspaceRoot, 'staging'),
+                pluginRootDir: ({ pluginId }, _optional = {}) => pluginStatePaths({ workspaceRoot, pluginId }).root,
+                pluginPackagesDir: ({ pluginId }, _optional = {}) => pluginStatePaths({ workspaceRoot, pluginId }).packages,
+                pluginMemoryDir: ({ pluginId, kind }, _optional = {}) => {
+                    if (kind !== 'learned' && kind !== 'notes')
+                        throw new Error('Invalid memory kind');
+                    return pluginStatePaths({ workspaceRoot, pluginId })[kind];
+                },
                 pluginDataDir({ pluginId }) {
                     assertSafeSegment(pluginId);
-                    return path.join(workspaceRoot, 'data', pluginId);
+                    return pluginStatePaths({ workspaceRoot, pluginId }).data;
                 },
             };
         },

package/dist/lifecycle/persistent-state.d.ts

@@ -0,0 +1,24 @@
+import type { AgentPluginLifecyclePorts } from './ports.js';
+/** Reuses the platform lock with injected effects, never age-stealing a living migration. */
+export declare function createPersistentStateModule(ports: AgentPluginLifecyclePorts, _optional?: Record<string, never>): {
+    withPluginLock: <T>(required: {
+        workspaceRoot: string;
+        pluginId: string;
+        run(): Promise<T>;
+    }, optional?: {}) => Promise<T>;
+    memory: (required: {
+        workspaceRoot: string;
+        pluginId: string;
+    }, optional?: {}) => import("../../persistent-state.js").PluginMemory;
+    assertOwnedPath: (required: {
+        workspaceRoot: string;
+        entryPath: string;
+    }, optional?: {}) => Promise<string>;
+    migrate: (required: {
+        workspaceRoot: string;
+    }, optional?: {}) => Promise<{
+        complete: boolean;
+        moved: number;
+    }>;
+};
+//# sourceMappingURL=persistent-state.d.ts.map

package/dist/lifecycle/persistent-state.js

@@ -0,0 +1,32 @@
+import { createPluginMemory, migratePluginLayout, assertPluginStatePath, withPluginStateLock } from '../../persistent-state.js';
+import { withFileLock } from '@jini-ai/platform/fs/file-lock';
+import { createPackagePathsModule } from './package-paths.js';
+import { parseAgentPluginManifest } from './manifest.js';
+/** Reuses the platform lock with injected effects, never age-stealing a living migration. */
+export function createPersistentStateModule(ports, _optional = {}) {
+    const { assertContainedOnDisk } = createPackagePathsModule(ports);
+    const effects = {
+        filesystem: ports.filesystem,
+        contain: ({ root, entryPath }) => assertContainedOnDisk(root, entryPath),
+        withLock: ({ lockPath, run }) => withFileLock({ lockPath, run }, {
+            filesystem: ports.filesystem, clock: ports.clock, process: ports.process,
+            hostname: () => ports.process.hostname({}), token: () => ports.ids.newId(),
+            monotonicMs: () => ports.clock.monotonicMs(), sleep: ({ durationMs }) => ports.clock.sleep({ ms: durationMs }),
+            staleMs: Infinity, createParent: true,
+        }),
+    };
+    return {
+        withPluginLock: (required, optional = {}) => withPluginStateLock({ ...effects, ...required }, optional),
+        memory: (required, optional = {}) => createPluginMemory({ ...effects, ...required }, optional),
+        assertOwnedPath: (required, optional = {}) => assertPluginStatePath({ ...effects, ...required }, optional),
+        migrate: (required, optional = {}) => migratePluginLayout({ ...effects, ...required,
+            parsePluginId: ({ value }) => {
+                const parsed = parseAgentPluginManifest({ value });
+                if (!parsed.ok)
+                    throw new Error(parsed.errors.join('; '));
+                return parsed.manifest.name;
+            }, ...(ports.onEvent ? { onEvent: ports.onEvent } : {}),
+        }, optional),
+    };
+}
+//# sourceMappingURL=persistent-state.js.map

package/dist/lifecycle/ports.d.ts

@@ -4,7 +4,7 @@ import type { AgentPluginLayoutPort } from './layout.js';
 import type { AgentPluginDeliveryMode, InstalledAgentPlugin } from './types.js';
 /** Native Node filesystem ABI, narrowed to the operations used by lifecycle.
  * Inject instrumented fs/promises effects directly; native handles are never rewrapped. */
-export type FilesystemPort = Pick<typeof import('node:fs/promises'), 'chmod' | 'mkdir' | 'mkdtemp' | 'open' | 'readdir' | 'readFile' | 'rename' | 'rm' | 'stat' | 'realpath' | 'unlink'>;
+export type FilesystemPort = Pick<typeof import('node:fs/promises'), 'chmod' | 'mkdir' | 'mkdtemp' | 'open' | 'readdir' | 'readFile' | 'rename' | 'rm' | 'rmdir' | 'stat' | 'realpath' | 'unlink'>;
 export type AgentPluginFetchPort = (required: {
     readonly url: string;
 }, optional?: RequestInit) => Promise<Response>;

package/dist/lifecycle/resolve-agent-plugin-refs.d.ts

@@ -12,7 +12,7 @@ export type ResolveAgentPluginRefsResult = {
 /** Internal composition; one state/queue instance per injected host context. */
 export declare function createResolveAgentPluginRefsModule(ports: AgentPluginLifecyclePorts): {
     resolveAgentPluginRefs: (pluginRefIds: readonly string[], workspaceLayout: Pick<AgentPluginWorkspaceLayout, "packages" | "root">, deliveryMode?: AgentPluginDeliveryMode) => Promise<ResolveAgentPluginRefsResult>;
-    listInstalledPlugins: (packagesDir: string) => Promise<readonly InstalledAgentPlugin[]>;
+    listInstalledPlugins: (workspaceRoot: string) => Promise<readonly InstalledAgentPlugin[]>;
     isInstalledDigestPresent: (packagesDir: string, archiveDigest: string) => Promise<boolean>;
 };
 //# sourceMappingURL=resolve-agent-plugin-refs.d.ts.map

package/dist/lifecycle/resolve-agent-plugin-refs.js

@@ -1,5 +1,7 @@
+import { createPersistentStateModule } from "./persistent-state.js";
 /** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
 import path from "node:path";
+import { createPackagePathsModule } from "./package-paths.js";
 import {} from "./activation.js";
 import { createActivationModule } from "./activation.js";
 import {} from "./bundled-digests.js";
@@ -7,6 +9,8 @@ import { createBundledDigestsModule } from "./bundled-digests.js";
 import { createInstallModule } from "./install.js";
 import { createCapabilityProjectionModule } from "./capability-projection.js";
 function buildModule(ports) {
+    const persistentState = createPersistentStateModule(ports);
+    const { assertContainedOnDisk } = createPackagePathsModule(ports);
     const readdir = ports.filesystem.readdir.bind(ports.filesystem);
     const stat = ports.filesystem.stat.bind(ports.filesystem);
     const { resolveAgentPluginActivation } = createActivationModule(ports);
@@ -24,7 +28,7 @@ function buildModule(ports) {
             const refusal = activationRefusal(pluginRefId, await resolveAgentPluginActivation(workspaceLayout.root, pluginRefId));
             if (refusal !== undefined)
                 return { ok: false, reason: refusal };
-            const resolved = await resolveOnePluginRef(pluginRefId, workspaceLayout.packages, deliveryMode, bundledDigests);
+            const resolved = await resolveOnePluginRef(pluginRefId, workspaceLayout.root, deliveryMode, bundledDigests);
             if (!resolved.ok)
                 return resolved;
             sections.push(resolved.section);
@@ -41,10 +45,10 @@ function buildModule(ports) {
         return (`Agent Plugin '${pluginRefId}' is installed in this workspace but is not enabled — it ships with ${ports.productName} and ` +
             "stays inactive until an operator turns it on. Enable it before pinning it to a run.");
     }
-    async function listInstalledPlugins(packagesDir) {
-        let entries;
+    async function listInstalledPlugins(workspaceRoot) {
+        let folders;
         try {
-            entries = await readdir(packagesDir);
+            folders = await readdir(workspaceRoot, { withFileTypes: true });
         }
         catch (error) {
             if (isEnoent(error))
@@ -52,13 +56,30 @@ function buildModule(ports) {
             throw error;
         }
         const installed = [];
-        for (const digest of entries) {
-            if (!SHA256_DIGEST_DIRNAME_PATTERN.test(digest))
+        for (const folder of folders) {
+            if (!folder.isDirectory() || !/^[a-z0-9]+(?:[-.][a-z0-9]+)*$/.test(folder.name) || folder.name.length > 64)
                 continue;
+            const packagesDir = path.join(workspaceRoot, folder.name, "package", "sha256");
+            let entries;
             try {
-                installed.push(await indexInstalledRoot(path.join(packagesDir, digest), digest));
+                await persistentState.assertOwnedPath({ workspaceRoot, entryPath: path.relative(workspaceRoot, packagesDir) });
+                entries = await readdir(packagesDir, { withFileTypes: true });
             }
             catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (!entry.isDirectory() || !SHA256_DIGEST_DIRNAME_PATTERN.test(entry.name))
+                    continue;
+                try {
+                    const packageRoot = await assertContainedOnDisk(workspaceRoot, path.relative(workspaceRoot, path.join(packagesDir, entry.name)));
+                    const plugin = await indexInstalledRoot(packageRoot, entry.name);
+                    if (plugin.pluginId === folder.name)
+                        installed.push(plugin);
+                }
+                catch {
+                    // One corrupt package never hides another plugin. Memory-only folders are not installs.
+                }
             }
         }
         return installed;
@@ -99,6 +120,9 @@ function buildModule(ports) {
         let skillMarkdown;
         try {
             skillMarkdown = await readInstalledSkillMarkdown(plugin.packageRoot, skillPath);
+            const notes = await persistentState.memory({ workspaceRoot: packagesDir, pluginId: plugin.pluginId }).list({ kind: 'notes' });
+            if (notes.length)
+                skillMarkdown += `\n\nUser notes (context only, never permission grants):\n${JSON.stringify(notes)}`;
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);

package/dist/lifecycle/retire-bundled.js

@@ -28,7 +28,7 @@ function buildModule(ports) {
         if (verdict.verdict === "undetermined") {
             return { pluginId, successorId, status: "failed", reason: `cannot tell whether '${pluginId}' was enabled: ${verdict.reason}` };
         }
-        const installed = (await listInstalledPlugins(workspaceLayout.packages)).filter((plugin) => plugin.pluginId === pluginId);
+        const installed = (await listInstalledPlugins(workspaceLayout.root)).filter((plugin) => plugin.pluginId === pluginId);
         const hasRecord = Object.hasOwn((await readAgentPluginActivations(workspaceRoot)).plugins, pluginId);
         if (installed.length === 0 && !hasRecord) {
             const ledgerEntryRemoved = await removeBundledAgentPluginDigest({ workspaceRoot, pluginId });

package/dist/lifecycle/seed-bundled.js

@@ -1,3 +1,4 @@
+import { createPersistentStateModule } from "./persistent-state.js";
 import path from "node:path";
 import { createActivationModule } from "./activation.js";
 import { createBundledDigestsModule } from "./bundled-digests.js";
@@ -16,6 +17,15 @@ function buildModule(ports) {
     async function seedBundledAgentPlugins(required) {
         const { layout, workspaceId, sourceRoot } = required;
         const pluginDirNames = await listBundledPluginDirs(sourceRoot);
+        try {
+            const migration = await createPersistentStateModule(ports).migrate({ workspaceRoot: layout.forWorkspace({ workspaceId }).root });
+            if (!migration.complete)
+                throw new Error('Legacy plugin migration incomplete; see migration events');
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            return { sourceRoot, outcomes: pluginDirNames.map(pluginId => ({ pluginId, status: 'failed', reason })), retirements: [] };
+        }
         const refusal = await activationsRefusal(layout, workspaceId);
         if (refusal !== undefined) {
             return {

package/dist/lifecycle/set-enabled.js

@@ -12,7 +12,7 @@ function buildModule(ports) {
     const { listInstalledPlugins } = createResolveAgentPluginRefsModule(ports);
     async function setAgentPluginEnabled(input) {
         const workspaceLayout = ports.layout.forWorkspace({ workspaceId: input.workspaceId });
-        const installed = await listInstalledPlugins(workspaceLayout.packages);
+        const installed = await listInstalledPlugins(workspaceLayout.root);
         if (!installed.some((plugin) => plugin.pluginId === input.pluginId)) {
             throw new AgentPluginNotInstalledError({ pluginId: input.pluginId });
         }

package/dist/lifecycle/trusted-plugin-files.js

@@ -15,7 +15,7 @@ function buildModule(ports) {
     async function findTrustedPluginPackages(query) {
         const layout = ports.layout.forWorkspace({ workspaceId: query.workspaceId });
         const bundled = await readBundledAgentPluginDigests(layout.root);
-        const preferred = preferBundledAgentPluginDigests(await listInstalledPlugins(layout.packages), bundled);
+        const preferred = preferBundledAgentPluginDigests(await listInstalledPlugins(layout.root), bundled);
         const installed = query.orderByPluginId ? [...preferred].sort((a, b) => a.pluginId.localeCompare(b.pluginId)) : preferred;
         const verdicts = [];
         for (const plugin of installed) {

package/dist/lifecycle/uninstall.d.ts

@@ -22,6 +22,7 @@ export interface UninstallAgentPluginRequired {
 }
 export interface UninstallAgentPluginOptional {
     readonly confirmedPreview?: (AgentPluginUninstallPreview) | undefined;
+    readonly deleteMemory?: boolean | undefined;
     readonly retiredBundled?: (boolean) | undefined;
 }
 export interface UninstallAgentPluginResult {

package/dist/lifecycle/uninstall.js

@@ -1,4 +1,6 @@
+import { createPersistentStateModule } from "./persistent-state.js";
 import path from "node:path";
+import { createPackagePathsModule } from "./package-paths.js";
 import { createActivationModule } from "./activation.js";
 import { createResolveAgentPluginRefsModule } from "./resolve-agent-plugin-refs.js";
 export class AgentPluginNotFoundError extends Error {
@@ -12,6 +14,8 @@ export class AgentPluginChangedSincePreviewError extends Error {
 }
 function buildModule(ports) {
     const randomUUID = () => ports.ids.newId();
+    const { assertContainedOnDisk } = createPackagePathsModule(ports);
+    const rmdir = ports.filesystem.rmdir.bind(ports.filesystem);
     const chmod = ports.filesystem.chmod.bind(ports.filesystem);
     const readdir = ports.filesystem.readdir.bind(ports.filesystem);
     const rename = ports.filesystem.rename.bind(ports.filesystem);
@@ -26,8 +30,16 @@ function buildModule(ports) {
         return { pluginId: required.pluginId, versions, archiveDigests: matches.map((plugin) => plugin.archiveDigest) };
     }
     async function uninstallAgentPlugin(required, optional = {}) {
+        const workspaceRoot = required.layout.forWorkspace({ workspaceId: required.workspaceId }).root;
+        return createPersistentStateModule(ports).withPluginLock({ workspaceRoot, pluginId: required.pluginId,
+            run: () => uninstallAgentPluginUnlocked(required, optional) });
+    }
+    async function uninstallAgentPluginUnlocked(required, optional = {}) {
         const { workspaceRoot, packagesDir, matches } = await resolveUninstallTargets(required, optional.retiredBundled === true);
         assertUnchangedSincePreview(required.pluginId, optional.confirmedPreview, matches);
+        if (optional.deleteMemory && (!optional.confirmedPreview || optional.confirmedPreview.pluginId !== required.pluginId)) {
+            throw new Error('Deleting persistent plugin state requires a confirmed preview');
+        }
         const staged = [];
         try {
             for (const plugin of matches) {
@@ -41,6 +53,22 @@ function buildModule(ports) {
         for (const tree of staged) {
             await removeFrozenPackageTree(tree.quarantined);
         }
+        for (const directory of [packagesDir, path.dirname(packagesDir)]) {
+            try {
+                await rmdir(directory);
+            }
+            catch (error) {
+                if (!error || typeof error !== 'object' || !('code' in error) || !['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(String(error.code)))
+                    throw error;
+            }
+        }
+        if (optional.deleteMemory) {
+            const pluginRoot = required.layout.forWorkspace({ workspaceId: required.workspaceId }).pluginRootDir({ pluginId: required.pluginId });
+            await assertContainedOnDisk(workspaceRoot, path.relative(workspaceRoot, pluginRoot));
+            if ((await listInstalledPlugins(workspaceRoot)).some(plugin => plugin.pluginId === required.pluginId))
+                throw new Error('Plugin was reinstalled; persistent state was kept');
+            await rm(pluginRoot, { recursive: true, force: true });
+        }
         return { pluginId: required.pluginId, removedDigests: matches.map((plugin) => plugin.archiveDigest) };
     }
     function assertUnchangedSincePreview(pluginId, confirmedPreview, matches) {
@@ -86,7 +114,7 @@ function buildModule(ports) {
     async function resolveUninstallTargets(required, retiredBundled = false) {
         const { layout, workspaceId, pluginId } = required;
         const workspaceLayout = layout.forWorkspace({ workspaceId });
-        const installed = await listInstalledPlugins(workspaceLayout.packages);
+        const installed = await listInstalledPlugins(workspaceLayout.root);
         const matches = installed.filter((plugin) => plugin.pluginId === pluginId);
         if (matches.length === 0) {
             throw new AgentPluginNotFoundError({ message: `Agent Plugin '${pluginId}' is not installed in this workspace — nothing to uninstall` });
@@ -97,7 +125,7 @@ function buildModule(ports) {
         if ((await resolveAgentPluginActivation(workspaceLayout.root, pluginId)).verdict === "undetermined") {
             throw new AgentPluginNotUninstallableError({ message: malformedEntryRefusalMessage(pluginId) });
         }
-        return { workspaceRoot: workspaceLayout.root, packagesDir: workspaceLayout.packages, matches };
+        return { workspaceRoot: workspaceLayout.root, packagesDir: workspaceLayout.pluginPackagesDir({ pluginId }), matches };
     }
     function bundledRefusalMessage(pluginId) {
         return (`Agent Plugin '${pluginId}' is bundled with ${ports.productName} and cannot be uninstalled — it is re-seeded on every boot ` +

package/dist/lifecycle/yauzl-archive-reader.js

@@ -30,14 +30,15 @@ export function createYauzlAgentPluginArchiveReader({ yauzl }) {
                      * module's header. `install.ts` rejects every symlink entry unconditionally.
                      */
                     const unixMode = readUnixMode(entry);
-                    if (entry.fileName.endsWith("/")) {
-                        yield { kind: "directory", entryPath: entry.fileName };
-                        continue;
-                    }
                     if (unixMode !== null && (unixMode & S_IFMT) === S_IFLNK) {
                         yield { kind: "symlink", entryPath: entry.fileName };
                         continue;
                     }
+                    // File mode defines links even when a hostile filename masquerades as a directory.
+                    if (entry.fileName.endsWith("/")) {
+                        yield { kind: "directory", entryPath: entry.fileName };
+                        continue;
+                    }
                     yield {
                         kind: "file",
                         entryPath: entry.fileName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/agent-plugins",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Support for Agent Plugins, the open, vendor-neutral spec (v1.0.0, published 2026-08-06, Technical Steering Committee with maintainers from Amazon, Cursor, Google, Microsoft, OpenAI, and Vercel) for bundling Agent Skills and MCP servers into one portable directory: PluginManifest/McpManifest types + structural validators on the package root, plus the bundled plugins themselves, each on a subpath named for itself (./ui-ux-design). Extracted 2026-08-18 from @jini-ai/plugins, which now only reserves the unrelated, unimplemented ./host format.",
   "license": "Apache-2.0",
   "repository": {
@@ -18,7 +18,8 @@
       "./lifecycle": "node",
       "./lifecycle/node": "node",
       "./lifecycle/yauzl": "node",
-      "./manifest": "universal"
+      "./manifest": "universal",
+      "./persistent-state": "node"
     }
   },
   "type": "module",
@@ -49,6 +50,11 @@
       "types": "./dist/lifecycle/manifest.d.ts",
       "import": "./dist/lifecycle/manifest.js",
       "default": "./dist/lifecycle/manifest.js"
+    },
+    "./persistent-state": {
+      "types": "./persistent-state.d.ts",
+      "import": "./persistent-state.js",
+      "default": "./persistent-state.js"
     }
   },
   "files": [
@@ -61,7 +67,9 @@
     "!dist/**/*.test.d.ts",
     "!dist/**/*.test.js.map",
     "!dist/**/*.test.d.ts.map",
-    "!dist/**/__tests__/**"
+    "!dist/**/__tests__/**",
+    "persistent-state.js",
+    "persistent-state.d.ts"
   ],
   "publishConfig": {
     "access": "public",

package/persistent-state.d.ts

@@ -0,0 +1,25 @@
+export type PluginMemoryKind = 'learned' | 'notes';
+export interface PluginStatePaths { root: string; packages: string; data: string; learned: string; notes: string; }
+export const DEFAULT_PLUGIN_MEMORY_LIMITS: Readonly<{ learned: number; notes: number; files: number }>;
+export interface PluginStateEffects {
+  filesystem: Pick<typeof import('node:fs/promises'), 'mkdir' | 'rmdir' | 'readdir' | 'open' | 'readFile' | 'rename' | 'rm' | 'stat' | 'chmod' | 'realpath'>;
+  contain(required: { root: string; entryPath: string }): Promise<string>;
+  withLock<T>(required: { lockPath: string; run(): Promise<T> }): Promise<T>;
+}
+export interface PluginMemoryFile { relativePath: string; text: string; }
+export interface PluginMemory {
+  list(required: { kind: PluginMemoryKind }, optional?: {}): Promise<PluginMemoryFile[]>;
+  read(required: { kind: PluginMemoryKind; entryPath: string }, optional?: {}): Promise<string>;
+  writeNote(required: { entryPath: string; text: string }, optional?: {}): Promise<{ relativePath: string; bytes: number }>;
+  learned: {
+    read(required: { entryPath: string }, optional?: {}): Promise<string>;
+    write(required: { entryPath: string; text: string }, optional?: {}): Promise<{ relativePath: string; bytes: number }>;
+  };
+}
+export function pluginStatePaths(required: { workspaceRoot: string; pluginId: string }, optional?: {}): PluginStatePaths;
+export function createPluginMemory(required: PluginStateEffects & { workspaceRoot: string; pluginId: string }, optional?: { limits?: Partial<typeof DEFAULT_PLUGIN_MEMORY_LIMITS> }): PluginMemory;
+export function migratePluginLayout(required: PluginStateEffects & { workspaceRoot: string; parsePluginId(required: { value: unknown }): string; onEvent?(required: { event: string; message: string }): void }, optional?: {}): Promise<{ complete: boolean; moved: number }>;
+
+export function assertPluginStatePath(required: Pick<PluginStateEffects, "filesystem" | "contain"> & { workspaceRoot: string; entryPath: string }, optional?: {}): Promise<string>;
+
+export function withPluginStateLock<T>(required: PluginStateEffects & { workspaceRoot: string; pluginId: string; run(): Promise<T> }, optional?: {}): Promise<T>;

package/persistent-state.js

@@ -0,0 +1,260 @@
+/** Build-free Node entry: effects and policy belong to the host; no product namespaces here. */
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const SAFE_ID = /^[a-z0-9]+(?:[-.][a-z0-9]+)*$/;
+const DIGEST = /^[a-f0-9]{64}$/;
+export const DEFAULT_PLUGIN_MEMORY_LIMITS = Object.freeze({ learned: 1024 * 1024, notes: 16 * 1024, files: 128 });
+export function pluginStatePaths({ workspaceRoot, pluginId }, _optional = {}) {
+  if (!path.isAbsolute(workspaceRoot) || !SAFE_ID.test(pluginId) || pluginId.length > 64 || ['staging', 'packages', 'memory', 'data'].includes(pluginId)) throw new Error('Invalid plugin state root or id');
+  const root = path.join(workspaceRoot, pluginId);
+  return { root, packages: path.join(root, 'package', 'sha256'), data: path.join(root, 'data'),
+    learned: path.join(root, 'memory', 'learned'), notes: path.join(root, 'memory', 'notes') };
+}
+/** Containment plus ownership: a sibling plugin inside the workspace is still outside this one. */
+export async function assertPluginStatePath({ filesystem: fs, contain, workspaceRoot, entryPath }, _optional = {}) {
+  const absolute = await contain({ root: workspaceRoot, entryPath });
+  const realWorkspace = await fs.realpath(workspaceRoot);
+  const relative = path.relative(realWorkspace, absolute);
+  let current = realWorkspace;
+  for (const segment of relative.split(path.sep)) {
+    current = path.join(current, segment);
+    try { if (await fs.realpath(current) !== current) throw new Error('Plugin state ancestors must not be symlinks'); }
+    catch (error) { if (code(error) === 'ENOENT') break; throw error; }
+  }
+  return absolute;
+}
+function code(error) { return error && typeof error === 'object' ? error.code : undefined; }
+
+/** Lock files are workspace scratch so uninstall cannot delete a lock another process holds. */
+export async function withPluginStateLock({ filesystem: fs, contain, workspaceRoot, pluginId, withLock, run }, _optional = {}) {
+  pluginStatePaths({ workspaceRoot, pluginId });
+  await fs.mkdir(workspaceRoot, { recursive: true, mode: 0o700 });
+  const lockPath = await assertPluginStatePath({ filesystem: fs, contain, workspaceRoot, entryPath: `staging/.plugin-state-${pluginId}.lock` });
+  return withLock({ lockPath, run });
+}
+/** Each instance is bound to one plugin. No read/write method accepts an id or arbitrary root. */
+export function createPluginMemory({ filesystem: fs, contain, workspaceRoot, pluginId, withLock }, optional = {}) {
+  const paths = pluginStatePaths({ workspaceRoot, pluginId });
+  const limits = { ...DEFAULT_PLUGIN_MEMORY_LIMITS, ...optional.limits };
+  for (const kind of ['learned', 'notes', 'files']) {
+    if (!Number.isSafeInteger(limits[kind]) || limits[kind] <= 0 || limits[kind] > DEFAULT_PLUGIN_MEMORY_LIMITS[kind]) throw new Error('Memory caps must be positive and cannot exceed host ceilings');
+  }
+  function checkKind(kind) { if (kind !== 'learned' && kind !== 'notes') throw new Error('Invalid memory kind'); }
+  async function root(kind, create = false) {
+    checkKind(kind);
+    if (create) await fs.mkdir(workspaceRoot, { recursive: true, mode: 0o700 });
+    await assertPluginStatePath({ filesystem: fs, contain, workspaceRoot, entryPath: path.relative(workspaceRoot, paths[kind]) });
+    if (create) await fs.mkdir(paths[kind], { recursive: true, mode: 0o700 });
+    return paths[kind];
+  }
+  async function readText(filename, cap) {
+    // A bounded read protects against a concurrent file growing after stat. Invalid UTF-8 is refused.
+    const handle = await fs.open(filename, 'r');
+    try {
+      if (!(await handle.stat()).isFile()) throw new Error('Memory must contain regular UTF-8 files');
+      const bytes = Buffer.alloc(cap + 1);
+      let size = 0;
+      while (size < bytes.length) {
+        const result = await handle.read(bytes, size, bytes.length - size, size);
+        if (result.bytesRead === 0) break;
+        size += result.bytesRead;
+      }
+      if (size > cap) throw new Error('Memory byte cap exceeded');
+      const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, size));
+      if (text.includes('\0')) throw new Error('Memory must be UTF-8 text');
+      return text;
+    } finally { await handle.close(); }
+  }
+  async function list({ kind }, _optional = {}) {
+    const base = await root(kind).catch(error => { if (code(error) === 'ENOENT') return undefined; throw error; });
+    if (!base) return [];
+    const files = [];
+    let total = 0, entriesSeen = 0;
+    async function walk(prefix) {
+      let entries;
+      try { entries = await fs.readdir(path.join(base, prefix), { withFileTypes: true }); }
+      catch (error) { if (code(error) === 'ENOENT' && prefix === '') return; throw error; }
+      for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (++entriesSeen > limits.files * 4) throw new Error('Memory entry cap exceeded');
+        const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+        const filename = await contain({ root: base, entryPath: relativePath });
+        if (entry.isDirectory()) await walk(relativePath);
+        else if (entry.isFile()) {
+          if (files.length >= limits.files) throw new Error('Memory file cap exceeded');
+          const text = await readText(filename, limits[kind] - total);
+          total += Buffer.byteLength(text, 'utf8');
+          files.push({ relativePath, text });
+        } else throw new Error('Memory symlinks and special files are refused');
+      }
+    }
+    await walk('');
+    return files;
+  }
+  async function read({ kind, entryPath }, _optional = {}) {
+    const base = await root(kind);
+    return readText(await contain({ root: base, entryPath }), limits[kind]);
+  }
+  async function write({ kind, entryPath, text }, _optional = {}) {
+    checkKind(kind);
+    if (typeof text !== 'string' || text.includes('\0') || Buffer.from(text, 'utf8').toString('utf8') !== text) throw new Error('Memory must be valid UTF-8 text');
+    if (Buffer.byteLength(text, 'utf8') > limits[kind]) throw new Error('Memory byte cap exceeded');
+    // The same lock protects total-size accounting for all processes using this plugin.
+    return withPluginStateLock({ filesystem: fs, contain, workspaceRoot, pluginId, withLock, run: async () => {
+      const base = await root(kind, true);
+      const destination = await contain({ root: base, entryPath });
+      const normalized = path.relative(base, destination).split(path.sep).join('/');
+      const files = await list({ kind });
+      const existing = files.find(file => file.relativePath === normalized);
+      const total = files.reduce((sum, file) => sum + Buffer.byteLength(file.text, 'utf8'), 0);
+      if ((!existing && files.length >= limits.files) || total - Buffer.byteLength(existing?.text ?? '', 'utf8') + Buffer.byteLength(text, 'utf8') > limits[kind]) throw new Error('Memory cap exceeded');
+      await fs.mkdir(path.dirname(destination), { recursive: true, mode: 0o700 });
+      await contain({ root: base, entryPath });
+      const temporary = path.join(path.dirname(destination), `.memory-${randomUUID()}.tmp`);
+      const handle = await fs.open(temporary, 'wx', 0o600);
+      try {
+        try { await handle.writeFile(text, 'utf8'); await handle.sync(); } finally { await handle.close(); }
+        await fs.rename(temporary, destination);
+      } finally { await fs.rm(temporary, { force: true }); }
+      return { relativePath: normalized, bytes: Buffer.byteLength(text, 'utf8') };
+    } });
+  }
+  // The plugin-facing capability has no notes writer, even if an input tries to supply kind/id.
+  return { list, read, writeNote: ({ entryPath, text }, optional = {}) => write({ kind: 'notes', entryPath, text }, optional),
+    learned: { read: ({ entryPath }, optional = {}) => read({ kind: 'learned', entryPath }, optional),
+      write: ({ entryPath, text }, optional = {}) => write({ kind: 'learned', entryPath, text }, optional) } };
+}
+
+/** Interrupted moves are resumable; refused legacy entries are kept in quarantine and reported. */
+export async function migratePluginLayout({ filesystem: fs, contain, workspaceRoot, parsePluginId, withLock, onEvent }, _optional = {}) {
+  await fs.mkdir(workspaceRoot, { recursive: true, mode: 0o700 });
+  // Containment returns canonical paths; relative moves must use the same root (e.g. /var -> /private/var).
+  workspaceRoot = await fs.realpath(workspaceRoot);
+  const marker = path.join(workspaceRoot, '.agent-plugin-layout-migrated');
+  const emit = (event, message) => onEvent?.({ event, message });
+  return withLock({ lockPath: `${marker}.lock`, run: async () => {
+    await assertPluginStatePath({ filesystem: fs, contain, workspaceRoot, entryPath: path.basename(marker) });
+    try { if (JSON.parse(await fs.readFile(marker, 'utf8')).layoutVersion === 2) return { complete: true, moved: 0 }; }
+    catch (error) { if (code(error) !== 'ENOENT') emit('migration-marker-invalid', String(error)); }
+    let complete = true, moved = 0;
+    let quarantineRoot;
+    async function entries(directory) {
+      try { return await fs.readdir(directory, { withFileTypes: true }); }
+      catch (error) { if (code(error) === 'ENOENT') return []; throw error; }
+    }
+    async function renameEntry({ source, destination, frozen }, _optional = {}) {
+      await fs.mkdir(path.dirname(destination), { recursive: true, mode: 0o700 });
+      const mode = frozen ? (await fs.stat(source)).mode & 0o777 : undefined;
+      if (frozen) await fs.chmod(source, mode | 0o700);
+      try { await fs.rename(source, destination); }
+      catch (error) { if (frozen) await fs.chmod(source, mode).catch(() => undefined); throw error; }
+      if (frozen) await fs.chmod(destination, mode);
+    }
+    async function quarantine({ source, reason, frozen = false }, _optional = {}) {
+      // Validate ancestors, then rename the entry itself: even an unsafe symlink is preserved,
+      // never followed into another plugin or outside the workspace.
+      await assertPluginStatePath({ filesystem: fs, contain, workspaceRoot, entryPath: path.relative(workspaceRoot, path.dirname(source)) });
+      if (!quarantineRoot) {
+        const base = await assertPluginStatePath({ filesystem: fs, contain, workspaceRoot, entryPath: 'staging/legacy-quarantine' });
+        await fs.mkdir(base, { recursive: true, mode: 0o700 });
+        const candidate = path.join(base, `${new Date().toISOString().replaceAll(':', '-')}-${randomUUID()}`);
+        // Exclusive creation prevents a retry or another boot from overwriting saved bytes.
+        await fs.mkdir(candidate, { mode: 0o700 });
+        quarantineRoot = candidate;
+      }
+      const destinationParent = await assertPluginStatePath({ filesystem: fs, contain, workspaceRoot,
+        entryPath: path.relative(workspaceRoot, path.join(quarantineRoot, path.relative(workspaceRoot, path.dirname(source)))) });
+      // Keep the native directory-entry name verbatim, even if it is not a valid portable package
+      // path (e.g. a literal backslash on POSIX). The fresh quarantine tree has no existing leaf.
+      const destination = path.join(destinationParent, path.basename(source));
+      await renameEntry({ source, destination, frozen });
+      emit('migration-quarantined', `${source} -> ${destination}: ${reason}`);
+    }
+    async function move(source, destination, frozen = false) {
+      await contain({ root: workspaceRoot, entryPath: path.relative(workspaceRoot, source) });
+      await assertPluginStatePath({ filesystem: fs, contain, workspaceRoot, entryPath: path.relative(workspaceRoot, destination) });
+      let exists = false;
+      try { await fs.stat(destination); exists = true; }
+      catch (error) { if (code(error) !== 'ENOENT') throw error; }
+      if (exists) {
+        // The Layout B copy wins. This runs under the plugin lock, so no in-flight move is discarded.
+        await quarantine({ source, frozen, reason: 'Migration destination already exists; Layout B copy kept' });
+        return;
+      }
+      await renameEntry({ source, destination, frozen });
+      moved++;
+      emit('migration-moved', `${source} -> ${destination}`);
+    }
+    const oldPackages = path.join(workspaceRoot, 'packages', 'sha256');
+    for (const entry of await entries(oldPackages)) {
+      const source = path.join(oldPackages, entry.name);
+      try {
+        if (!DIGEST.test(entry.name) || !entry.isDirectory()) {
+          await quarantine({ source, frozen: entry.isDirectory(), reason: 'Unrecognized legacy package entry' });
+          continue;
+        }
+        let pluginId, paths;
+        try {
+          await contain({ root: workspaceRoot, entryPath: `packages/sha256/${entry.name}` });
+          const manifestPath = await contain({ root: source, entryPath: 'plugin.json' });
+          pluginId = parsePluginId({ value: JSON.parse(await fs.readFile(manifestPath, 'utf8')) });
+          paths = pluginStatePaths({ workspaceRoot, pluginId });
+        } catch (error) {
+          // Missing/invalid manifests are refused entries; filesystem failures remain resumable.
+          if (code(error) && !['ENOENT', 'EISDIR'].includes(code(error))) throw error;
+          await quarantine({ source, frozen: true, reason: String(error) });
+          continue;
+        }
+        await withPluginStateLock({ filesystem: fs, contain, workspaceRoot, pluginId, withLock, run: () => move(source, path.join(paths.packages, entry.name), true) });
+      } catch (error) { complete = false; emit('migration-failed', `${entry.name}: ${String(error)}`); }
+    }
+    // Layout A memory and PLUGIN_DATA may exist without an installed package; migrate them too.
+    for (const bucket of ['memory', 'data']) {
+      for (const entry of await entries(path.join(workspaceRoot, bucket))) {
+        const source = path.join(workspaceRoot, bucket, entry.name);
+        try {
+          if (!entry.isDirectory()) {
+            await quarantine({ source, reason: 'Legacy state is not a directory' });
+            continue;
+          }
+          let paths;
+          try { paths = pluginStatePaths({ workspaceRoot, pluginId: entry.name }); }
+          catch (error) { await quarantine({ source, reason: String(error) }); continue; }
+          await withPluginStateLock({ filesystem: fs, contain, workspaceRoot, pluginId: entry.name, withLock, run: () => move(source, bucket === 'data' ? paths.data : path.join(paths.root, 'memory')) });
+        } catch (error) { complete = false; emit('migration-failed', `${bucket}/${entry.name}: ${String(error)}`); }
+      }
+    }
+    for (const folder of await entries(workspaceRoot)) {
+      if (!folder.isDirectory() || !SAFE_ID.test(folder.name) || ['staging', 'packages', 'memory', 'data'].includes(folder.name)) continue;
+      try {
+        await withPluginStateLock({ filesystem: fs, contain, workspaceRoot, pluginId: folder.name, withLock, run: async () => {
+          const paths = pluginStatePaths({ workspaceRoot, pluginId: folder.name });
+          await assertPluginStatePath({ filesystem: fs, contain, workspaceRoot, entryPath: path.relative(workspaceRoot, paths.packages) });
+          const digests = (await entries(paths.packages)).filter(digest => digest.isDirectory() && DIGEST.test(digest.name));
+          for (const digest of digests) {
+            const packageRoot = await assertPluginStatePath({ filesystem: fs, contain, workspaceRoot, entryPath: path.relative(workspaceRoot, path.join(paths.packages, digest.name)) });
+            // Legacy install froze every package; a crash after rename can leave only its root writable.
+            await fs.chmod(packageRoot, 0o555);
+          }
+          // Wait until legacy memory/data moves have finished before creating destinations for them.
+          if (complete && digests.length) for (const directory of [paths.learned, paths.notes, paths.data]) {
+            await assertPluginStatePath({ filesystem: fs, contain, workspaceRoot, entryPath: path.relative(workspaceRoot, directory) });
+            await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+          }
+        } });
+      } catch (error) { complete = false; emit('migration-failed', `${folder.name}: ${String(error)}`); }
+    }
+    if (complete) {
+      for (const directory of [oldPackages, path.dirname(oldPackages), path.join(workspaceRoot, 'memory'), path.join(workspaceRoot, 'data')]) {
+        try { await fs.rmdir(directory); } catch (error) { if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(code(error))) throw error; }
+      }
+      const temporary = `${marker}.${randomUUID()}.tmp`;
+      const handle = await fs.open(temporary, 'wx', 0o600);
+      try { await handle.writeFile(JSON.stringify({ layoutVersion: 2 }), 'utf8'); await handle.sync(); }
+      finally { await handle.close(); }
+      try { await fs.rename(temporary, marker); } finally { await fs.rm(temporary, { force: true }); }
+      emit('migration-complete', workspaceRoot);
+    }
+    return { complete, moved };
+  } });
+}