canopycms 0.0.54 → 0.0.56

package/dist/validation/field-traversal.d.ts

@@ -5,7 +5,7 @@
  * according to a schema, handling objects, blocks, and arrays with their
  * own schemas.
  */
-import type { FieldConfig } from '../config';
+import type { FieldConfig, BlockFieldConfig } from '../config';
 /**
  * Context provided to the visitor function for each field.
  */
@@ -22,6 +22,28 @@ export interface TraversalContext {
  * Return an empty array to skip this field, or return items to collect.
  */
 export type FieldVisitor<T> = (context: TraversalContext) => T[];
+/**
+ * A block item resolved to its template fields and the data record that
+ * holds the nested field values.
+ */
+export interface ResolvedBlockItem {
+    /** The template's field schema */
+    fields: FieldConfig[];
+    /** The record containing the block's nested field values */
+    data: Record<string, unknown>;
+}
+/**
+ * Resolve a block item to its template fields and nested data record.
+ *
+ * Real block data — as produced by the editor (BlockField.tsx) and persisted
+ * by ContentStore — has the shape `{ template: string, value: {...} }`:
+ * the template name lives on `template` and the nested field values live
+ * under `value`. A `_type` discriminator with inline field values is also
+ * accepted defensively (mirroring ai/json-to-markdown.ts).
+ *
+ * Returns undefined when the item has no resolvable template.
+ */
+export declare function resolveBlockItem(blockField: BlockFieldConfig, item: Record<string, unknown>): ResolvedBlockItem | undefined;
 /**
  * Recursively traverse fields in data according to schema.
  *

package/dist/validation/field-traversal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"field-traversal.d.ts","sourceRoot":"","sources":["../../src/validation/field-traversal.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,WAAW,EAIZ,MAAM,WAAW,CAAA;AAElB;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,KAAK,EAAE,WAAW,CAAA;IAClB,0CAA0C;IAC1C,KAAK,EAAE,OAAO,CAAA;IACd,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,gBAAgB,KAAK,CAAC,EAAE,CAAA;AAiBhE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EACxB,UAAU,SAAK,GACd,CAAC,EAAE,CA0EL;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,SAAS,EAAE,MAAM,GAChB,gBAAgB,EAAE,CAOpB"}
+{"version":3,"file":"field-traversal.d.ts","sourceRoot":"","sources":["../../src/validation/field-traversal.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,WAAW,EAEX,gBAAgB,EAEjB,MAAM,WAAW,CAAA;AAElB;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,KAAK,EAAE,WAAW,CAAA;IAClB,0CAA0C;IAC1C,KAAK,EAAE,OAAO,CAAA;IACd,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,gBAAgB,KAAK,CAAC,EAAE,CAAA;AAEhE;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,kCAAkC;IAClC,MAAM,EAAE,WAAW,EAAE,CAAA;IACrB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC9B;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,gBAAgB,EAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,iBAAiB,GAAG,SAAS,CAkB/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EACxB,UAAU,SAAK,GACd,CAAC,EAAE,CA0EL;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,SAAS,EAAE,MAAM,GAChB,gBAAgB,EAAE,CAOpB"}

package/dist/validation/field-traversal.js

@@ -5,16 +5,36 @@
  * according to a schema, handling objects, blocks, and arrays with their
  * own schemas.
  */
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 /**
- * Get the nested fields for a block template by looking up _type.
+ * Resolve a block item to its template fields and nested data record.
+ *
+ * Real block data — as produced by the editor (BlockField.tsx) and persisted
+ * by ContentStore — has the shape `{ template: string, value: {...} }`:
+ * the template name lives on `template` and the nested field values live
+ * under `value`. A `_type` discriminator with inline field values is also
+ * accepted defensively (mirroring ai/json-to-markdown.ts).
+ *
+ * Returns undefined when the item has no resolvable template.
  */
-function getBlockTemplateFields(blockField, item) {
-    const blockType = item._type;
-    if (!blockType)
+export function resolveBlockItem(blockField, item) {
+    const templateName = typeof item.template === 'string'
+        ? item.template
+        : typeof item._type === 'string'
+            ? item._type
+            : undefined;
+    if (!templateName)
         return undefined;
     // Block fields use 'templates' property
-    const template = blockField.templates?.find((t) => t.name === blockType);
-    return template?.fields;
+    const template = blockField.templates?.find((t) => t.name === templateName);
+    if (!template?.fields)
+        return undefined;
+    // Nested field values live under `value` in the canonical shape; fall back
+    // to the item itself for the inline `_type` shape.
+    const data = isPlainRecord(item.value) ? item.value : item;
+    return { fields: template.fields, data };
 }
 /**
  * Recursively traverse fields in data according to schema.
@@ -81,9 +101,9 @@ export function traverseFields(fields, data, visitor, pathPrefix = '') {
             if (Array.isArray(value)) {
                 value.forEach((item, index) => {
                     if (typeof item === 'object' && item !== null) {
-                        const blockFields = getBlockTemplateFields(blockField, item);
-                        if (blockFields) {
-                            results.push(...traverseFields(blockFields, item, visitor, `${fieldPath}[${index}]`));
+                        const resolved = resolveBlockItem(blockField, item);
+                        if (resolved) {
+                            results.push(...traverseFields(resolved.fields, resolved.data, visitor, `${fieldPath}[${index}]`));
                         }
                     }
                 });

package/dist/validation/field-traversal.js.map

@@ -1 +1 @@
-{"version":3,"file":"field-traversal.js","sourceRoot":"","sources":["../../src/validation/field-traversal.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"field-traversal.js","sourceRoot":"","sources":["../../src/validation/field-traversal.ts"],"names":[],"mappings":"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"}

package/dist/worker/cms-worker.d.ts

@@ -35,7 +35,45 @@ export interface CmsWorkerConfig {
     maxRetries?: number;
     /** Content root directory name relative to repo root (default: 'content') */
     contentRoot?: string;
+    /**
+     * Worker lock staleness TTL in ms (default: 60000, minimum 2000).
+     * The holder refreshes the lock heartbeat at half this interval; a lock
+     * whose heartbeat is older than this is considered abandoned and taken
+     * over by the next worker to start.
+     */
+    lockStaleMs?: number;
+}
+/**
+ * An error inherent to the task itself (malformed payload, unknown action):
+ * retrying can never succeed, so the task should fail fast instead of
+ * burning its retry budget.
+ */
+export declare class PermanentTaskError extends Error {
 }
+/**
+ * Classify a task failure as permanent (fail fast) or transient (retry).
+ *
+ * Transient — worth retrying with backoff:
+ * - network errors / anything without an HTTP status (git failures included:
+ *   most push/fetch failures are connectivity or contention and the retry
+ *   budget bounds the pathological cases)
+ * - HTTP 408 (request timeout) and 429 (rate limited)
+ * - HTTP 403 that carries a rate-limit signal (see `isRateLimitSignal403`):
+ *   GitHub returns 403, not 429, for both primary and secondary/abuse rate
+ *   limits. The throttling plugin (see github-service.ts createCanopyOctokit)
+ *   proactively retries short waits, but this carve-out remains the safety
+ *   net for waits the plugin gives up on (`shouldRetryRateLimit`/
+ *   `shouldRetrySecondaryRateLimit`) and for errors it never sees — without
+ *   it a rate-limited push-and-create-or-update-pr task would fail
+ *   permanently and wedge the branch (`sync-failed`, no retry).
+ * - HTTP 5xx (server-side, usually recovers)
+ *
+ * Permanent — retrying the identical request cannot succeed:
+ * - PermanentTaskError (malformed payload, unknown action)
+ * - other HTTP 4xx (e.g. 401/404/422): the request itself is bad
+ * - plain HTTP 403 with no rate-limit signal: a real permission denial
+ */
+export declare function isPermanentTaskFailure(err: unknown): boolean;
 /**
  * CMS Worker daemon.
  * Handles operations that Lambda (with no internet) cannot perform:
@@ -61,19 +99,40 @@ export declare class CmsWorker {
     private taskTimeoutMs;
     private maxRetries;
     private lockFilePath;
+    private lockStaleMs;
+    private releaseLockFn;
     private contentRoot;
     private log;
     constructor(config: CmsWorkerConfig);
     start(): Promise<void>;
     stop(): Promise<void>;
     /**
-     * Acquire an EFS-based lock file to prevent concurrent workers.
-     * Uses O_CREAT|O_EXCL for atomic file creation.
-     * Stale locks (older than 10 minutes with no running PID) are overwritten.
+     * Acquire the cross-host worker lock (DEP-C2).
+     *
+     * The task queue is single-consumer (see task-queue/task-queue.ts): two
+     * concurrent workers would double-process tasks (duplicate pushes, duplicate
+     * PRs). The workspace lives on a shared filesystem (EFS), so mutual
+     * exclusion must be sound ACROSS HOSTS — a PID liveness probe
+     * (`process.kill(pid, 0)`) only means something on the holder's own machine
+     * and must never participate in staleness decisions.
+     *
+     * proper-lockfile provides a heartbeat lease with no PID involved: the lock
+     * is a directory created atomically (mkdir — atomic on NFS/EFS), the holder
+     * refreshes its mtime every lockStaleMs/2, and the lock is considered
+     * abandoned — and taken over — only when that heartbeat is older than
+     * lockStaleMs. Liveness is judged purely by heartbeat freshness.
+     *
+     * No acquire retries: a second worker exits immediately, matching daemon
+     * semantics (the supervisor restarts it later). After a crash, the dead
+     * holder's heartbeat expires within lockStaleMs and the next start succeeds.
+     *
+     * Staleness is judged by comparing the lock's mtime against the local
+     * clock, so correct cross-host takeover assumes reasonable clock agreement
+     * between hosts (e.g. NTP); with the default TTL, ordinary clock skew is
+     * negligible, but a host with a badly wrong clock could misjudge liveness.
      */
     private acquireLock;
     private releaseLock;
-    private isPidAlive;
     /**
      * Schedule a function to run repeatedly with setTimeout chaining.
      * The next invocation starts `interval` ms after the previous one completes,
@@ -93,8 +152,13 @@ export declare class CmsWorker {
      */
     processTaskQueue(): Promise<void>;
     /**
-     * Execute a task with a timeout. Uses AbortController to cancel
-     * the underlying operation if the timeout fires.
+     * Execute a task bounded by taskTimeoutMs (DEP-H1). Two layers:
+     * - An AbortSignal cancels Octokit HTTP calls promptly.
+     * - A Promise.race rejects when the timeout fires, so work that cannot
+     *   observe the signal (git subprocesses via simple-git) still fails the
+     *   attempt and the worker moves on instead of stalling forever.
+     * pushBranchToGitHub additionally kills stalled git processes via
+     * simple-git's block timeout, so a hung push doesn't leak a process.
      */
     private executeTaskWithTimeout;
     private executeTask;

package/dist/worker/cms-worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cms-worker.d.ts","sourceRoot":"","sources":["../../src/worker/cms-worker.ts"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;AAEpD,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAA;IACrB,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAA;IACnB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAA;IAClB,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,kBAAkB,CAAA;IACrC,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,uDAAuD;IACvD,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,kEAAkE;IAClE,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,8CAA8C;IAC9C,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAwBD;;;;;;;;;;GAUG;AACH,qBAAa,SAAS;IAgBR,OAAO,CAAC,MAAM;IAf1B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,mBAAmB,CAAQ;IACnC,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,cAAc,CAA4B;IAClD,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,gBAAgB,CAA2B;IACnD,OAAO,CAAC,gBAAgB,CAAQ;IAChC,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,YAAY,CAAQ;IAC5B,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,GAAG,CAAqB;gBAEZ,MAAM,EAAE,eAAe;IAarC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0CtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB3B;;;;OAIG;YACW,WAAW;YAoDX,WAAW;IAQzB,OAAO,CAAC,UAAU;IASlB;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAkBpB;;;OAGG;YACW,eAAe;IAe7B;;;;;OAKG;IACG,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAgCvC;;;OAGG;YACW,sBAAsB;YAUtB,WAAW;IAyHzB;;;OAGG;YACW,oBAAoB;IA4BlC;;;OAGG;YACW,6BAA6B;IAsB3C,OAAO,CAAC,cAAc;YAIR,kBAAkB;IAOhC;;;OAGG;YACW,oBAAoB;IAqB5B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAsBhB,oBAAoB;IAwL5B,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;CAYxC"}
+{"version":3,"file":"cms-worker.d.ts","sourceRoot":"","sources":["../../src/worker/cms-worker.ts"],"names":[],"mappings":"AAsBA;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;AAEpD,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAA;IACrB,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAA;IACnB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAA;IAClB,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,kBAAkB,CAAA;IACrC,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,uDAAuD;IACvD,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,kEAAkE;IAClE,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,8CAA8C;IAC9C,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAMD;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;CAAG;AAEhD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAO5D;AA2DD;;;;;;;;;;GAUG;AACH,qBAAa,SAAS;IAkBR,OAAO,CAAC,MAAM;IAjB1B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,mBAAmB,CAAQ;IACnC,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,cAAc,CAA4B;IAClD,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,gBAAgB,CAA2B;IACnD,OAAO,CAAC,gBAAgB,CAAQ;IAChC,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,YAAY,CAAQ;IAC5B,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,aAAa,CAAqC;IAC1D,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,GAAG,CAAqB;gBAEZ,MAAM,EAAE,eAAe;IAcrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0CtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB3B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;YACW,WAAW;YAyBX,WAAW;IAWzB;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAkBpB;;;OAGG;YACW,eAAe;IAe7B;;;;;OAKG;IACG,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAwCvC;;;;;;;;OAQG;YACW,sBAAsB;YAqBtB,WAAW;IAkHzB;;;OAGG;YACW,oBAAoB;IA4BlC;;;OAGG;YACW,6BAA6B;IAsB3C,OAAO,CAAC,cAAc;YAIR,kBAAkB;IAahC;;;OAGG;YACW,oBAAoB;IAqB5B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YA4BhB,oBAAoB;IA8L5B,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;CAYxC"}

