@hybridlabor-api/aos 4.2.0-beta.0 → 4.2.0

package/skills/global_config/bdbresilience/contracts/nodes-integration.md

@@ -0,0 +1,225 @@
+# 🤝 Node & Pipeline Integration Contracts
+
+> **Status: partially applied. Read the split below before relying on anything here.**
+>
+> **Applied (2026-09-09).** This skill ships inside AOS at
+> `skills/global_config/bdbresilience/`, and `.agents/nodes.json` lists
+> `bdbresilience` in the `skills` array of two nodes: **`shipping`** (it runs
+> lint/typecheck/tests, which is exactly what the triage parsers read) and
+> **`engineering`** (the error taxonomy and backoff guidance). The dispatcher
+> injects each node's `skills` list into its prompt, so those two nodes are told
+> to reach for this skill. That is the whole of the integration: **guidance, not
+> code.** AOS does not depend on the `bdb-cicd-resilience` package — it has two
+> runtime dependencies and neither is this one.
+>
+> **Not applied, and not currently possible.** Every code-level integration below.
+> `startcycle-dispatch.mjs` contains no `withStateLock` call and cannot contain one:
+> the Workflow runtime gives the dispatcher script **no filesystem access**, which is
+> precisely why AOS solves its own concurrent-write race with single-writer fragments
+> (`production_artifacts/state.d/<node>.json`) plus a merge step instead of a lock.
+> A lock needs a filesystem; the dispatcher does not have one. Do not wire one in.
+>
+> **Where a lock would genuinely fit**, if this is revisited: `installer.js`, which
+> does a real read-modify-write on `~/.agents/.bdb-install-manifest.json` and can be
+> run twice concurrently. That is the only place in AOS with both filesystem access
+> and real contention. Before doing it, note that this library's Windows paths
+> (`EPERM`/`EBUSY` handling, close-before-unlink ordering) are **written but never
+> executed** — two tests skip on non-Windows — and AOS ships to Windows users.
+>
+> §6 documents the `withStateLock()` signature as it actually exists in
+> `src/locking/resource-lock.ts`.
+
+**Deliverable**: Requirement R4 Integration Contracts (proposal)  
+**Target Architecture**: BDB Agent OS (`.agents/nodes.json`, `/startcycle-graph`, `/bdbrainstorm`)  
+**Specification Reference**: `survey_miner_1/survey_report.md`
+
+---
+
+## 1. Proposed Architectural Role
+
+The proposal is to wire the `/bdbresilience` skill suite into the BDB Agent OS multi-agent dispatcher graph. Equipping the **Reviewer** and **Shipping** nodes with resilience capabilities would give the ecosystem automated adversarial auditing of network and concurrency boundaries, and deterministic self-healing quality gates.
+
+Resilience principles would additionally be seeded upstream in **`/bdbrainstorm`** during concept ideation, so that downstream implementation nodes (Engineering, UI/UX, Media) receive explicit reliability requirements.
+
+Applying this proposal is out of scope for the current cycle. It belongs to an AOS integration cycle, which is also where several deferred design questions get their answers — fencing-token verification, the default `ttlMs`, and retry idempotency.
+
+---
+
+## 2. Not adopted: the Reviewer node
+
+> **This proposal was considered and declined on 2026-09-09.** The live
+> `nodes.json` does **not** carry `bdbresilience` in `reviewer.skills`, and that is
+> deliberate, not an oversight.
+>
+> Reviewer reads build artifacts and the plan's contract and argues about
+> correctness. It does not run CI, does not read tool logs, and does not classify
+> retryable failures — the three things this skill is for. A skill allowlist that
+> lists everything guides nothing, so the registration went to `shipping` (which
+> runs the gates whose output the triage parsers read) and `engineering` (which
+> owns the error taxonomy) and stopped there.
+>
+> The section is kept because the reasoning is worth having on record, and because
+> the shape of the entry is a useful template if a future node genuinely needs it.
+
+The **Reviewer** node executes adversarial verification of build-node outputs against the execution plan contract using the *doubt-driven development* discipline. The JSON below is the entry that **would** be added, had this been adopted.
+
+### Declarative Configuration (`.agents/nodes.json`)
+```json
+{
+  "reviewer": {
+    "label": "Reviewer",
+    "agentType": "reviewer",
+    "personaFile": ".claude/agents/reviewer.md",
+    "model": "sonnet",
+    "role": "review",
+    "artifactKey": "review",
+    "writes": null,
+    "optional": false,
+    "skills": [
+      "ui-review",
+      "ux-audit",
+      "architect-review",
+      "systematic-debugging",
+      "bdbresilience"
+    ],
+    "instructions": null
+  }
+}
+```
+
+### Proposed Reviewer Resilience Audit Discipline
+Once equipped with `bdbresilience`, Reviewer would evaluate build outputs (`state.artifacts.{frontend,backend,media}`) against strict resilience checks:
+
+1. **Network & Tool Call Audits**:
+   - Verifies that all external HTTP, API, database, and MCP calls implement structured error classification and Full Jitter exponential backoff.
+   - Flags bare `catch (e) {}` blocks, unhandled Promise rejections, and silent error swallows as:
+     `{ "id": "F-RES-NET-01", "severity": "blocking", "node": "engineering", "status": "open" }`.
+2. **Concurrency & Resource Access Audits**:
+   - Verifies that parallel operations accessing shared files, worktrees, or databases either write isolated fragments (`production_artifacts/state.d/<nodeId>.json`) or acquire a distributed file lock.
+   - Flags missing `finally { await handle.release(); }` blocks as `severity: "blocking"`.
+3. **Ownership Attribution & Stable ID Generation**:
+   - Findings must be attributed strictly to the owning build node (`engineering`, `ui_ux`, or `media`).
+   - Finding IDs must remain stable across cycles (e.g. `F-ENG-01`) so the dispatcher's **No-Progress Guard** can detect stalled repair loops and escalate immediately to human review.
+
+---
+
+## 3. Applied: the Shipping node (`.agents/nodes.json`)
+
+> **Adopted 2026-09-09.** `shipping.skills` now ends with `"bdbresilience"`, and
+> `engineering.skills` likewise. Those two are the whole of the applied
+> integration — see the status block at the top of this file.
+
+The **Shipping** node acts as the release gatekeeper, running mechanical verification gates (lint, typecheck, tests, a11y, seo) after Reviewer findings are cleared. It is the natural home for this skill: the triage parsers read exactly the tsc, ESLint and Jest/Vitest output those gates produce, and `isCleanRun()` is the predicate that decides whether an unrecognised log counts as passing (it does not).
+
+### Declarative Configuration (`.agents/nodes.json`)
+```json
+{
+  "shipping": {
+    "label": "Godmode_Shipping",
+    "agentType": "godmode-shipping",
+    "personaFile": ".claude/agents/godmode-shipping.md",
+    "model": "sonnet",
+    "role": "gate",
+    "artifactKey": "report",
+    "writes": null,
+    "optional": false,
+    "skills": [
+      "godmode-shipping",
+      "webapp-testing",
+      "seo-audit",
+      "wcag-audit-patterns",
+      "github-repo",
+      "clean-code",
+      "bdbresilience"
+    ],
+    "instructions": null
+  }
+}
+```
+
+### Proposed Shipping Quality Gate & Verification Discipline
+Once equipped with `bdbresilience`, Shipping would execute automated diagnostic triage and gating:
+
+1. **Automated Diagnostic Triage Execution**:
+   - Runs mechanical verification commands: `npm run typecheck`, `npm run build`, `npm test`, `npm run lint`.
+   - If a command fails, Shipping pipes stderr/stdout directly into `generateDiagnosticReport(log, runner)`:
+     - A run counts as clean **only if `isCleanRun(report)` is true**, never on `totalFailures === 0` alone — an empty or unparseable log also has zero diagnostics, and reading that as a pass is a fail-open gate.
+     - If all failures are classified as `transient_infra` (`canAutoRetry: true`): Shipping automatically retries the command up to 2 times with Full Jitter before recording a failure.
+     - If any failure is classified as `deterministic_code_regression`: Shipping generates a structured failure section in `production_artifacts/04_release_report.md` detailing the exact failed assertion, target file, line coordinate, and remediation command.
+2. **Gate Population & Node Attribution**:
+   - Updates `state.gate`:
+     ```json
+     {
+       "lint": "pass",
+       "typecheck": "fail",
+       "tests": "pass",
+       "a11y": "skip",
+       "seo": "skip",
+       "blockingNodes": ["engineering"]
+     }
+     ```
+   - Instructs the dispatcher to re-invoke only the failing node (`engineering`) rather than re-running all build nodes.
+3. **Pre-Tool GO Gate Release Protocol**:
+   - When all checks pass, Shipping sets `state.phase = "ready_to_ship"`.
+   - Concludes turn by outputting the Release Report and instructing the operator:
+     > *"All quality gates passed. Reply with the literal word GO to authorize release deployment."*
+   - Strictly prohibits calling `git push` or `npm publish` without human approval verified via `verifyGoGate()`.
+
+---
+
+## 4. Proposed: Integration with `/startcycle-graph`
+
+`~/.claude/workflows/startcycle-dispatch.mjs` and `~/.claude/hooks/graph-gate.mjs` both exist, but neither references this library. The proposal is that `bdbresilience` would power core graph infrastructure:
+
+1. **Parallel Build Fan-Out Isolation**:
+   - When `ui_ux`, `engineering`, and `media` execute concurrently, each node would write exclusively to:
+     `production_artifacts/state.d/<nodeId>.json`
+   - A dedicated barrier folding agent would consolidate fragments into `production_artifacts/state.json` under `withStateLock()`. **This call does not exist in the dispatcher today.**
+2. **Loop Retention Hook (`graph-gate.mjs`)**:
+   - Would intercept turn completion if `state.gate` contains failing checks and `iteration < max_iterations`, blocking session turn-end with exit code 2 to force repair execution. Whether the existing hook already does this independently of `bdbresilience` was not verified for this document.
+3. **No-Progress Guard**:
+   - If Reviewer reports the exact same set of blocking finding IDs across successive iterations, the dispatcher halts immediately (`state.phase = "escalated"`, `state.needs_human = true`). This guard is part of the AOS graph contract, not of this library.
+
+---
+
+## 5. Proposed: Integration with `/bdbrainstorm`
+
+The proposal is that `~/.agents/skills/bdbrainstorm/SKILL.md` would embed resilience requirements into concept planning. Its current content was not inspected for this document:
+
+1. **Pillar 2: `/grill-me` Interactive Inquiries**:
+   - Grills the user on SLA thresholds, API rate limits, failure blast radius, and recovery procedures:
+     - *"What are the rate limits and fallback providers for external dependency X?"*
+     - *"How will concurrent writes to shared database entities be serialized?"*
+2. **Pillar 4: Engineering Godmode (DDD & Clean Architecture)**:
+   - Mandates that domain models represent failure states explicitly as Discriminated Unions (e.g. `Result<T, ClassifiedError>`).
+   - Requires Architecture Decision Records (ADRs) for locking mechanisms and retry backoff strategies.
+3. **Pillar 6: Shipping Godmode & Pipeline Hand-off**:
+   - Packages resilience specifications directly into `state.goal` so downstream Architect and TechLead nodes include them in `production_artifacts/00_execution_plan.md`.
+
+---
+
+## 6. `withStateLock()` — the one part of this document that is real
+
+This function exists today in `src/locking/resource-lock.ts` and behaves as described. It is what a barrier folding agent in §4 would call.
+
+```typescript
+import { withStateLock } from 'bdb-cicd-resilience/locking/index.js';
+
+const merged = await withStateLock(
+  'production_artifacts/state.json',
+  async (state) => {
+    state.findings.push({ id: 'F-ENG-01', status: 'fixed' });
+    return state;
+  },
+  { ttlMs: 15000, acquireTimeoutMs: 10000 }
+);
+```
+
+- Signature: `withStateLock<T>(statePath, updater, options?) => Promise<T>`.
+- The lock resource key is `state:<resolved absolute path>`, so two callers passing different relative paths to the same file still serialize.
+- `acquireTimeoutMs` defaults to `10000` here (not `0` as in `acquireLock`), so callers queue rather than fail on first contention.
+- A missing state file is read as `{}`; any other read error propagates.
+- The updater's return value is written; returning `undefined` writes the state object as mutated.
+- **The write is refused if the lease was lost while the updater ran** — `handle.isExpired()` is checked after the updater returns and before the temp+rename write, and throws rather than clobber a successor's state file.
+- The state file itself *is* written temp+rename. That is unrelated to the lockfile, which is never renamed into place (see `references/distributed-locking.md` §2).
+- The lock is released in a `finally`, and release errors are swallowed.

