@frockbot/plugin-shell 0.3.9 → 0.3.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-shell",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "private": false,
   "type": "module",
   "exports": {
@@ -30,6 +30,7 @@
     "./frockbot.json": "./frockbot.json",
     "./host": "./src/host.ts",
     "./manifest": "./src/manifest.ts",
+    "./notification-id": "./src/notification-id.ts",
     "./package.json": "./package.json",
     "./run-cursor": "./src/run-cursor.ts",
     "./run-protocol": "./src/run-protocol.ts",
@@ -47,41 +48,41 @@
   },
   "dependencies": {
     "@cordisjs/plugin-webui": "0.8.2",
-    "@frockbot/agent-runtime": "0.3.9",
-    "@frockbot/application-foundation": "0.3.9",
-    "@frockbot/catalog-core": "0.3.9",
-    "@frockbot/client-core": "0.3.9",
-    "@frockbot/client-ui": "0.3.9",
-    "@frockbot/computer-core": "0.3.9",
-    "@frockbot/computer-host-protocol": "0.3.9",
-    "@frockbot/configuration-core": "0.3.9",
-    "@frockbot/connection-core": "0.3.9",
-    "@frockbot/kernel-agent-loop": "0.3.9",
-    "@frockbot/kernel-composition": "0.3.9",
-    "@frockbot/kernel-contracts": "0.3.9",
-    "@frockbot/kernel-do": "0.3.9",
-    "@frockbot/machine-protocol": "0.3.9",
-    "@frockbot/plugin-applets": "0.3.9",
-    "@frockbot/plugin-authoring": "0.3.9",
-    "@frockbot/plugin-bot-template": "0.3.9",
-    "@frockbot/plugin-computer": "0.3.9",
-    "@frockbot/plugin-flock": "0.3.9",
-    "@frockbot/plugin-image": "0.3.9",
-    "@frockbot/plugin-machine-messages": "0.3.9",
-    "@frockbot/plugin-mcp": "0.3.9",
-    "@frockbot/plugin-memory": "0.3.9",
-    "@frockbot/plugin-package-catalog": "0.3.9",
-    "@frockbot/plugin-routines": "0.3.9",
-    "@frockbot/plugin-skills": "0.3.9",
-    "@frockbot/plugin-subagents": "0.3.9",
-    "@frockbot/plugin-user-machine": "0.3.9",
-    "@frockbot/protocol": "0.3.9",
+    "@frockbot/agent-runtime": "0.3.10",
+    "@frockbot/application-foundation": "0.3.10",
+    "@frockbot/catalog-core": "0.3.10",
+    "@frockbot/client-core": "0.3.10",
+    "@frockbot/client-ui": "0.3.10",
+    "@frockbot/computer-core": "0.3.10",
+    "@frockbot/computer-host-protocol": "0.3.10",
+    "@frockbot/configuration-core": "0.3.10",
+    "@frockbot/connection-core": "0.3.10",
+    "@frockbot/kernel-agent-loop": "0.3.10",
+    "@frockbot/kernel-composition": "0.3.10",
+    "@frockbot/kernel-contracts": "0.3.10",
+    "@frockbot/kernel-do": "0.3.10",
+    "@frockbot/machine-protocol": "0.3.10",
+    "@frockbot/plugin-applets": "0.3.10",
+    "@frockbot/plugin-authoring": "0.3.10",
+    "@frockbot/plugin-bot-template": "0.3.10",
+    "@frockbot/plugin-computer": "0.3.10",
+    "@frockbot/plugin-flock": "0.3.10",
+    "@frockbot/plugin-image": "0.3.10",
+    "@frockbot/plugin-machine-messages": "0.3.10",
+    "@frockbot/plugin-mcp": "0.3.10",
+    "@frockbot/plugin-memory": "0.3.10",
+    "@frockbot/plugin-package-catalog": "0.3.10",
+    "@frockbot/plugin-routines": "0.3.10",
+    "@frockbot/plugin-skills": "0.3.10",
+    "@frockbot/plugin-subagents": "0.3.10",
+    "@frockbot/plugin-user-machine": "0.3.10",
+    "@frockbot/protocol": "0.3.10",
     "cordis": "4.0.0-rc.8",
     "vue": "3.5.41"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "latest",
-    "@frockbot/plugin-tools": "0.3.9",
+    "@frockbot/plugin-tools": "0.3.10",
     "@types/bun": "1.3.6",
     "@types/node": "26.2.0",
     "@vitejs/plugin-vue": "6.0.8",

package/src/backend-configuration.test.ts

@@ -600,8 +600,10 @@ describe("generic per-Turn model resolution", () => {
     });
     await expect(contribution.listNotifications()).resolves.toEqual([
       expect.objectContaining({
+        // Colons would fail the acknowledge decoder, so the mint replaces
+        // them; a notification nobody can acknowledge 400s forever.
         notificationId:
-          "package-connection-unavailable:run-1:bot-authored:flock-ai-ambient",
+          "package-connection-unavailable-run-1-bot-authored-flock-ai-ambient",
         title: "Connection unavailable",
       }),
     ]);

package/src/backend-package-catalog.ts

@@ -320,7 +320,7 @@ export function createPackageCatalogHost(
           change.action === "remove"
             ? change.input.packageId
             : change.input.catalogId,
-        ...(change.action === "remove"
+        ...(change.action === "remove" || change.input.contentHash === undefined
           ? {}
           : { contentHash: change.input.contentHash }),
       }),
@@ -520,9 +520,12 @@ export function createPackageCatalogHost(
           index,
           catalogId: provenance.catalogId,
         });
