@githolon/dsl 0.73.0 → 0.74.0

package/dart/CHANGELOG.md

@@ -1,3 +1,22 @@
+## 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/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) {

package/dart/pubspec.yaml

@@ -11,7 +11,7 @@ description: >-
   Nomos 2 Dart frontend types — the hand-written kernel wire types plus the
   code-generated per-domain aggregate + directive-payload types. (De)serializes
   the EXACT serde JSON the Rust kernel + projection produce/consume.
-version: 0.49.0
+version: 0.50.0
 
 environment:
   sdk: ^3.5.0

package/dart/test/cluster_device_keyed_acceptance_test.dart

@@ -0,0 +1,108 @@
+// CO2'S ACCEPTANCE (verbatim, 2026-07): `NomosTestHarness.cluster(deviceKeyed: …)` re-opens the keyed
+// session (keygen → keyed reconnect) and MUST NEVER hang — the reported wedge was phase 3b, the second
+// `connect` on an already-open session. Acceptance:
+//   1. cluster(..., deviceKeyed: {workspace}) completes           (co2's exact shape: 4 sessions, one
+//      deviceKeyed, colon-namespaced workspace names)
+//   2. devicePublicKey(workspace) is populated
+//   3. a colocated attested read succeeds (served + SIGNED with the device key the re-open installed)
+//   4. harness disposal completes without being killed
+// Phase diagnostics (their ask 5) are asserted too: 3b logs enter/exit for keygen + keyed reconnect.
+@TestOn('vm')
+@Timeout(Duration(minutes: 3))
+library;
+
+import 'dart:io';
+
+import 'package:nomos_client/nomos_headless.dart';
+import 'package:test/test.dart';
+
+String get _root => '${Directory.current.path}/../..';
+String get _repoEntry => '$_root/cloud/web-client/runner/node-entry.mjs';
+String get _catDeploy => '$_root/bench/scale/fixtures/catalogue-src/build/cat.deploy.json';
+String get _estateDeploy => '$_root/bench/scale/fixtures/catalogue-reader/build/estate.deploy.json';
+String get _runtimeDir => '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
+
+String? _missingPrereq() {
+  if (!File(_repoEntry).existsSync()) return 'in-repo runner not found at $_repoEntry';
+  for (final p in [_catDeploy, _estateDeploy]) {
+    if (!File(p).existsSync()) return 'missing fixture $p (compile bench/scale/fixtures first)';
+  }
+  if (!File('$_runtimeDir/holon.wasm').existsSync() ||
+      !File('$_runtimeDir/packages.json').existsSync()) {
+    return 'warm ~/.holon/runtime first (run any `githolon` command once)';
+  }
+  return null;
+}
+
+void main() {
+  test('cluster(deviceKeyed) completes: keyed re-open, device key populated, colocated attested read, disposal',
+      () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+
+    const keyed = 'catalogue:test-catalogue';
+    final log = <String>[];
+    // 1. cluster construction with a deviceKeyed workspace COMPLETES (the reported hang was here).
+    final harness = await NomosTestHarness.cluster(
+      workspaces: {
+        keyed: [_catDeploy],
+        'estate:a': [_estateDeploy],
+        'estate:b': [_estateDeploy],
+        'estate:c': [_estateDeploy],
+      },
+      deviceKeyed: {keyed},
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+      onDiagnostic: log.add,
+    );
+    try {
+      expect(harness.sessions.toSet(),
+          {keyed, 'estate:a', 'estate:b', 'estate:c'});
+
+      // 2. devicePublicKey is populated for the keyed session.
+      final public = harness.devicePublicKey(keyed);
+      expect(public, isNotNull);
+      expect(public, isNotEmpty,
+          reason: 'the 3b keygen public half must be recorded on the harness');
+
+      // ask 5 — phase diagnostics: 3b logs enter AND exit for keygen + keyed reconnect.
+      expect(log.any((l) => l.contains('3b: device keygen')), isTrue,
+          reason: 'phase 3b keygen must log');
+      expect(log.any((l) => l.contains("3b: keyed reconnect of '$keyed'") && l.contains('…')),
+          isTrue, reason: 'phase 3b reconnect must log its enter line');
+      expect(log.any((l) => l.contains("3b: keyed reconnect of '$keyed'") && l.contains('done')),
+          isTrue, reason: 'phase 3b reconnect must log its exit line');
+
+      // 3. a COLOCATED ATTESTED READ succeeds, signed with the device key the re-open installed
+      //    (no attestorSecret injected — the source session signs with its connect authorSecret).
+      final cat = harness.session(keyed);
+      final seeded = await cat.offerCreates(
+        domain: 'cat',
+        directiveId: 'listCatalogue',
+        payload: {
+          'listingId': 'L-1',
+          'title': 'Walnut desk',
+          'priceGbp': '900',
+          'listedAt': '2026-07-11T00:00:00Z',
+        },
+        actor: 'user:seller',
+      );
+      expect(seeded.head, isNotEmpty);
+      final served = await harness.session('estate:a').attestedRead(
+        from: keyed,
+        queryId: 'listingById',
+        args: {'listingId': 'L-1'},
+      );
+      final entry = (served['entry'] as Map).cast<String, Object?>();
+      final attestation = (entry['attestation'] as Map).cast<String, Object?>();
+      expect((attestation['public_key'] ?? '').toString(), public,
+          reason: 'the colocated read is signed by the re-opened session device key');
+    } finally {
+      // 4. disposal completes (the harness deadline guarantees it can never wedge the test runner).
+      await harness.dispose();
+    }
+  });
+}

