Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

Add holder identification for terminal watchers and update related tests

Dev jacobcb632a5a00bd
diff --git a/cli/src/lib/terminalStreamManager.spec.ts b/cli/src/lib/terminalStreamManager.spec.ts
index 19adaa437..40721542d 100644
--- a/cli/src/lib/terminalStreamManager.spec.ts
+++ b/cli/src/lib/terminalStreamManager.spec.ts
@@ -608,6 +608,41 @@ describe('TerminalStreamManager', () => {
})
})
+ // The phone opens politely (`takeover: false`) and watches a terminal the desktop is driving. Its
+ // banner says WHO has it — the desktop names a taker the same way — so the ready carries the
+ // holder's own introduction, and nothing when the holder never gave one.
+ it('names the holder on a watcher\'s ready', async () => {
+ await manager.handleFrame('web-1', 'terminal_open', {
+ requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
+ client: { kind: 'desktop', name: 'MacBookPro2021.local', machineId: 'ab12ab12ab12ab12' },
+ })
+ await manager.handleFrame('phone-1', 'terminal_open', {
+ requestId: 'open-2', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30, takeover: false,
+ client: { kind: 'phone', name: 'iPhone' },
+ })
+ const ready = sent.find((frame) => frame.connId === 'phone-1' && frame.type === 'terminal_ready')
+ expect(ready?.payload).toMatchObject({
+ readOnly: true,
+ heldBy: { kind: 'desktop', name: 'MacBookPro2021.local', machineId: 'ab12ab12ab12ab12' },
+ })
+ // The holder keeps the terminal, and a controller's own ready never names anybody.
+ expect(sent.some((frame) => frame.connId === 'web-1' && frame.type === 'terminal_closed')).toBe(false)
+ expect(sent.find((frame) => frame.connId === 'web-1' && frame.type === 'terminal_ready')?.payload)
+ .not.toHaveProperty('heldBy')
+ })
+
+ it('says nothing about a holder that never introduced itself', async () => {
+ await manager.handleFrame('web-1', 'terminal_open', {
+ requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
+ })
+ await manager.handleFrame('phone-1', 'terminal_open', {
+ requestId: 'open-2', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30, takeover: false,
+ })
+ const ready = sent.find((frame) => frame.connId === 'phone-1' && frame.type === 'terminal_ready')
+ expect(ready?.payload.readOnly).toBe(true)
+ expect(ready?.payload).not.toHaveProperty('heldBy')
+ })
+
it('falls back to what the daemon can say about a silent winner, and says nothing over a bad claim', async () => {
manager = newManager({
describeClient: (connId) => connId === 'local-2' ? { kind: 'desktop', name: 'This Mac' } : null,
diff --git a/cli/src/lib/terminalStreamManager.ts b/cli/src/lib/terminalStreamManager.ts
index 5cebeaa75..e90d87432 100644
--- a/cli/src/lib/terminalStreamManager.ts
+++ b/cli/src/lib/terminalStreamManager.ts
@@ -420,6 +420,9 @@ export class TerminalStreamManager {
// a WATCHER: tmux attaches read-only (no control lease, no resize, no input), the incumbent
// keeps the terminal, and the client is told which it got by `readOnly` on `terminal_ready`.
const watching = !this.deps.readOnly && !takeover && incumbents.length > 0
+ // Who a watcher is watching, named on its banner — "MacBook Pro is using this terminal" — as
+ // `takenBy` names the winner on the incumbent's. Read now, before any stream below moves.
+ const heldBy = watching ? this.holderOf(incumbents, reservedPlacement) : undefined
// A terminal is single-controller. A later client explicitly wins the lease and the incumbent
// receives a targeted close notification; it must not be broadcast to other clients. The
// notification names the winner when it can (`takenBy`), so the incumbent's banner can too.
@@ -535,6 +538,7 @@ export class TerminalStreamManager {
// True for a watcher too: the client draws output and withholds input, exactly as it does
// for an observer's stream. See the `takeover: false` branch above.
readOnly: this.deps.readOnly === true || watching,
+ ...(heldBy ? { heldBy } : {}),
})) {
await this.closeStream(state, 'backend disconnected', false)
return
@@ -1189,6 +1193,15 @@ export class TerminalStreamManager {
&& (state.agentId === agentId || state.placementKey === placementKey))
}
+ /** The client driving a terminal a watcher opened onto: the placement's controller, or failing
+ * that the first incumbent that said who it is. Undefined when none did — the banner then says
+ * "another app", as it always has. */
+ private holderOf(incumbents: ActiveStream[], placementKey: string): TerminalClientDescriptor | undefined {
+ const controller = this.controllerByPlacement.get(placementKey)
+ return (incumbents.find((state) => state.connId === controller && state.client)
+ ?? incumbents.find((state) => state.client))?.client
+ }
+
private async closeStreamsForTakeover(
agentId: string,
placementKey: string,
diff --git a/mobile/lib/phone/phone_status.dart b/mobile/lib/phone/phone_status.dart
index e6b046954..39612cc31 100644
--- a/mobile/lib/phone/phone_status.dart
+++ b/mobile/lib/phone/phone_status.dart
@@ -195,6 +195,13 @@ String? phoneTakerName(
? session?.takenOverBy?.label(resolveMachine)
: null;
+/// Who is driving the terminal this session only watches, when the daemon said — the fleet's name
+/// for that machine where it knows one. Null unless [TerminalSession.watching].
+String? phoneHolderName(
+ TerminalSession? session,
+ String? Function(String machineId) resolveMachine,
+) => session?.watching == true ? session?.heldBy?.label(resolveMachine) : null;
+
/// The one line under the header while another client drives this terminal —
/// the desktop's banner, at phone size. Null in every other state.
String? phoneTakeoverNotice(TerminalSession? session, String? takerName) =>
diff --git a/mobile/lib/phone/terminal_page.dart b/mobile/lib/phone/terminal_page.dart
index 90740d073..ed6aecca8 100644
--- a/mobile/lib/phone/terminal_page.dart
+++ b/mobile/lib/phone/terminal_page.dart
@@ -1151,6 +1151,10 @@ class _TerminalPageState extends State<TerminalPage>
(id) => widget.notifier.stateOf(id)?.machine.displayName,
);
final takeoverNotice = phoneTakeoverNotice(session, takerName);
+ final holderName = phoneHolderName(
+ session,
+ (id) => widget.notifier.stateOf(id)?.machine.displayName,
+ );
final headerStatus = phoneSessionSummary(
session,
takerName: takerName,
@@ -1534,6 +1538,7 @@ class _TerminalPageState extends State<TerminalPage>
watching: session?.watching ?? false,
busy: !blocked,
takeoverNotice: takeoverNotice,
+ holderName: holderName,
onTakeControl: _takeControl,
),
],
@@ -1948,6 +1953,7 @@ class _ControlBanner extends StatelessWidget {
required this.watching,
required this.busy,
required this.takeoverNotice,
+ required this.holderName,
required this.onTakeControl,
});
@@ -1961,11 +1967,15 @@ class _ControlBanner extends StatelessWidget {
/// never lost a terminal, and while a take is in flight.
final String? takeoverNotice;
+ /// Who is driving the terminal a watcher is looking at, as [phoneHolderName] names it — the
+ /// machine, as the desktop names a taker. Null when the daemon did not say.
+ final String? holderName;
+
final VoidCallback onTakeControl;
String get _title {
if (busy) return 'Taking control…';
- if (watching) return 'Another app is using this terminal';
+ if (watching) return '${holderName ?? 'Another app'} is using this terminal';
return takeoverNotice ?? 'Another app took control of this terminal';
}
diff --git a/mobile/lib/terminal/terminal_session.dart b/mobile/lib/terminal/terminal_session.dart
index 27db0bfa4..d5eb5e62e 100644
--- a/mobile/lib/terminal/terminal_session.dart
+++ b/mobile/lib/terminal/terminal_session.dart
@@ -232,6 +232,12 @@ class TerminalSession extends ChangeNotifier {
/// and the daemon said (`terminal_closed.takenBy`); null from an older daemon
/// or a taker that did not introduce itself — "another app", then.
TerminalClientDescriptor? takenOverBy;
+
+ /// Who is driving this terminal while this session only [watching] it — the daemon's
+ /// `terminal_ready.heldBy`, so the banner can say "MacBook Pro is using this terminal" as the
+ /// desktop names a taker. Null when not watching, from an older daemon, or when the holder never
+ /// introduced itself — "another app", then.
+ TerminalClientDescriptor? heldBy;
int cols = 80;
int rows = 24;
@@ -384,6 +390,7 @@ class TerminalSession extends ChangeNotifier {
streamId = null;
linkMode = null;
watching = false;
+ heldBy = null;
errorCode = null;
errorMessage = null;
takenOverBy = null;
@@ -571,6 +578,9 @@ class TerminalSession extends ChangeNotifier {
// The daemon's answer to a polite open on a terminal somebody else holds: it opened, it
// renders, and it may not type. See [watching].
watching = payload['readOnly'] == true;
+ heldBy = watching
+ ? TerminalClientDescriptor.fromJson(payload['heldBy'])
+ : null;
// ⚠️ **The press is spent here.** A takeover was asked for and ANSWERED, so the claim it
// was making is now a lease this session holds — and holding it is what later opens should
// rest on, not the press that won it.
@@ -651,6 +661,7 @@ class TerminalSession extends ChangeNotifier {
takenOverBy = takenOver
? TerminalClientDescriptor.fromJson(payload['takenBy'])
: null;
+ heldBy = null;
errorMessage = takenOver
? (takenOverBy == null
? 'Another client connected to this terminal.'
diff --git a/mobile/test/phone_reclaim_test.dart b/mobile/test/phone_reclaim_test.dart
index 947945ea6..430e34af0 100644
--- a/mobile/test/phone_reclaim_test.dart
+++ b/mobile/test/phone_reclaim_test.dart
@@ -107,6 +107,68 @@ void main() {
);
});
+ group('who is driving a terminal this phone only watches', () {
+ /// Opened politely onto a terminal somebody else holds: the daemon's
+ /// ready says `readOnly`, and — from a daemon new enough — who holds it.
+ Future<TerminalSession> watching({Map<String, dynamic>? heldBy}) async {
+ final sent = <Map<String, dynamic>>[];
+ final session = TerminalSession(
+ machineId: 'm',
+ agentId: 'a',
+ agentName: 'Agent',
+ engineId: 'codex',
+ send: (_, payload) async {
+ sent.add(payload);
+ return true;
+ },
+ sendBinary: (_) async => true,
+ );
+ addTearDown(session.dispose);
+ await session.open(initialCols: 100, initialRows: 30);
+ await session.handleFrame('terminal_ready', {
+ 'requestId': sent.single['requestId'],
+ 'protocolVersion': 3,
+ 'streamId': 's',
+ 'agentId': 'a',
+ 'readOnly': true,
+ 'heldBy': ?heldBy,
+ });
+ return session;
+ }
+
+ test('the banner names the machine, as the desktop does', () async {
+ final session = await watching(
+ heldBy: {
+ 'kind': 'desktop',
+ 'name': 'MacBookPro2021.local',
+ 'machineId': 'ab12ab12ab12ab12',
+ },
+ );
+ expect(session.watching, isTrue);
+ expect(phoneHolderName(session, (_) => null), 'MacBookPro2021.local');
+ // The fleet's current name for that machine wins, as it does for a taker.
+ expect(
+ phoneHolderName(
+ session,
+ (id) => id == 'ab12ab12ab12ab12' ? 'Studio' : null,
+ ),
+ 'Studio',
+ );
+ });
+
+ test('an older daemon names nobody — "another app", then', () async {
+ final session = await watching();
+ expect(session.watching, isTrue);
+ expect(phoneHolderName(session, (_) => 'Mac'), isNull);
+ });
+
+ test('a session this phone drives has no holder to name', () {
+ final session = _session(TerminalSessionStatus.controlling)
+ ..heldBy = const TerminalClientDescriptor(kind: 'desktop', name: 'x');
+ expect(phoneHolderName(session, (_) => null), isNull);
+ });
+ });
+
test('nothing to say while this phone drives, or nobody does', () {
expect(phoneTakeoverNotice(null, null), isNull);
for (final status in [