crewly 1.6.4 → 1.6.5

package/dist/cli/backend/src/services/task-pool/pool-storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pool-storage.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/task-pool/pool-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAO/D;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,2CAA2C;IAC3C,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,uCAAuC;IACvC,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAmBD;;;;;;;GAOG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAEzC,wDAAwD;IACxD,OAAO,CAAC,KAAK,CAAyB;IAEtC,iDAAiD;IACjD,OAAO,CAAC,UAAU,CAA+B;IAEjD,kCAAkC;IAClC,OAAO,CAAC,KAAK,CAAS;gBAEV,OAAO,CAAC,EAAE,kBAAkB;IAYxC;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,QAAQ,CAAC;IAa/B;;;;OAIG;IACG,YAAY,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAKzC;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAKvC;;;;;OAKG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAKrE;;;;;OAKG;IACG,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAOnF;;;;;OAKG;IACG,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAO7E;;;;OAIG;IACG,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpD;;;;;;OAMG;IACG,cAAc,CAClB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,CAAC,EAAE,EAAE,QAAQ,KAAK,IAAI,GAC9B,OAAO,CAAC,OAAO,CAAC;IASnB;;;;;OAKG;IACG,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAS1D;;;;OAIG;IACG,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAM/C;;;;;;OAMG;IACG,WAAW,CACf,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,GAClC,OAAO,CAAC,OAAO,CAAC;IASnB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAa5B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B;;OAEG;IACH,OAAO,CAAC,SAAS;CAUlB;AAMD;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,QAAQ,CAM9C"}
+{"version":3,"file":"pool-storage.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/task-pool/pool-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAQ/D;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,2CAA2C;IAC3C,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,uCAAuC;IACvC,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAmBD;;;;;;;GAOG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAEzC,wDAAwD;IACxD,OAAO,CAAC,KAAK,CAAyB;IAEtC,iDAAiD;IACjD,OAAO,CAAC,UAAU,CAA+B;IAEjD,kCAAkC;IAClC,OAAO,CAAC,KAAK,CAAS;gBAEV,OAAO,CAAC,EAAE,kBAAkB;IAYxC;;;;;;;;;;;;OAYG;IACG,IAAI,IAAI,OAAO,CAAC,QAAQ,CAAC;IAsB/B;;;;;;;OAOG;IACG,YAAY,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAKzC;;;;;;;OAOG;IACG,SAAS,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAKvC;;;;;OAKG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAKrE;;;;;OAKG;IACG,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAOnF;;;;;OAKG;IACG,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAO7E;;;;OAIG;IACG,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpD;;;;;;OAMG;IACG,cAAc,CAClB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,CAAC,EAAE,EAAE,QAAQ,KAAK,IAAI,GAC9B,OAAO,CAAC,OAAO,CAAC;IASnB;;;;;OAKG;IACG,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAS1D;;;;OAIG;IACG,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAM/C;;;;;;OAMG;IACG,WAAW,CACf,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,GAClC,OAAO,CAAC,OAAO,CAAC;IASnB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAa5B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B;;OAEG;IACH,OAAO,CAAC,SAAS;CAUlB;AAMD;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,QAAQ,CAM9C"}

package/dist/cli/backend/src/services/task-pool/pool-storage.js

@@ -8,9 +8,9 @@
  * @module services/task-pool/pool-storage
  */
 import * as path from 'path';
-import * as os from 'os';
 import { ensureDir, safeReadJson, atomicWriteJson, } from '../../utils/file-io.utils.js';
 import { LoggerService } from '../core/logger.service.js';
+import { getCrewlyHomePath } from '../core/crewly-home.utils.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -42,7 +42,7 @@ export class PoolStorage {
     dirty = false;
     constructor(options) {
         const dataDir = options?.dataDir ??
-            path.join(os.homedir(), '.crewly', POOL_DIR_NAME);
+            path.join(getCrewlyHomePath(), POOL_DIR_NAME);
         this.filePath = path.join(dataDir, POOL_FILE_NAME);
         this.logger = LoggerService.getInstance().createComponentLogger('PoolStorage');
     }