package/dart/test/fixtures/wedge/fake-install.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// A FAKE offline-install helper for the hermetic HARNESS PHASE-TIMEOUT tests: honours the real helper's
+// flag + one-line-JSON contract (--deploy/--workspace/--out) but installs nothing — it just writes a tiny
+// dummy snapshot so the harness proceeds to the runner phases.
+import { writeFileSync } from "node:fs";
+const args = process.argv.slice(2);
+const val = (f) => { const i = args.indexOf(f); return i >= 0 ? args[i + 1] : undefined; };
+const out = val("--out");
+const workspace = val("--workspace");
+writeFileSync(out, Buffer.from("fake-snapshot"));
+process.stdout.write(JSON.stringify({ ok: true, snapshot: out, workspace, lawHashes: ["deadbeef"], frameworkHash: "cafebabe" }) + "\n");

package/dart/test/fixtures/wedge/wedge-entry.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// A WEDGING FAKE RUNNER for the hermetic HARNESS PHASE-TIMEOUT tests: speaks the NDJSON bridge protocol,
+// answers everything — EXCEPT the op named in NOMOS_WEDGE_OP (optionally only when the args carry an
+// authorSecret, i.e. the 3b keyed reconnect), which it swallows FOREVER. This forges the exact "silent
+// hang" co2 reported so the harness's typed HarnessPhaseTimeout can be asserted without a real wait.
+import { createInterface } from "node:readline";
+const post = (msg) => process.stdout.write(JSON.stringify(msg) + "\n");
+const wedgeOp = process.env.NOMOS_WEDGE_OP || "connect"; // default: wedge the KEYED reconnect (co2's shape)
+const wedgeOnlyKeyed = process.env.NOMOS_WEDGE_ONLY_KEYED !== "0";
+post({ v: 1, event: "ready" });
+const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+rl.on("line", (line) => {
+  const s = line.trim();
+  if (!s) return;
+  let msg; try { msg = JSON.parse(s); } catch { return; }
+  const a = msg.args || {};
+  if (msg.op === wedgeOp && (!wedgeOnlyKeyed || a.authorSecret)) return; // THE WEDGE: never answer
+  if (msg.op === "authorKeygen") return post({ v: 1, id: msg.id, ok: true, result: { secret: "c2VjcmV0", public: "cHVibGlj" } });
+  if (msg.op === "connect") return post({ v: 1, id: msg.id, ok: true, result: { workspace: a.workspace, session: a.session } });
+  post({ v: 1, id: msg.id, ok: true, result: {} });
+});
+rl.on("close", () => process.exit(0));

package/dart/test/harness_phase_timeout_test.dart

