[Ark0N]

The problem

A running Codeman remembers that a coding agent is missing, for up to 5 minutes after it last looked. That is there for a good reason: the last step of the lookup spawns a login shell, and without the memory every status poll would freeze the server for up to 5 seconds.

The Run button reads that same memory. So this sequence, the most likely one for a new user, goes wrong:

1. Press Run. Codeman says the agent is not installed.
2. Add the agent, with install.sh agent <id> or Codeman Desktop's Add a coding agent (feat(desktop): install Codeman from the app, with no Terminal and no password #773).
3. Press Run again. Codeman still says it is not installed, for up to 5 minutes, right after being told it was ready.

Restarting the service would clear it, but a tool that adds an agent has no business restarting a server with sessions on it. The only code that cleared the memory is the CLI management routes in Settings, which are off by default.

The fix

The installer leaves a note, and the server reads it.

• install.sh touches ~/.codeman/cli-installed once an agent has landed, and for an agent it finds already there, since that one may have been installed by hand a minute ago. The file is empty. A failed install writes nothing.
• resolve() in src/utils/cli-executable-resolver.ts leaves its backoff when that file's mtime changes.

The change buys one run of the lookup, so an agent that is still missing goes back to waiting. Each agent keeps its own resolver, so each one notices separately.

Why this and not a re-scan

The obvious alternative is to re-walk PATH during the backoff, skipping only the login shell. It would also find agents installed by hand, but it was rejected:

• It puts a synchronous stat of every PATH entry on the request path, and one dead network mount in PATH would then freeze the server on every request. That is the failure fix(cases): bound path probes for linked workspaces and session creation, so an unreachable mount cannot freeze the server #516 fixed elsewhere.
• It would execute candidates that were already refused, like Debian's unrelated dsh, because some resolvers run the binary to check what it is.

This check is one stat of one file in the data folder, which the server reads constantly anyway. It sits after the cached-success return, so a resolved agent never pays for it.

Stacked on #773

The base is feat/graphical-installer, because the only thing that really needs this, install.sh agent, is in #773 and is not on master. On master it would be a reader with almost nothing writing to it, plus a conflict in install.sh. Merge order: #763, #773, then this one. GitHub retargets it when its base merges.

The diff is one commit, and it merges cleanly with the local branch that combines #763's unpushed review commits with #773. Against master it adds no conflict of its own. #773 has one, a single line of install.sh --help text that a later fix on master also changed, which this PR neither causes nor solves.

It also changes the wording on the desktop app's last screen, because "within a few minutes" is no longer the normal case.

No changeset: COM writes it.

Tested

On a real Mac (Apple Silicon, macOS 27.2, stock /bin/bash 3.2). A real install of this branch with no agent, under a throwaway home folder, with its server running and already remembering every agent as missing. Then real agents, through the same Rust code the desktop app calls:

	Before this change	With it
Codex (npm route): the server sees it	56 seconds after the install	48 ms
Claude Code (curl route): the server sees it	not measured	43 ms

• The 56 seconds is from the same scenario without this change, on a first miss, which is the shortest backoff there is. The longest is 5 minutes.
• GitHub Copilot, which was not installed, stayed unavailable afterwards.
• The server's process never changed, and the page a browser loads listed both new agents.
• A real shell session in that server ran claude --version: 2.1.318 (Claude Code).

In the test suites. New tests in test/cli-executable-resolver.test.ts and test/install-sh-invariants.test.ts, and the marker's name is pinned on both sides. Each part of the fix was broken on purpose to prove a test catches it, which is how one test that could not fail was found and fixed.

Known limits

• An agent installed by hand is not covered. npm install -g @openai/codex in a terminal writes no marker, so it waits out the backoff as it always has. Running install.sh agent codex afterwards clears it.
• Only servers with this change read the marker. An older Codeman ignores the file, so the app's last screen still says it can take a few minutes.
• An open page still needs a reload. The list of installed agents is part of the page. Opening Codeman from the app loads a fresh one.
• Another CODEMAN_INSTANCE has its own data folder, and the installer only writes under ~/.codeman, so a beta instance waits out the backoff too.