+        // A first-party member pins no bundle, so "the entry still offers
+        // what the target generation recorded" is the two hashes agreeing,
+        // both present or both absent.
         if (
-          !targetEntry?.bundle ||
-          targetEntry.bundle.contentHash !== provenance.contentHash
+          !targetEntry ||
+          targetEntry.bundle?.contentHash !== provenance.contentHash
         ) {
           return undoRefused(
             request,
@@ -538,7 +541,9 @@ export function createPackageCatalogHost(
           version: targetCatalogMember.version,
           catalogId: provenance.catalogId,
           catalogGeneration: provenance.catalogGeneration,
-          contentHash: provenance.contentHash,
+          ...(provenance.contentHash === undefined
+            ? {}
+            : { contentHash: provenance.contentHash }),
         };
       }
       const receipt = await options.user.execute(command);
@@ -673,17 +678,22 @@ export function createPackageCatalogHost(
           const resolved = await pinnedEntry(request.change.input.catalogId);
           user = resolved.user;
           entry = resolved.entry;
-          if (!entry.bundle) {
-            throw new Error(
-              `Catalog entry "${entry.catalogId}" does not carry installable code`,
-            );
-          }
-          if (entry.bundle.contentHash !== request.change.input.contentHash) {
+          // A first-party entry names reviewed compiled-in code and publishes
+          // no bundle: there is no artifact to verify and no hash to pin. The
+          // Plugins page has always installed such an entry; refusing it here
+          // is what made `package_install` by chat disagree with the UI (F4).
+          if (entry.bundle) {
+            if (entry.bundle.contentHash !== request.change.input.contentHash) {
+              throw new Error(
+                `Catalog entry "${entry.catalogId}" has content hash "${entry.bundle.contentHash}", not "${request.change.input.contentHash}"`,
+              );
+            }
+            await verifyArtifact(entry);
+          } else if (request.change.input.contentHash !== undefined) {
             throw new Error(
-              `Catalog entry "${entry.catalogId}" has content hash "${entry.bundle.contentHash}", not "${request.change.input.contentHash}"`,
+              `Catalog entry "${entry.catalogId}" does not carry a Package bundle`,
             );
           }
-          await verifyArtifact(entry);
           const member = base.members.find(
             (candidate) => candidate.packageId === entry.packageId,
           );
@@ -716,7 +726,7 @@ export function createPackageCatalogHost(
             version: entry.version,
             catalogId: entry.catalogId,
             catalogGeneration: resolved.generation,
-            contentHash: entry.bundle.contentHash,
+            ...(entry.bundle ? { contentHash: entry.bundle.contentHash } : {}),
             manifestHash: entry.manifestHash,
             summary:
               request.change.input.summary ??
@@ -744,16 +754,24 @@ export function createPackageCatalogHost(
       // Intent and manifest before the User settings effect. The manifest key
       // is the existing isolate loader seam used by authored Packages.
       if (!existingIntent) {
+        const bundle = entry.bundle;
         await options.storage.put({
           [packageCatalogChangeIntentKey(request.effectId)]: intent,
-          [authorshipManifestKey(intent.manifestHash)]: {
-            schemaVersion: 1,
-            manifestHash: intent.manifestHash,
-            packageId: intent.packageId,
-            version: intent.version,
-            manifest: entry.bundle!.manifest,
-            createdAt: intent.recordedAt,
-          } satisfies AuthoredManifestRecordV1,
+          // A bundle-less entry has no manifest document to store; the mount
+          // resolves it from the compiled-in application instead, still
+          // against the `manifestHash` the generation records.
+          ...(bundle
+            ? {
+                [authorshipManifestKey(intent.manifestHash)]: {
+                  schemaVersion: 1,
+                  manifestHash: intent.manifestHash,
+                  packageId: intent.packageId,
+                  version: intent.version,
+                  manifest: bundle.manifest,
+                  createdAt: intent.recordedAt,
+                } satisfies AuthoredManifestRecordV1,
+              }
+            : {}),
         });
         existingIntent = intent;
       }
@@ -776,7 +794,9 @@ export function createPackageCatalogHost(
               version: intent.version,
               catalogId: intent.catalogId,
               catalogGeneration: intent.catalogGeneration,
-              contentHash: intent.contentHash,
+              ...(intent.contentHash === undefined
+                ? {}
+                : { contentHash: intent.contentHash }),
             };
       const receipt = await options.user.execute(command);
       if (receipt.status === "rejected") {
@@ -789,7 +809,7 @@ export function createPackageCatalogHost(
         (member) => member.packageId !== intent.packageId,
       );
       if (action !== "remove") {
-        const bundle = entry.bundle!;
+        const bundle = entry.bundle;
         const member: CompositionMemberV1 = {
           packageId: entry.packageId,
           specifier: `catalog:${entry.catalogId}`,
@@ -801,14 +821,20 @@ export function createPackageCatalogHost(
             version: entry.version,
             catalogId: entry.catalogId,
             catalogGeneration: intent.catalogGeneration,
-            contentHash: bundle.contentHash,
-          },
-          artifact: {
-            contentHash: bundle.contentHash,
-            size: bundle.size,
-            mediaType: bundle.mediaType,
-            bundlerVersion: bundle.bundlerVersion,
+            ...(bundle ? { contentHash: bundle.contentHash } : {}),
           },
+          // No artifact ⇒ the member mounts in the kernel isolate from the
+          // compiled-in Package, exactly as the UI install records it.
+          ...(bundle
+            ? {
+                artifact: {
+                  contentHash: bundle.contentHash,
+                  size: bundle.size,
+                  mediaType: bundle.mediaType,
+                  bundlerVersion: bundle.bundlerVersion,
+                },
+              }
+            : {}),
         };
         members.push(member);
       }
@@ -850,7 +876,9 @@ export function createPackageCatalogHost(
         packageId: intent.packageId,
         displayName: intent.displayName,
         ...(action === "remove" ? {} : { version: intent.version }),
-        ...(action === "remove" ? {} : { contentHash: intent.contentHash }),
+        ...(action === "remove" || intent.contentHash === undefined
+          ? {}
+          : { contentHash: intent.contentHash }),
         generationId: generation.generationId,
         missingConnectionTypes: intent.missingConnectionTypes,
         recordedAt: intent.recordedAt,

package/src/backend.ts

@@ -415,6 +415,12 @@ import {
   type ClientRunV1,
   type ClientTurnV1,
 } from "./run-protocol.js";
+import { notificationIdV1 } from "./notification-id.js";
+import {
+  type CompositionManifestSourcesV1,
+  compositionMemberManifestDocumentV1,
+  compositionMemberManifestV1,
+} from "./composition-manifest.js";
 import {
   BOT_DEBUG_DEFAULT_RUN_LIMIT_V1,
   BOT_DEBUG_EVENT_BYTES_V1,
@@ -1233,15 +1239,44 @@ export class ShellBotBackendContribution {
     return { schemaVersion: 1, skills: entries };
   }
 
-  /** The one durable manifest lookup used by mounts, commands, and UI views. */
-  private async readCompositionMemberManifest(
+  /**
+   * The one durable manifest lookup used by mounts, commands, and UI views —
+   * as the **stored document**, byte-for-byte what `manifestHash` was taken
+   * over at authoring time.
+   *
+   * Decoding rebuilds the object (`decodeV5` always writes a `configuration`
+   * key, for one), so a decoded manifest does not canonicalize back to the
+   * recorded hash. Every mount re-verifies that hash
+   * (`botIsolatePackageDescriptorV1`), so the raw document is the only thing
+   * that can be handed to it; callers that want the typed shape decode it
+   * themselves through `readCompositionMemberManifest`.
+   */
+  private compositionManifestSources(): CompositionManifestSourcesV1 {
+    return {
+      stored: (manifestHash) =>
+        this.ctx.storage.get<AuthoredManifestRecordV1>(
+          authorshipManifestKey(manifestHash),
+        ),
+      application: (member) => this.readApplicationMemberManifest(member),
+    };
+  }
+
+  private readCompositionMemberManifestDocument(
+    member: CompositionMemberV1,
+  ): Promise<unknown | undefined> {
+    return compositionMemberManifestDocumentV1(
+      member,
+      this.compositionManifestSources(),
+    );
+  }
+
+  private readCompositionMemberManifest(
     member: CompositionMemberV1,
   ): Promise<FrockBotManifest | undefined> {
-    const stored = await this.ctx.storage.get<AuthoredManifestRecordV1>(
-      authorshipManifestKey(member.manifestHash),
+    return compositionMemberManifestV1(
+      member,
+      this.compositionManifestSources(),
     );
-    if (stored) return decodeFrockBotManifest(stored.manifest);
-    return await this.readApplicationMemberManifest(member);
   }
 
   /**
@@ -1270,6 +1305,19 @@ export class ShellBotBackendContribution {
     return declared.manifest;
   }
 
+  /** The stored manifest document a mount hashes, or a modelled failure. */
+  private async requireCompositionMemberManifestDocument(
+    member: CompositionMemberV1,
+  ): Promise<unknown> {
+    const document = await this.readCompositionMemberManifestDocument(member);
+    if (document === undefined) {
+      throw new Error(
+        `package "${member.packageId}" manifest "${member.manifestHash}" is unavailable`,
+      );
+    }
+    return document;
+  }
+
   private async requireCompositionMemberManifest(
     member: CompositionMemberV1,
   ): Promise<FrockBotManifest> {
@@ -1832,7 +1880,11 @@ export class ShellBotBackendContribution {
     fallback: CompositionGenerationV1,
   ): Promise<void> {
     await this.authority.recordNotification({
-      notificationId: `composition-failure:${failure.generationId}:${failure.attempt}`,
+      notificationId: notificationIdV1(
+        "composition-failure",
+        failure.generationId,
+        failure.attempt,
+      ),
       runId,
       createdAt: failure.at,
       title: `${settings.profile.name} kept its last working Packages`,
@@ -1883,7 +1935,8 @@ export class ShellBotBackendContribution {
         artifacts,
         this.bundledPackageArtifacts,
       ),
-      manifestFor: (member) => this.requireCompositionMemberManifest(member),
+      manifestFor: (member) =>
+        this.requireCompositionMemberManifestDocument(member),
       capabilitiesFor: (member) =>
         mintCapabilities({
           props: {
@@ -2692,7 +2745,12 @@ export class ShellBotBackendContribution {
     );
     if (!connection?.generation) {
       await this.authority.recordNotification({
-        notificationId: `package-connection-unavailable:${input.runId}:${input.packageId}:${input.request}`,
+        notificationId: notificationIdV1(
+          "package-connection-unavailable",
+          input.runId,
+          input.packageId,
+          input.request,
+        ),
         runId: input.runId,
         createdAt: new Date().toISOString(),
         title: "Connection unavailable",
@@ -2720,7 +2778,11 @@ export class ShellBotBackendContribution {
     }
     const request = decodeIsolateNotificationRequestV1(input.request);
     await this.authority.recordNotification({
-      notificationId: `package:${input.packageId}:${request.notificationId}`,
+      notificationId: notificationIdV1(
+        "package",
+        input.packageId,
+        request.notificationId,
+      ),
       runId: input.runId,
       createdAt: new Date().toISOString(),
       title: request.title,
@@ -3107,7 +3169,7 @@ export class ShellBotBackendContribution {
     await this.authority.recordNotification({
       // The same id shape the completion path uses, so one firing is one
       // intent however many times the alarm retries it.
-      notificationId: `routine-failed:${fire.fireId}`,
+      notificationId: notificationIdV1("routine-failed", fire.fireId),
       runId: fire.fireId,
       createdAt: new Date().toISOString(),
       title: `${settings.profile.name} could not run a Routine`,
@@ -3660,7 +3722,7 @@ export class ShellBotBackendContribution {
     }
     if (!settings.notifications.enabled) return;
     await this.authority.recordNotification({
-      notificationId: `task-settled:${task.taskId}`,
+      notificationId: notificationIdV1("task-settled", task.taskId),
       runId: task.taskId,
       createdAt: at,
       title: `${settings.profile.name} finished a subagent task`,
@@ -5464,7 +5526,7 @@ export class ShellBotBackendContribution {
       // `automation_completion_inbox` row".
       if (handoff === undefined) return undefined;
       return {
-        notificationId: `routine-wake:${result.runId}`,
+        notificationId: notificationIdV1("routine-wake", result.runId),
         runId: result.runId,
         createdAt: new Date().toISOString(),
         title: `${settings.profile.name} finished a Routine`,

package/src/client/index.ts

@@ -1228,6 +1228,7 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
       packageDisplayName: catalogPackage?.displayName,
       connectionDisplayName: connection?.displayName,
       failure: effective.binding?.failure,
+      fallback: Boolean(effective.fallback),
     });
   }
 

package/src/client/model-presentation.test.ts

@@ -35,6 +35,20 @@ describe("model runtime presentation", () => {
     );
   });
 
+  test("names the stand-in model when the chosen one is unavailable", () => {
+    // The Bot is answering, so the line is not a failure — it names the model
+    // actually in use and says the User's own choice is not it.
+    expect(
+      modelRuntimeLabel({
+        source: "platform",
+        modelDisplayName: "Auto",
+        providerModelId: "@flock/auto",
+        packageDisplayName: "Flock AI",
+        fallback: true,
+      }),
+    ).toBe("Auto · Flock AI · your chosen model is unavailable");
+  });
+
   test("shows unavailable and backend failure states", () => {
     expect(modelRuntimeLabel({ source: "none" })).toBe(
       "No model available — set one up in Models",

package/src/client/model-presentation.ts

@@ -11,6 +11,11 @@ export function modelRuntimeLabel(input: {
   packageDisplayName?: string;
   connectionDisplayName?: string;
   failure?: string;
+  /**
+   * The chosen model could not bind — its provider Package is off, or its
+   * Connection is gone — and the platform default is answering in its place.
+   */
+  fallback?: boolean;
 }): string {
   if (input.failure) return input.failure;
   if (input.source === "none" || !input.providerModelId) {
@@ -22,5 +27,6 @@ export function modelRuntimeLabel(input: {
   const runtime = provider ? `${model} · ${provider}` : model;
   if (input.source === "bot") return `${runtime} · this Bot only`;
   if (input.source === "account") return `${runtime} · Account model`;
+  if (input.fallback) return `${runtime} · your chosen model is unavailable`;
   return runtime;
 }

package/src/composition-manifest.test.ts

@@ -0,0 +1,126 @@
+// Every Bot-authored Package failed to mount with `package "aud-usd" stored
+// manifest failed hash verification`, deterministically, on byte-identical
+// source. The mount hashed a *decoded* manifest against a hash taken over the
+// *raw* one, so journey 4 step 2 — "use the tool you just built" — was
+// impossible for anybody. First-party members mounted fine, because their
+// reader already returned the raw document.
+import { describe, expect, test } from "bun:test";
+import { authoredManifestV1 } from "@frockbot/plugin-authoring/shared";
+import { decodeFrockBotManifest } from "@frockbot/kernel-composition";
+import type { CompositionMemberV1 } from "@frockbot/kernel-composition/generation";
+import { botIsolatePackageDescriptorV1 } from "@frockbot/kernel-composition/isolate";
+import { canonicalJson, sha256 } from "@frockbot/kernel-composition/compiler";
+
+import {
+  type CompositionManifestSourcesV1,
+  compositionMemberManifestDocumentV1,
+  compositionMemberManifestV1,
+} from "./composition-manifest.js";
+
+/** What `package_author` writes, exactly as `backend-authoring.ts` builds it. */
+function authoredManifest(): unknown {
+  return authoredManifestV1({
+    packageId: "aud-usd",
+    displayName: "AUD/USD",
+    version: "0.0.1",
+    tools: [
+      {
+        name: "aud_usd_rate",
+        description: "The current AUD/USD rate.",
+        inputSchema: { type: "object", properties: {} },
+      },
+    ],
+  });
+}
+
+/** The durable store, as `authorship:manifest:<hash>` holds it. */
+async function storedMember(): Promise<{
+  member: CompositionMemberV1;
+  manifest: unknown;
+  sources: CompositionManifestSourcesV1;
+}> {
+  const manifest = authoredManifest();
+  // The one hash that matters: taken over the raw document at authoring time.
+  const manifestHash = await sha256(canonicalJson(manifest));
+  const member: CompositionMemberV1 = {
+    packageId: "aud-usd",
+    specifier: "bot:aud-usd",
+    version: "0.0.1",
+    manifestHash,
+    provenance: {
+      kind: "bot",
+      packageId: "aud-usd",
+      version: "0.0.1",
+      botId: "toolsmith",
+      sessionId: "user-1:toolsmith",
+      turnId: "turn-1",
+      runId: "run-1",
+      authoredAt: "2026-09-03T23:49:00.416Z",
+    },
+    artifact: {
+      contentHash: "b".repeat(64),
+      size: 128,
+      mediaType: "application/javascript",
+      bundlerVersion: "worker-bundler@0.2.3",
+    },
+  };
+  const sources: CompositionManifestSourcesV1 = {
+    stored: (hash) =>
+      Promise.resolve(hash === manifestHash ? { manifest } : undefined),
+    application: () => Promise.resolve(undefined),
+  };
+  return { member, manifest, sources };
+}
+
+describe("the manifest a mount is handed", () => {
+  test("hashes to what the Composition member recorded", async () => {
+    const { member, sources } = await storedMember();
+
+    const document = await compositionMemberManifestDocumentV1(member, sources);
+    const descriptor = await botIsolatePackageDescriptorV1(member, document);
+
+    expect(descriptor.manifest.id).toBe("aud-usd");
+    expect(descriptor.manifest.version).toBe("0.0.1");
+  });
+
+  test("is the stored document, not a rebuild of it", async () => {
+    const { member, manifest, sources } = await storedMember();
+
+    const document = await compositionMemberManifestDocumentV1(member, sources);
+
+    expect(document).toBe(manifest);
+  });
+
+  test("decoding first is what broke it, and still would", async () => {
+    // The guard this test exists for. `decodeFrockBotManifest` rebuilds the
+    // object — `decodeV5` always writes a `configuration` key — so the decoded
+    // manifest does not canonicalize back to the recorded hash. If the reader
+    // ever decodes again, the test above fails and this one says why.
+    const { member, manifest } = await storedMember();
+    const decoded = decodeFrockBotManifest(manifest);
+
+    expect(canonicalJson(decoded)).not.toBe(canonicalJson(manifest));
+    await expect(
+      botIsolatePackageDescriptorV1(member, decoded),
+    ).rejects.toThrow("stored manifest failed hash verification");
+  });
+
+  test("the typed reader still answers the shape its callers want", async () => {
+    const { member, sources } = await storedMember();
+
+    const typed = await compositionMemberManifestV1(member, sources);
+
+    expect(typed?.id).toBe("aud-usd");
+    expect(typed?.version).toBe("0.0.1");
+  });
+
+  test("a member with no stored manifest falls back to the application's", async () => {
+    const { member, manifest } = await storedMember();
+    const document = await compositionMemberManifestDocumentV1(member, {
+      stored: () => Promise.resolve(undefined),
+      application: () => Promise.resolve(manifest),
+    });
+
+    expect(document).toBe(manifest);
+  });
+});

package/src/composition-manifest.ts

@@ -0,0 +1,55 @@
+import {
+  type FrockBotManifest,
+  decodeFrockBotManifest,
+} from "@frockbot/kernel-composition";
+import type { CompositionMemberV1 } from "@frockbot/kernel-composition/generation";
+
+/**
+ * Where a Composition member's manifest can be found. `stored` is
+ * `authorship:manifest:<hash>` — written by the authoring path and by a
+ * Catalog install, so it covers every member a Bot or its User put into the
+ * Composition. `application` is the compiled-in manifest of a first-party
+ * artifact-backed member (ADR 0022 decision 8), which came from neither and is
+ * already in this bundle. Two *places*, never two answers: the `manifestHash`
+ * decides in both.
+ */
+export interface CompositionManifestSourcesV1 {
+  stored(manifestHash: string): Promise<{ manifest: unknown } | undefined>;
+  application(member: CompositionMemberV1): Promise<unknown | undefined>;
+}
+
+/**
+ * A member's manifest **as the stored document** — byte-for-byte what its
+ * `manifestHash` was taken over.
+ *
+ * This is the seam that broke every Bot-authored Package. Authoring hashes
+ * `canonicalJson(rawManifest)` and stores `rawManifest` verbatim; the mount
+ * re-hashes whatever it is handed and refuses a mismatch
+ * (`botIsolatePackageDescriptorV1`). Returning a *decoded* manifest here put a
+ * rebuilt object on the mount's side of that comparison — `decodeV5` always
+ * writes a `configuration` key, among other things — so the two hashes could
+ * never agree, and every authored Package failed with `stored manifest failed
+ * hash verification` while first-party members (which were already read raw)
+ * mounted fine.
+ *
+ * Callers that want the typed shape decode it themselves, downstream of the
+ * hash check.
+ */
+export async function compositionMemberManifestDocumentV1(
+  member: CompositionMemberV1,
+  sources: CompositionManifestSourcesV1,
+): Promise<unknown | undefined> {
+  const stored = await sources.stored(member.manifestHash);
+  if (stored) return stored.manifest;
+  return await sources.application(member);
+}
+
+/** The same manifest as the typed shape, for readers that are not mounts. */
+export async function compositionMemberManifestV1(
+  member: CompositionMemberV1,
+  sources: CompositionManifestSourcesV1,
+): Promise<FrockBotManifest | undefined> {
+  const document = await compositionMemberManifestDocumentV1(member, sources);
+  if (document === undefined) return undefined;
+  return decodeFrockBotManifest(document);
+}

package/src/notification-id.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from "bun:test";
+
+import { notificationIdV1 } from "./notification-id.js";
+import { decodeClientNotificationAcknowledgementCommandV1 } from "./run-protocol.js";
+
+/** What the acknowledge endpoint does with an id a notification carried. */
+function acknowledge(notificationId: string): string {
+  return decodeClientNotificationAcknowledgementCommandV1({
+    schemaVersion: 1,
+    action: "acknowledge",
+    notificationId,
+  }).notificationId;
+}
+
+describe("notificationIdV1", () => {
+  test("a Composition failure id round-trips through acknowledgement", () => {
+    // The shape that 400'd forever: a generation id is `<ISO instant>:<hash>`,
+    // and the acknowledge decoder admits no colons.
+    const id = notificationIdV1(
+      "composition-failure",
+      "2026-09-03T23:49:00.416Z:dc03a32d9b717619",
+      1,
+    );
+    expect(id).not.toContain(":");
+    expect(acknowledge(id)).toBe(id);
+  });
+
+  test("every minted id shape acknowledges", () => {
+    const minted = [
+      notificationIdV1(
+        "package-connection-unavailable",
+        crypto.randomUUID(),
+        "aud-usd",
+        "gmail",
+      ),
+      notificationIdV1("package", "aud-usd", "rate:moved"),
+      notificationIdV1("routine-failed", "2026-09-03T23:49:00.416Z:fire"),
+      notificationIdV1("task-settled", crypto.randomUUID()),
+      notificationIdV1("routine-wake", crypto.randomUUID()),
+    ];
+    for (const id of minted) expect(acknowledge(id)).toBe(id);
+  });
+
+  test("the same parts mint the same id, so a retry is one intent", () => {
+    const parts = [
+      "composition-failure",
+      "2026-09-03T23:49:00.416Z:abc",
+      2,
+    ] as const;
+    expect(notificationIdV1(...parts)).toBe(notificationIdV1(...parts));
+  });
+
+  test("distinct parts stay distinct, even past the length ceiling", () => {
+    const long = "x".repeat(400);
+    const a = notificationIdV1("package", long, "one");
+    const b = notificationIdV1("package", long, "two");
+    expect(a).not.toBe(b);
+    expect(a.length).toBeLessThanOrEqual(128);
+    expect(acknowledge(a)).toBe(a);
+    expect(acknowledge(b)).toBe(b);
+  });
+
+  test("parts that sanitize to nothing still mint an acknowledgeable id", () => {
+    const id = notificationIdV1(":::", "::");
+    expect(acknowledge(id)).toBe(id);
+  });
+});

package/src/notification-id.ts

@@ -0,0 +1,58 @@
+import { isPublicIdentifier } from "@frockbot/configuration-core";
+
+/**
+ * The acknowledge decoder's ceiling: `isPublicIdentifier` admits a leading
+ * alphanumeric plus at most 127 more characters.
+ */
+const MAX_NOTIFICATION_ID_LENGTH = 128;
+
+/** How much of a folded id the digest suffix costs: `-` plus eight hex. */
+const DIGEST_SUFFIX_LENGTH = 9;
+
+/**
+ * A notification is only useful if it can be acknowledged, and acknowledgement
+ * decodes the id through `isPublicIdentifier`
+ * (`/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/`) — which admits no colons. Delivery
+ * only bounds the length, so an id minted by hand out of a generation id
+ * (`2026-09-03T23:49:00.416Z:dc03a32d9b717619`) or a package request went out,
+ * came back, and was refused with `400` on every poll for the life of the Bot.
+ *
+ * Every notification id is minted here instead, so the two sides cannot drift:
+ * the parts are joined with `-`, anything outside the admitted alphabet
+ * becomes `-`, and an over-long id keeps its readable head and folds the rest
+ * into a digest so distinct inputs stay distinct ids. Ids are stable for the
+ * same parts, which is what makes one firing one intent however many times a
+ * retry re-mints it.
+ */
+export function notificationIdV1(
+  ...parts: readonly (string | number)[]
+): string {
+  const raw = parts.map((part) => String(part)).join("-");
+  const sanitized = raw
+    .replace(/[^a-zA-Z0-9._-]/g, "-")
+    .replace(/^[^a-zA-Z0-9]+/, "");
+  const seeded =
+    sanitized.length === 0 ? `notification-${digest(raw)}` : sanitized;
+  const bounded =
+    seeded.length <= MAX_NOTIFICATION_ID_LENGTH
+      ? seeded
+      : `${seeded.slice(0, MAX_NOTIFICATION_ID_LENGTH - DIGEST_SUFFIX_LENGTH)}-${digest(raw)}`;
+  if (!isPublicIdentifier(bounded)) {
+    // Unreachable by construction; a mint that cannot be acknowledged is a
+    // bug, never something to ship to a client that will 400 on it forever.
+    throw new Error(
+      `minted notification id "${bounded}" is not acknowledgeable`,
+    );
+  }
+  return bounded;
+}
+
+/** FNV-1a, eight hex digits — an id disambiguator, not a security claim. */
+function digest(value: string): string {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}