@@ -52,33 +52,56 @@ export class PoolStorage {
     /**
      * Loads pool data from disk (or returns cached copy).
      *
-     * @returns Current pool data
+     * **F-CYCLE7-3 (2026-05-07):** Normalizes legacy / partial on-disk
+     * shapes — if a previous write produced a `pool.json` missing the
+     * `workItems` or `claims` arrays (root cause of the post-restart
+     * `Cannot read properties of undefined (reading 'filter')` storm in
+     * `ReconcilerDataProvider`), we coerce the missing slots to `[]`
+     * before caching so every downstream consumer can rely on the
+     * `PoolData` invariant.
+     *
+     * @returns Current pool data with `workItems` and `claims` guaranteed to be arrays
      */
     async load() {
         if (this.cache)
             return this.cache;
         await ensureDir(path.dirname(this.filePath));
-        const data = await safeReadJson(this.filePath, createEmptyPoolData(), this.logger);
-        this.cache = data;
-        return data;
+        const raw = await safeReadJson(this.filePath, createEmptyPoolData(), this.logger);
+        // Defensive normalization. `safeReadJson` round-trips whatever
+        // shape is on disk, so a partial / pre-migration file can produce
+        // `data.workItems === undefined`. Repair to canonical shape once,
+        // here, instead of every read site.
+        const normalized = {
+            workItems: Array.isArray(raw?.workItems) ? raw.workItems : [],
+            claims: Array.isArray(raw?.claims) ? raw.claims : [],
+            lastUpdatedAt: raw?.lastUpdatedAt ?? new Date(0).toISOString(),
+        };
+        this.cache = normalized;
+        return normalized;
     }
     /**
      * Returns all work items currently in the pool.
      *
+     * Always returns an array — `load()` normalizes a missing
+     * `workItems` field to `[]` (F-CYCLE7-3).
+     *
      * @returns Array of WorkItems
      */
     async getWorkItems() {
         const data = await this.load();
-        return data.workItems;
+        return data.workItems ?? [];
     }
     /**
      * Returns all claims.
      *
+     * Always returns an array — `load()` normalizes a missing `claims`
+     * field to `[]` (F-CYCLE7-3).
+     *
      * @returns Array of TaskClaims
      */
     async getClaims() {
         const data = await this.load();
-        return data.claims;
+        return data.claims ?? [];
     }
     /**
      * Finds a work item by ID.

package/dist/cli/backend/src/services/task-pool/pool-storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"pool-storage.js","sourceRoot":"","sources":["../../../../../../backend/src/services/task-pool/pool-storage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pool-storage.js","sourceRoot":"","sources":["../../../../../../backend/src/services/task-pool/pool-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EACL,SAAS,EACT,YAAY,EACZ,eAAe,GAEhB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EAAE,aAAa,EAAwB,MAAM,2BAA2B,CAAC;AAChF,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AA0BjE,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,6DAA6D;AAC7D,MAAM,aAAa,GAAG,WAAW,CAAC;AAElC,mCAAmC;AACnC,MAAM,cAAc,GAAG,WAAW,CAAC;AAEnC,kDAAkD;AAClD,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAE9B,8EAA8E;AAC9E,cAAc;AACd,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,OAAO,WAAW;IACL,QAAQ,CAAS;IACjB,MAAM,CAAkB;IAEzC,wDAAwD;IAChD,KAAK,GAAoB,IAAI,CAAC;IAEtC,iDAAiD;IACzC,UAAU,GAA0B,IAAI,CAAC;IAEjD,kCAAkC;IAC1B,KAAK,GAAG,KAAK,CAAC;IAEtB,YAAY,OAA4B;QACtC,MAAM,OAAO,GACX,OAAO,EAAE,OAAO;YAChB,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,EAAE,aAAa,CAAC,CAAC;QAChD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;QACnD,IAAI,CAAC,MAAM,GAAG,aAAa,CAAC,WAAW,EAAE,CAAC,qBAAqB,CAAC,aAAa,CAAC,CAAC;IACjF,CAAC;IAED,0EAA0E;IAC1E,aAAa;IACb,0EAA0E;IAE1E;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,IAAI;QACR,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC;QAElC,MAAM,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC7C,MAAM,GAAG,GAAG,MAAM,YAAY,CAC5B,IAAI,CAAC,QAAQ,EACb,mBAAmB,EAAE,EACrB,IAAI,CAAC,MAAM,CACZ,CAAC;QACF,+DAA+D;QAC/D,kEAAkE;QAClE,kEAAkE;QAClE,oCAAoC;QACpC,MAAM,UAAU,GAAa;YAC3B,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE;YAC7D,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;YACpD,aAAa,EAAE,GAAG,EAAE,aAAa,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE;SAC/D,CAAC;QACF,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC;QACxB,OAAO,UAAU,CAAC;IACpB,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,YAAY;QAChB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC;IAC9B,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,SAAS;QACb,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;IAC3B,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,YAAY,CAAC,UAAkB;QACnC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,UAAU,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,yBAAyB,CAAC,UAAkB;QAChD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CACrB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,UAAU,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ,CAC5D,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,sBAAsB,CAAC,OAAe;QAC1C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CACrB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ,CACtD,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,WAAW,CAAC,QAAkB;QAClC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC/B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC9B,IAAI,CAAC,SAAS,EAAE,CAAC;IACnB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,cAAc,CAClB,UAAkB,EAClB,OAA+B;QAE/B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,UAAU,CAAC,CAAC;QAC/D,IAAI,CAAC,IAAI;YAAE,OAAO,KAAK,CAAC;QACxB,OAAO,CAAC,IAAI,CAAC,CAAC;QACd,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,cAAc,CAAC,UAAkB;QACrC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,UAAU,CAAC,CAAC;QACnE,IAAI,GAAG,KAAK,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QAC7B,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAC9B,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAQ,CAAC,KAAgB;QAC7B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC/B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,CAAC,SAAS,EAAE,CAAC;IACnB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,WAAW,CACf,OAAe,EACf,OAAmC;QAEnC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,CAAC,CAAC;QACxD,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACzB,OAAO,CAAC,KAAK,CAAC,CAAC;QACf,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC9B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACzB,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,OAAO;QAEvC,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACpD,MAAM,eAAe,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QACjD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,2BAA2B,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,KAAK,GAAG,mBAAmB,EAAE,CAAC;QACnC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO;QACX,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED,0EAA0E;IAC1E,WAAW;IACX,0EAA0E;IAE1E;;OAEG;IACK,SAAS;QACf,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,IAAI,CAAC,UAAU;YAAE,OAAO,CAAC,oBAAoB;QACjD,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC,GAAG,EAAE;YAChC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;YACvB,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;gBACzB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,2BAA2B,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACxE,CAAC,CAAC,CAAC;QACL,CAAC,EAAE,iBAAiB,CAAC,CAAC;IACxB,CAAC;CACF;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO;QACL,SAAS,EAAE,EAAE;QACb,MAAM,EAAE,EAAE;QACV,aAAa,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACxC,CAAC;AACJ,CAAC"}

package/dist/cli/backend/src/services/task-pool/task-pool.service.d.ts

@@ -12,6 +12,57 @@ import { PoolStorage } from './pool-storage.js';
 import { ClaimService, type HeartbeatResult, type ExtendLeaseResult, type ExpiredClaimsSummary } from './claim.service.js';
 import type { WorkItem, WorkItemStatus, WorkItemType, WorkItemOwner } from '../../types/v2/work-item.types.js';
 import { type TaskClaim } from '../../types/v2/claim.types.js';
+import type { EventBusService } from '../event-bus/event-bus.service.js';
+/**
+ * Narrow Request-link contract consumed by {@link TaskPoolService.addToPool}.
+ *
+ * Defined as a duck-typed interface (rather than importing the full
+ * `RequestService` class) so tests can supply fakes without depending on
+ * the RequestService transitive imports, and to keep the dependency
+ * direction one-way: TaskPool → Request, never the reverse.
+ *
+ * P1 Bug B (Pool umbrella WI 72ca743a-3a66-4d0e-a6cf-1a861f849dbd):
+ * the production `linkWorkItem` is idempotent — it short-circuits when
+ * `workItemId` is already in `request.workItemIds[]` — so the
+ * intrinsic-link path here is safe to coexist with downstream
+ * subscriber-driven linking (request-sla.subscriber, V3DataService).
+ */
+export interface IRequestWorkItemLinker {
+    /**
+     * Idempotently link a WorkItem id to a Request's workItemIds[].
+     *
+     * @param requestId - The parent Request id (already on the WI).
+     * @param workItemId - The WorkItem id to link.
+     * @returns The updated Request, or null if the Request was not found.
+     *   `addToPool` ignores the return value — link failure is best-effort.
+     */
+    linkWorkItem(requestId: string, workItemId: string): Promise<unknown>;
+}
+/** Result of {@link TaskPoolService.removeFromPool}. */
+export interface RemoveFromPoolResult {
+    /** `true` when the WorkItem existed and was removed. */
+    removed: boolean;
+    /** The deleted WorkItem (only when removed === true). */
+    workItem?: WorkItem;
+    /** `true` when an active claim was found at delete time. */
+    hadActiveClaim?: boolean;
+    /** Cause when removed === false. */
+    reason?: 'not_found';
+}
+/**
+ * Structured error thrown by {@link TaskPoolService.removeFromPool}
+ * when an active claim exists and `force: true` was not passed.
+ */
+export declare class WorkItemClaimedError extends Error {
+    readonly workItemId: string;
+    readonly claimId: string;
+    readonly claimedBy: string;
+    constructor(args: {
+        workItemId: string;
+        claimId: string;
+        claimedBy: string;
+    });
+}
 /**
  * Filters for claiming work items from the pool.
  */
@@ -79,7 +130,72 @@ export declare class TaskPoolService {
     private readonly storage;
     private readonly claimService;
     private readonly logger;
+    /**
+     * Optional EventBus reference — wired via {@link setEventBusService} from
+     * the boot path. When set, {@link addToPool} publishes a `workitem:queued`
+     * event so subscribers (notably {@link RequestSlaSubscriber}) can react to
+     * queue mutations. Optional because singleton callers (tests, CLI) bring
+     * up the pool before the bus exists; missing bus is treated as a no-op
+     * publish at warn level.
+     */
+    private eventBus;
+    /**
+     * Optional Request-linker reference — wired via {@link setRequestService}
+     * from the boot path. When set, {@link addToPool} pushes the new WI's id
+     * into the parent `Request.workItemIds[]` immediately after the storage
+     * flush, independent of any downstream subscriber.
+     *
+     * P1 Bug B (Pool umbrella WI 72ca743a) intrinsic-link contract:
+     *  - The pre-fix path relied on `workitem:queued` / `task:delegated`
+     *    subscribers (request-sla.subscriber, V3DataService) to backfill
+     *    `Request.workItemIds[]`. Manual / programmatic / cron callers that
+     *    bypass the standard event chain left Requests with
+     *    `workItemIds=[]` even though their WIs were in the pool.
+     *  - The intrinsic path here is the source-of-truth link and runs on
+     *    every `addToPool`. Subscriber-driven linking remains as
+     *    belt-and-suspenders (idempotent — see request.service.ts:328
+     *    short-circuit on duplicate id).
+     *  - Optional because singleton callers (tests, CLI) bring up the pool
+     *    before RequestService exists; missing linker is a no-op debug log.
+     */
+    private requestService;
+    /**
+     * Serializes claim operations to prevent the race where two concurrent
+     * claimFromPool / claimSpecificItem calls both select the same queued
+     * WorkItem between their read and write phases. In-process only — does
+     * not protect against cross-process races, but the backend runs as a
+     * single process today.
+     */
+    private claimMutex;
     constructor(storage?: PoolStorage);
+    /**
+     * Wire the EventBus reference used by {@link addToPool} to publish
+     * `workitem:queued` events (INBOUND-1.f1). Called from the backend boot
+     * path after both services have been constructed. Idempotent and may be
+     * called with `null` to disable publishing (testing).
+     *
+     * @param bus - The EventBus instance, or null to clear
+     */
+    setEventBusService(bus: EventBusService | null): void;
+    /**
+     * Wire the Request-linker reference used by {@link addToPool} to
+     * intrinsically link the new WI into its parent `Request.workItemIds[]`
+     * (P1 Bug B — Pool umbrella WI 72ca743a).
+     *
+     * Called from the backend boot path after both services exist.
+     * Idempotent and may be called with `null` to disable intrinsic
+     * linking (testing). Mirrors the {@link setEventBusService} setter
+     * pattern so the dependency wiring stays uniform and grep-able.
+     *
+     * @param svc - The RequestService instance (or any object satisfying
+     *   {@link IRequestWorkItemLinker}), or null to clear.
+     */
+    setRequestService(svc: IRequestWorkItemLinker | null): void;
+    /**
+     * Chains the given critical section after any in-flight claim operation.
+     * Guarantees FIFO ordering even under concurrent invocation.
+     */
+    private withClaimLock;
     /**
      * Get singleton instance of TaskPoolService.
      *
@@ -93,13 +209,104 @@ export declare class TaskPoolService {
     /**
      * Adds an execution-ready WorkItem to the pool.
      *
-     * The item must have status 'queued' to be added. Items with other
-     * statuses are rejected.
+     * Accepted statuses:
+     * - `queued`  — ready to run
+     * - `blocked` — waiting on unresolved dependsOn; the resolver will promote
+     *               it to `queued` when every upstream dep reaches terminal success.
      *
      * @param workItem - The work item to add
-     * @throws Error if workItem is not valid or not in 'queued' status
+     * @throws Error if workItem is invalid or in an ineligible status
      */
     addToPool(workItem: WorkItem): Promise<void>;
+    /**
+     * P1 Bug B helper: intrinsically link a freshly-added WI into its
+     * parent `Request.workItemIds[]`.
+     *
+     * Stays a separate method (vs inlining) so:
+     *   1. The dependency on RequestService stays explicit and grep-able,
+     *      mirroring {@link publishWorkItemQueued}.
+     *   2. Future enqueue paths (e.g. a batch addAll) can route through
+     *      the same linker for consistent behaviour.
+     *   3. Error handling stays in one place — a thrown linker must NOT
+     *      back out the pool mutation (the storage write already committed).
+     *
+     * @param workItem - The WI just persisted into the pool.
+     */
+    private linkWorkItemToRequest;
+    /**
+     * INBOUND-1.f1 helper: publish a `workitem:queued` event with correlation
+     * ids the SLA subscriber needs (`requestId`, `missionId`, plus the new
+     * `workItemId`). Called by {@link addToPool} after the storage flush.
+     *
+     * Stays a separate method (vs inlining) so:
+     *   1. The dependency on EventBus stays explicit and grep-able.
+     *   2. A future caller adding an alternate enqueue path (e.g. a batch
+     *      addAll) can route through the same publisher for consistent
+     *      observability.
+     *   3. Error handling stays in one place — a thrown publisher must NOT
+     *      back out the pool mutation (the storage write already committed).
+     */
+    private publishWorkItemQueued;
+    /**
+     * F1-BRIDGE-1 helper: publish `task:done_by_worker` after a successful
+     * `submitForVerification` transition. The {@link EventToWorkItemBridge}
+     * subscribes to this event and creates a verification WorkItem for the
+     * resolved team-lead session.
+     *
+     * Stays a separate method (mirrors {@link publishWorkItemQueued}) so:
+     *   1. The dependency on EventBus stays explicit and grep-able — Arch's
+     *      grep guard checks both the type declaration AND a publish call
+     *      site for `task:done_by_worker`.
+     *   2. Error handling is uniform with the other publishers — a thrown
+     *      bus must NOT back out the verified state transition; the storage
+     *      flush has already committed.
+     *   3. A future caller adding an alternate verification-submission path
+     *      (e.g. an admin endpoint or a CLI) routes through the same publisher.
+     *
+     * The deterministic event id (`task:done_by_worker:${workItemId}`) keys
+     * dedup so a redelivered submitForVerification (theoretical) collapses
+     * through the bus without firing the bridge handler twice.
+     */
+    private publishTaskDoneByWorker;
+    /**
+     * F1-BRIDGE-1 helper: publish `task:rejected` after a successful
+     * `verifyItem` transition with verdict='rejected'. The
+     * {@link EventToWorkItemBridge} subscribes and either creates a retry
+     * WI (`retryCount < maxRetries`) or escalates to a TL review WI with
+     * `reviewReason='max_retries_exceeded'` at the cap.
+     *
+     * Mirrors {@link publishTaskDoneByWorker} for symmetry. Only the
+     * verdict='rejected' branch reaches this publisher — `verdict='verified'`
+     * does NOT publish (terminal-success path goes through
+     * {@link resolveBlockedDependents}, which is not a bridge trigger).
+     */
+    private publishTaskRejected;
+    /**
+     * Publish `task:cancelled` whenever a WorkItem transitions to the
+     * cancelled status via {@link updateItemStatus} or {@link transitionStatus}.
+     *
+     * **Why this exists.** 2026-05-09 dogfood: 4 child WIs of a Slack-
+     * originated Request all landed in `cancelled` (orc-not-in-health-map
+     * loop, fixed in #531) but the Request stayed in `ready` for hours.
+     * `cascadeRequestStatus` only fires from V3DataService's task
+     * handlers, which are wired to the retired `v3:task_*` events
+     * (`mission-executor.service.ts:152` v1-cleanup comment) — so out-of-
+     * band cancellations never reached cascade. The heartbeat sweep
+     * eventually caught it (#533), but with up-to-30-min latency that
+     * showed up as a misleading "0/4 in every bucket" ping in the user's
+     * Slack thread.
+     *
+     * Publishing `task:cancelled` lets `RequestCascadeSubscriber` close
+     * the Request within seconds of the last child cancelling, instead
+     * of waiting for the heartbeat catch.
+     *
+     * Mirrors {@link publishTaskDoneByWorker} / {@link publishTaskRejected}
+     * so the EventBus surface stays uniform.
+     *
+     * @param workItem - The WI snapshot AFTER the cancelled transition committed
+     * @param previousStatus - The status it transitioned from (for the event payload)
+     */
+    private publishTaskCancelled;
     /**
      * Claims the next available WorkItem from the pool for an agent.
      *
@@ -132,13 +339,133 @@ export declare class TaskPoolService {
      */
     releaseBack(workItemId: string, reason: string): Promise<void>;
     /**
-     * Marks a work item as completed ('done').
+     * Decide whether a WorkItem requires TL verification before reaching a
+     * terminal-success status.
      *
-     * @param workItemId - ID of the work item
-     * @param result - Optional result data
-     * @throws Error if work item not found or not in 'running' status
+     * Default policy (VERIF-1):
+     *   - `delegate` items default to *requires verification* — a worker
+     *     marking their own delegated work as "done" should produce
+     *     `done_by_worker` and wake the TL for sign-off.
+     *   - All other types (`cron_run`, `notify`, `reconcile`, `check`,
+     *     `confirm`, `review`, ...) default to simple completion (`done`).
+     *
+     * The default is overridable via `wi.metadata.requiresVerification`:
+     *   - `true`  — force verification path even for non-delegate types
+     *   - `false` — skip verification even for delegate types (this is the
+     *     F-H affordance REVIEW-1 needs: review WIs are themselves the
+     *     verification step, so they must NOT loop back to TL self-verify)
+     *
+     * @param wi - The WorkItem under inspection
+     * @returns true when the verification path should fire
+     */
+    private requiresVerification;
+    /**
+     * Internal: release the active claim on a WorkItem (if any). Shared by
+     * `completeSimpleItem` and `submitForVerification` because both
+     * represent the worker handing the item back to the system.
+     *
+     * @param workItemId - WorkItem whose claim should be released
+     * @param endReason - Reason recorded on the claim (`completed` /
+     *   `submitted_for_verification`) for auditability
+     */
+    private releaseClaim;
+    /**
+     * Worker reports a delegated WorkItem as done and submits it for TL
+     * verification.
+     *
+     * Transitions `running → done_by_worker` via {@link transitionStatus},
+     * which enforces the V3 actor-role gate (`'agent'` is allowed; any
+     * other role throws). The active claim is released as
+     * `submitted_for_verification` so the TL queue is the only thing
+     * blocking forward progress.
+     *
+     * Used by the `completeItem` facade for `delegate`-type items and any
+     * item whose `metadata.requiresVerification === true`.
+     *
+     * @param workItemId - WorkItem id
+     * @param actorRole - Role of the caller (`'agent'` for normal worker
+     *   submissions; passed through to `isTransitionPermitted`)
+     * @param result - Optional result payload to attach to the WorkItem
+     * @returns The updated WorkItem, or `null` if the WI was deleted
+     *   between the find and the update (race window)
+     * @throws When the WorkItem is missing, the transition is invalid, or
+     *   the actor is not permitted to perform `running → done_by_worker`.
+     */
+    submitForVerification(workItemId: string, actorRole: WorkItemOwner, result?: Record<string, unknown>): Promise<WorkItem | null>;
+    /**
+     * Worker (or system) marks a non-delegated WorkItem as fully done.
+     *
+     * Transitions `running → done` via {@link transitionStatus}. Used by
+     * the `completeItem` facade for `cron_run`, `notify`, `reconcile`,
+     * `check`, `confirm`, `review` types — anything whose lifecycle does
+     * NOT include a TL verification step.
+     *
+     * The Reconciler service is the only system-actor caller and uses
+     * `actorRole='system'`, which bypasses the actor check while still
+     * respecting the state-machine legality check.
+     *
+     * @param workItemId - WorkItem id
+     * @param actorRole - Role of the caller (`'agent'`, `'system'`, etc.)
+     * @param result - Optional result payload to attach
+     * @returns The updated WorkItem, or `null` if the WI was deleted
+     *   between the find and the update (race window)
+     * @throws When the WorkItem is missing, the transition is invalid, or
+     *   the actor is not permitted to perform `running → done`.
+     */
+    completeSimpleItem(workItemId: string, actorRole: WorkItemOwner, result?: Record<string, unknown>): Promise<WorkItem | null>;
+    /**
+     * TL records a verdict on a WorkItem in `done_by_worker` status.
+     *
+     * `verified` advances to terminal success and unblocks dependents;
+     * `rejected` parks the item until the TL re-queues it (which TRANS-1
+     * gates to TL/orchestrator/system actors). Worker-actor calls throw
+     * automatically via {@link transitionStatus}'s permission gate — we
+     * do NOT need to add an explicit role check here, the matrix in
+     * `TRANSITION_PERMISSIONS` handles it.
+     *
+     * @param workItemId - WorkItem id (must currently be `done_by_worker`)
+     * @param actorRole - Role of the caller (`'team_lead'` or `'orchestrator'`
+     *   for verify/reject; worker calls throw)
+     * @param verdict - `'verified'` or `'rejected'`
+     * @param comment - Optional reviewer comment recorded in `wi.error`
+     *   (the field is reused — the WorkItem schema does not yet have a
+     *   dedicated `verifierComment` slot; keeping this on `error` lets
+     *   downstream UIs render TL feedback alongside failure causes)
+     * @returns The updated WorkItem, or `null` on race-window deletion
+     * @throws When the WorkItem is missing, the verdict is invalid, the
+     *   transition is illegal, or the actor is not permitted to verify.
+     */
+    verifyItem(workItemId: string, actorRole: WorkItemOwner, verdict: 'verified' | 'rejected', comment?: string): Promise<WorkItem | null>;
+    /**
+     * Legacy facade — picks the verification path for the caller.
+     *
+     * Existing call sites (REST controller, task-management controllers,
+     * V3 data service) invoke `completeItem(id, result)` without an
+     * explicit actor role. The facade reads the WorkItem, applies the
+     * {@link requiresVerification} policy, and dispatches to either
+     * {@link submitForVerification} (delegate items / explicit opt-in)
+     * or {@link completeSimpleItem} (everything else).
+     *
+     * The legacy actor role for these implicit callers is `'agent'`.
+     * Migrations to explicit-actor calls can land in follow-up tickets
+     * without touching the five call sites in this PR.
+     *
+     * @param workItemId - WorkItem id
+     * @param result - Optional result payload
+     * @throws When the WorkItem is missing or the underlying transition
+     *   is rejected (invalid state, forbidden actor).
      */
     completeItem(workItemId: string, result?: Record<string, unknown>): Promise<void>;
+    /**
+     * Scans blocked WorkItems that list `completedId` in their `dependsOn` and
+     * promotes each to `queued` if every one of their deps has reached terminal
+     * success (`done` or `verified`). Idempotent and safe to call on any terminal
+     * success transition.
+     *
+     * Serialized via the claim mutex — a concurrent claimFromPool call must not
+     * observe a half-promoted item.
+     */
+    resolveBlockedDependents(completedId: string): Promise<void>;
     /**
      * Marks a work item as failed.
      *
@@ -203,6 +530,62 @@ export declare class TaskPoolService {
      * @returns Array of all WorkItems
      */
     getAllItems(): Promise<WorkItem[]>;
+    /**
+     * Find a WorkItem by id without mutating it.
+     *
+     * Public read accessor used by callers that need to inspect a
+     * specific item — for example REVIEW-1's reentrancy lock checks the
+     * status of a Mission's `pendingReviewWorkItemId` to decide whether
+     * to clear the lock. Returns `null` (not `undefined`) so callers can
+     * use a uniform null-fallthrough idiom shared with
+     * `getWorkItemSnapshot` and `transitionStatus`.
+     *
+     * @param workItemId - WorkItem id to look up
+     * @returns The WorkItem, or `null` if no item has that id
+     */
+    findWorkItem(workItemId: string): Promise<WorkItem | null>;
+    /**
+     * Stores worker-supplied structured output on a WorkItem.
+     *
+     * Replaces the v1 `<taskId>.output.json` filesystem store with an
+     * in-pool field (see {@link WorkItem.output}). Used by the worker
+     * `complete-task` flow and read back by the TL `verify-output` skill.
+     *
+     * @param workItemId - WorkItem id to attach output to
+     * @param output - Arbitrary task-specific output object
+     * @returns The updated WorkItem, or null if not found
+     */
+    setOutput(workItemId: string, output: Record<string, unknown>): Promise<WorkItem | null>;
+    /**
+     * Reassigns a WorkItem to a different target agent.
+     *
+     * Replaces the v1 `/task-management/handoff` filesystem reassign with a
+     * direct `target` field update on the WorkItem.
+     *
+     * Allowed transitions:
+     *   - `target` must be a non-empty string
+     *   - WI must not be in a terminal state (done/cancelled/failed-final)
+     *
+     * @param workItemId - WorkItem to reassign
+     * @param newTarget  - Session name of the new target agent
+     * @param fromAgent  - Session name of the agent handing off (for audit)
+     * @param reason     - Human-readable reason recorded as a working-note
+     * @returns The updated WorkItem, or null if not found
+     */
+    handoff(workItemId: string, newTarget: string, fromAgent: string, reason: string): Promise<WorkItem | null>;
+    /**
+     * Appends a working-state note to a WorkItem's metadata.notes array.
+     *
+     * Replaces v1 `/task-management/sync` and `/task-management/save-working-notes`,
+     * both of which appended progress notes to the `.md` task body. With v1
+     * retired, notes live on the WorkItem itself under `metadata.notes[]`.
+     *
+     * @param workItemId - WorkItem id
+     * @param author - Session name of note author
+     * @param note - Note content (free-form)
+     * @returns The updated WorkItem, or null if not found
+     */
+    appendNote(workItemId: string, author: string, note: string): Promise<WorkItem | null>;
     /**
      * Removes a WorkItem from the pool entirely.
      * Used for purging old completed/cancelled items.
@@ -210,6 +593,22 @@ export declare class TaskPoolService {
      * @param workItemId - ID of the item to remove
      */
     removeItem(workItemId: string): Promise<void>;
+    /**
+     * Public delete API used by the bulk-cleanup script and the new
+     * `DELETE /api/task-pool/:id` HTTP endpoint (P1 umbrella WI 1ffffb84
+     * component a, Steve directive 2026-05-06: just-DELETE-not-backfill).
+     *
+     * Three guarantees over {@link removeItem}:
+     *   1. Idempotent — `not_found` is a no-op return, not a throw.
+     *   2. Claim-safety — refuses claimed delete unless `opts.force`.
+     *   3. Audit log — single info-level log per removal.
+     *
+     * Force path also revokes the orphaned claim (status='revoked',
+     * endedAt, endReason).
+     */
+    removeFromPool(workItemId: string, opts?: {
+        force?: boolean;
+    }): Promise<RemoveFromPoolResult>;
     /**
      * Forces an immediate flush of pool data to disk.
      * Called during graceful shutdown to prevent data loss.
@@ -226,11 +625,62 @@ export declare class TaskPoolService {
      * Updates a work item's status directly.
      * Used by the Reconciler for corrections (e.g., stuck → blocked).
      *
+     * Reconciler invocations pass through `actorRole='system'` (default) which
+     * bypasses the per-role gate at {@link isTransitionPermitted} but still
+     * enforces the state-machine via {@link isValidWorkItemTransition}. Other
+     * callers MUST supply the actor's role so TRANS-1 V3 enforcement applies.
+     *
      * @param workItemId - The work item ID
      * @param newStatus - The target status
-     * @throws Error if work item not found or transition is invalid
+     * @param actorRole - Role of the caller (defaults to `'system'` for Reconciler)
+     * @throws Error if work item not found
+     * @throws Error if transition is invalid (state machine — see WORK_ITEM_TRANSITIONS)
+     * @throws Error if actor is not permitted (role check — see TRANSITION_PERMISSIONS)
+     */
+    updateItemStatus(workItemId: string, newStatus: WorkItemStatus, actorRole?: WorkItemOwner): Promise<void>;
+    /**
+     * Public guarded transition helper — TRANS-1's canonical entrypoint.
+     *
+     * Routes any externally-initiated WorkItem status change through the
+     * combined state-machine + actor-role gates. Designed as the public API
+     * VERIF-1 will call from `submitForVerification` / `verifyItem`, and as
+     * the recommended path for any future caller that previously reached
+     * for `storage.updateWorkItem` to flip status.
+     *
+     * Differences vs {@link updateItemStatus}:
+     *   - Requires `actorRole` explicitly (no default) — forces the caller to
+     *     decide the trust posture rather than silently inheriting `'system'`.
+     *   - Accepts an optional `mutator` so callers can carry additional field
+     *     updates (e.g. `result`, `error`, `completedAt`) atomically with the
+     *     status flip — preventing races between status update and metadata
+     *     attachment that direct `storage.updateWorkItem` callers risked.
+     *
+     * @param workItemId - The work item ID
+     * @param newStatus - The target status
+     * @param actorRole - Role of the caller (REQUIRED; pass `'system'` for trusted server-internal paths)
+     * @param mutator - Optional additional WorkItem field updates applied atomically with the status change
+     * @returns The updated WorkItem after the transition
+     * @throws Error if work item not found
+     * @throws Error if transition is invalid (state machine)
+     * @throws Error if actor is not permitted (role check)
+     *
+     * @example
+     * ```typescript
+     * // VERIF-1 worker submitting for verification
+     * await pool.transitionStatus(wiId, 'done_by_worker', 'agent', (wi) => {
+     *   wi.result = output;
+     * });
+     *
+     * // VERIF-1 TL verifying
+     * await pool.transitionStatus(wiId, 'verified', 'team_lead');
+     *
+     * // VERIF-1 TL rejecting (allowed for TL only)
+     * await pool.transitionStatus(wiId, 'rejected', 'team_lead', (wi) => {
+     *   wi.error = 'Did not meet acceptance criteria';
+     * });
+     * ```
      */
-    updateItemStatus(workItemId: string, newStatus: WorkItemStatus): Promise<void>;
+    transitionStatus(workItemId: string, newStatus: WorkItemStatus, actorRole: WorkItemOwner, mutator?: (wi: WorkItem) => void): Promise<WorkItem | null>;
     /**
      * Update token usage and cost on a WorkItem.
      * Called after task completion when token data is available from TokenUsageService.