@githolon/dsl 0.72.1 → 0.74.0

package/dart/CHANGELOG.md

@@ -1,3 +1,37 @@
+## 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
+  autoSync registered the full cloud machinery (doorbell WebSocket retry loop, fallback timers,
+  intent-offer POSTs that could never land) — the future never completed, the runner dispatcher
+  starved, sibling queries and `listWorkspaces()` hung, and teardown wedged. `autoSync()` on a
+  local-only session now registers nothing and returns immediately; `sync()` is a true no-op
+  (`localOnly: true` summary); a local:// holon performs ZERO network attempts. (co2's acceptance
+  test implemented verbatim; failed before, passes after.)
+- **New: `acquireSession(workspace, {ifAbsentCredentials})`** — atomic single-flight session
+  acquisition: reuses a connected session, joins an in-flight open (concurrent calls yield the
+  same handle, one connect), opens local-only for workspaces the plane already knows
+  (mounted/parked/resident custody — credentials never invoked), and only calls
+  `ifAbsentCredentials` (exactly once) when a genuine cloud open is required.
+
 ## 0.48.1
 
 - **Fix: `NomosSession.watchPendingConflicts()` never emitted.** The session overrode every other

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/lib/src/webview_bridge.dart

@@ -661,6 +661,34 @@ class NomosOfferOutcome {
       .toList();
 }
 
