@pellux/goodvibes-sdk 0.37.0 → 0.37.1

package/dist/contracts/artifacts/operator-contract.json

@@ -3,7 +3,7 @@
   "product": {
     "id": "goodvibes",
     "surface": "operator",
-    "version": "0.37.0"
+    "version": "0.37.1"
   },
   "auth": {
     "modes": [

package/dist/platform/version.js

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-let version = '0.37.0';
+let version = '0.37.1';
 try {
     const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', '..', 'package.json'), 'utf-8'));
     version = pkg.version ?? version;

package/dist/platform/workspace/checkpoint/manager.d.ts

@@ -75,6 +75,30 @@ export declare class WorkspaceCheckpointManager {
     private checkpoints;
     private initialized;
     private initPromise;
+    /**
+     * Promise-chain mutex serializing every public operation that touches the
+     * side repo's shared index or shared object store: `create`, `restore`,
+     * `gc`, and `diff` (see each method's `*Internal` body below). Without
+     * this, an auto-snapshot `create()` firing on a bus event (TURN_COMPLETED,
+     * TURN_ERROR, TURN_CANCEL, or AGENT_COMPLETED) could run its `git add -A`
+     * in between `restore()`'s
+     * `read-tree --reset` and `checkout-index -a -f`, silently corrupting the
+     * restore; two concurrent `create()` calls share the same hazard on the
+     * index, and a same-tick `gc()` could treat a not-yet-ref'd loose commit
+     * from an in-flight `create()` as unreachable and prune it out from under
+     * it. `diff()` is included too: the single-argument `git diff <tree-ish>`
+     * form (diffing a checkpoint against the live working tree) refreshes the
+     * index's stat cache as a side effect, which is itself a write.
+     *
+     * Each public method below only does `await this.init()` (idempotent, safe
+     * to race) before calling `withLock`; the actual git-touching work lives in
+     * a same-named `*Internal` method. Internal callers that need another
+     * locked operation's behavior (e.g. `restore()`'s safety checkpoint) call
+     * the `*Internal` method directly — never the public wrapper — so a single
+     * logical operation never tries to re-enter its own lock.
+     */
+    private lockChain;
+    private withLock;
     constructor(opts: WorkspaceCheckpointManagerOptions);
     /**
      * Idempotent setup: init the side repo, load the manifest (re-hydrating the
@@ -103,15 +127,25 @@ export declare class WorkspaceCheckpointManager {
      * Create a new checkpoint. Returns `null` (a cheap no-op) when the current
      * workspace tree is identical to the parent checkpoint's tree — no commit,
      * no ref, no manifest entry is created in that case.
+     *
+     * Serialized against every other index-touching operation on this manager
+     * — see `withLock`.
      */
     create(opts: CreateCheckpointOptions): Promise<WorkspaceCheckpoint | null>;
+    private createInternal;
     /** List checkpoints, newest-first. `list()[0]` is always the most recent checkpoint. */
     list(filter?: ListCheckpointsFilter): Promise<WorkspaceCheckpoint[]>;
     /**
      * Diff two checkpoints, or a checkpoint against the live working tree when
      * `b` is omitted.
+     *
+     * Serialized against every other index-touching operation on this manager
+     * — see `withLock`. The single-argument form (`b` omitted, diffing against
+     * the live working tree) refreshes the side index's stat cache as a side
+     * effect, so it is not purely read-only.
      */
     diff(a: string, b?: string): Promise<CheckpointDiff>;
+    private diffInternal;
     /**
      * Restore the workspace to the state captured by checkpoint `id`.
      *
@@ -133,8 +167,14 @@ export declare class WorkspaceCheckpointManager {
      *
      * Scoped restore (`opts.paths` provided) only checks out those paths from
      * the target tree; it never removes files outside the given paths.
+     *
+     * Serialized against every other index-touching operation on this manager
+     * — see `withLock`. Without this, an auto-snapshot `create()` firing on a
+     * bus event could run its `git add -A` in between the `read-tree --reset`
+     * and `checkout-index -a -f` calls below, silently corrupting the restore.
      */
     restore(id: string, opts?: RestoreOptions): Promise<RestoreResult>;
+    private restoreInternal;
     /**
      * Apply retention limits: `RetentionPolicy` selects prune candidates,
      * `WorkspaceCheckpointPruner` deletes their refs, then (only if anything
@@ -142,8 +182,19 @@ export declare class WorkspaceCheckpointManager {
      * unreachable objects. This never touches compaction's boundary commits —
      * they are tracked in an entirely separate `RetentionPolicy` instance
      * (../../runtime/compaction) with no shared state.
+     *
+     * Reclamation only works because checkpoint commits are parentless (see
+     * `SideGitRunner.commitTree`): a pruned ref's commit has no descendant
+     * keeping it reachable via a git parent pointer, so once its ref is
+     * deleted it is genuinely unreachable and `--prune=now` frees it.
+     *
+     * Serialized against every other index/object-store-touching operation on
+     * this manager — see `withLock`. Without this, a `create()` racing this
+     * method could write a loose commit object that isn't ref'd yet at the
+     * moment `--prune=now` runs, and lose it.
      */
     gc(): Promise<PruneResult>;
+    private gcInternal;
     /** Unsubscribe from the runtime bus. Does not touch anything on disk. */
     dispose(): void;
     private mostRecentCheckpoint;

package/dist/platform/workspace/checkpoint/manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../../src/platform/workspace/checkpoint/manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../../src/platform/workspace/checkpoint/manager.ts"],"names":[],"mappings":"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"}

package/dist/platform/workspace/checkpoint/manager.js

@@ -130,6 +130,39 @@ export class WorkspaceCheckpointManager {
     checkpoints = new Map();
     initialized = false;
     initPromise = null;
+    /**
+     * Promise-chain mutex serializing every public operation that touches the
+     * side repo's shared index or shared object store: `create`, `restore`,
+     * `gc`, and `diff` (see each method's `*Internal` body below). Without
+     * this, an auto-snapshot `create()` firing on a bus event (TURN_COMPLETED,
+     * TURN_ERROR, TURN_CANCEL, or AGENT_COMPLETED) could run its `git add -A`
+     * in between `restore()`'s
+     * `read-tree --reset` and `checkout-index -a -f`, silently corrupting the
+     * restore; two concurrent `create()` calls share the same hazard on the
+     * index, and a same-tick `gc()` could treat a not-yet-ref'd loose commit
+     * from an in-flight `create()` as unreachable and prune it out from under
+     * it. `diff()` is included too: the single-argument `git diff <tree-ish>`
+     * form (diffing a checkpoint against the live working tree) refreshes the
+     * index's stat cache as a side effect, which is itself a write.
+     *
+     * Each public method below only does `await this.init()` (idempotent, safe
+     * to race) before calling `withLock`; the actual git-touching work lives in
+     * a same-named `*Internal` method. Internal callers that need another
+     * locked operation's behavior (e.g. `restore()`'s safety checkpoint) call
+     * the `*Internal` method directly — never the public wrapper — so a single
+     * logical operation never tries to re-enter its own lock.
+     */
+    lockChain = Promise.resolve();
+    withLock(fn) {
+        // `lockChain` is constructed below so it never itself rejects (its
+        // continuation always swallows both outcomes) — chaining with a single
+        // `.then(fn)` is enough to guarantee `fn` only starts after every
+        // previously-queued operation has settled, regardless of whether that
+        // prior operation resolved or rejected.
+        const result = this.lockChain.then(fn);
+        this.lockChain = result.then(() => undefined, () => undefined);
+        return result;
+    }
     constructor(opts) {
         this.workspaceRoot = opts.workspaceRoot;
         this.checkpointRootDir = opts.checkpointDir ?? join(opts.workspaceRoot, '.goodvibes', 'checkpoints');
@@ -226,9 +259,15 @@ export class WorkspaceCheckpointManager {
      * Create a new checkpoint. Returns `null` (a cheap no-op) when the current
      * workspace tree is identical to the parent checkpoint's tree — no commit,
      * no ref, no manifest entry is created in that case.
+     *
+     * Serialized against every other index-touching operation on this manager
+     * — see `withLock`.
      */
     async create(opts) {
         await this.init();
+        return this.withLock(() => this.createInternal(opts));
+    }
+    async createInternal(opts) {
         await this.sideGit.stageAll(opts.paths);
         const treeHash = await this.sideGit.writeTree();
         const parent = this.mostRecentCheckpoint();
@@ -245,7 +284,7 @@ export class WorkspaceCheckpointManager {
         const retentionClass = opts.retentionClass ?? defaultRetentionClassFor(kind);
         const label = opts.label ?? this.defaultLabel(kind, id);
         const message = `wcp: ${kind} ${label}`.trim();
-        const commit = await this.sideGit.commitTree(treeHash, message, parent?.commit ?? null);
+        const commit = await this.sideGit.commitTree(treeHash, message);
         await this.sideGit.updateRef(`${CHECKPOINT_REF_PREFIX}${id}`, commit);
         const changedPaths = parent
             ? await this.sideGit.diffNameOnly(parent.commit, commit)
@@ -290,9 +329,17 @@ export class WorkspaceCheckpointManager {
     /**
      * Diff two checkpoints, or a checkpoint against the live working tree when
      * `b` is omitted.
+     *
+     * Serialized against every other index-touching operation on this manager
+     * — see `withLock`. The single-argument form (`b` omitted, diffing against
+     * the live working tree) refreshes the side index's stat cache as a side
+     * effect, so it is not purely read-only.
      */
     async diff(a, b) {
         await this.init();
+        return this.withLock(() => this.diffInternal(a, b));
+    }
+    async diffInternal(a, b) {
         const fromCheckpoint = this.requireCheckpoint(a);
         const toCheckpoint = b ? this.requireCheckpoint(b) : undefined;
         const [unifiedDiff, stat_, files] = await Promise.all([
@@ -329,15 +376,25 @@ export class WorkspaceCheckpointManager {
      *
      * Scoped restore (`opts.paths` provided) only checks out those paths from
      * the target tree; it never removes files outside the given paths.
+     *
+     * Serialized against every other index-touching operation on this manager
+     * — see `withLock`. Without this, an auto-snapshot `create()` firing on a
+     * bus event could run its `git add -A` in between the `read-tree --reset`
+     * and `checkout-index -a -f` calls below, silently corrupting the restore.
      */
     async restore(id, opts) {
         await this.init();
+        return this.withLock(() => this.restoreInternal(id, opts));
+    }
+    async restoreInternal(id, opts) {
         const target = this.requireCheckpoint(id);
         const wantSafety = opts?.safetyCheckpoint ?? true;
         let beforeFiles;
         let safetyCheckpointId = null;
         if (wantSafety) {
-            const safety = await this.create({ kind: 'manual', label: `pre-restore safety (before ${id})`, retentionClass: 'forensic' });
+            // Calls createInternal directly (not the public, lock-acquiring
+            // `create()`) — this whole method already holds the lock.
+            const safety = await this.createInternal({ kind: 'manual', label: `pre-restore safety (before ${id})`, retentionClass: 'forensic' });
             safetyCheckpointId = safety?.id ?? null;
             const current = safety ?? this.mostRecentCheckpoint();
             beforeFiles = current ? await this.sideGit.listTrackedFiles(current.commit) : [];
@@ -396,9 +453,22 @@ export class WorkspaceCheckpointManager {
      * unreachable objects. This never touches compaction's boundary commits —
      * they are tracked in an entirely separate `RetentionPolicy` instance
      * (../../runtime/compaction) with no shared state.
+     *
+     * Reclamation only works because checkpoint commits are parentless (see
+     * `SideGitRunner.commitTree`): a pruned ref's commit has no descendant
+     * keeping it reachable via a git parent pointer, so once its ref is
+     * deleted it is genuinely unreachable and `--prune=now` frees it.
+     *
+     * Serialized against every other index/object-store-touching operation on
+     * this manager — see `withLock`. Without this, a `create()` racing this
+     * method could write a loose commit object that isn't ref'd yet at the
+     * moment `--prune=now` runs, and lose it.
      */
     async gc() {
         await this.init();
+        return this.withLock(() => this.gcInternal());
+    }
+    async gcInternal() {
         const result = await this.retentionPolicy.prune();
         if (result.deletedCount > 0) {
             await this.persistManifest();

package/dist/platform/workspace/checkpoint/side-git.d.ts

@@ -87,11 +87,24 @@ export declare class SideGitRunner {
     /** Resolve `<commit>^{tree}` for an existing commit hash. */
     treeOf(commit: string): Promise<string>;
     /**
-     * Create a commit object from a tree (optionally with a parent), WITHOUT
-     * moving any branch/HEAD. The returned hash is only reachable once a ref is
-     * pointed at it via `updateRef`.
+     * Create a commit object from a tree, deliberately WITHOUT a git parent
+     * (no `-p`) and WITHOUT moving any branch/HEAD.
+     *
+     * Checkpoint lineage is tracked exclusively via the manifest's `parentId`
+     * field (manager.ts) — never via git ancestry. This isn't just a style
+     * choice: if checkpoint commits chained via `-p` the way a normal git
+     * history does, deleting an OLD checkpoint's ref in `gc()` would free
+     * nothing, because that commit stays reachable through every NEWER
+     * checkpoint's parent pointer — the ref is gone but the commit (and any
+     * tree/blob objects unique to it) is still walkable from every surviving
+     * descendant. Parentless commits mean a checkpoint's own ref is the ONLY
+     * thing keeping its commit reachable, so once that ref is deleted,
+     * `git gc --prune=now` can genuinely reclaim it.
+     *
+     * The returned hash is only reachable once a ref is pointed at it via
+     * `updateRef`.
      */
-    commitTree(treeHash: string, message: string, parentCommit: string | null): Promise<string>;
+    commitTree(treeHash: string, message: string): Promise<string>;
     updateRef(refName: string, commit: string): Promise<void>;
     deleteRef(refName: string): Promise<void>;
     /** List every ref under CHECKPOINT_REF_PREFIX as `{ id, commit }`. */

package/dist/platform/workspace/checkpoint/side-git.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"side-git.d.ts","sourceRoot":"","sources":["../../../../src/platform/workspace/checkpoint/side-git.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAQH,0EAA0E;AAC1E,eAAO,MAAM,eAAe,6CAA6C,CAAC;AAE1E,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,gCAAgC,CAAC;AA8CnE,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAY;gBAEpB,IAAI,EAAE,oBAAoB;IAUtC,gFAAgF;IAC1E,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1C;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB3B;;;;;;;;;OASG;IACH,OAAO,CAAC,sBAAsB;IAuB9B;;;;;;;;;;;;OAYG;IACG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/C,wGAAwG;IAClG,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IAIlC,6DAA6D;IACvD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI7C;;;;OAIG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IAM3F,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C,sEAAsE;IAChE,kBAAkB,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAmBrE,+DAA+D;IACzD,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAK/D,+FAA+F;IACzF,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,wGAAwG;IAClG,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIvC,iGAAiG;IAC3F,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAItD,wGAAwG;IAClG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1D,6GAA6G;IACvG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAKhE,6CAA6C;IACvC,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;CAG1B"}
+{"version":3,"file":"side-git.d.ts","sourceRoot":"","sources":["../../../../src/platform/workspace/checkpoint/side-git.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAQH,0EAA0E;AAC1E,eAAO,MAAM,eAAe,6CAA6C,CAAC;AAE1E,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,gCAAgC,CAAC;AA8CnE,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAY;gBAEpB,IAAI,EAAE,oBAAoB;IAUtC,gFAAgF;IAC1E,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1C;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB3B;;;;;;;;;OASG;IACH,OAAO,CAAC,sBAAsB;IAuB9B;;;;;;;;;;;;OAYG;IACG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/C,wGAAwG;IAClG,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IAIlC,6DAA6D;IACvD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI7C;;;;;;;;;;;;;;;;;OAiBG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI9D,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C,sEAAsE;IAChE,kBAAkB,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAmBrE,+DAA+D;IACzD,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAK/D,+FAA+F;IACzF,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,wGAAwG;IAClG,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIvC,iGAAiG;IAC3F,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAItD,wGAAwG;IAClG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1D,6GAA6G;IACvG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAKhE,6CAA6C;IACvC,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;CAG1B"}

package/dist/platform/workspace/checkpoint/side-git.js

@@ -185,15 +185,25 @@ export class SideGitRunner {
         return (await this.git.raw(['rev-parse', `${commit}^{tree}`])).trim();
     }
     /**
-     * Create a commit object from a tree (optionally with a parent), WITHOUT
-     * moving any branch/HEAD. The returned hash is only reachable once a ref is
-     * pointed at it via `updateRef`.
+     * Create a commit object from a tree, deliberately WITHOUT a git parent
+     * (no `-p`) and WITHOUT moving any branch/HEAD.
+     *
+     * Checkpoint lineage is tracked exclusively via the manifest's `parentId`
+     * field (manager.ts) — never via git ancestry. This isn't just a style
+     * choice: if checkpoint commits chained via `-p` the way a normal git
+     * history does, deleting an OLD checkpoint's ref in `gc()` would free
+     * nothing, because that commit stays reachable through every NEWER
+     * checkpoint's parent pointer — the ref is gone but the commit (and any
+     * tree/blob objects unique to it) is still walkable from every surviving
+     * descendant. Parentless commits mean a checkpoint's own ref is the ONLY
+     * thing keeping its commit reachable, so once that ref is deleted,
+     * `git gc --prune=now` can genuinely reclaim it.
+     *
+     * The returned hash is only reachable once a ref is pointed at it via
+     * `updateRef`.
      */
-    async commitTree(treeHash, message, parentCommit) {
-        const args = ['commit-tree', treeHash, '-m', message];
-        if (parentCommit)
-            args.push('-p', parentCommit);
-        return (await this.git.raw(args)).trim();
+    async commitTree(treeHash, message) {
+        return (await this.git.raw(['commit-tree', treeHash, '-m', message])).trim();
     }
     async updateRef(refName, commit) {
         await this.git.raw(['update-ref', refName, commit]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-sdk",
-  "version": "0.37.0",
+  "version": "0.37.1",
   "description": "TypeScript SDK for building GoodVibes operator, peer, web, mobile, and daemon-connected apps with typed contracts, auth, realtime events, and transport layers.",
   "keywords": [
     "goodvibes",
@@ -453,14 +453,14 @@
   "sideEffects": false,
   "type": "module",
   "dependencies": {
-    "@pellux/goodvibes-contracts": "0.37.0",
-    "@pellux/goodvibes-daemon-sdk": "0.37.0",
-    "@pellux/goodvibes-errors": "0.37.0",
-    "@pellux/goodvibes-operator-sdk": "0.37.0",
-    "@pellux/goodvibes-peer-sdk": "0.37.0",
-    "@pellux/goodvibes-transport-core": "0.37.0",
-    "@pellux/goodvibes-transport-http": "0.37.0",
-    "@pellux/goodvibes-transport-realtime": "0.37.0"
+    "@pellux/goodvibes-contracts": "0.37.1",
+    "@pellux/goodvibes-daemon-sdk": "0.37.1",
+    "@pellux/goodvibes-errors": "0.37.1",
+    "@pellux/goodvibes-operator-sdk": "0.37.1",
+    "@pellux/goodvibes-peer-sdk": "0.37.1",
+    "@pellux/goodvibes-transport-core": "0.37.1",
+    "@pellux/goodvibes-transport-http": "0.37.1",
+    "@pellux/goodvibes-transport-realtime": "0.37.1"
   },
   "optionalDependencies": {
     "@agentclientprotocol/sdk": "^0.21.0",