@githolon/dsl 0.73.0 → 0.75.0

package/dart/CHANGELOG.md

@@ -1,3 +1,50 @@
+## 0.51.0
+
+- **The burn-down wave.** Dead-letter queue surface on the session plane: `deadLetters()`,
+  `retryDeadLetter()`, `discardDeadLetter()`, `salvage()`, `absorbSalvage()` — with the local-only
+  retry/absorb fixes and the salvage-shape parking fix (refused work is NEVER silently dropped).
+  `nomos_headless.dart` exports the full session surface. Requires Nomos Cloud ≥ the 2026-07-11
+  burn-down deploy for the fleet DLQ sweep lanes (`/dlq-summary`, `/dlq-sweep`) and the
+  content-addressed large-deploy staging lane.
+
+## 0.50.1
+
+- **Structural: the session-delegation-gap class is closed.** All event-dispatch registries
+  (watch subscriptions, compat watches, custody/sync/signal/flame/span/transfer/status
+  controllers, span buffers, session registries) now route through one `_eventPlane` seam that
+  resolves to the plane owning the message loop — the base class is correct for `NomosSession`
+  automatically, and all 17 hand-written per-method session overrides are DELETED (including the
+  0.48.1 `watchPendingConflicts` fix, whose regression test still passes — the proof). Five
+  latent unreported instances of the same bug fixed en passant: `session.custodyEvents` (dead
+  stream), `connectedSessions` (empty), `connect()`-on-session state stamping, `checkCompat()`
+  caching, `noteLocalSpan()` (dead buffer). A source-level tripwire test fails the suite if a
+  future Stream-returning method bypasses the seam.
+- **The first-five-minutes gauntlet** — one checklist test walking the entire promised surface
+  (deviceKeyed cluster + phase diagnostics, the blessed session-bound shape, local autoSync
+  posture with zero-fetch assertion, acquireSession single-flight, reactive first-snapshots,
+  attested keyed reads, custody reset/re-seed, deadline-bounded disposal) — now runs in CI on
+  every client/runner/codegen change. Every one of this week's four tenant-reported lifecycle
+  bugs appears as an explicit leg.
+
+## 0.50.0
+
+- **No silent hangs — the standing harness property.** Every `NomosTestHarness` lifecycle phase now
+  has a deadline (overridable via the new `phaseTimeout` param) and throws a typed
+  `HarnessPhaseTimeout` naming the phase (e.g. `"3b: keyed reconnect of 'catalogue'"`), workspace,
+  elapsed time, the awaited bridge op, and likely causes — a wedge is a 30-second named exception,
+  never a 40-minute bisection. Every phase logs terse enter/exit diagnostics. Disposal deadline
+  breaches are logged, not thrown — teardown always completes.
+- **Keyed-reconnect lane hardened** (the `deviceKeyed` cluster hang report): harness phase 3b
+  (keygen + keyed reconnect) had no timeout and no diagnostics — any wedge there hung silently
+  after "4 session(s) connected". Additionally two runner/realm defects fixed: the stale session
+  record stayed routable during an async re-open (concurrent ops could hit the disposed holon —
+  now an atomic replace with a fast typed refusal in the window), and a re-open with new
+  credentials but no `restoreFrom` silently kept the OLD identity (the fresh authorSecret was
+  never installed) — an identity-bearing option change now forces an in-place re-mount over
+  resident custody.
+- co2's acceptance implemented verbatim: `cluster(deviceKeyed:)` completes, `devicePublicKey`
+  populated, colocated attested read signed by the re-opened key, disposal completes.
+
 ## 0.49.0
 
 - **Fix: local-only `autoSync()` deadlocked the multi-workspace plane.** A `local://` session's

package/dart/lib/nomos_headless.dart

@@ -39,3 +39,11 @@ library;
 
 export 'src/node_runner_transport.dart';
 export 'src/test_harness.dart';
