Skip to content

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.md
index 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.ts
index 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.ts
index 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.ts
index 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 () => {