package/skills/global_config/bdbresilience/references/cicd-triage.md

@@ -0,0 +1,179 @@
+# 🩺 Reference Guide: CI/CD Self-Healing Triage & Diagnostic Reporting
+
+**Pattern**: Pattern 3 — Build, Test & Lint Failure Triage  
+**Module**: `bdb-cicd-resilience/triage`  
+**Authoritative Source**: BDB Agent OS CI/CD Triage Specification
+
+---
+
+## 1. Overview & Problem Statement
+
+When automated CI/CD pipelines fail (during `npm test`, `tsc --noEmit`, `eslint`, or GitHub Actions runs), agents frequently hallucinate root causes by reading unstructured terminal output or trying random edits without identifying the real failure. Alternatively, agents waste execution turns retrying deterministic code bugs, or conversely halt prematurely on transient infrastructure hiccups (such as an npm registry timeout or port bind collision).
+
+The CI/CD Triage Engine ingests raw terminal logs, normalizes ANSI codes and runner annotations, parses failure coordinates across 5 major runners, classifies failures into transient infrastructure versus deterministic regressions, and produces verified JSON diagnostic summaries with exact remediation commands.
+
+---
+
+## 2. Multi-Runner Log Ingestion & Normalization
+
+Raw build logs contain noisy ANSI color sequences, carriage return overwrites (`\r\n`), and runner-specific group wrappers (`##[group]`, `::error::`).
+
+### ANSI Normalization Pipeline
+1. **Control Sequence Stripping**: Removes terminal escapes (`\x1b[[0-9;]*[mGKF]`).
+2. **CRLF Normalization**: Converts Windows line endings to standard Unix newlines (`\r\n` → `\n`).
+3. **CI Annotation Scrubbing**: Normalizes GitHub Actions workflow commands:
+   - `##[group]...##[endgroup]`
+   - `##[error]...`
+   - `::error file={name},line={line}::{message}`
+
+---
+
+## 3. Runner-Specific Log Parsers
+
+The engine incorporates dedicated parsers for each standard ecosystem tool:
+
+| Runner | Detected Signatures | Extracted Data Coordinates | Remediation Command Generated |
+|--------|---------------------|----------------------------|-------------------------------|
+| **Vitest** | `FAIL tests/...`<br>`AssertionError:`<br>`expected ... to be ...` | Test file path, line, column, assertion diff snippet | `npx vitest run <file> -t "<test>"` |
+| **Jest** | `● <describe> › <test>`<br>`Expected: ... Received: ...`<br>`at ... (<file>:<line>:<col>)` | Test spec file, stack frame line/col (prioritizing user code over `node_modules`) | `npx jest <file> -t "<test>"` |
+| **TypeScript (`tsc`)** | `src/auth.ts(42,15): error TS2322`<br>`src/auth.ts:42:15 - error TS2322` | Source file, line, column, TS error code, type mismatch explanation | `npx tsc --noEmit` |
+| **ESLint** | `<file>:<line>:<col>: <msg> [<rule>]`<br>Tabular/Stylish reporter lines | Target source file, line, col, rule ID, severity | `npx eslint --fix <file>` |
+| **GitHub Actions** | `##[error]Process completed with exit code 137`<br>`The operation was canceled`<br>`Request timeout after 30000ms` | Runner step, exit code, memory or timeout fault | Automated infrastructure retry with jitter |
+
+---
+
+## 4. Flaky Infrastructure vs. Deterministic Regression Classifier
+
+The core intelligence distinguishes between errors that can be safely retried and code bugs requiring source modification:
+
+```
+                            [ Parsed Diagnostic Error ]
+                                         │
+                                         ▼
+                 ┌───────────────────────────────────────────────┐
+                 │     classifyDiagnostic(error, context)        │
+                 └───────────────────────┬───────────────────────┘
+                                         │
+                 ┌───────────────────────┴───────────────────────┐
+                 ▼                                               ▼
+     [ TRANSIENT INFRASTRUCTURE ]                   [ DETERMINISTIC REGRESSION ]
+     - HTTP 429 Throttling                          - AssertionError (Expected X, got Y)
+     - Socket ETIMEDOUT / ECONNRESET                - TypeScript Type Error (TS2322)
+     - Runner Exit Code 137 (OOM)                   - SyntaxError / Parsing Failure
+     - EADDRINUSE (Port collision)                  - ESLint Rule Violation
+     - Registry 503 / DNS Blip                      - Missing Export / ReferenceError
+                 │                                               │
+                 ▼                                               ▼
+       canAutoRetry: true                              canAutoRetry: false
+   (Retry step with Full Jitter)                  (Requires source code repair)
+```
+
+### Classification Heuristics
+- **Transient Infrastructure (`transient_infra`)**:
+  - `canAutoRetry: true`
+  - Does NOT count against agent repair loop limits.
+  - Automatically triggered up to 2 times before escalating.
+- **Deterministic Code Regression (`deterministic_code_regression`)**:
+  - `canAutoRetry: false`
+  - Attributed to the responsible build node (Engineering, UI/UX).
+  - Feeds into `production_artifacts/review_findings.md` or `state.findings`.
+- **Unrecognised text** falls to `deterministic_code_regression`, i.e. this classifier **fails closed**. That is the opposite of `classifyError`'s unknown default in the recovery module, and deliberately so — see `error-recovery.md` §7 for why neither should be changed to match the other.
+
+---
+
+## 5. Was Anything Understood? — `parseStatus` and `isCleanRun`
+
+`totalFailures === 0` is **not** the answer to "did this run pass". A log that was empty, and a log that no parser recognised, both produce zero diagnostics. Reading either as a clean gate is a fail-open defect, so the report carries a third axis:
+
+| `parseStatus` | When | `totalFailures` | `canAutoRetry` | `requiresHumanIntervention` |
+|---|---|---|---|---|
+| `parsed` | a runner signature matched, or a parser extracted ≥1 diagnostic | as extracted | `n > 0 && transient === n` | `deterministic > 0` |
+| `empty` | the log is empty or pure ANSI after stripping | `0` | `false` | `true` |
+| `unparsed` | nothing matched — e.g. a Go, pytest or Maven failure | `0` | `false` | `true` |
+
+`empty` is deliberately **not** clean: a build step that produced no output is not evidence that it passed. Neither status ever carries a synthetic diagnostic — inventing one would inflate `totalFailures` and lie to every consumer counting failures.
+
+The predicate is exported so no consumer has to reconstruct the rule:
+
+```typescript
+import { isCleanRun } from 'bdb-cicd-resilience/triage/index.js';
+
+if (isCleanRun(report)) { /* the only sanctioned "it passed" */ }
+```
+
+`isCleanRun(report) === (report.summary.parseStatus === 'parsed' && report.summary.totalFailures === 0)`. Any AOS integration must call it rather than reading `totalFailures` directly.
+
+---
+
+## 6. Structured JSON Diagnostic Schema
+
+`dominantCategory` is `undefined` whenever `totalFailures === 0`; it is not defaulted to a classification.
+
+```json
+{
+  "timestamp": "2026-09-05T14:45:00.000Z",
+  "runner": "vitest",
+  "summary": {
+    "totalFailures": 2,
+    "transientCount": 1,
+    "deterministicCount": 1,
+    "parseStatus": "parsed",
+    "dominantCategory": "deterministic_code_regression",
+    "canAutoRetry": false,
+    "requiresHumanIntervention": true
+  },
+  "diagnostics": [
+    {
+      "file": "tests/unit/auth.test.ts",
+      "line": 42,
+      "column": 14,
+      "assertionSnippet": "expect(user.isAuthenticated).toBe(true)",
+      "classification": "deterministic_code_regression",
+      "rootCause": "AssertionError: expected false to be true // Received user object without auth token",
+      "remediationCommand": "npx vitest run tests/unit/auth.test.ts -t \"verifies authenticated user\"",
+      "canAutoRetry": false
+    },
+    {
+      "file": "src/services/api.ts",
+      "classification": "transient_infra",
+      "rootCause": "FetchError: request to https://registry.npmjs.org timed out after 30000ms (ETIMEDOUT)",
+      "remediationCommand": "npm cache clean --force && npm install",
+      "canAutoRetry": true
+    }
+  ]
+}
+```
+
+---
+
+## 7. TypeScript API Usage Example
+
+```typescript
+import {
+  generateDiagnosticReport,
+  classifyDiagnostic,
+  isCleanRun,
+  stripAnsi
+} from 'bdb-cicd-resilience/triage/index.js';
+
+// Clean and parse raw output
+const cleanLog = stripAnsi(rawStderr);
+const report = generateDiagnosticReport(cleanLog);
+
+if (isCleanRun(report)) {
+  console.log('✅ All checks passed clean.');
+} else if (report.summary.parseStatus !== 'parsed') {
+  console.error(`❌ Log was ${report.summary.parseStatus} — nothing was understood, not a pass.`);
+} else if (report.summary.canAutoRetry && report.summary.deterministicCount === 0) {
+  console.log('⚠️ Transient infrastructure failure detected. Executing auto-retry...');
+  await executeRetryCommand();
+} else {
+  console.error('❌ Deterministic code regression detected:');
+  for (const diag of report.diagnostics) {
+    if (diag.classification === 'deterministic_code_regression') {
+      console.error(`  - ${diag.file}:${diag.line} -> ${diag.rootCause}`);
+      console.error(`    Suggested fix command: ${diag.remediationCommand}`);
+    }
+  }
+}
+```

