canopycms 0.0.67-int.90 → 0.0.67

package/dist/worker/history-rewrite.d.ts

@@ -1,11 +1,8 @@
 import type { WorkerContext } from './worker-context.js';
 /**
  * [SYNC-H1] The history-rewrite kernel: what happens when the rebase loop
- * rewrites history that was ALREADY published to `remote.git` (and from there
- * to GitHub).
- *
- * Extracted from cms-worker.ts because it is the one thing all three of the
- * worker's big clusters touch, and for opposite-looking reasons:
+ * rewrites history ALREADY published to `remote.git` (and from there to
+ * GitHub). It lives here because all three of the worker's clusters touch it:
  *
  * - rebase.ts ARMS a rewrite (mark -> publish -> queue) and completes an
  *   interrupted one via `reconcilePendingRewrite`;
@@ -14,99 +11,89 @@ import type { WorkerContext } from './worker-context.js';
  * - git-sync.ts READS it in `reconcileTrackedBranches`, to tell this worker's
  *   own in-flight rewrite apart from a genuine cross-deployment collision.
  *
- * Leaving these on the class would have made every cluster's module import
- * every other one. They share no state beyond four resolved paths, so they
- * belong here.
- *
  * THE INVARIANT, since it is spread across those three callers: every force
  * push leases on a SPECIFIC commit this worker knows its own rebase replaced
  * -- the marker, or the pre-rebase tip -- never on "whatever remote.git holds
- * right now". A lease on the current tip is satisfied by a reviewer's direct
- * push to the PR branch and would delete it, silently, from remote.git and
- * then from GitHub.
+ * right now". A lease on the current tip is satisfied by anyone's direct push
+ * to the PR branch and would delete it, silently, from remote.git and then
+ * from GitHub.
  */
 export type HistoryRewriteContext = Pick<WorkerContext, 'remoteGitPath' | 'contentBranchesPath' | 'taskDir' | 'taskTimeoutMs'>;
 /**
- * What `remote.git` currently holds for `branchRef`, or null when this
- * branch was never published there (never submitted) or the ref is
- * unreadable.
+ * What `remote.git` currently holds for `branchRef`, or null when this branch
+ * was never published there (never submitted) or the ref is unreadable.
  *
- * Uses the same explicit `--git-dir` shape as verifyBaseBranchExists()
- * in cms-worker.ts: reading a bare repo that way does not depend on
- * `safe.bareRepository` being permissive, which is why prod code takes
- * this route rather than the config override the test-only `openBareRepo`
- * helper uses.
+ * Explicit `--git-dir`, like verifyBaseBranchExists() in cms-worker.ts:
+ * reading a bare repo that way does not depend on `safe.bareRepository` being
+ * permissive, which is why prod code takes this route rather than the config
+ * override the test-only `openBareRepo` helper uses.
  */
 export declare function readPublishedSha(ctx: Pick<HistoryRewriteContext, 'remoteGitPath'>, branchRef: string): Promise<string | null>;
 /**
  * Record that this worker rewrote `expectedSha` out of a branch's already
  * published history (see BranchMetadata.historyRewrittenFrom).
  *
- * Set-once: if a marker is already present it is LEFT ALONE. Across two
- * rebases before any GitHub push lands, GitHub still holds the commit the
- * FIRST rebase replaced, so advancing the marker would aim the lease at a
- * commit GitHub never had and permanently wedge the branch.
+ * Set-once: an existing marker is LEFT ALONE. Across two rebases before any
+ * GitHub push lands, GitHub still holds the commit the FIRST rebase replaced,
+ * so advancing the marker would aim the lease at a commit GitHub never had and
+ * permanently wedge the branch.
  *
- * Re-reads metadata rather than trusting the caller's loop-top snapshot:
- * the task loop runs concurrently with syncGit() (see scheduleLoop) and may
- * have cleared the marker while this branch was rebasing.
+ * Re-reads metadata rather than trusting the caller's snapshot: the task loop
+ * runs concurrently with syncGit() and may have cleared the marker while this
+ * branch was rebasing.
  */
 export declare function markHistoryRewritten(ctx: Pick<HistoryRewriteContext, 'contentBranchesPath'>, branchPath: string, branchDir: string, expectedSha: string): Promise<void>;
 /**
  * Clear the marker once GitHub is confirmed to hold the rewritten history.
  *
- * Best-effort only in the sense that a failure here destroys nothing: the
- * lease still refuses anything unexpected, and the plain-push fallback only
- * ever fast-forwards. It is NOT harmless. A marker that outlives its
- * episode can wedge the NEXT one -- if the base advances before the stale
- * marker is revisited, the queued push leases a commit GitHub has already
- * moved off, falls back to a plain push of a rebased (non-ancestor)
- * history, and fails permanently with a "something else moved it on
- * GitHub" diagnosis that is false: we did.
+ * A failure here destroys nothing (the lease still refuses anything
+ * unexpected, and the plain-push fallback only ever fast-forwards) but is NOT
+ * harmless: a marker that outlives its episode can wedge the NEXT one. If the
+ * base advances before the stale marker is revisited, the queued push leases a
+ * commit GitHub has already moved off, falls back to a plain push of a rebased
+ * (non-ancestor) history, and fails permanently with a "something else moved
+ * it on GitHub" diagnosis that is false -- we did.
  *
- * Tracked, with the concurrent-clear race that can drop a marker
- * mid-arming, in
- * .claude/future-tasks/worker-history-rewrite-marker-races.md.
+ * Tracked, with the concurrent-clear race that can drop a marker mid-arming,
+ * in .claude/future-tasks/worker-history-rewrite-marker-races.md.
  */
 export declare function clearHistoryRewrittenMarker(ctx: Pick<HistoryRewriteContext, 'contentBranchesPath'>, branchPath: string, branchDir: string): Promise<void>;
 /**
  * Publish a branch clone's rebased history into `remote.git`, replacing
  * EXACTLY `expectedSha` and nothing else.
  *
- * The lease is the entire safety argument. `--force-with-lease=<ref>:<sha>`
- * refuses unless `remote.git` still stands at `<sha>`, so this can only
- * ever undo the commit our own rebase rewrote away. Callers must never pass
- * "whatever remote.git currently holds" -- see the arming guard in
- * rebase.ts's carryForwardRewrittenHistory for the interleaving where that
- * would silently delete a reviewer's direct push.
+ * The lease is the entire safety argument: `--force-with-lease=<ref>:<sha>`
+ * refuses unless `remote.git` still stands at `<sha>`, so this can only ever
+ * undo the commit our own rebase rewrote away. Callers must NEVER pass
+ * "whatever remote.git currently holds" -- see the arming guard in rebase.ts's
+ * carryForwardRewrittenHistory for the interleaving where that would silently
+ * delete someone's direct push.
  *
- * Returns whether the push landed. A refused lease means a concurrent
- * Lambda push moved the ref; that is logged and retried by the self-heal
- * pass on a later cycle, never thrown.
+ * Returns whether the push landed. A refused lease means a concurrent Lambda
+ * push moved the ref; logged and retried by the self-heal pass, never thrown.
  */
 export declare function forcePublishToLocalRemote(ctx: Pick<HistoryRewriteContext, 'taskTimeoutMs'>, branchPath: string, branchRef: string, expectedSha: string): Promise<boolean>;
 /**
  * Queue the GitHub hop for a branch whose rewritten history now sits in
- * `remote.git`, so an open PR's head follows the rebase within a cycle
- * instead of waiting for the editor's next submit.
+ * `remote.git`, so an open PR's head follows the rebase within a cycle instead
+ * of waiting for the editor's next submit.
  *
- * Deliberately NOT skipped when a marker is already set: inferring "a task
- * must already be queued" from the marker starves this hop whenever a task
- * was lost, failed permanently, or was never written. Duplicate push tasks
- * are bounded by base-branch advances and are idempotent (a repeat push is
- * a no-op once GitHub holds the tip).
+ * Deliberately NOT skipped when a marker is already set: inferring "a task must
+ * already be queued" from the marker starves this hop whenever a task was lost,
+ * failed permanently, or was never written. Duplicate push tasks are bounded by
+ * base-branch advances and are idempotent.
  */
 export declare function enqueueGitHubPush(ctx: Pick<HistoryRewriteContext, 'taskDir'>, branchRef: string): Promise<void>;
 /**
- * Complete a rewrite this worker started but did not finish: get the
- * rebased history into `remote.git` and queued for GitHub.
+ * Complete a rewrite this worker started but did not finish: get the rebased
+ * history into `remote.git` and queued for GitHub.
  *
- * Runs from the rebase loop for any branch carrying a marker, whether or
- * not it is behind base this cycle, so an interrupted publish converges
- * without waiting for the next base-branch advance.
+ * Runs from the rebase loop for any branch carrying a marker, whether or not it
+ * is behind base this cycle, so an interrupted publish converges without
+ * waiting for the next base-branch advance.
  *
- * Always leases on the MARKER, never on remote.git's current tip -- the
- * marker is the one commit we know our own rebase replaced.
+ * Always leases on the MARKER, never on remote.git's current tip -- the marker
+ * is the one commit we know our own rebase replaced.
  */
 export declare function reconcilePendingRewrite(ctx: HistoryRewriteContext, options: {
     branchPath: string;
@@ -120,10 +107,10 @@ export declare function reconcilePendingRewrite(ctx: HistoryRewriteContext, opti
  * rewrote already-published history and the GitHub push has not landed yet
  * (see BranchMetadata.historyRewrittenFrom).
  *
- * `branchName` is a git ref name; branch workspaces are directories named
- * with the sanitized form, hence the conversion. Best-effort: a settings
- * branch (no workspace at all), a missing directory or an unreadable
- * branch.json all mean "no known rewrite", which is the conservative
- * answer -- it keeps the branch in the louder `diverged` bucket.
+ * `branchName` is a git ref name; branch workspaces are directories named with
+ * the sanitized form, hence the conversion. Best-effort: a settings branch (no
+ * workspace at all), a missing directory or an unreadable branch.json all mean
+ * "no known rewrite", the conservative answer -- it keeps the branch in the
+ * louder `diverged` bucket.
  */
 export declare function hasPendingHistoryRewrite(ctx: Pick<HistoryRewriteContext, 'contentBranchesPath'>, branchName: string): Promise<boolean>;

package/dist/worker/history-rewrite.js

@@ -5,18 +5,16 @@ import { gitChildEnv } from '../git-manager.js';
 import { sanitizeBranchName } from '../paths/branch-name.js';
 import { getErrorMessage, redactCredentials } from '../utils/error.js';
 import { isStaleLeaseRejection } from '../utils/git.js';
-import { enqueueTask, listTasks } from './task-queue.js';
+import { enqueueTask, listTasks } from '../task-queue/cms-task-queue.js';
 import { workerLog, workerLogWarn } from './log.js';
 /**
- * What `remote.git` currently holds for `branchRef`, or null when this
- * branch was never published there (never submitted) or the ref is
- * unreadable.
+ * What `remote.git` currently holds for `branchRef`, or null when this branch
+ * was never published there (never submitted) or the ref is unreadable.
  *
- * Uses the same explicit `--git-dir` shape as verifyBaseBranchExists()
- * in cms-worker.ts: reading a bare repo that way does not depend on
- * `safe.bareRepository` being permissive, which is why prod code takes
- * this route rather than the config override the test-only `openBareRepo`
- * helper uses.
+ * Explicit `--git-dir`, like verifyBaseBranchExists() in cms-worker.ts:
+ * reading a bare repo that way does not depend on `safe.bareRepository` being
+ * permissive, which is why prod code takes this route rather than the config
+ * override the test-only `openBareRepo` helper uses.
  */
 export async function readPublishedSha(ctx, branchRef) {
     try {
@@ -40,14 +38,14 @@ export async function readPublishedSha(ctx, branchRef) {
  * Record that this worker rewrote `expectedSha` out of a branch's already
  * published history (see BranchMetadata.historyRewrittenFrom).
  *
- * Set-once: if a marker is already present it is LEFT ALONE. Across two
- * rebases before any GitHub push lands, GitHub still holds the commit the
- * FIRST rebase replaced, so advancing the marker would aim the lease at a
- * commit GitHub never had and permanently wedge the branch.
+ * Set-once: an existing marker is LEFT ALONE. Across two rebases before any
+ * GitHub push lands, GitHub still holds the commit the FIRST rebase replaced,
+ * so advancing the marker would aim the lease at a commit GitHub never had and
+ * permanently wedge the branch.
  *
- * Re-reads metadata rather than trusting the caller's loop-top snapshot:
- * the task loop runs concurrently with syncGit() (see scheduleLoop) and may
- * have cleared the marker while this branch was rebasing.
+ * Re-reads metadata rather than trusting the caller's snapshot: the task loop
+ * runs concurrently with syncGit() and may have cleared the marker while this
+ * branch was rebasing.
  */
 export async function markHistoryRewritten(ctx, branchPath, branchDir, expectedSha) {
     const current = await BranchMetadataFileManager.loadOnly(branchPath);
@@ -59,18 +57,16 @@ export async function markHistoryRewritten(ctx, branchPath, branchDir, expectedS
 /**
  * Clear the marker once GitHub is confirmed to hold the rewritten history.
  *
- * Best-effort only in the sense that a failure here destroys nothing: the
- * lease still refuses anything unexpected, and the plain-push fallback only
- * ever fast-forwards. It is NOT harmless. A marker that outlives its
- * episode can wedge the NEXT one -- if the base advances before the stale
- * marker is revisited, the queued push leases a commit GitHub has already
- * moved off, falls back to a plain push of a rebased (non-ancestor)
- * history, and fails permanently with a "something else moved it on
- * GitHub" diagnosis that is false: we did.
+ * A failure here destroys nothing (the lease still refuses anything
+ * unexpected, and the plain-push fallback only ever fast-forwards) but is NOT
+ * harmless: a marker that outlives its episode can wedge the NEXT one. If the
+ * base advances before the stale marker is revisited, the queued push leases a
+ * commit GitHub has already moved off, falls back to a plain push of a rebased
+ * (non-ancestor) history, and fails permanently with a "something else moved
+ * it on GitHub" diagnosis that is false -- we did.
  *
- * Tracked, with the concurrent-clear race that can drop a marker
- * mid-arming, in
- * .claude/future-tasks/worker-history-rewrite-marker-races.md.
+ * Tracked, with the concurrent-clear race that can drop a marker mid-arming,
+ * in .claude/future-tasks/worker-history-rewrite-marker-races.md.
  */
 export async function clearHistoryRewrittenMarker(ctx, branchPath, branchDir) {
     try {
@@ -87,23 +83,22 @@ export async function clearHistoryRewrittenMarker(ctx, branchPath, branchDir) {
  * Publish a branch clone's rebased history into `remote.git`, replacing
  * EXACTLY `expectedSha` and nothing else.
  *
- * The lease is the entire safety argument. `--force-with-lease=<ref>:<sha>`
- * refuses unless `remote.git` still stands at `<sha>`, so this can only
- * ever undo the commit our own rebase rewrote away. Callers must never pass
- * "whatever remote.git currently holds" -- see the arming guard in
- * rebase.ts's carryForwardRewrittenHistory for the interleaving where that
- * would silently delete a reviewer's direct push.
+ * The lease is the entire safety argument: `--force-with-lease=<ref>:<sha>`
+ * refuses unless `remote.git` still stands at `<sha>`, so this can only ever
+ * undo the commit our own rebase rewrote away. Callers must NEVER pass
+ * "whatever remote.git currently holds" -- see the arming guard in rebase.ts's
+ * carryForwardRewrittenHistory for the interleaving where that would silently
+ * delete someone's direct push.
  *
- * Returns whether the push landed. A refused lease means a concurrent
- * Lambda push moved the ref; that is logged and retried by the self-heal
- * pass on a later cycle, never thrown.
+ * Returns whether the push landed. A refused lease means a concurrent Lambda
+ * push moved the ref; logged and retried by the self-heal pass, never thrown.
  */
 export async function forcePublishToLocalRemote(ctx, branchPath, branchRef, expectedSha) {
-    // A dedicated instance rather than the caller's: `.env()` replaces the
-    // whole child environment, and the rebase loop's instance must keep its
-    // ambient one. gitChildEnv (not gitNetworkChildEnv) because this push
-    // targets the local bare repo -- and the locale pin is what keeps
-    // isStaleLeaseRejection below from silently becoming a no-op.
+    // A dedicated instance rather than the caller's: `.env()` replaces the whole
+    // child environment, and the rebase loop's instance must keep its ambient
+    // one. gitChildEnv (not gitNetworkChildEnv) because this push targets the
+    // local bare repo -- and its locale pin is what keeps isStaleLeaseRejection
+    // below from silently becoming a no-op on a non-English host.
     const pushGit = simpleGit({ baseDir: branchPath, timeout: { block: ctx.taskTimeoutMs } });
     pushGit.env(gitChildEnv({}));
     try {
@@ -129,14 +124,13 @@ export async function forcePublishToLocalRemote(ctx, branchPath, branchRef, expe
 }
 /**
  * Queue the GitHub hop for a branch whose rewritten history now sits in
- * `remote.git`, so an open PR's head follows the rebase within a cycle
- * instead of waiting for the editor's next submit.
+ * `remote.git`, so an open PR's head follows the rebase within a cycle instead
+ * of waiting for the editor's next submit.
  *
- * Deliberately NOT skipped when a marker is already set: inferring "a task
- * must already be queued" from the marker starves this hop whenever a task
- * was lost, failed permanently, or was never written. Duplicate push tasks
- * are bounded by base-branch advances and are idempotent (a repeat push is
- * a no-op once GitHub holds the tip).
+ * Deliberately NOT skipped when a marker is already set: inferring "a task must
+ * already be queued" from the marker starves this hop whenever a task was lost,
+ * failed permanently, or was never written. Duplicate push tasks are bounded by
+ * base-branch advances and are idempotent.
  */
 export async function enqueueGitHubPush(ctx, branchRef) {
     try {
@@ -157,15 +151,15 @@ export async function enqueueGitHubPush(ctx, branchRef) {
     }
 }
 /**
- * Complete a rewrite this worker started but did not finish: get the
- * rebased history into `remote.git` and queued for GitHub.
+ * Complete a rewrite this worker started but did not finish: get the rebased
+ * history into `remote.git` and queued for GitHub.
  *
- * Runs from the rebase loop for any branch carrying a marker, whether or
- * not it is behind base this cycle, so an interrupted publish converges
- * without waiting for the next base-branch advance.
+ * Runs from the rebase loop for any branch carrying a marker, whether or not it
+ * is behind base this cycle, so an interrupted publish converges without
+ * waiting for the next base-branch advance.
  *
- * Always leases on the MARKER, never on remote.git's current tip -- the
- * marker is the one commit we know our own rebase replaced.
+ * Always leases on the MARKER, never on remote.git's current tip -- the marker
+ * is the one commit we know our own rebase replaced.
  */
 export async function reconcilePendingRewrite(ctx, options) {
     const { branchPath, branchDir, branchRef, headSha, marker } = options;
@@ -198,11 +192,11 @@ export async function reconcilePendingRewrite(ctx, options) {
  * rewrote already-published history and the GitHub push has not landed yet
  * (see BranchMetadata.historyRewrittenFrom).
  *
- * `branchName` is a git ref name; branch workspaces are directories named
- * with the sanitized form, hence the conversion. Best-effort: a settings
- * branch (no workspace at all), a missing directory or an unreadable
- * branch.json all mean "no known rewrite", which is the conservative
- * answer -- it keeps the branch in the louder `diverged` bucket.
+ * `branchName` is a git ref name; branch workspaces are directories named with
+ * the sanitized form, hence the conversion. Best-effort: a settings branch (no
+ * workspace at all), a missing directory or an unreadable branch.json all mean
+ * "no known rewrite", the conservative answer -- it keeps the branch in the
+ * louder `diverged` bucket.
  */
 export async function hasPendingHistoryRewrite(ctx, branchName) {
     try {

package/dist/worker/log.d.ts

@@ -1,41 +1,26 @@
 /**
  * Timestamp-prefixed logging for the CMS worker daemon.
  *
- * The worker's stdout AND stderr both append to
- * `/var/log/canopy-worker/worker.log` (see the systemd unit written by
- * `packages/canopycms-cdk/src/constructs/cms-service.ts` user-data), which the
- * amazon-cloudwatch-agent tails. That arrangement loses two things a bare
- * `console.log` used to get for free under journald:
+ * INVARIANT: every line written to worker.log starts with this ISO-8601
+ * timestamp and a level tag. The worker's stdout AND stderr both append to
+ * `/var/log/canopy-worker/worker.log` (the systemd unit written by
+ * `packages/canopycms-cdk/src/constructs/cms-service.ts` user-data), so the
+ * level tag is the only thing separating `console.log` from `console.error`
+ * downstream; and the amazon-cloudwatch-agent that tails it keys
+ * `multi_line_start_pattern` on the timestamp, so a stack trace collapses into
+ * ONE event while any UNPREFIXED line is appended to the preceding event
+ * instead of starting its own. CloudWatch's own stamp is INGESTION time, which
+ * skews most exactly when it matters (agent hiccup, buffered burst, restart).
  *
- * 1. **A real timestamp.** CloudWatch otherwise stamps events with their
- *    *ingestion* time - when the agent read and shipped the line, not when the
- *    worker emitted it. The skew is small in steady state and largest exactly
- *    when it matters most (agent hiccup, buffered burst, instance restart).
- * 2. **Severity.** Both streams land in one file, so `console.log` and
- *    `console.error` are indistinguishable downstream. The level tag restores
- *    it as a greppable field (`filter @message like /ERROR/`).
+ * Hence the AWS entrypoint (`packages/canopycms-cdk/worker/index.ts`) imports
+ * these helpers rather than calling `console`. Node's own uncaught-exception
+ * dump on the way down is the one uncovered case.
  *
- * INVARIANT: every line written to worker.log must start with this ISO-8601
- * timestamp. The agent config sets `multi_line_start_pattern` keyed on that
- * prefix so a stack trace collapses into ONE CloudWatch event instead of
- * fragmenting line-by-line - which also means any line WITHOUT the prefix is
- * appended to the preceding event rather than starting its own. That is why
- * the AWS entrypoint (`packages/canopycms-cdk/worker/index.ts`) imports these
- * helpers too rather than calling `console` directly. Output Node itself
- * prints (an uncaught-exception dump on the way down) is the one uncovered
- * case: it attaches to the previous event, still strictly better than the
- * per-line fragmentation it replaces.
- *
- * The timestamp and level are passed as SEPARATE console arguments rather than
- * concatenated into the message, so console's native formatting of non-string
- * arguments survives - Errors keep their stacks, objects keep their inspection
- * output.
- */
-/**
- * Named `workerLog*` rather than a bare `log`/`logError`: `CmsWorker` already
- * carries a `private log = cmsTaskQueueLogger` field, and two different things
- * called `log` in one file is a readability trap.
+ * The timestamp and level are SEPARATE console arguments, never concatenated
+ * into the message, so console's native formatting of non-string arguments
+ * survives - Errors keep their stacks.
  */
+/** Named `workerLog*`, not `log`: `CmsWorker` already carries a `log` field. */
 /** Informational worker output. Routes to stdout. */
 export declare function workerLog(...args: unknown[]): void;
 /** Recoverable problem - the worker carries on. Routes to stderr. */
@@ -45,16 +30,14 @@ export declare function workerLogError(...args: unknown[]): void;
 /**
  * Point the shared `canopyLog*` helpers (`utils/logger.ts`) at the prefixing
  * functions above, so modules the worker executes but does not own -
- * `github-service.ts`, `branch-registry.ts` - satisfy the INVARIANT documented
- * at the top of this file instead of writing bare, unprefixed lines into
- * worker.log.
+ * `github-service.ts`, `branch-registry.ts` - satisfy the INVARIANT above
+ * instead of writing bare lines into worker.log. The eslint ban on bare
+ * `console` covers the two worker directories but cannot reach those shared
+ * modules, which are legitimately plain `console` under Lambda.
  *
  * Call this ONCE, first thing in a worker entrypoint, before any work that
- * could log. Deliberately not a module-level side effect: importing
- * `worker/log.ts` (or anything that re-exports it) must not silently
- * reconfigure logging for a Lambda or dev-server process that merely wants the
- * helpers' types. The eslint override for the two worker directories bans bare
- * `console` there, but it cannot reach the shared modules above - those are
- * legitimately plain `console` under Lambda. This is the half that covers them.
+ * could log. Deliberately not a module-level side effect: importing this module
+ * must not reconfigure logging for a Lambda or dev-server process that merely
+ * wants the helpers' types.
  */
 export declare function installWorkerLogger(): void;

package/dist/worker/log.js

@@ -1,46 +1,31 @@
 /**
  * Timestamp-prefixed logging for the CMS worker daemon.
  *
- * The worker's stdout AND stderr both append to
- * `/var/log/canopy-worker/worker.log` (see the systemd unit written by
- * `packages/canopycms-cdk/src/constructs/cms-service.ts` user-data), which the
- * amazon-cloudwatch-agent tails. That arrangement loses two things a bare
- * `console.log` used to get for free under journald:
+ * INVARIANT: every line written to worker.log starts with this ISO-8601
+ * timestamp and a level tag. The worker's stdout AND stderr both append to
+ * `/var/log/canopy-worker/worker.log` (the systemd unit written by
+ * `packages/canopycms-cdk/src/constructs/cms-service.ts` user-data), so the
+ * level tag is the only thing separating `console.log` from `console.error`
+ * downstream; and the amazon-cloudwatch-agent that tails it keys
+ * `multi_line_start_pattern` on the timestamp, so a stack trace collapses into
+ * ONE event while any UNPREFIXED line is appended to the preceding event
+ * instead of starting its own. CloudWatch's own stamp is INGESTION time, which
+ * skews most exactly when it matters (agent hiccup, buffered burst, restart).
  *
- * 1. **A real timestamp.** CloudWatch otherwise stamps events with their
- *    *ingestion* time - when the agent read and shipped the line, not when the
- *    worker emitted it. The skew is small in steady state and largest exactly
- *    when it matters most (agent hiccup, buffered burst, instance restart).
- * 2. **Severity.** Both streams land in one file, so `console.log` and
- *    `console.error` are indistinguishable downstream. The level tag restores
- *    it as a greppable field (`filter @message like /ERROR/`).
+ * Hence the AWS entrypoint (`packages/canopycms-cdk/worker/index.ts`) imports
+ * these helpers rather than calling `console`. Node's own uncaught-exception
+ * dump on the way down is the one uncovered case.
  *
- * INVARIANT: every line written to worker.log must start with this ISO-8601
- * timestamp. The agent config sets `multi_line_start_pattern` keyed on that
- * prefix so a stack trace collapses into ONE CloudWatch event instead of
- * fragmenting line-by-line - which also means any line WITHOUT the prefix is
- * appended to the preceding event rather than starting its own. That is why
- * the AWS entrypoint (`packages/canopycms-cdk/worker/index.ts`) imports these
- * helpers too rather than calling `console` directly. Output Node itself
- * prints (an uncaught-exception dump on the way down) is the one uncovered
- * case: it attaches to the previous event, still strictly better than the
- * per-line fragmentation it replaces.
- *
- * The timestamp and level are passed as SEPARATE console arguments rather than
- * concatenated into the message, so console's native formatting of non-string
- * arguments survives - Errors keep their stacks, objects keep their inspection
- * output.
+ * The timestamp and level are SEPARATE console arguments, never concatenated
+ * into the message, so console's native formatting of non-string arguments
+ * survives - Errors keep their stacks.
  */
 import { setCanopyLogger } from '../utils/logger.js';
-/** ISO-8601 with milliseconds, e.g. `2026-08-12T14:30:00.000Z`. */
+/** ISO-8601 with milliseconds: `YYYY-MM-DDTHH:mm:ss.sssZ`. */
 function timestamp() {
     return new Date().toISOString();
 }
-/**
- * Named `workerLog*` rather than a bare `log`/`logError`: `CmsWorker` already
- * carries a `private log = cmsTaskQueueLogger` field, and two different things
- * called `log` in one file is a readability trap.
- */
+/** Named `workerLog*`, not `log`: `CmsWorker` already carries a `log` field. */
 /** Informational worker output. Routes to stdout. */
 export function workerLog(...args) {
     console.log(timestamp(), 'INFO', ...args);
@@ -56,17 +41,15 @@ export function workerLogError(...args) {
 /**
  * Point the shared `canopyLog*` helpers (`utils/logger.ts`) at the prefixing
  * functions above, so modules the worker executes but does not own -
- * `github-service.ts`, `branch-registry.ts` - satisfy the INVARIANT documented
- * at the top of this file instead of writing bare, unprefixed lines into
- * worker.log.
+ * `github-service.ts`, `branch-registry.ts` - satisfy the INVARIANT above
+ * instead of writing bare lines into worker.log. The eslint ban on bare
+ * `console` covers the two worker directories but cannot reach those shared
+ * modules, which are legitimately plain `console` under Lambda.
  *
  * Call this ONCE, first thing in a worker entrypoint, before any work that
- * could log. Deliberately not a module-level side effect: importing
- * `worker/log.ts` (or anything that re-exports it) must not silently
- * reconfigure logging for a Lambda or dev-server process that merely wants the
- * helpers' types. The eslint override for the two worker directories bans bare
- * `console` there, but it cannot reach the shared modules above - those are
- * legitimately plain `console` under Lambda. This is the half that covers them.
+ * could log. Deliberately not a module-level side effect: importing this module
+ * must not reconfigure logging for a Lambda or dev-server process that merely
+ * wants the helpers' types.
  */
 export function installWorkerLogger() {
     setCanopyLogger({ log: workerLog, warn: workerLogWarn, error: workerLogError });