+// THE FULL SESSION SURFACE (task #86 gap 1): a headless test types everything the harness hands out —
+// [NomosSessionCredentials] (the `acquireSession` ifAbsentCredentials callback's return type),
+// [NomosBridge]/[NomosSession]/[NomosBbox]/[NomosCompat], the E2E sealing client
+// ([NomosKeyStore]/[WrappedKeyStore]/[NomosEncryption]), and the typed session-bound errors —
+// WITHOUT also importing the web barrel. Both files are web-safe (they are exported from
+// `nomos_client.dart` too); re-exporting them here just makes the headless import self-sufficient.
+export 'src/webview_bridge.dart';
+export 'src/session_bound.dart';

package/dart/lib/src/test_harness.dart

@@ -63,6 +63,43 @@ class NomosTestHarnessException implements Exception {
   String toString() => 'NomosTestHarnessException: $message';
 }
 
+/// A TYPED per-phase deadline breach — the "NO SILENT HANGS" guarantee: every lifecycle await in
+/// [NomosTestHarness] (install, runner spawn, ready, connect, keygen, keyed reconnect, seed, dispose)
+/// runs under a generous deadline and, instead of wedging forever with no output, throws THIS —
+/// naming the phase, the workspace, how long it waited, the bridge op it was awaiting, and the
+/// likely causes where they are known. Subclasses [NomosTestHarnessException] so existing
+/// `on NomosTestHarnessException` handling keeps working. Tune deadlines with the harness's
+/// `phaseTimeout` parameter (it overrides EVERY phase's default when set).
+class HarnessPhaseTimeout extends NomosTestHarnessException {
+  /// The human phase name (e.g. `3b: keyed reconnect of 'catalogue'`).
+  final String phase;
+
+  /// The workspace the phase was operating on (null for plane-wide phases like runner spawn).
+  final String? workspace;
+
+  /// How long the harness waited before giving up.
+  final Duration elapsed;
+
+  /// What the harness was awaiting (the bridge op / subprocess), e.g. `connect`, `authorKeygen`.
+  final String awaiting;
+
+  /// Likely causes, where the harness knows them (mirrors DomainNotInstalledForSession.possibleCauses).
+  final List<String> likelyCauses;
+
+  HarnessPhaseTimeout({
+    required this.phase,
+    this.workspace,
+    required this.elapsed,
+    required this.awaiting,
+    this.likelyCauses = const [],
+  }) : super(
+            'phase "$phase"${workspace != null ? ' (workspace "$workspace")' : ''} '
+            'did not complete within ${elapsed.inSeconds}s while awaiting `$awaiting`'
+            '${likelyCauses.isEmpty ? '' : ' — likely causes: ${likelyCauses.map((c) => '\n  • $c').join()}'}');
+  @override
+  String toString() => 'HarnessPhaseTimeout: $message';
+}
+
 /// The decoy session [NomosTestHarness.ephemeral] connects alongside the workspace under test — it exists
 /// so the plane is ALWAYS multi-session in tests (sole-session inference never silently passes).
 const String _decoyWorkspace = '__nomos-decoy';
@@ -107,17 +144,58 @@ class NomosTestHarness {
   /// The offline-install lane config (for [seedWorkspaceFromDeployJson]); null when unknown.
   final _InstallLane? _installLane;
 
+  /// When set, overrides EVERY phase's default deadline (see [HarnessPhaseTimeout]).
+  final Duration? _phaseTimeout;
+
   NomosTestHarness._(this.bridge, this.workspace, this._transport, this._workdir,
       this._onDiagnostic, this._sessionNames,
       {Map<String, String> devicePublics = const {},
       this.frameworkHash,
       Map<String, List<String>> lawHashes = const {},
       Map<String, String> snapshots = const {},
-      _InstallLane? installLane})
+      _InstallLane? installLane,
+      Duration? phaseTimeout})
       : _devicePublics = devicePublics,
         _lawHashes = Map.of(lawHashes),
         _snapshots = Map.of(snapshots),