package/skills/global_config/bdbresilience/references/distributed-locking.md

@@ -0,0 +1,235 @@
+# 🔒 Reference Guide: Distributed File Locking & Concurrency Control
+
+**Pattern**: Pattern 2 — Mutual Exclusion & Concurrency Control  
+**Module**: `bdb-cicd-resilience/locking`  
+**Authoritative Source**: BDB Agent OS Concurrency Specification
+
+---
+
+## 1. Overview & Problem Statement
+
+In the BDB Agent OS multi-agent ecosystem, multiple autonomous agents, terminal sessions, and worktree subprocesses operate concurrently. Without rigorous synchronization, concurrent access to shared resources leads to critical data corruption:
+- **`production_artifacts/state.json` Overwrites**: Parallel agents clobbering each other's status, findings, and phase transitions.
+- **Git Branch & Worktree Collisions**: Concurrent `git checkout`, `git commit`, or branch operations producing index lock contention (`.git/index.lock`).
+- **Database Migration Races**: Competing processes applying conflicting schema alterations simultaneously.
+
+The Distributed Locking Engine provides deterministic mutual exclusion using atomic POSIX/APFS filesystem primitives, configurable lease timeouts, background heartbeat renewals, monotonic fencing tokens, and safe stale/orphan lock eviction.
+
+---
+
+## 2. Deterministic Atomic Locking Mechanics
+
+### POSIX Atomic Test-and-Set
+File creation with the flags `O_CREAT | O_EXCL` (Node.js flag `'wx'`) is guaranteed by POSIX and APFS kernel implementations to be strictly atomic.
+
+```
+Worker A (Attempt Acquire)                    Worker B (Attempt Acquire)
+           │                                             │
+           ├─────────────────────┬───────────────────────┤
+           │                     │                       │
+           ▼                     ▼                       ▼
+    [ open('...lock', 'wx') ]                 [ open('...lock', 'wx') ]
+           │                                             │
+     Kernel Awards                                 Kernel Rejects
+  File Descriptor (FD)                            with code EEXIST
+           │                                             │
+           ▼                                             ▼
+  [ Writes Metadata JSON ]                     [ Inspects Lock / Enters ]
+  [ Enters Critical Sec  ]                     [ Polling Backoff Retry  ]
+```
+
+If the lockfile already exists, the OS kernel immediately fails the call with `EEXIST` without modifying the target file, ensuring zero window for race conditions.
+
+### Pre-Serialization, and the window that remains
+1. The complete metadata JSON payload is formatted in memory *before* `fs.open(lockPath, 'wx')` is invoked.
+2. The payload is written through the returned file descriptor and `fsync`'d (`fileHandle.sync()`) **before the handle is published to the caller**.
+3. The descriptor is then **retained**, not closed. It is handed to the heartbeat manager and closed in `release()`. Every renewal writes through it, so a renewal can only ever land on the inode this holder created — never on whatever file currently occupies the path.
+
+What step 2 does *not* guarantee: the **containing directory is not `fsync`'d**, so on ext4 the directory entry itself may not survive a power cut. That is deliberate and is the safe failure direction here — a missing lock is recoverable, a phantom lock is not.
+
+The gap between `open('wx')` and the payload write is a real 0-byte window and cannot be closed from the writer side: `O_CREAT | O_EXCL` is the only atomic create-if-not-exists primitive available, and replacing it with temp+`rename()` would destroy mutual exclusion, because `rename()` overwrites its target unconditionally and every contender would win. The window is closed from the **reader** side instead, by the unreadable-lock grace in §4.
+
+### Structured Lock Metadata Schema
+```json
+{
+  "lockId": "7f8b9e20-94d3-4f2a-8b1a-9f5e1284d0a1",
+  "resource": "production_artifacts/state.json",
+  "ownerId": "pid_28419_9f5e1284",
+  "pid": 28419,
+  "acquiredAt": 1757083200000,
+  "heartbeatAt": 1757083210000,
+  "ttlMs": 10000,
+  "fencingToken": 42,
+  "hostname": "denck-studio.local"
+}
+```
+
+- **There is no `leaseExpiresAt` field.** The lease expiry is *derived* — `heartbeatAt + ttlMs` — and evaluated at the point of use. Storing it as well would create a second source of truth that can disagree with its own inputs on every heartbeat.
+- **`fencingToken`**: Monotonically increasing integer, allocated per lock path. **Advisory only** — see §7.
+- **`pid`** / **`hostname`**: Used together for liveness verification during eviction. The PID is only probed when `hostname` matches the local host, because PIDs are not meaningful across machines.
+
+### Lease expiry as seen by the holder
+
+`handle.isExpired()` does **not** read `heartbeatAt` from the metadata: that value is frozen at acquisition and only moved by `extend()`, so a healthy, actively-renewing lock would report expired the moment `ttlMs` elapsed. It reads the heartbeat manager's `lastRenewedAt` instead — the timestamp of the last write+truncate that actually resolved:
+
+```
+isExpired() === released || lockLost || Date.now() > lastRenewedAt + ttlMs
+```
+
+`withStateLock` relies on this: after the updater returns and before the state file is written, it throws rather than write if the lease was lost while the updater ran.
+
+---
+
+## 3. Lease Timeouts (TTL) & Background Heartbeat Renewal
+
+Static lockfiles are vulnerable to permanent deadlocks if the holding process crashes or is forcefully terminated (`SIGKILL`). The engine solves this using expiring leases backed by active background heartbeat renewal.
+
+### Heartbeat Renewal Architecture
+1. **Configurable TTL**: The code default is **`10,000 ms`** (`ttlMs` in `LockAcquisitionOptions`). That is aggressive for CI workloads, where a single step can block on a network call for longer than 10 s; **raise it explicitly** for CI-held locks. The default is a candidate for revision once real hold times are measurable against AOS.
+2. **Periodic Renewal Interval**: `heartbeatIntervalMs` defaults to `Math.max(10, Math.floor(ttlMs / 3))` — i.e. TTL/3 with a 10 ms floor, so a very short TTL cannot produce a busy timer.
+3. **In-place write through the retained descriptor.** Renewal does **not** use a temporary file and does **not** `rename()`. It writes the new payload at offset 0 through the fd retained from acquisition, then `truncate()`s to the new byte length. A tempfile+rename renewal would write by *path*, which is exactly how a holder ends up clobbering a successor's lock.
+
+Each tick:
+
+| Step | Condition | Outcome |
+|---|---|---|
+| 1 | read the file **by path**; `ENOENT` | lock lost |
+| 2 | present but unparseable | **skip the tick** — no write, no truncate, no `lastRenewedAt` advance, and *not* lock-lost |
+| 3 | `lockId` in the file ≠ our own | lock lost (evicted or stolen) |
+| 4 | match | `write(payload, 0)` through the fd, `truncate(Buffer.byteLength(payload))`, then record `lastRenewedAt` |
+
+**Step 2 is deliberate.** Step 1 reads by path and can legitimately catch a successor mid-write; treating one torn read as terminal would make a healthy lock self-evict. Skipping is not silent either — `lastRenewedAt` stops advancing, so *persistent* unparseability still terminates the lease exactly one `ttlMs` later through the ordinary expiry path.
+
+**The truncate in step 4 is not optional.** Writing a shorter payload at offset 0 leaves the tail of the previous one behind, producing permanently invalid JSON — which the §4 grace then hides for its full window, because these very writes keep refreshing `mtime`. `extend()` uses the same write+truncate and records `lastRenewedAt` only after **both** resolve, for the same reason.
+
+"Lock lost" means: stop the timer, close the fd, mark the handle released, fire `onEvicted`, and make `isExpired()` return `true`.
+
+```
+       [ Active Lock Lease (TTL: 15s) ]
+  0s   ├──────────────────────────────────────────────────┤ 15s
+       │                                                  │
+       ▼ (Heartbeat @ 5s)                                 │
+  5s   ├── In-place write + truncate (own fd) ────────────┤ 20s
+       │                                                  │
+       ▼ (Heartbeat @ 10s)                                │
+  10s  ├── In-place write + truncate (own fd) ────────────┤ 25s
+```
+
+### Release ordering
+
+`release()` sequences **stop heartbeat → close fd → unlink**, and that ordering satisfies two unrelated constraints at once. A refactor can satisfy either while breaking the other, and neither break is visible on the other's platform:
+
+1. **Stop before unlink** — otherwise a tick firing between the unlink and the stop reads `ENOENT` and fires `onEvicted` on a lock that was released normally: a self-inflicted false eviction signal.
+2. **Close before unlink** — otherwise Windows leaves a pending-delete entry and the next `open(lockPath, 'wx')` fails `EEXIST` against a file that is logically already gone.
+
+If the lease was already lost, `release()` skips the unlink entirely: the file at that path belongs to a successor now.
+
+---
+
+## 4. Safe Stale & Orphaned Lock Eviction Protocol
+
+When an agent encounters an existing lockfile, it must verify whether the lock is actively held or orphaned.
+
+**Eviction is detection, not prevention.** Step 6 narrows the decide-then-break window; it does not close it. Two processes on a POSIX filesystem cannot make "decide stale" and "break" one atomic operation without a shared arbiter. The actual guarantee is weaker and worth stating plainly: an owner whose live lock is wrongly broken **learns within one heartbeat interval**, via renewal step 3.
+
+### Multi-Step Eviction Verification
+1. **Existence**: `stat` the lockfile. `ENOENT` ⇒ `{evicted: false, reason: "not_found"}`.
+2. **Unreadable-lock grace**: a 0-byte *or* unparseable-JSON lockfile is evicted only once `Date.now() - stat.mtimeMs > grace`, where `grace = max(1000, callerTtlMs ?? 10000)`. Otherwise `not_stale`. This is what closes the 0-byte creation window from §2 without a debounce.
+3. **Process liveness**: inspect `lock.pid`, and only if `lock.hostname` is absent or matches the local host. Send POSIX signal 0 (`process.kill(pid, 0)`); `ESRCH` means the holding process is dead.
+4. **Clock-skew clamp**: `effectiveHeartbeat = Math.min(lock.heartbeatAt, Date.now())`. **There is no skew tolerance constant** — a future-dated heartbeat is clamped to now, and liveness and TTL both still run against it.
+5. **Lease floor**: `effectiveTtl = Math.max(callerTtlMs ?? 0, lock.ttlMs ?? 10000)`. A contender may *lengthen* the grace it extends to a holder; it may never *shorten* the lease the holder recorded. The lease is a property of the owner.
+6. **Revalidate immediately before the break**: re-read the file and compare `lockId` and `heartbeatAt` against the values the staleness decision was made on. Any change ⇒ `{evicted: false, reason: "race_lost"}` — most often a stalled holder that resumed and renewed.
+7. **Atomic rename break protocol**:
+   - Competing evictors never call `fs.unlink()` directly, as multiple processes could race and unlink a newly acquired legitimate lock.
+   - The evictor renames the stale lockfile to a unique quarantine path: `.evict.<uuid>`.
+   - Exactly one evictor succeeds. A competing evictor receives `ENOENT` — or, on Windows, `EPERM`/`EBUSY` because another process still holds the file open — and reports `reason: "race_lost"` in either case.
+   - The winning evictor immediately unlinks the quarantine file, and the caller retries acquisition.
+
+#### Why step 2 discriminates at all
+
+The grace tells crash debris apart from a live holder **only because renewal writes in place and therefore refreshes the file's `mtime` on every tick**. A live holder's unreadable moment is always young relative to `mtime`; genuine debris ages without bound because nothing writes to it. Do not make renewal lazy, conditional, or optional without re-deriving this check — it silently degrades into "evict anything unreadable after 1 s".
+
+Step 2 also cannot apply step 5's protection: there is by definition no parseable `ttlMs` to defend. When a contender passes a short TTL, **the 1000 ms floor is doing all of the safety work**, and a holder stalled mid-write for more than 1 s is evictable regardless of the lease it recorded. The window being protected is a single `write()` on an already-open fd, three orders of magnitude under the floor — a real ceiling, not a proof.
+
+### Clock skew, stated as a change of direction
+
+Earlier revisions of this guide documented a `+60000 ms` skew tolerance and said a future-dated lock was "treated as invalid". The code did neither: it returned `not_stale` for anything more than 1 s in the future, which made every future-dated lock **immortal — including one whose holder was provably dead**. Both the tolerance and that early return are gone. Step 4 clamps instead, so no number survives to be tuned.
+
+---
+
+## 5. State Partitioning vs. Locking in BDB Agent OS
+
+The BDB ecosystem balances coarse-grained locking with fine-grained partition isolation:
+
+```
++---------------------------------------------------------------------------------------+
+|                               Concurrency Strategy Selection                           |
++-------------------------------------------+-------------------------------------------+
+                                            |
+           ┌────────────────────────────────┴────────────────────────────────┐
+           ▼                                                                 ▼
+┌──────────────────────────────────────┐          ┌──────────────────────────────────────┐
+│       Parallel Build Fan-Out         │          │     Shared Mutable Resources         │
+│  (Engineering, UI/UX, Media Nodes)   │          │  (state.json, git branches, worktree)│
+├──────────────────────────────────────┤          ├──────────────────────────────────────┤
+│ Strategy: State Partitioning         │          │ Strategy: Distributed File Locking   │
+│ Each node writes isolated fragment:  │          │ Wrap mutation in withStateLock, which│
+│ production_artifacts/state.d/<id>.json│         │ serializes on the lock and writes the │
+│ Followed by single merge agent       │          │ STATE FILE via temp+rename           │
+└──────────────────────────────────────┘          └──────────────────────────────────────┘
+```
+
+---
+
+## 6. TypeScript API Usage Examples
+
+### Guarding Shared State Mutation
+```typescript
+import { withStateLock } from 'bdb-cicd-resilience/locking/index.js';
+
+await withStateLock(
+  'production_artifacts/state.json',
+  async (state) => {
+    state.phase = 'build';
+    state.artifacts.backend = 'production_artifacts/02_backend_schema.md';
+    state.findings.push({ id: 'F-ENG-02', status: 'fixed' });
+    return state; // Automatically written back via atomic rename
+  },
+  { ttlMs: 15000, acquireTimeoutMs: 10000 }
+);
+```
+
+### Resource Guard with Auto-Eviction
+```typescript
+import { acquireLock } from 'bdb-cicd-resilience/locking/index.js';
+
+const handle = await acquireLock('git_worktree_main', {
+  lockDir: '.git/locks',
+  ttlMs: 20000,
+  acquireTimeoutMs: 15000,
+  retryIntervalMs: 100,
+});
+
+try {
+  // Critical section
+  await performGitOperations();
+} finally {
+  await handle.release();
+}
+```
+
+### Inspecting a lock without taking it
+`inspectLock(resource, { lockDir })` returns the parsed metadata, or `null`. Because renewal writes in place, a reader can catch a torn write, so `inspectLock` **re-reads once after ~5 ms** before answering `null`. An unreadable lock is not evidence of no lock — the same argument as the §4 eviction grace, applied to a public query.
+
+---
+
+## 7. Known limitations
+
+These are load-bearing and deliberately not engineered away in this cycle. Do not design against a stronger guarantee than the ones listed here.
+
+- **Fencing tokens are advisory.** No resource in this library verifies a token, and the `.seq` counter backing them is written with a plain `writeFile` whose failure is swallowed — it is **not crash-durable**. Tokens are also allocated *before* the `open('wx')` attempt, so every losing poll burns one. They are strictly increasing per process, non-decreasing across a run, and **must not be relied on for cross-host safety** until some resource actually validates them.
+- **The default lock directory is `process.cwd()/.locks/`.** It follows the working directory of whichever process acquires, which is not the same thing as following the resource.
+- **No re-entrancy.** A second acquisition of a path already held by the same process fast-rejects without touching the filesystem. That is correct for a mutex, but it means a sibling async task in the same process fails fast rather than queuing. Distinguishing "same logical caller re-entering" from "sibling task waiting" needs a caller identity that no consumer currently supplies.
+- **`HeartbeatManager` is not part of the public barrel.** It requires the `lockId` and the fd from the acquiring `open('wx')`, neither of which a caller that did not acquire the lock can synthesise. That removes the *accidental* path to renewing someone else's lock, not the determined one — a caller can still open the path `r+` and copy the `lockId` out of the file. No file-based lock can prevent that.
+- **The containing directory is not `fsync`'d** on acquisition (§2).
+- **Windows behaviour is unverified.** The `EPERM`/`EBUSY` handling in the break protocol and in `release()` exists to be correct on Windows, but has never been executed on a Windows host.