@@ -0,0 +1,72 @@
+// NO SILENT HANGS — the harness's per-phase deadline machinery, proven HERMETICALLY (no real waits, no
+// wasm, no network): a fake runner (test/fixtures/wedge/wedge-entry.mjs) speaks the bridge protocol but
+// SWALLOWS the 3b keyed reconnect forever — the exact wedge co2 reported. With a short `phaseTimeout` the
+// harness must throw the TYPED [HarnessPhaseTimeout] naming the phase/workspace/op, never hang; and the
+// failed construction must tear the runner down by itself (no leaked process holding the test runner).
+@TestOn('vm')
+@Timeout(Duration(seconds: 60))
+library;
+
+import 'dart:io';
+
+import 'package:nomos_client/nomos_headless.dart';
+import 'package:test/test.dart';
+
+String get _fixtures => '${Directory.current.path}/test/fixtures/wedge';
+String get _wedgeEntry => '$_fixtures/wedge-entry.mjs';
+String get _fakeInstall => '$_fixtures/fake-install.mjs';
+
+void main() {
+  test('a wedged keyed reconnect fires HarnessPhaseTimeout naming phase 3b (typed, no hang)', () async {
+    final log = <String>[];
+    Object? err;
+    try {
+      await NomosTestHarness.cluster(
+        workspaces: {
+          'catalogue': ['unused.deploy.json'], // the fake install helper ignores the paths
+        },
+        deviceKeyed: {'catalogue'},
+        nodeEntry: _wedgeEntry,
+        installHelper: _fakeInstall,
+        phaseTimeout: const Duration(seconds: 2), // hermetic: a short deadline, not a real 120s wait
+        onDiagnostic: log.add,
+      );
+    } catch (e) {
+      err = e;
+    }
+    expect(err, isA<HarnessPhaseTimeout>(),
+        reason: 'the wedge must surface as the typed phase timeout, never an eternal await');
+    final t = err as HarnessPhaseTimeout;
+    expect(t.phase, "3b: keyed reconnect of 'catalogue'");
+    expect(t.workspace, 'catalogue');
+    expect(t.awaiting, 'connect');
+    expect(t.elapsed, const Duration(seconds: 2));
+    expect(t.likelyCauses, isNotEmpty, reason: 'known wedges carry their likely causes');
+    expect(t, isA<NomosTestHarnessException>(),
+        reason: 'existing on-NomosTestHarnessException handling keeps working');
+    expect(t.toString(), contains("3b: keyed reconnect of 'catalogue'"));
+    // ask 5 — the phases before the wedge logged enter AND exit; the wedged phase logged its enter.
+    expect(log.any((l) => l.contains('3: connect session') && l.contains('done')), isTrue);
+    expect(log.any((l) => l.contains('3b: device keygen') && l.contains('done')), isTrue);
+    expect(log.any((l) => l.contains("3b: keyed reconnect of 'catalogue'")), isTrue);
+  });
+
+  test('deviceKeyed naming an unknown workspace refuses typed (never a wedge)', () async {
+    Object? err;
+    try {
+      await NomosTestHarness.cluster(
+        workspaces: {
+          'catalogue': ['unused.deploy.json'],
+        },
+        deviceKeyed: {'not-a-workspace'},
+        nodeEntry: _wedgeEntry,
+        installHelper: _fakeInstall,
+        phaseTimeout: const Duration(seconds: 5),
+      );
+    } catch (e) {
+      err = e;
+    }
+    expect(err, isA<NomosTestHarnessException>());
+    expect(err.toString(), contains('not-a-workspace'));
+  });
+}

package/dart/test/test_harness_test.dart

@@ -123,10 +123,12 @@ void main() {
     );
     final joined = lines.join('\n');
     // the four named phases are surfaced so an AppSim can tell install vs runner-wait vs connect-block.
-    expect(joined, contains('phase 1/4 installing'));
-    expect(joined, contains('phase 2/4 spawning the node runner'));
-    expect(joined, contains('phase 3/4 awaiting runner ready'));
-    expect(joined, contains('phase 4/4 connecting session'));
+    expect(joined, contains('phase 1/4: offline law install'));
+    expect(joined, contains('phase 2/4: spawn the node runner'));
+    expect(joined, contains('phase 2/4: spawn the node runner done'));
+    expect(joined, contains('phase 3/4: runner ready'));
+    expect(joined, contains('phase 4/4: connect session'));
+    expect(joined, contains('phase 4/4: connect session "test-ws" done'));
     expect(joined, contains('ready — session "test-ws" connected'));
     expect(harness.bridge, isNotNull);
   }, timeout: const Timeout(Duration(minutes: 2)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.73.0",
+  "version": "0.74.0",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/compile_package_main.ts

@@ -904,7 +904,7 @@ const NOMOS_TYPES_DEP = "^0.3.0";
 // 0.48.x: session-bound clients (XClient.bind/NomosClientInterface/DomainClientSessionMismatch/
 //         DomainNotInstalledForSession, engine.follow, pendingConflicts lanes) — the generated client
 //         REQUIRES this surface. 0.48.1 fixes NomosSession.watchPendingConflicts delegation.
-const NOMOS_CLIENT_DEP = "^0.49.0";
+const NOMOS_CLIENT_DEP = "^0.50.0";
 // DRIFT TRIPWIRE: pubspec_pins.test.ts asserts these equal the CURRENT versions in dsl/dart/pubspec.yaml
 // and dsl/dart_types/pubspec.yaml — a Dart release without this bump fails the suite, so tenants never
 // land back in dependency_overrides (the exact co2 report this closes, third occurrence).