Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(setup): resume an earlier release's packaged skill adoption on init retry (#8453)

garrytane460340ea2a4
diff --git a/docs/architecture/key-files/shared-skills.md b/docs/architecture/key-files/shared-skills.md
index f4a49c4d26..49ca318bf2 100644
--- a/docs/architecture/key-files/shared-skills.md
+++ b/docs/architecture/key-files/shared-skills.md
@@ -5,7 +5,7 @@
- `src/core/shared-skills/{schema-all,schema,persistence-schema,membership-schema,access-schema}.ts` supplies shared schema migration/bootstrap SQL. Access DDL explicitly enables row-level security for bypass-capable owners even when the database-wide event trigger is unavailable. Protocol guards reject old consumer claims and writes before filesystem effects; the request and effect guards refuse `writer_coordinator_required` when the writing role cannot see the `persistence_brain` floor, and activation refuses any role that row-level security filters on `sources` or the request, effect, worktree and binding tables. Their function bodies are exported alone so a migration replaces them without re-creating triggers. `src/core/persistence/{protocol,skill-activation,bundle-files}.ts` implements explicit owner/quiescence activation and bounded whole-set recovery while preserving the existing page target and permanent receipt identity.
- `src/core/shared-skills/{membership,membership-authority,membership-types,adapter}.ts` implements own-principal enrollment, source/policy-bound follow approval, issued batch acknowledgments and conflict-safe immutable local caches. Acknowledgments are self-reported delivery, never vendor-native activation. Enforced library admission rechecks freshness and requirements; native instruction routers remain advisory until separately observed. The adapter's leave treats a server `membership_inactive` (its own enrollment epoch was left or re-enrolled past) as remote cleanup complete (`remote_membership_reason: superseded`), so harness rotation converges; `gbrain bootstrap harness --refresh-skills` re-runs `join` to adopt the current epoch.
- `src/core/harness/{shared-skills,native-router}.ts` connects the enrollment protocol to target-local installation and ownership-tracked Claude Code, Codex and opencode router placement. Native registration, restart and actual task use are separate states. Removal keeps modified files and reports retained native state.
-- `src/core/shared-skills/{setup,setup-bundle,setup-files,migration,migration-export}.ts` owns combined-content roots, compile-safe starter skills, staged legacy adoption and explicitly approved DB-only export with round-trip validation. Existing roots, opt-outs, private/excluded skills and grant ceilings survive upgrades. `src/commands/migrations/shared-content.ts` integrates previews and recurring pending-stage reconciliation into the migration runner. The 0.53 migration retakes an inventory that never completed at a corrected root (#5569), moves a DB-only export checkpoint that stopped before its source was bound (stage `inventory` or `exported`, no started claim) to another absent `--content-root`, leaving the old root and staging as they are and rechecking the checkpoint's inventory (#8528), refuses at inventory a pack whose adoption would exceed `packFiles` (A-NEW-4), and accepts a post-inventory change only through `--accept-reviewed-inventory <source>=<inventoryDigest>` printed in the conflict reason (#5476).
+- `src/core/shared-skills/{setup,setup-bundle,setup-files,migration,migration-export}.ts` owns combined-content roots, compile-safe starter skills, staged legacy adoption and explicitly approved DB-only export with round-trip validation. `installPackagedSharedSkills` resumes (or keeps, once committed) the caller's newest packaged adoption of the source incarnation's `gbrain-memory` pack before admitting one, since the adoption key binds the release-stamped `skillpack.json` and README (#8453). Existing roots, opt-outs, private/excluded skills and grant ceilings survive upgrades. `src/commands/migrations/shared-content.ts` integrates previews and recurring pending-stage reconciliation into the migration runner. The 0.53 migration retakes an inventory that never completed at a corrected root (#5569), moves a DB-only export checkpoint that stopped before its source was bound (stage `inventory` or `exported`, no started claim) to another absent `--content-root`, leaving the old root and staging as they are and rechecking the checkpoint's inventory (#8528), refuses at inventory a pack whose adoption would exceed `packFiles` (A-NEW-4), and accepts a post-inventory change only through `--accept-reviewed-inventory <source>=<inventoryDigest>` printed in the conflict reason (#5476).
- `src/core/shared-skills/{setup-source-policy,content-freshness}.ts` excludes external, connector, company and opted-out (`config.shared_skills=false`) sources from owned-root scaffolding and freshness exemptions. A completed content receipt must match the current brain, incarnation, source root and active owner binding. `src/commands/doctor/checks/canonical-content.ts` reports pending publication and recovery separately; it never invents an upstream sync timestamp. `src/core/shared-skills/adopted-packs.ts` names the sources holding an adopted pack (`source_routing_health` skips their zero-page warning) and, of those, the read-only catalogs (no commit, no `.git` when the checkout is readable) that `sync_freshness` exempts; a failing read exempts nothing and is a note. `staleOwnedContent` names a receipt, or an unfinished setup checkpoint, left on an old root (doctor `content_receipt_stale`); `setup.ts` refuses a resumed setup whose checkpoint names another root with `gbrain repair content-receipt-root --source <id>` as the fix. `src/core/shared-skills/receipt-root.ts` (`rebindContentReceipts`) rebinds the receipt root and `root_identity` of every current incarnation on the moved worktrees (nested by `relative_path`) inside the writer transfer accept and `sources set-path` transactions. `src/core/repair/content-receipt-root.ts` (`gbrain repair content-receipt-root`, explicit-only, preview-bound, owner host) rebinds a stale receipt when the source path is the owner root and the owner tree hashes to the recorded manifest, else lists `source_path_mismatch` / `tree_mismatch` (both digests) / `not_owner_host` / `root_missing`; it keeps `<key>.backup`. Test: `test/pathological/c7-content-receipt-root.test.ts`.
- `src/core/shared-skills/{source-opt-out,inventory-limits}.ts` and `src/commands/sources-shared-skills.ts` implement `gbrain sources shared-skills <id> on|off|status`: `off` writes `config.shared_skills=false`, `on` deletes it and releases a parked inventory, and every form reports the configured value and the effective policy mode with its reason. Trusted local only; a remote attempt gets `trusted_local_only` with a `host_admin` fix and a read-only verify. `inventorySkillpack` reads its file-count, total-byte, per-file and entry bounds from the capped `shared_skills.inventory.*` keys; confinement checks are fixed. An overflow (`payload_too_large`) parks the source in its per-source migration record, so the 0.53.0 orchestrator completes and later runs skip it until the bounds change, it opts out, or it is released. `src/commands/doctor/checks/shared-skills.ts` (`shared_skills_sources`) lists opted-out and parked sources. Operator recipe: `docs/guides/shared-brain-skills.md#choose-which-sources-adopt-shared-skills`.
- `src/core/shared-skills/optimizer.ts` stages opt-in optimization outside canonical roots with the original grants, immutable approved closure and protected metadata. Publication rechecks authority and the original revision through the coordinator; provider evaluation cannot write canonical skill files directly.
diff --git a/src/core/shared-skills/setup.ts b/src/core/shared-skills/setup.ts
index 8798e6247d..2dc49a0a88 100644
--- a/src/core/shared-skills/setup.ts
+++ b/src/core/shared-skills/setup.ts
@@ -12,6 +12,9 @@ import { publicationEnabled, setSharedSkillPolicy } from './policy.ts';
import type { BrainEngine } from '../engine.ts';
import { assertPackagedSkillSource, sharedSkillSourcePolicy } from './setup-source-policy.ts';
import { gitChildEnv } from '../git-env.ts';
+import { initializeLocalPersistence, requestPrincipalForContext } from '../persistence/page-mutations.ts';
+import { waitForWrite } from '../persistence/service.ts';
+import { isTerminal, type WriteRequest } from '../persistence/model.ts';
export async function isNewContentDatabase(engine: BrainEngine): Promise<boolean> {
const [row] = await engine.executeRaw<{ fresh: boolean }>("SELECT to_regclass('public.pages') IS NULL AND to_regclass('public.config') IS NULL AND to_regclass('public.persistence_brain') IS NULL AS fresh");
@@ -233,6 +236,17 @@ export async function setupSharedBrainContent(ctx: OperationContext, options: Sh
export async function installPackagedSharedSkills(ctx: OperationContext, sourceId: string, preservePaths: string[] = []): Promise<void> {
await assertPackagedSkillSource(ctx.engine, sourceId);
+ // #8453: the adoption key binds the release-stamped payload, so an install begun on an earlier release left its adoption
+ // under another key. Resume (or keep) that request instead of admitting a second publication of the pack.
+ await initializeLocalPersistence(ctx);
+ const principal = await requestPrincipalForContext(ctx);
+ const [open] = await ctx.engine.executeRaw<WriteRequest>(`SELECT r.* FROM persistence_requests r JOIN sources s ON s.id=r.source_id AND s.incarnation=r.source_incarnation
+ WHERE r.operation='put_skill' AND r.source_id=$1 AND r.principal_kind=$2 AND r.principal_id=$3 AND r.intent->>'pack_id'=$4
+ AND r.authority ? 'skillAdoptionPreconditions' AND r.state IN ('queued','running','recovering','committed') ORDER BY r.sequence DESC LIMIT 1`,
+ [sourceId, principal.kind, principal.id, DEFAULT_SHARED_PACK_ID]);
+ const resumed = open ? await waitForWrite(ctx.engine, open, ctx.config, ctx.writeWaitMs) : null;
+ if (resumed?.state === 'committed') return;
+ if (resumed && !isTerminal(resumed)) throw packagedPublicationPending(resumed.request_id);
const files = packagedSharedSkills();
for (const path of preservePaths) if (['README.md', 'LICENSE'].includes(path)) delete files[path];
const { adoptSharedSkillpack } = await import('./catalog.ts');
@@ -245,9 +259,11 @@ export async function installPackagedSharedSkills(ctx: OperationContext, sourceI
})),
});
const pending = result.receipts.map(receipt => receipt.write_request as { state?: string; request_id?: string } | undefined).find(request => request?.state !== 'committed');
- if (pending) {
- throw opError('publication_pending', 'The default pack was accepted but is not fully committed; rerun init to resume its durable requests.',
- `Inspect the accepted request${pending.request_id ? ` ${pending.request_id}` : ''} first; gbrain init resumes the same durable request (same request_id), so it never publishes the pack twice.`,
- pending.request_id ? { fix: readFix('Shows whether the default pack publication committed, is still pending, or failed.', { argv: ['gbrain', 'write-request', '--', pending.request_id] }) } : {});
- }
+ if (pending) throw packagedPublicationPending(pending.request_id);
+}
+
+function packagedPublicationPending(requestId: string | undefined) {
+ return opError('publication_pending', 'The default pack was accepted but is not fully committed; rerun init to resume its durable requests.',
+ `Inspect the accepted request${requestId ? ` ${requestId}` : ''} first; gbrain init resumes the same durable request (same request_id), so it never publishes the pack twice.`,
+ requestId ? { fix: readFix('Shows whether the default pack publication committed, is still pending, or failed.', { argv: ['gbrain', 'write-request', '--', requestId] }) } : {});
}
diff --git a/test/shared-skills-packaged-key-7734.test.ts b/test/shared-skills-packaged-key-7734.test.ts
index a1d4d766c5..0cecff669c 100644
--- a/test/shared-skills-packaged-key-7734.test.ts
+++ b/test/shared-skills-packaged-key-7734.test.ts
@@ -1,5 +1,5 @@
import { expect, test } from 'bun:test';
-import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
@@ -10,6 +10,8 @@ import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { adoptSharedSkillpack } from '../src/core/shared-skills/publication.ts';
import { listSharedSkills } from '../src/core/shared-skills/catalog.ts';
import { packagedSharedSkills } from '../src/core/shared-skills/setup-bundle.ts';
+import { installPackagedSharedSkills } from '../src/core/shared-skills/setup.ts';
+import { VERSION } from '../src/version.ts';
import { withEnv } from './helpers/with-env.ts';
import { isolatedSharedSkillsEngine } from './helpers/shared-skills-engine.ts';
@@ -49,12 +51,12 @@ function packaged(edit?: (files: Record<string, string>) => void) {
files: [{ path: `${path}/SKILL.md`, content: initial_files[`${path}/SKILL.md`], file_class: 'prose' as const }] })) };
}
-/** Admits the adoption, then fails its canonical apply, leaving the accepted request uncommitted (host work pending). */
-function interrupted(ctx: OperationContext): OperationContext {
+/** Admits the adoption, then fails its canonical apply with `error`, leaving the accepted request uncommitted (host work pending). */
+function interrupted(ctx: OperationContext, error = () => new Error('synthetic storage interruption')): OperationContext {
const failing = new Proxy(ctx.engine, { get(target, key) {
if (key === 'transaction') return async (fn: (tx: BrainEngine) => Promise<unknown>) => target.transaction((real) => fn(new Proxy(real, { get(tx, prop) {
if (prop === 'executeRaw') return async (sql: string, params?: unknown[]) => {
- if (sql.includes('INSERT INTO shared_skill_revisions')) throw new Error('synthetic storage interruption');
+ if (sql.includes('INSERT INTO shared_skill_revisions')) throw error();
return tx.executeRaw(sql, params);
};
const value = Reflect.get(tx, prop); return typeof value === 'function' ? value.bind(tx) : value;
@@ -88,3 +90,31 @@ test('an exact replay of the packaged payload resumes the same request', () => f
expect(replay.receipts[0].revision).toBe(first.receipts[0].revision);
expect(await requestIds(f.engine)).toHaveLength(1);
}), 120_000);
+
+test('#8453: an init retried after an upgrade resumes the adoption the earlier release admitted instead of admitting a second', () => fixture(async (f) => {
+ const older = packaged((files) => { for (const path of ['skillpack.json', 'README.md']) files[path] = files[path].replaceAll(VERSION, '0.0.1.0'); });
+ expect(older.initial_files['skillpack.json']).not.toBe(packagedSharedSkills()['skillpack.json']);
+ // A statement cancel is a transient interruption: the admitted request goes back to the queue, uncommitted.
+ const broken = interrupted(f.local, () => Object.assign(new Error('canceling statement due to statement timeout'), { code: '57014' }));
+ await adoptSharedSkillpack(broken, 'default', older).catch(() => undefined);
+ await disposePersistenceConsumer(broken.engine);
+ await disposePersistenceConsumer(f.engine);
+ const admitted = await requestIds(f.engine);
+ expect(admitted).toHaveLength(1);
+ expect((await f.engine.executeRaw<{ state: string }>("SELECT state FROM persistence_requests WHERE operation='put_skill'")).map((r) => r.state)).toEqual(['queued']);
+ await installPackagedSharedSkills(f.local, 'default');
+ expect(await requestIds(f.engine)).toEqual(admitted);
+ expect((await f.engine.executeRaw<{ state: string }>("SELECT state FROM persistence_requests WHERE operation='put_skill'")).map((r) => r.state)).toEqual(['committed']);
+ const [{ local_path }] = await f.engine.executeRaw<{ local_path: string }>("SELECT local_path FROM sources WHERE id='default'");
+ expect(JSON.parse(readFileSync(join(local_path, 'skillpack.json'), 'utf8')).version).toBe('0.0.1.0');
+ expect((await listSharedSkills(f.reader)).skills.length).toBeGreaterThan(0);
+}), 120_000);
+
+test('#8453: an init retried after an upgrade keeps the pack an earlier release already committed', () => fixture(async (f) => {
+ const older = packaged((files) => { for (const path of ['skillpack.json', 'README.md']) files[path] = files[path].replaceAll(VERSION, '0.0.1.0'); });
+ await adoptSharedSkillpack(f.local, 'default', older);
+ const admitted = await requestIds(f.engine);
+ await installPackagedSharedSkills(f.local, 'default');
+ expect(await requestIds(f.engine)).toEqual(admitted);
+ expect((await f.engine.executeRaw<{ state: string }>("SELECT state FROM persistence_requests WHERE operation='put_skill'")).map((r) => r.state)).toEqual(['committed']);
+}), 120_000);