-        _installLane = installLane;
+        _installLane = installLane,
+        _phaseTimeout = phaseTimeout;
+
+  // ── THE "NO SILENT HANGS" MACHINERY — every lifecycle await runs as a named, deadlined PHASE ──
+
+  /// Per-phase default deadlines (a [phaseTimeout] argument overrides them all).
+  static const Duration _kInstallDeadline = Duration(seconds: 60);
+  static const Duration _kSpawnDeadline = Duration(seconds: 30);
+  static const Duration _kOtherDeadline = Duration(seconds: 30);
+
+  /// Run one lifecycle phase under a deadline, logging terse enter/exit lines (their ask 5) and
+  /// converting a breach into the typed [HarnessPhaseTimeout] — a wedge is NEVER a silent hang.
+  static Future<T> _phased<T>({
+    required String phase,
+    String? workspace,
+    required String awaiting,
+    required Duration timeout,
+    required Future<T> Function() run,
+    List<String> likelyCauses = const [],
+    void Function(String line)? onDiagnostic,
+  }) async {
+    void log(String m) {
+      if (onDiagnostic != null) onDiagnostic('[nomos-test-harness] $m');
+    }
+
+    final where = workspace != null ? ' "$workspace"' : '';
+    log('phase $phase$where (≤${timeout.inSeconds}s) …');
+    final sw = Stopwatch()..start();
+    final r = await run().timeout(timeout,
+        onTimeout: () => throw HarnessPhaseTimeout(
+            phase: phase,
+            workspace: workspace,
+            elapsed: timeout,
+            awaiting: awaiting,
+            likelyCauses: likelyCauses));
+    log('phase $phase$where done (${sw.elapsedMilliseconds}ms)');
+    return r;
+  }
 
   /// The base64 device PUBLIC key a `deviceKeyed` [cluster] session was opened with (null otherwise). Its
   /// `sha256(base64decode(...))` is the attestor keyHash a reader enrols to trust this source's signed reads.
