canopycms 0.0.67-int.90 → 0.0.67

package/dist/utils/error.js

@@ -1,24 +1,5 @@
-/**
- * Error handling utilities for type-safe error handling.
- *
- * These utilities help convert `catch (err: unknown)` to usable error information
- * without using `any` types.
- */
-/**
- * Extract a message string from an unknown error value.
- *
- * @param err - The caught error (unknown type)
- * @returns A string message suitable for logging or user display
- *
- * @example
- * ```ts
- * try {
- *   await riskyOperation()
- * } catch (err: unknown) {
- *   canopyLogError('Operation failed:', getErrorMessage(err))
- * }
- * ```
- */
+/** Reading a `catch (err: unknown)` value as usable error information, without `any`. */
+/** Message string for an unknown thrown value. */
 export function getErrorMessage(err) {
     if (err instanceof Error) {
         return err.message;
@@ -29,70 +10,51 @@ export function getErrorMessage(err) {
     return String(err);
 }
 /**
- * Redact sensitive material from an error message before sending it to API
- * clients. Log the ORIGINAL message server-side; send the sanitized one.
+ * Redact sensitive material from an error message before it reaches an API client. Log the
+ * ORIGINAL message server-side; send the sanitized one.
  *
- * Git/filesystem errors are unbounded (stderr varies by git version, locale,
- * and hooks can print anything), so enumerating safe messages is not
- * feasible. Instead, redact the known-sensitive SHAPES that can appear in
- * any of them:
- * - credentials embedded in URLs (`https://x-access-token:tok@github.com/…`)
- * - absolute filesystem paths (workspace roots, EFS mounts, home directories)
+ * Git/filesystem error text is unbounded (stderr varies by git version and locale, and hooks
+ * print anything), so this redacts the known-sensitive SHAPES rather than enumerating safe
+ * messages: credentials embedded in URLs (`https://x-access-token:tok@github.com/…`) and
+ * absolute filesystem paths (workspace roots, EFS mounts, home directories). Paths under the
+ * current working directory are shortened to relative form (CMS-internal layout like
+ * `.canopy-dev/remote.git` helps debugging and is not sensitive); absolute paths outside it
+ * become `<path>`.
  *
- * Paths under the current working directory are shortened to relative form
- * (CMS-internal layout like `.canopy-dev/remote.git` is useful for debugging
- * and not sensitive); absolute paths outside it are replaced with `<path>`.
- */
-/**
- * TAG: `[REDACT]`
- *
- * Grep `[REDACT]` to find every site that persists or surfaces raw error text on
- * a path that reaches a browser — worker task errors folded into
- * `worker-status.json`, `branch.json` parse failures served by the admin
- * branch-health endpoint, rebase-failure messages, and their tests.
- *
- * Those sites carried the tag `[HIGH-1]`/`[MEDIUM-2]` until 2026-08-23, IDs from
- * a review pass whose findings list was never committed — 13 occurrences across
- * 6 files resolving to nothing. Renamed rather than deleted because the
- * underlying rule is real and genuinely cross-file: a Node error embeds absolute
- * paths, and a git remote URL can embed a token, so anything on that path is
- * redacted through the function below.
- *
- * The tag is a grep aid, not the rule. The rule is stated at each site.
+ * TAG: `[REDACT]` — grep it for every site that persists or surfaces raw error text on a path
+ * reaching a browser (worker task errors folded into `worker-status.json`, `branch.json` parse
+ * failures served by the admin branch-health endpoint, rebase-failure messages, and their
+ * tests). A Node error embeds absolute paths and a git remote URL can embed a token, so
+ * everything on such a path goes through this function. The tag is a grep aid; the rule itself
+ * is stated at each site.
  */
 export function sanitizeErrorMessage(message) {
     let result = redactCredentials(message);
-    // Paths under the project root become relative (split/join avoids regex
-    // escaping issues with arbitrary cwd values). The bare-cwd replacement is
-    // anchored to a token boundary so sibling directories that merely share
-    // the cwd prefix (e.g. `${cwd}-other/…`) stay absolute and get fully
+    // Paths under the project root become relative (split/join avoids regex-escaping issues with
+    // arbitrary cwd values). The bare-cwd replacement is anchored to a token boundary so a sibling
+    // directory that merely shares the cwd prefix (`${cwd}-other/…`) stays absolute and is fully
     // redacted below instead of leaking a mangled remainder.
     const cwd = process.cwd();
     if (cwd !== '/') {
         result = result.split(`${cwd}/`).join('');
         const cwdPattern = cwd.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-        // cwdPattern is process.cwd() (server-controlled, not attacker/entry-content
-        // data) with regex metacharacters escaped by the literal regex above, so
-        // this cannot be used to inject an attacker-chosen pattern.
+        // cwdPattern is process.cwd() (server-controlled, not attacker or entry-content data) with
+        // regex metacharacters escaped by the literal regex above, so it cannot inject an
+        // attacker-chosen pattern.
         // eslint-disable-next-line security/detect-non-literal-regexp
         result = result.replace(new RegExp(`${cwdPattern}(?=[\\s'"),:;]|$)`, 'g'), '.');
     }
-    // Quoted absolute paths (git quotes most paths in its messages): redact
-    // the whole quoted span, spaces included.
+    // Quoted absolute paths (git quotes most paths): redact the whole quoted span, spaces included.
     result = result.replace(/'\/[^']*'/g, "'<path>'").replace(/"\/[^"]*"/g, '"<path>"');
-    // Remaining absolute POSIX paths (outside cwd, e.g. /mnt/efs/…). The
-    // leading boundary keeps URL slashes (`https://host/…`) untouched. Known
-    // limitation: an UNQUOTED path containing spaces is only redacted up to
-    // the first space — spaces are legal both inside paths and as message
-    // separators, so this is not generally solvable here.
+    // Remaining absolute POSIX paths (outside cwd, e.g. /mnt/efs/…). The leading boundary keeps
+    // URL slashes (`https://host/…`) untouched. Known limitation: an UNQUOTED path containing
+    // spaces is only redacted up to the first space — spaces are legal both inside paths and as
+    // message separators, so that is not generally solvable here.
     //
-    // The repeated group `(?:[^/\s'")]+\/)+` looks nested-quantifier-shaped, but
-    // the inner character class excludes `/`, so each repetition can only end at
-    // a literal `/` boundary in the input: there is exactly one way to decompose
-    // any matched string into repetitions (no same-substring ambiguity), so this
-    // does not backtrack catastrophically. Verified empirically with inputs up
-    // to 400k chars (adversarial runs of non-slash chars, with and without
-    // trailing slashes): scaling stayed linear, not quadratic/exponential.
+    // The repeated group `(?:[^/\s'")]+\/)+` looks nested-quantifier-shaped, but its inner class
+    // excludes `/`, so each repetition can only end at a literal `/`: a matched string has exactly
+    // one decomposition, so it cannot backtrack catastrophically. Measured linear on adversarial
+    // inputs up to 400k chars.
     // eslint-disable-next-line security/detect-unsafe-regex
     result = result.replace(/(^|[\s'"(=:,[])\/(?:[^/\s'")]+\/)+[^/\s'")]*/g, '$1<path>');
     // Windows drive paths
@@ -100,106 +62,57 @@ export function sanitizeErrorMessage(message) {
     return result;
 }
 /**
- * Redact only credential material from a message, leaving filesystem paths
- * intact. For server-side log lines that deliberately keep full path detail
- * (server logs only, useful for debugging) but must never persist a live
- * token — client-facing messages go through sanitizeErrorMessage instead,
- * which calls this and then also redacts paths.
+ * Redact only credential material, leaving filesystem paths intact — for server-side log lines
+ * that deliberately keep full path detail for debugging but must never persist a live token.
+ * Client-facing messages go through `sanitizeErrorMessage` instead, which calls this and then
+ * also redacts paths.
  */
 export function redactCredentials(message) {
     let result = message;
-    // Credentials in URLs: scheme://user:token@host or scheme://token@host.
-    // Anchored on the literal `://` (leaving the scheme untouched) — a `\w+`
-    // scheme prefix would backtrack polynomially on long word-character runs
-    // (CodeQL js/polynomial-redos).
+    // Credentials in URLs: scheme://user:token@host or scheme://token@host. Anchored on the
+    // literal `://` (leaving the scheme untouched) — a `\w+` scheme prefix backtracks
+    // polynomially on long word-character runs (CodeQL js/polynomial-redos).
     result = result.replace(/(:\/\/)[^/\s@]+@/g, '$1***@');
-    // Bare token shapes (defense-in-depth for messages that embed a token
-    // outside URL userinfo): GitHub token prefixes and Bearer values.
+    // Bare token shapes, for messages embedding a token outside URL userinfo: GitHub token
+    // prefixes and Bearer values.
     result = result.replace(/\b(?:gh[pousr]|github_pat)_[A-Za-z0-9_]{8,}/g, '***');
     result = result.replace(/\b(Bearer\s+)[A-Za-z0-9._~+/=-]{8,}/g, '$1***');
-    // PEM private-key blocks — a GitHub App's private key. Defense-in-depth,
-    // exactly like the bare-token rules above: no site today puts key material
-    // into an error (checked — `createPrivateKey` failures report
-    // `error:1E08010C:DECODER routines::unsupported` and jsonwebtoken's report
-    // neither `BEGIN` nor the body), and a rule added before the first leak
-    // costs nothing. None of the rules above would match one: a PEM has no URL
-    // userinfo, no `gh*_` prefix and no `Bearer`.
-    //
-    // Linear by construction. The label is `[A-Z]{0,9} ?` (bounded, so its
-    // backtracking is a constant factor) rather than an open `[A-Z ]*`, which
-    // would rescan a long run of capitals at every start position. The lazy
-    // `[\s\S]*?` is stopped by the END footer, or by end-of-string when the
-    // message was truncated mid-key — without that second alternative a
-    // half-quoted key would pass through in full.
+    // PEM private-key blocks — a GitHub App's private key. Defense-in-depth like the bare-token
+    // rules above: nothing today puts key material into an error, and none of those rules would
+    // match one (a PEM has no URL userinfo, no `gh*_` prefix and no `Bearer`).
     //
-    // The footer is spelled out, mirroring the header, rather than "`-----END`
-    // then anything up to the next dashes". Both looser spellings were measured
-    // wrong in opposite directions on a single-line message: `[^\n]*` (greedy to
-    // end of line) swallowed the text after the key, and `[^\n]*?-----` (lazy to
-    // any dashes) stopped on a label-less `-----END-----` and left a SECOND key
-    // after it unredacted. Matching only a real footer means anything else falls
-    // through to `$`, which over-redacts — the safe direction.
+    // Linear by construction. The label is bounded (`[A-Z]{0,9} ?`) rather than an open `[A-Z ]*`,
+    // which would rescan a long run of capitals at every start position, and the lazy `[\s\S]*?`
+    // stops at the END footer or at end-of-string — without that second alternative a key
+    // truncated mid-message passes through in full. The footer is spelled out rather than
+    // "`-----END` then anything up to the next dashes": greedy `[^\n]*` swallows the text after
+    // the key, and lazy `[^\n]*?-----` stops on a label-less `-----END-----` and leaves a SECOND
+    // key unredacted. Anything else falls through to `$`, which over-redacts — the safe direction.
     result = result.replace(/-----BEGIN [A-Z]{0,9} ?PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z]{0,9} ?PRIVATE KEY-----|$)/g, '<private-key>');
     // Bare JWTs (`eyJ…`) — three dot-separated base64url runs.
     //
-    // The leading boundary is `(?<![\w-])`, NOT `\b`. `-` is in the run class but
-    // is not a word character, so under `\b` every `-eyJ` inside one long
-    // `[\w-]` run starts a fresh match attempt that rescans the rest of the run
-    // for a `.` that never comes — quadratic, and measured on `'-eyJ'.repeat(n)`:
-    // roughly 200ms at 20KB, 900ms at 40KB, 13-16s at 160KB (the absolute
-    // numbers are machine-dependent; the quadrupling per doubling is not). With
-    // the lookbehind the same 160KB input is under a millisecond. It gives up
-    // exactly one case: a JWT
-    // glued directly to a preceding hyphen (`x-eyJ…`); every real prefix —
+    // The leading boundary is `(?<![\w-])`, NOT `\b`: `-` is in the run class but is not a word
+    // character, so under `\b` every `-eyJ` inside one long `[\w-]` run starts a fresh match
+    // attempt that rescans the rest of the run for a `.` that never comes — quadratic, measured in
+    // seconds on a 160KB input where the lookbehind stays under a millisecond. It gives up exactly
+    // one case: a JWT glued directly to a preceding hyphen (`x-eyJ…`); every real prefix —
     // whitespace, `"`, `=`, `(`, `Bearer ` — still matches.
     result = result.replace(/(?<![\w-])eyJ[\w-]{8,}\.[\w-]{8,}\.[\w-]+/g, '***');
     return result;
 }
-/**
- * Type guard to check if an error is a Node.js system error with a code property.
- *
- * @param err - The caught error (unknown type)
- * @returns True if the error has a `code` property (like ENOENT, EACCES, etc.)
- *
- * @example
- * ```ts
- * try {
- *   await fs.readFile(path)
- * } catch (err: unknown) {
- *   if (isNodeError(err) && err.code === 'ENOENT') {
- *     return null // File not found is expected
- *   }
- *   throw err
- * }
- * ```
- */
+/** True for a Node system error — an `Error` carrying a `code` (ENOENT, EACCES, …). */
 export function isNodeError(err) {
     return err instanceof Error && 'code' in err;
 }
-/**
- * Check if an error indicates a "file not found" condition.
- *
- * @param err - The caught error (unknown type)
- * @returns True if the error is ENOENT (file/directory not found)
- */
+/** True for ENOENT. */
 export function isNotFoundError(err) {
     return isNodeError(err) && err.code === 'ENOENT';
 }
-/**
- * Check if an error indicates a "permission denied" condition.
- *
- * @param err - The caught error (unknown type)
- * @returns True if the error is EACCES (permission denied)
- */
+/** True for EACCES. */
 export function isPermissionError(err) {
     return isNodeError(err) && err.code === 'EACCES';
 }
-/**
- * Check if an error indicates a "file already exists" condition.
- *
- * @param err - The caught error (unknown type)
- * @returns True if the error is EEXIST (file already exists)
- */
+/** True for EEXIST. */
 export function isFileExistsError(err) {
     return isNodeError(err) && err.code === 'EEXIST';
 }

package/dist/utils/flatten-group-fields.d.ts

@@ -1,12 +1,10 @@
 import type { FieldConfig } from '../config/index.js';
 /**
- * Recursively flatten inline groups out of a field array.
- * Group children are inlined at the parent level — groups are transparent to data.
+ * Recursively flatten inline groups out of a field array: group children are inlined at the
+ * parent level, because groups are transparent to data.
  *
- * Use this when iterating fields for data-layer purposes (reference resolution,
- * change detection, body-field lookup, etc.) where you need all data-carrying
- * fields without group wrappers.
- *
- * Not needed when using traverseFields() — that already handles groups transparently.
+ * For data-layer iteration (reference resolution, change detection, body-field lookup) that
+ * needs every data-carrying field without group wrappers. `traverseFields()` already handles
+ * groups transparently and does not need this.
  */
 export declare function flattenGroupFields(fields: readonly FieldConfig[]): FieldConfig[];

package/dist/utils/flatten-group-fields.js

@@ -1,12 +1,10 @@
 /**
- * Recursively flatten inline groups out of a field array.
- * Group children are inlined at the parent level — groups are transparent to data.
+ * Recursively flatten inline groups out of a field array: group children are inlined at the
+ * parent level, because groups are transparent to data.
  *
- * Use this when iterating fields for data-layer purposes (reference resolution,
- * change detection, body-field lookup, etc.) where you need all data-carrying
- * fields without group wrappers.
- *
- * Not needed when using traverseFields() — that already handles groups transparently.
+ * For data-layer iteration (reference resolution, change detection, body-field lookup) that
+ * needs every data-carrying field without group wrappers. `traverseFields()` already handles
+ * groups transparently and does not need this.
  */
 export function flattenGroupFields(fields) {
     const result = [];

package/dist/utils/format.d.ts

@@ -1,9 +1,5 @@
 import type { ContentFormat } from '../config/index.js';
-/**
- * Get the file extension for a content format
- * @param format - The content format (md, mdx, json, yaml)
- * @returns The file extension including the dot (e.g., '.md', '.json', '.yaml')
- */
+/** The file extension, dot included, for a content format. */
 export declare const getFormatExtension: (format: ContentFormat) => string;
 /** Returns true for data-only formats (no body/frontmatter separation) */
 export declare const isDataOnlyFormat: (format: ContentFormat) => boolean;

package/dist/utils/format.js

@@ -1,8 +1,4 @@
-/**
- * Get the file extension for a content format
- * @param format - The content format (md, mdx, json, yaml)
- * @returns The file extension including the dot (e.g., '.md', '.json', '.yaml')
- */
+/** The file extension, dot included, for a content format. */
 export const getFormatExtension = (format) => {
     if (format === 'md')
         return '.md';

package/dist/utils/fs.d.ts

@@ -1,9 +1,8 @@
 /** Check if a path exists on disk. */
 export declare function filePathExists(filePath: string): Promise<boolean>;
 /**
- * Read a UTF-8 file, or return undefined if it does not exist.
- *
- * Only ENOENT is swallowed — a permissions or I/O failure still throws, so a caller cannot
- * mistake "unreadable" for "not there yet".
+ * Read a UTF-8 file, or undefined if it does not exist. Only ENOENT is swallowed — a
+ * permissions or I/O failure still throws, so a caller cannot mistake "unreadable" for
+ * "not there yet".
  */
 export declare function readFileIfExists(filePath: string): Promise<string | undefined>;

package/dist/utils/fs.js

@@ -13,10 +13,9 @@ export async function filePathExists(filePath) {
     }
 }
 /**
- * Read a UTF-8 file, or return undefined if it does not exist.
- *
- * Only ENOENT is swallowed — a permissions or I/O failure still throws, so a caller cannot
- * mistake "unreadable" for "not there yet".
+ * Read a UTF-8 file, or undefined if it does not exist. Only ENOENT is swallowed — a
+ * permissions or I/O failure still throws, so a caller cannot mistake "unreadable" for
+ * "not there yet".
  */
 export async function readFileIfExists(filePath) {
     try {

package/dist/utils/git.d.ts

@@ -1,113 +1,82 @@
 import type { OperatingMode } from '../operating-mode/index.js';
 /**
- * Whether a git remote URL points at a network location — http(s)://,
- * ssh://, git://, scp-like `[user@]host:path`, a transport-helper `scheme::`
- * form, or a leading-`-` value git would parse as a command-line option —
- * rather than a local filesystem path.
+ * Whether a git remote URL points at a network location rather than a local filesystem path. Only
+ * `file://` URLs, plain filesystem paths and Windows drive paths are LOCAL; the patterns above
+ * enumerate the network forms.
  *
- * `file://` URLs and plain filesystem paths are LOCAL — this is the
- * distinction GitManager's prod-mode network-remote guard relies on (see
- * `resolveRemoteUrl`): the intended prod topology only ever resolves a local
- * path (an auto-detected/auto-initialized `remote.git`), so anything network
- * flowing in via an explicit param, config, or env var is almost always a
- * misconfiguration in prod. Because the guard's job is catching prod
- * misconfig (not being a strict URL parser), this classifier treats anything
- * git could interpret as a network transport, a transport helper, or a
- * command-line option as "network". The one local carve-out beyond `file://`
- * is a Windows drive path (`C:\...` / `C:/...`), which replaces the old
- * `@`-required heuristic for scp-like syntax.
+ * The distinction GitManager's prod-mode network-remote guard relies on (see `resolveRemoteUrl`):
+ * the intended prod topology only ever resolves a local path (an auto-detected/auto-initialized
+ * `remote.git`), so anything network arriving via an explicit param, config, or env var is almost
+ * always a prod misconfiguration. Catching that is the job, not being a strict URL parser, so
+ * anything git could read as a network transport, a transport helper, or a command-line option
+ * counts as "network".
  */
 export declare function isNetworkRemoteUrl(url: string): boolean;
 /**
- * Whether a git push failure message is git's non-fast-forward rejection --
- * the remote has diverged (moved ahead with commits this side never fetched),
- * so retrying the IDENTICAL push can never succeed. In CanopyCMS this is the
- * signature of two CanopyCMS deployments sharing one GitHub repo and picking
- * the same content-branch name, or someone pushing directly to GitHub.
+ * Whether a git push failure message is git's non-fast-forward rejection -- the remote has
+ * diverged, so retrying the IDENTICAL push can never succeed. In CanopyCMS that means two
+ * deployments sharing one GitHub repo and picking the same content-branch name, or someone pushing
+ * directly to GitHub.
  *
- * Deliberately narrow: ordinary transient push failures -- network drops,
- * auth/permission denial, lock contention -- must keep retrying with backoff
- * (see worker/task-runner.ts's `isPermanentTaskFailure`, which treats git
- * failures as transient precisely so those cases still get retried). Only
- * this specific, structurally-unretryable shape should fail fast (worker) or
- * return 409 (API) instead.
+ * Deliberately narrow: ordinary transient push failures -- network drops, auth/permission denial,
+ * lock contention -- must keep retrying with backoff (worker/task-runner.ts's
+ * `isPermanentTaskFailure` treats git failures as transient precisely so they do). Only this
+ * structurally-unretryable shape fails fast (worker) or returns 409 (API).
  *
- * Matches git's literal (English) rejection text, which is gettext-
- * translated -- callers MUST run the underlying git command with a
- * locale-pinning env (see `gitChildEnv` in `../git-manager.ts`) or an ambient
- * LANG/LC_ALL could silently turn this into a permanent no-op.
+ * Matches git's literal English rejection text, which is gettext-translated: callers MUST run the
+ * git command with a locale-pinning env (`gitChildEnv` in `../git-manager.ts`), or an ambient
+ * LANG/LC_ALL silently turns this into a permanent no-op.
  */
 export declare function isNonFastForwardRejection(message: string): boolean;
 /**
- * Whether a git push failure message is a refused `--force-with-lease` --
- * the remote ref is NOT at the commit the pusher expected, so the forced
- * update was declined and nothing was overwritten.
+ * Whether a git push failure message is a refused `--force-with-lease` -- the remote ref is NOT at
+ * the commit the pusher expected, so the forced update was declined and nothing overwritten.
  *
- * A SEPARATE predicate from `isNonFastForwardRejection` because git's output
- * for the two is disjoint: a refused lease prints
- * ` ! [rejected]        branch -> branch (stale info)` and, unlike an
- * ordinary rejection, emits NEITHER `non-fast-forward`/`fetch first` NOR the
- * `Updates were rejected because` hint. Without this predicate every lease
- * refusal would be classified transient and retried -- three identical,
- * guaranteed-to-fail force attempts -- instead of surfacing as the permanent,
- * human-actionable state it is.
- *
- * Same locale caveat as above: the reason text is gettext-translated, so
- * callers MUST pin the locale (`gitChildEnv`/`gitNetworkChildEnv`).
+ * A SEPARATE predicate from `isNonFastForwardRejection` because git's output for the two is
+ * disjoint: a refused lease prints `(stale info)` and emits NEITHER `non-fast-forward`/`fetch
+ * first` NOR the `Updates were rejected because` hint. Without it every lease refusal is
+ * classified transient and retried -- identical, guaranteed-to-fail force attempts -- instead of
+ * surfacing as the permanent, human-actionable state it is. Same locale caveat as above.
  */
 export declare function isStaleLeaseRejection(message: string): boolean;
 /**
- * Whether a `git fetch <remote> <branch>` failure is specifically "that ref
- * doesn't exist on the remote" -- the ONLY benign fetch outcome, meaning the
- * branch has never been pushed.
- *
- * Narrow on purpose, and the narrowness is the whole point. This predicate
- * exists because a bare `catch` around the fetch classified EVERY failure --
- * unreachable remote, auth denial, permission error on the workspace, corrupt
- * object store -- as "nothing to pull", which callers then logged as normal
- * and proceeded past. Anything this does not recognize must reach the caller
- * as the genuine error it is.
+ * Whether a `git fetch <remote> <branch>` failure is specifically "that ref doesn't exist on the
+ * remote" -- the ONLY benign fetch outcome, meaning the branch has never been pushed.
  *
- * Same locale caveat as the predicates above: the text is gettext-translated,
- * so callers MUST run git with a locale-pinning env (`gitChildEnv`).
+ * Narrow on purpose, and the narrowness is the point: a bare `catch` around the fetch classifies
+ * EVERY failure -- unreachable remote, auth denial, permission error on the workspace, corrupt
+ * object store -- as "nothing to pull", which callers then log as normal and proceed past.
+ * Anything this does not recognize must reach the caller as the genuine error it is. Same locale
+ * caveat as the predicates above.
  */
 export declare function isMissingRemoteRefFailure(message: string): boolean;
 /**
- * Whether a repository has an INTERRUPTED rebase on disk — the `rebase-merge`
- * (interactive/merge backend) or `rebase-apply` (am backend) state directory
- * git leaves behind when a rebase stops for conflicts or the process dies
- * mid-way.
+ * Whether a repository has an INTERRUPTED rebase on disk — the `rebase-merge` (interactive/merge
+ * backend) or `rebase-apply` (am backend) state directory git leaves when a rebase stops for
+ * conflicts or the process dies mid-way. Invisible to every other check the worker makes: a clone
+ * left mid-rebase reports uncommitted changes, so the sync loop's dirty check skips it as
+ * `skippedDirty` on every cycle forever, and `branch-health` sees valid branch.json and scans it
+ * as healthy. Nothing self-heals without it.
  *
- * This state is invisible to every other check the worker makes: a clone left
- * mid-rebase reports uncommitted changes, so the sync loop's dirty check skips
- * it as `skippedDirty` on every cycle forever, and `branch-health` sees valid
- * branch.json and scans it as healthy. Nothing self-heals, and recovery
- * previously meant an operator running `git rebase --abort` on EFS by hand.
- *
- * Never throws — a missing or unreadable repo is reported as "no rebase",
- * which is the safe direction for both callers (the worker only ever uses a
- * `true` to justify an abort it holds the content-write lock for).
+ * Never throws — a missing or unreadable repo is reported as "no rebase", the safe direction for
+ * both callers (the worker only uses a `true` to justify an abort it holds the content-write lock
+ * for).
  */
 export declare function isRebaseInProgress(repoPath: string): Promise<boolean>;
 /**
- * Detect the current HEAD branch name for a given repository root.
- * Returns the branch name, or the provided fallback (default 'main')
- * if detection fails or HEAD is detached.
+ * The repository's current HEAD branch name, or `fallback` when detection fails or HEAD is
+ * detached.
  */
 export declare function detectHeadBranch(repoRoot: string, fallback?: string): Promise<string>;
 /**
- * Resolve the base branch — the fork point for CMS editing branches and the
- * branch used to seed workspace clones.
- *
- * This is the single definition of base-branch behavior (see ARCHITECTURE.md
- * "Branch Identity"):
- * - An explicitly configured `defaultBaseBranch` always wins, in both modes.
- * - In dev mode it is detected from the current git HEAD, so workspaces fork
- *   from the branch the developer has checked out.
- * - Otherwise it is 'main'.
+ * Resolve the base branch — the fork point for CMS editing branches and the branch workspace
+ * clones are seeded from. The single definition of base-branch behavior (see ARCHITECTURE.md
+ * "Branch Identity"): a configured `defaultBaseBranch` always wins in both modes; dev mode
+ * otherwise detects the current git HEAD, so workspaces fork from the developer's checked-out
+ * branch; otherwise 'main'.
  *
- * Static deployments never reach git operations, so callers in static paths
- * must short-circuit before calling this (see createCanopyServices).
+ * Static deployments never reach git operations, so callers on static paths must short-circuit
+ * before calling this (see createCanopyServices).
  */
 export declare function resolveBaseBranch(options: {
     defaultBaseBranch?: string;