package/dist/worker/cms-worker.js

@@ -1,25 +1,110 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { simpleGit } from 'simple-git';
-import { Octokit } from '@octokit/rest';
+import lockfile from 'proper-lockfile';
 import { dequeueTask, completeTask, failTask, retryTask, recoverOrphanedTasks, cleanupOldTasks, cmsTaskQueueLogger, } from './task-queue.js';
+import { createOrUpdatePullRequest, createCanopyOctokit } from '../github-service.js';
 import { getBranchMetadataFileManager, BranchMetadataFileManager } from '../branch-metadata.js';
 import { extractIdFromFilename } from '../content-id-index.js';
+import { invalidateContentIndexesDurable } from '../content-index-generation.js';
 import { ROOT_COLLECTION_ID } from '../paths/types.js';
-import { isFileExistsError } from '../utils/error.js';
+import { getErrorMessage, isNodeError } from '../utils/error.js';
 const DEFAULT_TASK_TIMEOUT = 60_000;
 const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_LOCK_STALE_MS = 60_000;
+/**
+ * An error inherent to the task itself (malformed payload, unknown action):
+ * retrying can never succeed, so the task should fail fast instead of
+ * burning its retry budget.
+ */
+export class PermanentTaskError extends Error {
+}
+/**
+ * Classify a task failure as permanent (fail fast) or transient (retry).
+ *
+ * Transient — worth retrying with backoff:
+ * - network errors / anything without an HTTP status (git failures included:
+ *   most push/fetch failures are connectivity or contention and the retry
+ *   budget bounds the pathological cases)
+ * - HTTP 408 (request timeout) and 429 (rate limited)
+ * - HTTP 403 that carries a rate-limit signal (see `isRateLimitSignal403`):
+ *   GitHub returns 403, not 429, for both primary and secondary/abuse rate
+ *   limits. The throttling plugin (see github-service.ts createCanopyOctokit)
+ *   proactively retries short waits, but this carve-out remains the safety
+ *   net for waits the plugin gives up on (`shouldRetryRateLimit`/
+ *   `shouldRetrySecondaryRateLimit`) and for errors it never sees — without
+ *   it a rate-limited push-and-create-or-update-pr task would fail
+ *   permanently and wedge the branch (`sync-failed`, no retry).
+ * - HTTP 5xx (server-side, usually recovers)
+ *
+ * Permanent — retrying the identical request cannot succeed:
+ * - PermanentTaskError (malformed payload, unknown action)
+ * - other HTTP 4xx (e.g. 401/404/422): the request itself is bad
+ * - plain HTTP 403 with no rate-limit signal: a real permission denial
+ */
+export function isPermanentTaskFailure(err) {
+    if (err instanceof PermanentTaskError)
+        return true;
+    const status = getHttpStatus(err);
+    if (status === null)
+        return false;
+    if (status === 408 || status === 429)
+        return false;
+    if (status === 403 && isRateLimitSignal403(err))
+        return false;
+    return status >= 400 && status < 500;
+}
+/** Extract an HTTP status from an error, if present (Octokit RequestError shape). */
+function getHttpStatus(err) {
+    if (err instanceof Error && 'status' in err) {
+        const status = err.status;
+        if (typeof status === 'number')
+            return status;
+    }
+    return null;
+}
+/** Narrow an unknown value to a response-headers record, if present (Octokit lowercases header names). */
+function getResponseHeaders(err) {
+    if (typeof err !== 'object' || err === null || !('response' in err))
+        return null;
+    const response = err.response;
+    if (typeof response !== 'object' || response === null || !('headers' in response))
+        return null;
+    const headers = response.headers;
+    if (typeof headers !== 'object' || headers === null)
+        return null;
+    return headers;
+}
+/**
+ * Detect whether a 403 is a GitHub rate-limit response rather than a plain
+ * permission denial. GitHub signals rate limiting on 403s three ways: the
+ * primary limit zeroes out `x-ratelimit-remaining`, secondary/abuse limits
+ * often include a `retry-after` header, and both cases produce a message
+ * containing "rate limit" (e.g. "You have exceeded a secondary rate limit").
+ */
+function isRateLimitSignal403(err) {
+    const headers = getResponseHeaders(err);
+    if (headers) {
+        if (headers['x-ratelimit-remaining'] === '0')
+            return true;
+        if (typeof headers['retry-after'] === 'string' && headers['retry-after'].length > 0)
+            return true;
+    }
+    if (err instanceof Error && /rate limit/i.test(err.message))
+        return true;
+    return false;
+}
 // Payload validation helpers — fail fast with clear errors instead of silent `as` casts
 function requireString(payload, key) {
     const val = payload[key];
     if (typeof val !== 'string')
-        throw new Error(`Task payload missing required string field: ${key}`);
+        throw new PermanentTaskError(`Task payload missing required string field: ${key}`);
     return val;
 }
 function requireNumber(payload, key) {
     const val = payload[key];
     if (typeof val !== 'number')
-        throw new Error(`Task payload missing required number field: ${key}`);
+        throw new PermanentTaskError(`Task payload missing required number field: ${key}`);
     return val;
 }
 function optionalString(payload, key, fallback) {
@@ -43,8 +128,9 @@ export class CmsWorker {
         this.activeTimeouts = new Set();
         this.running = false;
         this.activeOperations = new Set();
+        this.releaseLockFn = null;
         this.log = cmsTaskQueueLogger;
-        this.octokit = new Octokit({ auth: config.githubToken });
+        this.octokit = createCanopyOctokit({ auth: config.githubToken });
         this.taskDir = path.join(config.workspacePath, '.tasks');
         this.remoteGitPath = path.join(config.workspacePath, 'remote.git');
         this.contentBranchesPath = path.join(config.workspacePath, 'content-branches');
@@ -53,6 +139,7 @@ export class CmsWorker {
         this.taskTimeoutMs = config.taskTimeoutMs ?? DEFAULT_TASK_TIMEOUT;
         this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
         this.lockFilePath = path.join(config.workspacePath, '.tasks', '.worker-lock');
+        this.lockStaleMs = config.lockStaleMs ?? DEFAULT_LOCK_STALE_MS;
         this.contentRoot = config.contentRoot ?? 'content';
     }
     async start() {
@@ -107,72 +194,63 @@ export class CmsWorker {
         console.log('CMS Worker stopped');
     }
     /**
-     * Acquire an EFS-based lock file to prevent concurrent workers.
-     * Uses O_CREAT|O_EXCL for atomic file creation.
-     * Stale locks (older than 10 minutes with no running PID) are overwritten.
+     * Acquire the cross-host worker lock (DEP-C2).
+     *
+     * The task queue is single-consumer (see task-queue/task-queue.ts): two
+     * concurrent workers would double-process tasks (duplicate pushes, duplicate
+     * PRs). The workspace lives on a shared filesystem (EFS), so mutual
+     * exclusion must be sound ACROSS HOSTS — a PID liveness probe
+     * (`process.kill(pid, 0)`) only means something on the holder's own machine
+     * and must never participate in staleness decisions.
+     *
+     * proper-lockfile provides a heartbeat lease with no PID involved: the lock
+     * is a directory created atomically (mkdir — atomic on NFS/EFS), the holder
+     * refreshes its mtime every lockStaleMs/2, and the lock is considered
+     * abandoned — and taken over — only when that heartbeat is older than
+     * lockStaleMs. Liveness is judged purely by heartbeat freshness.
+     *
+     * No acquire retries: a second worker exits immediately, matching daemon
+     * semantics (the supervisor restarts it later). After a crash, the dead
+     * holder's heartbeat expires within lockStaleMs and the next start succeeds.
+     *
+     * Staleness is judged by comparing the lock's mtime against the local
+     * clock, so correct cross-host takeover assumes reasonable clock agreement
+     * between hosts (e.g. NTP); with the default TTL, ordinary clock skew is
+     * negligible, but a host with a badly wrong clock could misjudge liveness.
      */
     async acquireLock() {
-        await fs.mkdir(path.dirname(this.lockFilePath), { recursive: true });
-        const lockContent = JSON.stringify({
-            pid: process.pid,
-            timestamp: new Date().toISOString(),
-        });
-        // Try atomic create first
+        await fs.mkdir(this.taskDir, { recursive: true });
         try {
-            const handle = await fs.open(this.lockFilePath, 'wx');
-            await handle.writeFile(lockContent, 'utf-8');
-            await handle.close();
-            return;
+            this.releaseLockFn = await lockfile.lock(this.taskDir, {
+                lockfilePath: this.lockFilePath,
+                stale: this.lockStaleMs,
+                onCompromised: (err) => {
+                    // Our heartbeat could not be maintained (lock deleted or taken
+                    // over). Another worker may now be consuming the queue — stop
+                    // processing to preserve the single-consumer invariant.
+                    console.error('Worker lock compromised, shutting down:', getErrorMessage(err));
+                    this.releaseLockFn = null; // the lock is already lost; nothing to release
+                    void this.stop();
+                },
+            });
         }
         catch (err) {
-            if (!isFileExistsError(err))
-                throw err;
-        }
-        // Lock file exists — check staleness
-        try {
-            const content = await fs.readFile(this.lockFilePath, 'utf-8');
-            const { pid, timestamp } = JSON.parse(content);
-            const lockAgeMs = Date.now() - new Date(timestamp).getTime();
-            const pidAlive = this.isPidAlive(pid);
-            if (pidAlive && lockAgeMs < 10 * 60_000) {
-                throw new Error(`Another worker is running (PID ${pid}, locked at ${timestamp}). Exiting.`);
-            }
-            console.log(`Overwriting stale lock (PID ${pid}, age ${Math.round(lockAgeMs / 1000)}s)`);
-        }
-        catch (err) {
-            if (err instanceof Error && err.message.startsWith('Another worker'))
-                throw err;
-            // Lock file is corrupt or unreadable — overwrite it
-        }
-        // Stale or corrupt lock — unlink and retry with atomic create
-        await fs.unlink(this.lockFilePath).catch(() => { });
-        try {
-            const handle = await fs.open(this.lockFilePath, 'wx');
-            await handle.writeFile(lockContent, 'utf-8');
-            await handle.close();
-        }
-        catch (err) {
-            if (isFileExistsError(err)) {
-                throw new Error('Another worker acquired the lock during stale lock recovery. Exiting.');
+            if (isNodeError(err) && err.code === 'ELOCKED') {
+                throw new Error(`Another worker is running (lock ${this.lockFilePath} has a heartbeat fresher than ${this.lockStaleMs}ms). Exiting.`);
             }
             throw err;
         }
     }
     async releaseLock() {
+        const release = this.releaseLockFn;
+        this.releaseLockFn = null;
+        if (!release)
+            return;
         try {
-            await fs.unlink(this.lockFilePath);
-        }
-        catch {
-            // Lock file already gone
-        }
-    }
-    isPidAlive(pid) {
-        try {
-            process.kill(pid, 0);
-            return true;
+            await release();
         }
         catch {
-            return false;
+            // Lock already released or compromised
         }
     }
     /**
@@ -236,32 +314,50 @@ export class CmsWorker {
                 await this.updateBranchMetadata(task, result);
             }
             catch (err) {
-                const message = err instanceof Error ? err.message : 'Unknown error';
+                const message = getErrorMessage(err);
                 console.error(`Task ${task.id} (${task.action}) failed:`, message);
+                // DEP-L1: only transient failures (network, 429/5xx, timeouts) are
+                // worth retrying; permanent ones (malformed payload, other 4xx) would
+                // just burn the retry budget on an identical doomed request.
+                const permanent = isPermanentTaskFailure(err);
                 const retryCount = task.retryCount ?? 0;
                 const maxRetries = task.maxRetries ?? this.maxRetries;
-                if (retryCount < maxRetries) {
+                if (!permanent && retryCount < maxRetries) {
                     await retryTask(this.taskDir, task.id, message, this.log);
                     console.log(`  Will retry (attempt ${retryCount + 1}/${maxRetries})`);
                 }
                 else {
                     await failTask(this.taskDir, task.id, message, this.log);
                     await this.updateBranchMetadataOnFailure(task, message);
-                    console.error(`  Permanently failed after ${maxRetries} retries`);
+                    console.error(permanent
+                        ? '  Permanently failed (non-retryable error)'
+                        : `  Permanently failed after ${maxRetries} retries`);
                 }
             }
             processed++;
         }
     }
     /**
-     * Execute a task with a timeout. Uses AbortController to cancel
-     * the underlying operation if the timeout fires.
+     * Execute a task bounded by taskTimeoutMs (DEP-H1). Two layers:
+     * - An AbortSignal cancels Octokit HTTP calls promptly.
+     * - A Promise.race rejects when the timeout fires, so work that cannot
+     *   observe the signal (git subprocesses via simple-git) still fails the
+     *   attempt and the worker moves on instead of stalling forever.
+     * pushBranchToGitHub additionally kills stalled git processes via
+     * simple-git's block timeout, so a hung push doesn't leak a process.
      */
     async executeTaskWithTimeout(task) {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), this.taskTimeoutMs);
         try {
-            return await this.executeTask(task, controller.signal);
+            const work = this.executeTask(task, controller.signal);
+            // If the timeout wins the race, the losing promise must not surface an
+            // unhandled rejection when it eventually settles.
+            work.catch(() => { });
+            const timedOut = new Promise((_, reject) => {
+                controller.signal.addEventListener('abort', () => reject(new Error(`Task timed out after ${this.taskTimeoutMs}ms`)), { once: true });
+            });
+            return await Promise.race([work, timedOut]);
         }
         finally {
             clearTimeout(timer);
@@ -306,40 +402,33 @@ export class CmsWorker {
                 return { prNumber };
             }
             case 'push-and-create-or-update-pr': {
+                // GIT-H1: idempotent create-or-update. Used for both content-branch
+                // submits and settings-branch syncs so a retry after a crash (task
+                // completed on GitHub but branch metadata never recorded the PR
+                // number) recovers the existing PR instead of hitting the 422 that
+                // a blind `pulls.create` would throw on a duplicate head+base.
+                // Delegates to the shared helper (also used by GitHubService's
+                // direct-API path) so the list->tiebreak->update/create logic and
+                // the draft->ready conversion live in one place.
                 const branch = requireString(payload, 'branch');
                 await this.pushBranchToGitHub(branch);
-                // Check if an open PR already exists for this branch
-                const existingPRs = await this.octokit.pulls.list({
-                    owner: this.config.githubOwner,
-                    repo: this.config.githubRepo,
-                    head: `${this.config.githubOwner}:${branch}`,
-                    base: optionalString(payload, 'baseBranch', this.baseBranch),
-                    state: 'open',
-                    request: { signal },
-                });
-                if (existingPRs.data.length > 0) {
-                    const existing = existingPRs.data[0];
-                    await this.octokit.pulls.update({
-                        owner: this.config.githubOwner,
-                        repo: this.config.githubRepo,
-                        pull_number: existing.number,
-                        body: optionalString(payload, 'body', ''),
-                        request: { signal },
-                    });
-                    console.log(`Updated existing PR #${existing.number} for ${branch}`);
-                    return { prUrl: existing.html_url, prNumber: existing.number };
-                }
-                const newPr = await this.octokit.pulls.create({
+                const result = await createOrUpdatePullRequest({
+                    octokit: this.octokit,
                     owner: this.config.githubOwner,
                     repo: this.config.githubRepo,
                     head: branch,
                     base: optionalString(payload, 'baseBranch', this.baseBranch),
-                    title: optionalString(payload, 'title', `Settings update`),
+                    title: optionalString(payload, 'title', `Submit ${branch}`),
                     body: optionalString(payload, 'body', ''),
-                    request: { signal },
+                    // Content submits (api/github-sync.ts) set this; settings-branch
+                    // syncs (services.ts) deliberately don't.
+                    markReadyIfDraft: payload.markReadyIfDraft === true,
+                    signal,
                 });
-                console.log(`Created PR #${newPr.data.number} for ${branch}`);
-                return { prUrl: newPr.data.html_url, prNumber: newPr.data.number };
+                console.log(result.created
+                    ? `Created PR #${result.number} for ${branch}`
+                    : `Updated existing PR #${result.number} for ${branch}`);
+                return { prUrl: result.url, prNumber: result.number };
             }
             case 'convert-to-draft': {
                 const draftPrNumber = requireNumber(payload, 'pullRequestNumber');
@@ -377,7 +466,7 @@ export class CmsWorker {
                 return { deleted: true };
             }
             default:
-                throw new Error(`Unknown task action: ${action}`);
+                throw new PermanentTaskError(`Unknown task action: ${action}`);
         }
     }
     /**
@@ -438,7 +527,13 @@ export class CmsWorker {
         return `https://x-access-token:${this.config.githubToken}@github.com/${this.config.githubOwner}/${this.config.githubRepo}.git`;
     }
     async pushBranchToGitHub(branch) {
-        const git = simpleGit({ baseDir: this.remoteGitPath });
+        const git = simpleGit({
+            baseDir: this.remoteGitPath,
+            // DEP-H1: kill the git process if it produces no output for
+            // taskTimeoutMs (network stall, credential prompt) instead of letting
+            // it hang past the task timeout.
+            timeout: { block: this.taskTimeoutMs },
+        });
         // Pass URL directly to avoid persisting the token in remote.git/config
         await git.push(this.buildGitHubUrl(), branch);
         console.log(`Pushed ${branch} to GitHub`);
@@ -470,7 +565,13 @@ export class CmsWorker {
         if (!this.running)
             return;
         console.log('Syncing git...');
-        const git = simpleGit({ baseDir: this.remoteGitPath });
+        const git = simpleGit({
+            baseDir: this.remoteGitPath,
+            // DEP-H1: a hung fetch/push would stall the sync loop forever
+            // (scheduleLoop only reschedules after completion). The block timeout
+            // is inactivity-based, so a slow-but-flowing transfer is unaffected.
+            timeout: { block: this.taskTimeoutMs },
+        });
         // Fetch all branches from GitHub using direct URL (no named remote)
         // We use raw git commands since simple-git's fetch() with a URL
         // doesn't support --prune directly
@@ -608,6 +709,11 @@ export class CmsWorker {
                     await branchGit.rebase(['--abort']).catch(() => { });
                     continue;
                 }
+                // The rebase rewrote the branch clone's working tree — mark ContentStore
+                // ID indexes rooted here stale so lookups rebuild from disk, in this
+                // process and (via the on-disk generation marker) in the Lambda
+                // containers sharing this filesystem.
+                await invalidateContentIndexesDurable(branchPath);
                 // Convert file paths to ContentIds — immutable, survives slug renames.
                 // Entry files have IDs in their filename (e.g., "post.slug.a1b2c3d4e5f6.mdx").
                 // .collection.json files have no ID themselves (extractIdFromFilename returns null