@@ -167,6 +245,7 @@ class NomosTestHarness {
     void Function(String line)? onDiagnostic,
     Duration readyTimeout = const Duration(seconds: 30),
     Duration connectTimeout = const Duration(seconds: 120),
+    Duration? phaseTimeout,
     bool decoySession = true,
   }) async {
     if (deployJsonPaths.isEmpty) {
@@ -196,48 +275,70 @@ class NomosTestHarness {
     final phase = (String m) { if (onDiagnostic != null) onDiagnostic('[nomos-test-harness] $m'); };
     try {
       final snapshot = '${workdir.path}/snapshot.bin';
-      phase('phase 1/4 installing ${deployJsonPaths.length} law package(s) offline into "$workspace" …');
-      final info = await _runInstall(
-          node: node,
-          useInRepoScript: useInRepoScript,
-          inRepoScript: resolvedHelper,
-          githolonCmd: githolonCmd,
-          deployJsonPaths: deployJsonPaths,
+      final info = await _phased(
+          phase: '1/4: offline law install (${deployJsonPaths.length} package(s))',
           workspace: workspace,
-          snapshot: snapshot,
-          runtimeDir: runtimeDir,
-          onDiagnostic: onDiagnostic);
-
-      phase('phase 2/4 spawning the node runner (node=$node) …');
-      transport = await NodeRunnerTransport.start(
-        entry: entry,
-        resolveFrom: resolveFrom,
-        node: node,
-        environment: {
-          'NOMOS_OFFLINE': '1',
-          'NOMOS_OFFLINE_RESTORE': snapshot,
-          if (runtimeDir != null) 'NOMOS_OFFLINE_RUNTIME': runtimeDir,
-        },
-        onDiagnostic: onDiagnostic,
-      );
-      final plane = NomosBridge(transport);
-      phase('phase 3/4 awaiting runner ready (≤${readyTimeout.inSeconds}s) …');
-      await plane.ready.timeout(readyTimeout,
-          onTimeout: () => throw NomosTestHarnessException(
-              'the offline runner never signalled ready within ${readyTimeout.inSeconds}s '
-              '(phase 3/4: is `node` on PATH and ~/.holon/runtime warm? the runner process may have '
-              'failed to boot the engine — run with onDiagnostic to see its stderr)'));
-      phase('phase 4/4 connecting session "$workspace" (≤${connectTimeout.inSeconds}s) …');
-      await plane.connect(
-        cloud: 'https://offline.invalid', // ignored: the offline runner serves everything locally
-        workspace: workspace,
-        clientId: clientId,
-        allowUnborn: true,
-      ).timeout(connectTimeout,
-          onTimeout: () => throw NomosTestHarnessException(
-              'connect("$workspace") did not complete within ${connectTimeout.inSeconds}s (phase 4/4) — '
-              'the runner is up but the session never mounted; a large ledger converge-fold can be slow, '
-              'raise connectTimeout, or run with onDiagnostic to see where it blocked'));
+          awaiting: useInRepoScript ? 'offline-install.mjs' : 'githolon harness-install',
+          timeout: phaseTimeout ?? _kInstallDeadline,
+          onDiagnostic: onDiagnostic,
+          likelyCauses: const [
+            'a cold npx download of githolon (pre-warm with any `githolon` run)',
+            'a very large law package folding through the offline gate — raise phaseTimeout',
+          ],
+          run: () => _runInstall(
+              node: node,
+              useInRepoScript: useInRepoScript,
+              inRepoScript: resolvedHelper,
+              githolonCmd: githolonCmd,
+              deployJsonPaths: deployJsonPaths,
+              workspace: workspace,
+              snapshot: snapshot,
+              runtimeDir: runtimeDir,
+              onDiagnostic: onDiagnostic));
+
+      transport = await _phased(
+          phase: '2/4: spawn the node runner',
+          awaiting: 'Process.start($node)',
+          timeout: phaseTimeout ?? _kSpawnDeadline,
+          onDiagnostic: onDiagnostic,
+          run: () => NodeRunnerTransport.start(
+                entry: entry,
+                resolveFrom: resolveFrom,
+                node: node,
+                environment: {
+                  'NOMOS_OFFLINE': '1',
+                  'NOMOS_OFFLINE_RESTORE': snapshot,
+                  if (runtimeDir != null) 'NOMOS_OFFLINE_RUNTIME': runtimeDir,
+                },
+                onDiagnostic: onDiagnostic,
+              ));
+      final plane = NomosBridge(transport!);
+      await _phased(
+          phase: '3/4: runner ready',
+          awaiting: "event:'ready'",
+          timeout: phaseTimeout ?? readyTimeout,
+          onDiagnostic: onDiagnostic,
+          likelyCauses: const [
+            'node is not on PATH, or ~/.holon/runtime is cold (holon.wasm + packages.json)',
+            'the runner process failed to boot the engine — run with onDiagnostic to see its stderr',
+          ],
+          run: () => plane.ready);
+      await _phased(
+          phase: '4/4: connect session',
+          workspace: workspace,
+          awaiting: 'connect',
+          timeout: phaseTimeout ?? connectTimeout,
+          onDiagnostic: onDiagnostic,
+          likelyCauses: const [
+            'a large ledger converge-fold can be slow — raise connectTimeout/phaseTimeout',
+            'run with onDiagnostic to see where the runner blocked',
+          ],
+          run: () => plane.connect(
+                cloud: 'https://offline.invalid', // ignored: the offline runner serves everything locally
+                workspace: workspace,
+                clientId: clientId,
+                allowUnborn: true,
+              ));
       phase('ready — session "$workspace" connected (law ${(info['lawHashes'] as List?)?.isNotEmpty == true ? (info['lawHashes'] as List).first.toString().substring(0, 12) : "installed"})');
       // THE DECOY SESSION (multi-workspace by default in tests): sole-session inference is how
       // single-workspace assumptions ship — with one session connected, an op that forgot its session
@@ -247,14 +348,20 @@ class NomosTestHarness {
       // against the harness keeps working unchanged; only code that grabs the raw plane and assumes
       // single-session trips. Opt out with `decoySession: false` (please don't).
       if (decoySession) {
-        await plane.connect(
-          cloud: 'https://offline.invalid',
-          workspace: _decoyWorkspace,
-          session: _decoyWorkspace,
-          clientId: '$clientId-decoy',
-          allowUnborn: true,
-          restoreFrom: base64Encode(await File(snapshot).readAsBytes()),
-        );
+        await _phased(
+            phase: 'decoy: connect the decoy session',
+            workspace: _decoyWorkspace,
+            awaiting: 'connect',
+            timeout: phaseTimeout ?? connectTimeout,
+            onDiagnostic: onDiagnostic,
+            run: () async => plane.connect(
+                  cloud: 'https://offline.invalid',
+                  workspace: _decoyWorkspace,
+                  session: _decoyWorkspace,
+                  clientId: '$clientId-decoy',
+                  allowUnborn: true,
+                  restoreFrom: base64Encode(await File(snapshot).readAsBytes()),
+                ));
       }
       final harness = NomosTestHarness._(
           plane.session(workspace), workspace, transport, workdir, onDiagnostic, [workspace],
@@ -271,7 +378,8 @@ class NomosTestHarness {
               inRepoScript: resolvedHelper,
               githolonCmd: githolonCmd,
               runtimeDir: runtimeDir,
-              clientId: clientId));
+              clientId: clientId),
+          phaseTimeout: phaseTimeout);
       if (autoTearDown && registerTearDown != null) {
         registerTearDown(harness.dispose);
       }
@@ -317,6 +425,7 @@ class NomosTestHarness {
     void Function(String line)? onDiagnostic,
     Duration readyTimeout = const Duration(seconds: 30),
     Duration connectTimeout = const Duration(seconds: 120),
+    Duration? phaseTimeout,
   }) async {
     if (workspaces.isEmpty) {
       throw NomosTestHarnessException(
@@ -343,18 +452,29 @@ class NomosTestHarness {
       final snapshots = <String, String>{};
       final lawHashesByWs = <String, List<String>>{};
       String? frameworkHash;
+      var _i = 0;
       for (final e in workspaces.entries) {
         final snap = '${workdir.path}/${e.key}.bin';
-        final info = await _runInstall(
-            node: node,
-            useInRepoScript: useInRepoScript,
-            inRepoScript: resolvedHelper,
-            githolonCmd: githolonCmd,
-            deployJsonPaths: e.value,
+        final info = await _phased(
+            phase: '1: offline law install ${++_i}/${workspaces.length}',
             workspace: e.key,
-            snapshot: snap,
-            runtimeDir: runtimeDir,
-            onDiagnostic: onDiagnostic);
+            awaiting: useInRepoScript ? 'offline-install.mjs' : 'githolon harness-install',
+            timeout: phaseTimeout ?? _kInstallDeadline,
+            onDiagnostic: onDiagnostic,
+            likelyCauses: const [
+              'a cold npx download of githolon (pre-warm with any `githolon` run)',
+              'a very large law package folding through the offline gate — raise phaseTimeout',
+            ],
+            run: () => _runInstall(
+                node: node,
+                useInRepoScript: useInRepoScript,
+                inRepoScript: resolvedHelper,
+                githolonCmd: githolonCmd,
+                deployJsonPaths: e.value,
+                workspace: e.key,
+                snapshot: snap,
+                runtimeDir: runtimeDir,
+                onDiagnostic: onDiagnostic));
         snapshots[e.key] = snap;
         lawHashesByWs[e.key] = ((info['lawHashes'] as List?) ?? const [])
             .map((x) => x.toString())
@@ -364,23 +484,32 @@ class NomosTestHarness {
 
       // 2. ONE runner / ONE bridge for the whole plane — no env restore default; each connect brings its own.
       final phase = (String m) { if (onDiagnostic != null) onDiagnostic('[nomos-test-harness] $m'); };
-      phase('cluster: spawning the node runner for ${workspaces.length} workspace(s) …');
-      transport = await NodeRunnerTransport.start(
-        entry: entry,
-        resolveFrom: resolveFrom,
-        node: node,
-        environment: {
-          'NOMOS_OFFLINE': '1',
-          if (runtimeDir != null) 'NOMOS_OFFLINE_RUNTIME': runtimeDir,
-        },
-        onDiagnostic: onDiagnostic,
-      );
-      final bridge = NomosBridge(transport);
-      phase('cluster: awaiting runner ready (≤${readyTimeout.inSeconds}s) …');
-      await bridge.ready.timeout(readyTimeout,
-          onTimeout: () => throw NomosTestHarnessException(
-              'the offline runner never signalled ready within ${readyTimeout.inSeconds}s '
-              '(is `node` on PATH and ~/.holon/runtime warm? run with onDiagnostic to see the runner stderr)'));
+      transport = await _phased(
+          phase: '2: spawn the node runner (${workspaces.length} workspace(s))',
+          awaiting: 'Process.start($node)',
+          timeout: phaseTimeout ?? _kSpawnDeadline,
+          onDiagnostic: onDiagnostic,
+          run: () => NodeRunnerTransport.start(
+                entry: entry,
+                resolveFrom: resolveFrom,
+                node: node,
+                environment: {
+                  'NOMOS_OFFLINE': '1',
+                  if (runtimeDir != null) 'NOMOS_OFFLINE_RUNTIME': runtimeDir,
+                },
+                onDiagnostic: onDiagnostic,
+              ));
+      final bridge = NomosBridge(transport!);
+      await _phased(
+          phase: '2: runner ready',
+          awaiting: "event:'ready'",
+          timeout: phaseTimeout ?? readyTimeout,
+          onDiagnostic: onDiagnostic,
+          likelyCauses: const [
+            'node is not on PATH, or ~/.holon/runtime is cold (holon.wasm + packages.json)',
+            'the runner process failed to boot the engine — run with onDiagnostic to see its stderr',
+          ],
+          run: () => bridge.ready);
 
       // 3. connect one SESSION per workspace, each restoring its OWN snapshot — LOCAL-ONLY (no cloud;
       //    these are local githolons on the device plane, offline by nature).
@@ -388,35 +517,67 @@ class NomosTestHarness {
       var _n = 0;
       for (final e in workspaces.entries) {
         snapshotB64[e.key] = base64Encode(await File(snapshots[e.key]!).readAsBytes());
-        phase('cluster: connecting session ${++_n}/${workspaces.length} "${e.key}" (≤${connectTimeout.inSeconds}s) …');
-        await bridge.connect(
-          workspace: e.key,
-          session: e.key,
-          clientId: '$clientId-${e.key}',
-          restoreFrom: snapshotB64[e.key],
-          allowUnborn: true,
-        ).timeout(connectTimeout,
-            onTimeout: () => throw NomosTestHarnessException(
-                'connect("${e.key}") did not complete within ${connectTimeout.inSeconds}s — the runner is up '
-                'but this session never mounted (a large ledger converge-fold can be slow; raise connectTimeout '
-                'or run with onDiagnostic)'));
+        await _phased(
+            phase: '3: connect session ${++_n}/${workspaces.length}',
+            workspace: e.key,
+            awaiting: 'connect',
+            timeout: phaseTimeout ?? connectTimeout,
+            onDiagnostic: onDiagnostic,
+            likelyCauses: const [
+              'a large ledger converge-fold can be slow — raise connectTimeout/phaseTimeout',
+              'run with onDiagnostic to see where the runner blocked',
+            ],
+            run: () => bridge.connect(
+                  workspace: e.key,
+                  session: e.key,
+                  clientId: '$clientId-${e.key}',
+                  restoreFrom: snapshotB64[e.key],
+                  allowUnborn: true,
+                ));
       }
       phase('cluster: ${workspaces.length} session(s) connected');
 
       // 3b. DEVICE-KEY the named sessions: mint a fresh in-kernel key on each (now that it is mounted) and
       //     RE-OPEN it with that key as its signing authorSecret — the resolver's attested-read signing key.
+      //     The re-open is the runner's ATOMIC session replace (dispose-then-connect under the hood); each
+      //     leg runs as a named, deadlined phase so a wedge is a typed HarnessPhaseTimeout, never a hang.
       final devicePublics = <String, String>{};
       for (final ws in deviceKeyed) {
-        final kp = await bridge.session(ws).authorKeygen();
+        if (!workspaces.containsKey(ws)) {
+          throw NomosTestHarnessException(
+              'deviceKeyed names "$ws" but it is not a workspace of this cluster — '
+              'workspaces: ${workspaces.keys.toList()}');
+        }
+        final kp = await _phased(
+            phase: '3b: device keygen',
+            workspace: ws,
+            awaiting: 'authorKeygen',
+            timeout: phaseTimeout ?? _kOtherDeadline,
+            onDiagnostic: onDiagnostic,
+            run: () => bridge.session(ws).authorKeygen());
         devicePublics[ws] = (kp['public'] ?? '').toString();
-        await bridge.connect(
-          workspace: ws,
-          session: ws,
-          clientId: '$clientId-$ws',
-          restoreFrom: snapshotB64[ws],
-          authorSecret: (kp['secret'] ?? '').toString(),
-          allowUnborn: true,
-        );
+        await _phased(
+            phase: "3b: keyed reconnect of '$ws'",
+            workspace: ws,
+            awaiting: 'connect',
+            timeout: phaseTimeout ?? connectTimeout,
+            onDiagnostic: onDiagnostic,
+            likelyCauses: const [
+              'the runner never answered the re-connect of an already-open session — '
+                  'update @githolon/client (the session re-open is an atomic replace)',
+              'a large ledger re-fold on the re-mount — raise connectTimeout/phaseTimeout',
+            ],
+            run: () => bridge.connect(
+                  workspace: ws,
+                  session: ws,
+                  clientId: '$clientId-$ws',
+                  restoreFrom: snapshotB64[ws],
+                  authorSecret: (kp['secret'] ?? '').toString(),
+                  allowUnborn: true,
+                ));
+      }
+      if (deviceKeyed.isNotEmpty) {
+        phase('cluster: ${deviceKeyed.length} device-keyed session(s) re-opened');
       }
 
       final names = workspaces.keys.toList();
@@ -432,7 +593,8 @@ class NomosTestHarness {
               inRepoScript: resolvedHelper,
               githolonCmd: githolonCmd,
               runtimeDir: runtimeDir,
-              clientId: clientId));
+              clientId: clientId),
+          phaseTimeout: phaseTimeout);
       if (autoTearDown && registerTearDown != null) {
         registerTearDown(harness.dispose);
       }
@@ -469,13 +631,19 @@ class NomosTestHarness {
           'resetWorkspaceCustody("$workspace"): no seed snapshot held for this workspace — '
           'seeded workspaces: ${_snapshots.keys.toList()}');
     }
-    await _plane.connect(
-      workspace: workspace,
-      session: workspace,
-      clientId: '${_installLane?.clientId ?? 'test-runner'}-$workspace',
-      restoreFrom: snap,
-      allowUnborn: true,
-    );
+    await _phased(
+        phase: 'resetWorkspaceCustody: reconnect from seed snapshot',
+        workspace: workspace,
+        awaiting: 'connect',
+        timeout: _phaseTimeout ?? const Duration(seconds: 60),
+        onDiagnostic: _onDiagnostic,
+        run: () => _plane.connect(
+              workspace: workspace,
+              session: workspace,
+              clientId: '${_installLane?.clientId ?? 'test-runner'}-$workspace',
+              restoreFrom: snap,
+              allowUnborn: true,
+            ));
   }
 
   /// SEED a NEW workspace on this plane from `build/<name>.deploy.json` law packages — the
@@ -495,28 +663,40 @@ class NomosTestHarness {
           'seedWorkspaceFromDeployJson("$workspace"): pass the build/<name>.deploy.json paths');
     }
     final snap = '${_workdir.path}/$workspace.bin';
-    final info = await _runInstall(
-        node: lane.node,
-        useInRepoScript: lane.useInRepoScript,
-        inRepoScript: lane.inRepoScript,
-        githolonCmd: lane.githolonCmd,
-        deployJsonPaths: deployJsonPaths,
+    final info = await _phased(
+        phase: 'seed: offline law install',
         workspace: workspace,
-        snapshot: snap,
-        runtimeDir: lane.runtimeDir,
-        onDiagnostic: _onDiagnostic);
+        awaiting: lane.useInRepoScript ? 'offline-install.mjs' : 'githolon harness-install',
+        timeout: _phaseTimeout ?? _kInstallDeadline,
+        onDiagnostic: _onDiagnostic,
+        run: () => _runInstall(
+            node: lane.node,
+            useInRepoScript: lane.useInRepoScript,
+            inRepoScript: lane.inRepoScript,
+            githolonCmd: lane.githolonCmd,
+            deployJsonPaths: deployJsonPaths,
+            workspace: workspace,
+            snapshot: snap,
+            runtimeDir: lane.runtimeDir,
+            onDiagnostic: _onDiagnostic));
     final b64 = base64Encode(await File(snap).readAsBytes());
     _snapshots[workspace] = b64;
     _lawHashes[workspace] = ((info['lawHashes'] as List?) ?? const [])
         .map((e) => e.toString())
         .toList();
-    await _plane.connect(
-      workspace: workspace,
-      session: workspace,
-      clientId: '${lane.clientId}-$workspace',
-      restoreFrom: b64,
-      allowUnborn: true,
-    );
+    await _phased(
+        phase: 'seed: connect session',
+        workspace: workspace,
+        awaiting: 'connect',
+        timeout: _phaseTimeout ?? const Duration(seconds: 60),
+        onDiagnostic: _onDiagnostic,
+        run: () => _plane.connect(
+              workspace: workspace,
+              session: workspace,
+              clientId: '${lane.clientId}-$workspace',
+              restoreFrom: b64,
+              allowUnborn: true,
+            ));
     if (!_sessionNames.contains(workspace)) _sessionNames.add(workspace);
     return _plane.session(workspace);
   }
@@ -527,7 +707,13 @@ class NomosTestHarness {
   /// `harness.session(ws).assertCompatible(XClient.interface)`.)
   Future<void> assertDomainInstalled(
       {required String workspace, required String domain}) async {
-    final offer = await _plane.session(workspace).interfaceOffer();
+    final offer = await _phased(
+        phase: 'assertDomainInstalled: read the interface offer',
+        workspace: workspace,
+        awaiting: 'interfaceOffer',
+        timeout: _phaseTimeout ?? _kOtherDeadline,
+        onDiagnostic: _onDiagnostic,
+        run: () => _plane.session(workspace).interfaceOffer());
     final keys = (offer?.keys.toList() ?? const <String>[])..sort();
     if (!keys.contains(domain)) {
       throw NomosTestHarnessException(
@@ -539,11 +725,21 @@ class NomosTestHarness {
   /// Deterministic, idempotent, total-ordered teardown: stop the runner (SIGTERM → 5s deadline → SIGKILL,
   /// via [NodeRunnerTransport.dispose]), then delete the temp dir. Safe to call twice; safe to call after a
   /// failed setup. Nothing left running, nothing left on disk.
+  /// Disposal must ALWAYS complete (never leave a hung teardown holding the test runner): the transport
+  /// dispose is deadlined too, and a breach is LOGGED (not thrown — throwing from teardown would mask the
+  /// test's own outcome) before the temp dir is still deleted.
   Future<void> dispose() async {
     if (_disposed) return;
     _disposed = true;
+    final f = _onDiagnostic;
+    if (f != null) f('[nomos-test-harness] phase dispose (≤${(_phaseTimeout ?? _kOtherDeadline).inSeconds}s) …');
     try {
-      await _transport.dispose();
+      await _transport.dispose().timeout(_phaseTimeout ?? _kOtherDeadline,
+          onTimeout: () => throw HarnessPhaseTimeout(
+              phase: 'dispose: stop the node runner',
+              workspace: workspace,
+              elapsed: _phaseTimeout ?? _kOtherDeadline,
+              awaiting: 'NodeRunnerTransport.dispose'));
     } catch (e) {
       _diag('[nomos-test-harness] transport dispose error (continuing to temp-dir cleanup): $e');
     }
@@ -552,6 +748,7 @@ class NomosTestHarness {
     } catch (e) {
       _diag('[nomos-test-harness] temp-dir cleanup error: $e');
     }
+    if (f != null) f('[nomos-test-harness] phase dispose done');
   }
 
   void _diag(String line) {