+/// What a GENUINE cloud open needs — returned by an [NomosBridge.acquireSession] `ifAbsentCredentials`
+/// callback, invoked ONLY when the workspace is nowhere on the local plane (never for a local-only or
+/// already-mounted workspace). Mirrors the cloud-shaped subset of [NomosBridge.connect]'s parameters.
+class NomosSessionCredentials {
+  /// The cloud base URL the workspace syncs from (e.g. `https://nomos.captainapp.co.uk`).
+  final String cloud;
+
+  /// The verified principal's access token (`x-nomos-auth`), when the workspace requires one.
+  final String? authToken;
+
+  /// The client id for this device's replica (defaults per the runner when omitted).
+  final String? clientId;
+
+  /// The device signing secret (base64, from `authorKeygen`) — the warrant default for every offer.
+  final String? authorSecret;
+
+  /// Open even when the workspace has no remote main yet (an unborn workspace reads empty).
+  final bool allowUnborn;
+
+  const NomosSessionCredentials({
+    required this.cloud,
+    this.authToken,
+    this.clientId,
+    this.authorSecret,
+    this.allowUnborn = false,
+  });
+}
+
 /// THE BRIDGE. Construct over a [BridgeTransport], `await ready`, then `connect(...)` and drive the holon.
 class NomosBridge {
   final BridgeTransport _transport;
@@ -708,6 +736,9 @@ class NomosBridge {
   // caches the per-workspace [NomosSession] handle so `bridge.session(ws)` is stable + cheap.
   final Set<String> _sessionNames = {};
   final Map<String, NomosSession> _sessionViews = {};
+  // [acquireSession]'s per-workspace single-flight: workspace → the in-flight open every concurrent
+  // acquirer joins (removed when it completes; a live session then hits the fast path instead).
+  final Map<String, Future<NomosSession>> _acquiring = {};
   int _seq = 0;
   final String _traceId = _newTraceId();
   late final StreamSubscription<Map<String, Object?>> _sub;
@@ -1205,6 +1236,60 @@ class NomosBridge {
     return session(ws);
   }
 
+  /// ACQUIRE A SESSION ATOMICALLY — the plug-and-play multi-workspace open (co2 DX ask). Semantics:
+  ///   • an already-connected session is returned as-is (no work, no credentials);
+  ///   • a workspace the local plane already holds (mounted by another path, LRU-parked, or with resident
+  ///     custody — e.g. a locally-born child) is opened LOCAL-ONLY, in place (no cloud, no credentials);
+  ///   • two concurrent [acquireSession] calls for the same workspace SINGLE-FLIGHT: the second joins the
+  ///     first's in-flight open and both yield the SAME [NomosSession] — one connect, never two;
+  ///   • ONLY when a genuine cloud open is required (the workspace is nowhere on this device) is
+  ///     [ifAbsentCredentials] invoked — exactly once — and the connect made with what it returns.
+  /// Omitting [ifAbsentCredentials] makes a genuinely-absent workspace a named [StateError] instead of a
+  /// silent cloudless mount.
+  Future<NomosSession> acquireSession(String workspace,
+      {Future<NomosSessionCredentials> Function()? ifAbsentCredentials}) {
+    // Fast path: a live session needs no runner round-trip (and never asks for credentials).
+    if (_sessionNames.contains(workspace)) return Future.value(session(workspace));
+    // SINGLE-FLIGHT: one in-flight open per workspace per plane; concurrent callers join it.
+    return _acquiring.putIfAbsent(workspace, () async {
+      try {
+        if (_sessionNames.contains(workspace)) return session(workspace);
+        // Consult the plane's TRUTHFUL registry (mounted ∪ parked ∪ resident custody — the runner's
+        // realm.list()): anything the device already holds opens locally, no cloud, no credentials.
+        var resident = false;
+        try {
+          resident = (await listWorkspaces())
+              .any((w) => w['workspace']?.toString() == workspace);
+        } catch (_) {
+          // a pre-connect plane has no registry yet — fall through to the credentials decision below.
+        }
+        if (resident) {
+          await connect(workspace: workspace, session: workspace, allowUnborn: true);
+          return session(workspace);
+        }
+        if (ifAbsentCredentials == null) {
+          throw StateError(
+              'acquireSession("$workspace"): the workspace is not on this device\'s plane and no '
+              'ifAbsentCredentials was given — a cloud open is genuinely required');
+        }
+        final c = await ifAbsentCredentials();
+        await connect(
+          cloud: c.cloud,
+          workspace: workspace,
+          session: workspace,
+          clientId: c.clientId,
+          authToken: c.authToken,
+          authorSecret: c.authorSecret,
+          allowUnborn: c.allowUnborn,
+        );
+        return session(workspace);
+      } finally {
+        // completed (either way) — the next acquire re-evaluates fresh (a live session hits the fast path).
+        _acquiring.remove(workspace);
+      }
+    });
+  }
+
   /// Reserve a KERNEL-MINTED typed id (`<TypeTag>_<uuidv7>`) via the holon's front-door mint — for app-side
   /// references (routing keys, optimistic UI). `.creates` payloads still carry NO id: the LAW mints those
   /// (see [offerCreates], which returns them).
@@ -1947,6 +2032,13 @@ class NomosSession extends NomosBridge {
   @override
   NomosSession session(String workspace) => parent.session(workspace);
 
+  /// An acquired session mounts on the SHARED plane — delegate to the parent (the plane owns the
+  /// single-flight registry; a session never owns mounts).
+  @override
+  Future<NomosSession> acquireSession(String workspace,
+          {Future<NomosSessionCredentials> Function()? ifAbsentCredentials}) =>
+      parent.acquireSession(workspace, ifAbsentCredentials: ifAbsentCredentials);
+
   /// A followed ref mounts on the SHARED plane — delegate to the parent (a session never owns mounts).
   @override
   Future<NomosSession> follow(NomosRef ref,

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.48.1
+version: 0.50.0
 
 environment:
   sdk: ^3.5.0

package/dart/test/acquire_session_test.dart

@@ -0,0 +1,152 @@
+// acquireSession — the ATOMIC session-open (co2 DX ask): reuses a mounted session, opens a plane-resident
+// (parked / resident-custody) workspace locally, JOINS an in-flight open (single-flight per workspace), and
+// invokes the credentials callback ONLY when a cloud open is genuinely required. Proven hermetically over a
+// fake transport (the same style as webview_bridge_test.dart) — the live-runner leg rides
+// cluster_local_autosync_test.dart.
+import 'dart:async';
+
+import 'package:nomos_client/nomos_client.dart';
+import 'package:test/test.dart';
+
+/// A fake runner: answers connect (after a real async gap, so concurrency is observable) and
+/// listWorkspaces (from [resident]); records every request.
+class FakeRunner implements BridgeTransport {
+  final _incoming = StreamController<Map<String, Object?>>.broadcast();
+  final List<Map<String, Object?>> sent = [];
+  final List<String> resident; // workspaces the plane already holds (realm.list())
+
+  FakeRunner({this.resident = const []}) {
+    scheduleMicrotask(
+        () => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready'}));
+  }
+
+  int get connectCount => sent.where((m) => m['op'] == 'connect').length;
+  Map<String, Object?> connectArgs(int i) =>
+      (sent.where((m) => m['op'] == 'connect').elementAt(i)['args'] as Map)
+          .cast<String, Object?>();
+
+  @override
+  Stream<Map<String, Object?>> get messages => _incoming.stream;
+
+  @override
+  void send(Map<String, Object?> message) {
+    sent.add(message);
+    final id = message['id'] as int;
+    final op = message['op'] as String;
+    final args = (message['args'] as Map).cast<String, Object?>();
+    Future<void>.delayed(const Duration(milliseconds: 5), () {
+      Object? result;
+      switch (op) {
+        case 'connect':
+          result = {'workspace': args['workspace']};
+          break;
+        case 'listWorkspaces':
+          result = {
+            'workspaces': [
+              for (final ws in resident)
+                {
+                  'session': ws,
+                  'workspace': ws,
+                  'mounted': false,
+                  'parked': true,
+                  'syncPosture': 'local-only'
+                }
+            ]
+          };
+          break;
+        default:
+          result = {};
+      }
+      _incoming
+          .add({'v': kWebviewBridgeVersion, 'id': id, 'ok': true, 'result': result});
+    });
+  }
+}
+
+void main() {
+  test('an already-connected session is reused — credentials NEVER invoked, no second connect', () async {
+    final runner = FakeRunner();
+    final bridge = NomosBridge(runner);
+    await bridge.ready;
+    await bridge.connect(workspace: 'home', session: 'home');
+    expect(runner.connectCount, 1);
+
+    final s = await bridge.acquireSession('home',
+        ifAbsentCredentials: () async =>
+            fail('credentials must not be requested for a mounted session'));
+    expect(identical(s, bridge.session('home')), isTrue);
+    expect(runner.connectCount, 1, reason: 'no re-connect for a live session');
+    await bridge.dispose();
+  });
+
+  test('a plane-resident (parked) workspace opens LOCALLY — no cloud, credentials NOT invoked', () async {
+    final runner = FakeRunner(resident: ['estate']);
+    final bridge = NomosBridge(runner);
+    await bridge.ready;
+
+    var asked = false;
+    final s = await bridge.acquireSession('estate', ifAbsentCredentials: () async {
+      asked = true;
+      return const NomosSessionCredentials(cloud: 'https://never.invalid');
+    });
+    expect(asked, isFalse, reason: 'a resident workspace never asks for credentials');
+    expect(s.workspace, 'estate');
+    expect(runner.connectCount, 1);
+    expect(runner.connectArgs(0).containsKey('cloud'), isFalse,
+        reason: 'a resident open is local-only — no cloud in the connect');
+    await bridge.dispose();
+  });
+
+  test('concurrent acquisition SINGLE-FLIGHTS: one open, one credentials call, the same session', () async {
+    final runner = FakeRunner();
+    final bridge = NomosBridge(runner);
+    await bridge.ready;
+
+    var credentialCalls = 0;
+    Future<NomosSessionCredentials> creds() async {
+      credentialCalls++;
+      await Future<void>.delayed(const Duration(milliseconds: 10));
+      return const NomosSessionCredentials(
+          cloud: 'https://cloud.example', authToken: 'tok', allowUnborn: true);
+    }
+
+    final results = await Future.wait([
+      bridge.acquireSession('cloudy', ifAbsentCredentials: creds),
+      bridge.acquireSession('cloudy', ifAbsentCredentials: creds),
+      bridge.acquireSession('cloudy', ifAbsentCredentials: creds),
+    ]);
+    expect(credentialCalls, 1, reason: 'the credentials callback fires exactly once');
+    expect(runner.connectCount, 1, reason: 'ONE connect for three concurrent acquires');
+    expect(identical(results[0], results[1]), isTrue);
+    expect(identical(results[1], results[2]), isTrue);
+    final args = runner.connectArgs(0);
+    expect(args['cloud'], 'https://cloud.example');
+    expect(args['authToken'], 'tok');
+    expect(args['allowUnborn'], isTrue);
+    await bridge.dispose();
+  });
+
+  test('genuinely absent + no credentials callback → a named StateError (never a silent cloudless mount)',
+      () async {
+    final runner = FakeRunner();
+    final bridge = NomosBridge(runner);
+    await bridge.ready;
+    await expectLater(bridge.acquireSession('nowhere'), throwsStateError);
+    expect(runner.connectCount, 0);
+    await bridge.dispose();
+  });
+
+  test('a NomosSession delegates acquireSession to the parent plane (one registry)', () async {
+    final runner = FakeRunner();
+    final bridge = NomosBridge(runner);
+    await bridge.ready;
+    await bridge.connect(workspace: 'home', session: 'home');
+    await bridge.connect(workspace: 'estate', session: 'estate');
+
+    final viaSession = await bridge.session('home').acquireSession('estate',
+        ifAbsentCredentials: () async =>
+            fail('estate is already mounted — no credentials'));
+    expect(identical(viaSession, bridge.session('estate')), isTrue);
+    await bridge.dispose();
+  });
+}

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/cluster_local_autosync_test.dart

@@ -0,0 +1,119 @@
+// CO2 ACCEPTANCE — local-only autoSync must not block the multi-workspace plane (their report, verbatim):
+//   - Open multiple local-only sessions with NomosTestHarness.cluster.
+//   - await homeSession.autoSync() completes promptly.
+//   - await bridge.listWorkspaces() and a query on a sibling estate session still complete.
+//   - stopAutoSync() and harness disposal complete.
+//   - No local://.../intent-offers fetch attempts occur.
+// autoSync() REGISTERS background behavior and returns immediately; for a local-only (local://) session it
+// performs NO network work and must not monopolize the runner request dispatcher.
+@TestOn('vm')
+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 _guestbookDeploy => '$_root/examples/guestbook/build/guestbook.deploy.json';
+String get _runtimeDir => '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
+
+String? _missingPrereq() {
+  if (!File(_repoEntry).existsSync()) return 'in-repo runner not found at $_repoEntry';
+  if (!File(_guestbookDeploy).existsSync()) {
+    return 'compile the guestbook example: cd examples/guestbook && npx nomos-compile — missing $_guestbookDeploy';
+  }
+  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(
+      'local-only autoSync() returns promptly, never fetches, and does not block the plane (co2 acceptance)',
+      () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+
+    // 1. Open multiple local-only sessions with NomosTestHarness.cluster (four, one bridge).
+    final names = ['home', 'estate-a', 'estate-b', 'estate-c'];
+    final diagnostics = <String>[];
+    final harness = await NomosTestHarness.cluster(
+      workspaces: {for (final ws in names) ws: [_guestbookDeploy]},
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+      onDiagnostic: diagnostics.add,
+    );
+    try {
+      final home = harness.session('home');
+
+      // A realistic home holds local writes (ahead of any base) — this is what drives the up-leg machinery.
+      await home.offerDirective(
+        domain: 'guestbook',
+        directiveId: 'signGuestbook',
+        payload: {
+          'author': 'ada',
+          'message': 'offline write before autoSync',
+          'mood': 'delighted',
+          'signedAt': '2026-07-11T00:00:00Z',
+        },
+        actor: 'ada',
+      );
+
+      // 2. await homeSession.autoSync() completes promptly.
+      await home.autoSync().timeout(const Duration(seconds: 10),
+          onTimeout: () => throw StateError(
+              'autoSync() on a local-only session did not complete within 10s (the reported deadlock)'));
+
+      // 3. await bridge.listWorkspaces() and a query on a sibling estate session still complete.
+      final listed = await harness.bridge.listWorkspaces().timeout(
+          const Duration(seconds: 10),
+          onTimeout: () => throw StateError(
+              'listWorkspaces() hung after a local-only autoSync (dispatcher monopolized)'));
+      expect(listed.map((w) => w['session'].toString()).toSet(),
+          containsAll(names.toSet()));
+      final sibling = await harness
+          .session('estate-a')
+          .query('entriesByAuthor', {'author': 'nobody'}).timeout(
+              const Duration(seconds: 10),
+              onTimeout: () => throw StateError(
+                  'a sibling estate query hung after a local-only autoSync'));
+      expect(sibling, isEmpty);
+
+      // Give any wrongly-registered background sync machinery time to fire so its fetch attempts would show.
+      await Future<void>.delayed(const Duration(seconds: 2));
+
+      // 4. stopAutoSync() and harness disposal complete (disposal asserted in finally / teardown).
+      await home.stopAutoSync().timeout(const Duration(seconds: 10),
+          onTimeout: () =>
+              throw StateError('stopAutoSync() hung on a local-only session'));
+
+      // Bonus (live-runner leg of the acquireSession DX ask): a mounted local workspace is acquired
+      // WITHOUT credentials, and yields the same cached session handle.
+      final acquired = await harness.bridge.acquireSession('estate-b',
+          ifAbsentCredentials: () async =>
+              fail('estate-b is mounted on the plane — credentials must not be requested'));
+      expect(identical(acquired, harness.session('estate-b')), isTrue);
+
+      // 5. No local://.../intent-offers fetch attempts occur (attempted-and-refused still counts as attempted).
+      final offending = diagnostics
+          .where((l) => l.contains('intent-offers') || l.contains('refusing network fetch'))
+          .toList();
+      expect(offending, isEmpty,
+          reason:
+              'a local-only session must perform NO network work — saw:\n${offending.join('\n')}');
+    } finally {
+      await harness
+          .dispose()
+          .timeout(const Duration(seconds: 20), onTimeout: () {
+        throw StateError('harness disposal hung (the reported teardown hang)');
+      });
+    }
+  }, timeout: const Timeout(Duration(minutes: 3)));
+}

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.72.1",
+  "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.48.1";
+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).