Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix: a refused storage card names what it breaks and carries its revision for the repair
garrytan2cf1d27f2b33
diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.mdindex ade5f9bd68..e6fb1f6e43 100644--- a/docs/guides/write-refusals.md+++ b/docs/guides/write-refusals.md@@ -1085,7 +1085,7 @@ An adopt or import apply whose plan changed since its preview refuses `preview_c| Code | What happened | What to do ||---|---|---|| `storage_source_managed` | `put_page`, `remember` or another page writer targeted the shelf. | Register with `gbrain storage-register`, change with `gbrain storage-update`. |-| `storage_record_invalid` | A card field is missing or malformed, names a command (`command`, `script`, `exec` and similar), or is one gbrain sets itself (`registered_by`, `origin`). `storage_get` refuses it too for a stored card that breaks these rules, such as a hand-edited card file. | Fix the field the message names. Restore runs through `restore.skill` and `restore.args`. For a stored card, `gbrain doctor --only storage_manifest` lists the invalid cards; the owner corrects the card. |+| `storage_record_invalid` | A card field is missing or malformed, names a command (`command`, `script`, `exec` and similar), or is one gbrain sets itself (`registered_by`, `origin`). `storage_get` refuses it too for a stored card that breaks these rules, such as a hand-edited card file. | Fix the field the message names. Restore runs through `restore.skill` and `restore.args`. For a stored card, `gbrain doctor --only storage_manifest` lists the invalid cards, and the refusal carries the card's revision for `gbrain storage-update <id> --expected-revision <rev> --patch '<json>'`. || `storage_record_secret` | A field looks like a secret or has a credential shape: an environment assignment, a credential-named variable, a URL password or a signed-URL parameter. The value is not echoed. | Remove it; the restore skill reads credentials from its own environment. || `storage_card_exists` | A card with that id is already registered. | Update it with the revision `storage_get` returns, or use another id. || `storage_revision_conflict` | The card changed since its revision was read; `detail` holds the current revision. | Read it again, apply the change, update once. |diff --git a/src/commands/doctor/checks/storage-manifest.ts b/src/commands/doctor/checks/storage-manifest.tsindex 5ce787394f..9e1499a012 100644--- a/src/commands/doctor/checks/storage-manifest.ts+++ b/src/commands/doctor/checks/storage-manifest.ts@@ -47,7 +47,7 @@ export async function storageManifestCheck(engine: BrainEngine): Promise<Check>? { ask_user: true, consent: [], actor: 'user', requires_exclusive: false, docs: DOCS, why: 'Only the user knows where the shelf repository went (moved, deleted, or on another machine).',user_message: `The storage shelf's Git directory is missing: ${missingDirs.join(', ')}. Restore it from its push remote or a backup to the same path, then run gbrain doctor --only storage_manifest again.` }: invalid.length- ? agentFix(['gbrain', 'storage-get', invalid[0]!, '--json'], 'Read-only: shows the card so it can be fixed with gbrain storage-update and its revision.', NAME, { docs: DOCS })+ ? agentFix(['gbrain', 'storage-get', invalid[0]!, '--json'], 'Read-only: names what the card breaks and its revision, so it can be fixed with gbrain storage-update.', NAME, { docs: DOCS }): agentFix(['gbrain', 'storage', 'adopt', ...(first && first !== 'default' ? ['--source', first] : []), '--json'], 'Read-only preview: the card each interim record maps to and the fields a card refuses; it writes nothing.', NAME, { docs: DOCS });return { name: NAME, status: 'warn', message: `Storage shelf: ${problems.join('; ')}.`, details, fix };} catch (error) {diff --git a/src/core/ops/storage-manifest.ts b/src/core/ops/storage-manifest.tsindex d8cf32dfaf..2114f05e72 100644--- a/src/core/ops/storage-manifest.ts+++ b/src/core/ops/storage-manifest.ts@@ -20,7 +20,7 @@ async function principalLabel(ctx: OperationContext): Promise<string> {const principal = await requestPrincipalForContext(ctx);return `${principal.kind}:${principal.id}`;}-import { cardContent, cardFromPage, cardPage, parseCardInput, STATUSES, STORES, withRestore, type Card, type CardInput, ORIGINS } from '../storage-manifest/schema.ts';+import { cardFromPage, cardPage, parseCardInput, STATUSES, STORES, withRestore, type Card, type CardInput, ORIGINS } from '../storage-manifest/schema.ts';import { ensureStorageSource, storageDoorContext, STORAGE_SOURCE_ID } from '../storage-manifest/source.ts';import { findCards, listCards, type CardFilters } from '../storage-manifest/find.ts';@@ -158,9 +158,12 @@ const storage_get: Operation = {throw opError('not_found', `No card ${id} on the storage shelf.`, 'Search with storage_find and the words people would use for the item; it lists the closest cards when nothing matches.',{ fix: readFix('Finds cards by phrase, with the closest cards when nothing matches.', { argv: ['gbrain', 'storage-find', id, '--json'], mcp: { tool: 'storage_find', arguments: { query: id } } }) });}- if (!cardContent(found.card)) {- throw opError('storage_record_invalid', `Card ${id} on the storage shelf fails the card rules, so it is not served; nothing was changed.`,- 'Ask the owner to correct the card (gbrain doctor --only storage_manifest lists the invalid cards), then read it again.', { reason: 'schema' });+ const { registered_by: _by, origin: _origin, ...content } = found.card;+ try { parseCardInput(content); } catch (error) {+ if (!(error instanceof OperationError)) throw error;+ throw opError('storage_record_invalid', `Card ${id} on the storage shelf fails the card rules, so it is not served (${error.message})`,+ `Correct it with gbrain storage-update ${id} --expected-revision ${found.revision} --patch '<the fields to replace, as JSON>'; the patch is validated like a new card.`,+ { reason: 'schema', detail: found.revision });}return { card: found.card, revision: found.revision, updated_at: found.updated_at, source_id: STORAGE_SOURCE_ID, registered_by: found.card.registered_by, origin: found.card.origin };},diff --git a/test/storage-manifest.test.ts b/test/storage-manifest.test.tsindex 4aa43577eb..c9dae79510 100644--- a/test/storage-manifest.test.ts+++ b/test/storage-manifest.test.ts@@ -9,7 +9,7 @@* - the write guard: put_page and remember into the shelf are refused storage_source_managed, a forged parameter* does not open it, and the storage verbs still write;* - storage_get refuses a stored card that fails the card rules (a hand-edited card file with a command field)- * with storage_record_invalid, locally and remotely, without echoing the value;+ * with storage_record_invalid, locally and remotely, without echoing the value, and its revision repairs it;* - register never overwrites (storage_card_exists); update binds to the revision it read (storage_revision_conflict* carries the current one) and records a restore newest first;* - register and update refuse remote callers; the shelf is not federated, so a remote connection reads cards only@@ -160,6 +160,10 @@ describe('storage shelf on a repo-less brain', () => {expect({ code: r?.code, reason: r?.reason }).toEqual({ code: 'storage_record_invalid', reason: 'schema' });expect(r!.message).not.toContain('example.invalid');}+ const refused = await operationsByName.storage_get!.handler(ctx(), { id: 'edited-item' }).then(() => null, (e: { detail?: string; suggestion?: string }) => e);+ expect(refused?.suggestion).toContain(`gbrain storage-update edited-item --expected-revision ${refused?.detail}`);+ await call('storage_update', { id: 'edited-item', expected_revision: refused!.detail, patch: { restore: { skill: 'restore-data', args: { id: 'edited-item' } } } });+ expect((await call('storage_get', { id: 'edited-item' })).card.restore).toEqual({ skill: 'restore-data', args: { id: 'edited-item' } });}, 30_000);test('register never overwrites; update binds to its revision and records restores newest first', async () => {