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.

fix(mobile): say why a machine refused a new harness

tonyea54b93c3559
diff --git a/mobile/lib/state/app_state.dart b/mobile/lib/state/app_state.dart
index 5187639f4..147c22fd3 100644
--- a/mobile/lib/state/app_state.dart
+++ b/mobile/lib/state/app_state.dart
@@ -5849,16 +5849,71 @@ class AppNotifier extends ChangeNotifier {
return null;
}
- String _creationFailureMessage(String code, String? detail, String machine) =>
+ String _creationFailureMessage(
+ String code,
+ String? detail,
+ String machine, {
+ Map<String, dynamic>? choices,
+ }) =>
switch (code) {
+ // A New Folder named after its first task (`projectNameMode:
+ // suggested`). A current machine numbers that name past a folder that
+ // exists (`robot-2`), so only one that predates the mode refuses it, and
+ // its sentence is written for a name somebody typed. The phone has no
+ // name field to change instead, so it says the way to a fresh folder.
+ 'PROJECT_EXISTS' when choices?['projectNameMode'] == 'suggested' =>
+ 'A folder named after this task already exists on $machine. '
+ 'Choose it from your projects, or update Harness there to make '
+ 'a new one.',
+ // Making the project folder (a new one, a clone, a worktree or a
+ // branch) before anything starts in it: `cli/src/lib/projectFolder.ts`
+ // and `gitProject.ts`. The machine's sentence says what to change: the
+ // URL, the branch, Worktree.
+ 'INVALID_PROJECT_SOURCE' ||
+ 'INVALID_REPOSITORY' ||
+ 'PROJECT_PREPARATION_FAILED' ||
+ 'PROJECT_EXISTS' ||
+ 'CLONE_FAILED' ||
+ 'CLONE_TIMEOUT' ||
+ 'GIT_PROJECT_UNAVAILABLE' ||
+ 'INVALID_BRANCH' ||
+ 'BRANCH_SWITCH_FAILED' ||
+ 'WORKTREE_FAILED' ||
+ 'GIT_UNAVAILABLE' =>
+ detail ?? 'Could not prepare the project folder on $machine.',
'CWD_NOT_FOUND' || 'INVALID_CWD' =>
'The project folder is unavailable on $machine. '
'Choose another folder and try again.',
'TMUX_UNAVAILABLE' =>
'Harness needs tmux to start harnesses on $machine. '
'Install tmux there, then try again.',
+ // The machine's own sentence names the engine and the flag it lacks.
+ // Without one, the phone's Approvals names the way out.
+ 'CODEX_CLI_TOO_OLD' =>
+ detail ??
+ 'The installed Codex CLI on $machine is too old for '
+ 'Auto-approve. Update Codex there, or choose Ask first under '
+ 'Approvals.',
'UNSUPPORTED_ON_REMOTE' || 'UNSUPPORTED' =>
'Update the harness CLI on this machine to create a harness',
+ 'INVALID_DSH' =>
+ 'This harness is not installed on $machine. '
+ '${detail ?? 'Install it there, then try again.'}',
+ 'PROMPT_UNSUPPORTED' =>
+ 'This engine cannot be opened with a first message on $machine.',
+ 'PROMPT_TOO_LONG' =>
+ 'This first task is too long for $machine. Shorten it and try again.',
+ 'AGENT_UNSUPPORTED' =>
+ 'This engine cannot be opened as a named agent on $machine.',
+ 'INVALID_AGENT' =>
+ 'This engine cannot be opened as that named agent on $machine.',
+ 'INVALID_PERMISSION_MODE' =>
+ 'This engine has no such permission mode on $machine.',
+ // A daemon older than the engine refuses it by name, with no detail;
+ // the fix is the update the UNSUPPORTED codes ask for. A detail is a
+ // reason of its own (the sample runs only Claude Code and Codex).
+ 'INVALID_ENGINE' =>
+ detail ?? 'Update the harness CLI on $machine to start this agent.',
// Opening a conversation Harness did not start (`resumeSessionId`). The machine says what
// stopped it: open elsewhere, already a harness, gone.
'SESSION_OPEN_ELSEWHERE' ||
@@ -5961,13 +6016,37 @@ class AppNotifier extends ChangeNotifier {
}
// Refusals that happen before a launch are safe to correct. INTERNAL,
// spawn timeouts and connection failures cannot prove nothing started.
+ //
+ // A code missing here reads as a lost reply ("has not confirmed the new
+ // harness yet. Check status before creating another."), which asks for
+ // a second create of something the machine already turned down. The CLI
+ // checks every one before any pane exists (`create` in its
+ // core/agents/launches.ts, and core/agents/create.ts before the spawn).
+ // The desktop's set is the same list; keep the two in step.
const refusedBeforeLaunch = {
+ // The project folder as asked for, refused before one is made or
+ // cloned.
+ 'INVALID_PROJECT_SOURCE',
+ 'INVALID_REPOSITORY',
+ 'PROJECT_EXISTS',
'CWD_NOT_FOUND',
'INVALID_CWD',
'INVALID_ENGINE',
'INVALID_GRID',
+ 'GRID_UNAVAILABLE',
'INVALID_CODEX_HOME',
+ 'INVALID_DSH',
+ // The first task, a named agent and the approval mode.
+ 'PROMPT_UNSUPPORTED',
+ 'PROMPT_TOO_LONG',
+ 'INVALID_PROMPT',
+ 'AGENT_UNSUPPORTED',
+ 'INVALID_AGENT',
+ 'INVALID_PERMISSION_MODE',
'TMUX_UNAVAILABLE',
+ // An engine too old for the approval mode's flag: refused rather than
+ // left printing its help in a pane.
+ 'CODEX_CLI_TOO_OLD',
'TMUX_TOO_OLD_FOR_GRID',
'GRID_CONFIG_FAILED',
'UNSUPPORTED_ON_REMOTE',
@@ -5989,7 +6068,12 @@ class AppNotifier extends ChangeNotifier {
};
if (refusedBeforeLaunch.contains(failure.code)) {
return creation._complete(
- _creationFailureMessage(failure.code, failure.detail, machineName),
+ _creationFailureMessage(
+ failure.code,
+ failure.detail,
+ machineName,
+ choices: choices,
+ ),
);
}
return unconfirmed;
@@ -6027,6 +6111,7 @@ class AppNotifier extends ChangeNotifier {
failure['code'] as String,
failure['detail'] is String ? failure['detail'] as String : null,
machineName,
+ choices: choices,
),
);
case 'created':
diff --git a/mobile/test/app_state_agent_rpcs_test.dart b/mobile/test/app_state_agent_rpcs_test.dart
index 7faa71ee8..5aaaeebce 100644
--- a/mobile/test/app_state_agent_rpcs_test.dart
+++ b/mobile/test/app_state_agent_rpcs_test.dart
@@ -299,7 +299,7 @@ void main() {
for (final (code, says) in [
('TMUX_UNAVAILABLE', 'needs tmux'),
('UNSUPPORTED', 'Update the harness CLI'),
- ('INVALID_ENGINE', 'Create harness failed'),
+ ('INVALID_ENGINE', 'Update the harness CLI on Machine m'),
]) {
test('$code is worded for a person', () async {
final rig = await signedInWith({'m': []});
@@ -313,6 +313,289 @@ void main() {
});
}
+ test('an engine refused with its own reason says it', () async {
+ final rig = await signedInWith({'m': []});
+ addTearDown(rig.app.dispose);
+ // The sample's machine runs two engines, and says so.
+ rig.conn('m').answers['agent_create'] = (_) => throw refusal(
+ 'INVALID_ENGINE',
+ detail: 'The sample runs Claude Code and Codex.',
+ );
+
+ expect(
+ await rig.app.createAgent('m', engine: 'cursor', folder: '/work'),
+ 'The sample runs Claude Code and Codex.',
+ );
+ });
+
+ // Every refusal the CLI makes before a pane exists that the phone used to
+ // read as a lost reply, with what the machine says and what the phone then
+ // says. Machine m is the rig's machine's name.
+ for (final (code, detail, says) in <(String, String?, String)>[
+ ('INVALID_PROJECT_SOURCE', 'Choose a project.', 'Choose a project.'),
+ (
+ 'INVALID_REPOSITORY',
+ 'Enter a GitHub URL or owner/repository.',
+ 'Enter a GitHub URL or owner/repository.',
+ ),
+ (
+ 'PROJECT_EXISTS',
+ '“app” already exists. Select that folder from your projects.',
+ '“app” already exists. Select that folder from your projects.',
+ ),
+ (
+ 'GRID_UNAVAILABLE',
+ 'The selected model is unavailable. Choose another model or refresh '
+ 'the list.',
+ 'Create harness failed: The selected model is unavailable. Choose '
+ 'another model or refresh the list.',
+ ),
+ (
+ 'INVALID_DSH',
+ 'blender is not installed on this machine',
+ 'This harness is not installed on Machine m. blender is not installed '
+ 'on this machine',
+ ),
+ (
+ 'PROMPT_UNSUPPORTED',
+ 'cursor cannot be started with a first message',
+ 'This engine cannot be opened with a first message on Machine m.',
+ ),
+ (
+ 'PROMPT_TOO_LONG',
+ 'prompt is longer than 2000 characters',
+ 'This first task is too long for Machine m. Shorten it and try again.',
+ ),
+ (
+ 'INVALID_PROMPT',
+ 'prompt must be a string',
+ 'Create harness failed: prompt must be a string',
+ ),
+ (
+ 'AGENT_UNSUPPORTED',
+ null,
+ 'This engine cannot be opened as a named agent on Machine m.',
+ ),
+ (
+ 'INVALID_AGENT',
+ 'agent must be 1-64 letters, digits, `-` or `_`',
+ 'This engine cannot be opened as that named agent on Machine m.',
+ ),
+ (
+ 'INVALID_PERMISSION_MODE',
+ 'claude has no permission mode "yolo"',
+ 'This engine has no such permission mode on Machine m.',
+ ),
+ (
+ 'CODEX_CLI_TOO_OLD',
+ 'The codex CLI on this machine does not support --ask-for-approval, '
+ 'which Harness uses for this permission mode.',
+ 'The codex CLI on this machine does not support --ask-for-approval, '
+ 'which Harness uses for this permission mode.',
+ ),
+ ]) {
+ test('$code is a refusal, said and final', () async {
+ final rig = await signedInWith({'m': []});
+ addTearDown(rig.app.dispose);
+ rig.conn('m').answers['agent_create'] = (_) =>
+ throw refusal(code, detail: detail);
+ final attempt = AgentCreationAttempt();
+
+ final error = await rig.app.createAgent(
+ 'm',
+ engine: 'claude',
+ folder: '/work',
+ attempt: attempt,
+ );
+
+ expect(error, says);
+ expect(error, isNot(contains('has not confirmed')));
+ expect(
+ attempt.awaitingConfirmation,
+ isFalse,
+ reason: 'nothing started, so there is nothing to check on',
+ );
+ // The same attempt again answers the same, without asking the machine.
+ expect(
+ await rig.app.createAgent(
+ 'm',
+ engine: 'claude',
+ folder: '/work',
+ attempt: attempt,
+ ),
+ says,
+ );
+ expect(rig.conn('m').payloadsOf('agent_create'), hasLength(1));
+ expect(rig.conn('m').payloadsOf('agent_create_status'), isEmpty);
+ });
+
+ test('$code in a failed receipt is said the same way', () async {
+ final rig = await signedInWith({'m': []});
+ addTearDown(rig.app.dispose);
+ rig.conn('m').answers['agent_create'] = (p) => {
+ 'creationId': p['creationId'],
+ 'state': 'failed',
+ 'failure': {'code': code, 'detail': ?detail},
+ };
+ final attempt = AgentCreationAttempt();
+
+ expect(
+ await rig.app.createAgent(
+ 'm',
+ engine: 'claude',
+ folder: '/work',
+ attempt: attempt,
+ ),
+ says,
+ );
+ expect(attempt.awaitingConfirmation, isFalse);
+ });
+ }
+
+ // Making the folder itself, which only a receipt reports: the machine's
+ // sentence names what to change.
+ for (final code in [
+ 'PROJECT_PREPARATION_FAILED',
+ 'CLONE_FAILED',
+ 'CLONE_TIMEOUT',
+ 'GIT_PROJECT_UNAVAILABLE',
+ 'INVALID_BRANCH',
+ 'BRANCH_SWITCH_FAILED',
+ 'WORKTREE_FAILED',
+ 'GIT_UNAVAILABLE',
+ ]) {
+ test('$code says why the project folder was not made', () async {
+ final rig = await signedInWith({'m': []});
+ addTearDown(rig.app.dispose);
+ String? detail = 'Check the URL and connection, then retry.';
+ rig.conn('m').answers['agent_create'] = (p) => {
+ 'creationId': p['creationId'],
+ 'state': 'failed',
+ 'failure': {'code': code, 'detail': ?detail},
+ };
+ final request = ProjectFolderRequest.remote(
+ GitHubRepository.parse('owner/app')!,
+ );
+
+ expect(
+ await rig.app.createAgent(
+ 'm',
+ engine: 'claude',
+ folder: '',
+ projectFolder: request,
+ ),
+ 'Check the URL and connection, then retry.',
+ );
+ detail = null;
+ expect(
+ await rig.app.createAgent(
+ 'm',
+ engine: 'claude',
+ folder: '',
+ projectFolder: request,
+ ),
+ 'Could not prepare the project folder on Machine m.',
+ );
+ });
+ }
+
+ test(
+ 'a folder named after the task, taken on an older machine, says how to get a new one',
+ () async {
+ final rig = await signedInWith({'m': []});
+ addTearDown(rig.app.dispose);
+ // A machine that predates `projectNameMode` refuses the name the phone
+ // made up, in words written for a name somebody typed.
+ const taken =
+ '“robot-talks-to-gemini” already exists. Select that folder from '
+ 'your projects.';
+ rig.conn('m').answers['agent_create'] = (_) =>
+ throw refusal('PROJECT_EXISTS', detail: taken);
+ final attempt = AgentCreationAttempt();
+
+ final error = await rig.app.createAgent(
+ 'm',
+ engine: 'claude',
+ folder: '',
+ projectFolder: ProjectFolderRequest.forTask('Robot talks to Gemini'),
+ prompt: 'Robot talks to Gemini',
+ attempt: attempt,
+ );
+
+ expect(error, contains('named after this task already exists'));
+ expect(error, contains('update Harness there'));
+ expect(attempt.awaitingConfirmation, isFalse);
+ expect(
+ rig.conn('m').payloadsOf('agent_create').single['projectNameMode'],
+ 'suggested',
+ );
+
+ // The same, when the refusal arrives as the receipt.
+ rig.conn('m').answers['agent_create'] = (p) => {
+ 'creationId': p['creationId'],
+ 'state': 'failed',
+ 'failure': {'code': 'PROJECT_EXISTS', 'detail': taken},
+ };
+ expect(
+ await rig.app.createAgent(
+ 'm',
+ engine: 'claude',
+ folder: '',
+ projectFolder: ProjectFolderRequest.forTask(
+ 'Robot talks to Gemini',
+ ),
+ prompt: 'Robot talks to Gemini',
+ ),
+ error,
+ );
+ },
+ );
+
+ test('an old engine with no reason names the way out', () async {
+ final rig = await signedInWith({'m': []});
+ addTearDown(rig.app.dispose);
+ rig.conn('m').answers['agent_create'] = (_) =>
+ throw refusal('CODEX_CLI_TOO_OLD');
+
+ final error = await rig.app.createAgent(
+ 'm',
+ engine: 'codex',
+ folder: '/work',
+ permissionMode: 'auto',
+ );
+ expect(error, contains('too old for Auto-approve'));
+ expect(error, contains('Ask first under Approvals'));
+ });
+
+ // Nothing proves that these did not start a harness, so each is checked
+ // rather than called final.
+ for (final (name, failure) in <(String, Object)>[
+ ('INTERNAL', refusal('INTERNAL')),
+ ('CREATION_CONFLICT', refusal('CREATION_CONFLICT')),
+ ('a code no machine sends yet', refusal('SOMETHING_NEW')),
+ ('a timeout', const WsRequestTimeout('agent_create')),
+ ('a dropped socket', StateError('socket closed')),
+ ]) {
+ test('$name leaves the harness unconfirmed', () async {
+ final rig = await signedInWith({'m': []});
+ addTearDown(rig.app.dispose);
+ rig.conn('m').answers['agent_create'] = (_) => throw failure;
+ final attempt = AgentCreationAttempt();
+
+ expect(
+ await rig.app.createAgent(
+ 'm',
+ engine: 'claude',
+ folder: '/work',
+ attempt: attempt,
+ ),
+ 'Machine m has not confirmed the new harness yet. '
+ 'Check status before creating another.',
+ );
+ expect(attempt.awaitingConfirmation, isTrue);
+ });
+ }
+
test('a lost reply is checked, never sent twice', () async {
final rig = await signedInWith({'m': []});
addTearDown(rig.app.dispose);