Skip to content

Give every recovery step an action that still works - #262

Merged
raphael merged 5 commits into
mainfrom
s4b-recovery-truth
Nov 20, 2026
Merged

raphael merged 5 commits into
mainfrom
s4b-recovery-truth

Conversation

@raphael

@raphael raphael commented Nov 20, 2026

Copy link
Copy Markdown
Member

After moving guide attachment and worker supervision to surla stdio and the browser views page, several server recovery messages and error declarations still assumed the earlier CLI startup flow: team preparation failures told the user to "run surla" to inspect steps, repair operator state, or restart team agents even though bare surla no longer prepares teams or starts agents; ensure_team still declared three error types it could no longer return; a stopped server's worker error and 401/403/version/state refusals still pointed to typed surla commands; and a guide started by Surla received different opening instructions from /surla.

Resulting behavior

  • Truthful agent, companion, and browser recovery steps: Team failure messages on Team, Build, and management attachment now name actions that actually work—retrying Start workers in Team, calling open_views from the coding agent or choosing Start Surla in the Herdr companion when the server is stopping, and distinguishing permission repair from missing or damaged files under surla/operator in user configuration storage.
  • Retired unproduced ensure_team errors: Because ensure_team only reads saved team metadata, ambiguous_space, window_busy, team_unavailable, and the unused TeamSpaceConflict DSL type (along with the dead CLI deadline wrapper and decoders that only handled them) are removed from the management project service contract, and duplicate-space reporting lives directly on controlplane.TeamSpaceConflict.
  • Consistent provider-key, session, worker, version-upgrade, and guide guidance: Missing live-target provider keys explain exporting the key in the environment where the coding agent starts and restarting it (or using a model gateway); init_project version refusals explain stopping the old server before reconnecting a release binary; worker stopped-server, guide-bind, and 401/403/state refusals route to the coding agent or Herdr companion rather than typed CLI detours; and roleFirstMessage("guide") matches skills/surla/SKILL.md's single-question start, omitted-module_path in-place initialization, Change Card ambiguities, and read-only surla preview exception.

Verification

Verified with Goa regeneration (goa gen), node ui/checkpoint/build.mjs --check, go vet, and unit, transport, and served-page suites across cmd/surla, internal/project, and internal/controlplane.

Since agents attach through surla stdio, bare surla neither prints a team
step nor starts agents, yet the page, start_build and guide attachment still
told the user to "run surla" to see a step, repair state or restart agents.
Each team failure cause now names its repair and a retry the user can take:
Start agents on the page, a coding agent's Surla tool call, or Start Surla in
the Herdr companion. The project_state step points to Surla's operator
storage instead of a CLI that no longer prints the folder.

ensure_team now only reads saved team metadata, so it can no longer return
ambiguous_space, window_busy or team_unavailable. Those errors are removed
from its contract, with the CLI decoding and the Herdr deadline wrapper that
only they reached. The duplicate-space count the worker start reports moves
from the generated type to controlplane.TeamSpaceConflict, which the Team
contract owns.

A missing provider key now says to export it where the coding agent starts
and restart it, since its first Surla call hands settings over. A worker
whose server stopped, the 401 and 403 refusals, the init_project version
refusal and the project state errors no longer tell the user to type surla
when an agent or companion action exists. A guide that Surla starts now
follows the same opening as /surla: one plain question, in-place init
without a module path, and product questions as Change Card ambiguities.
Review corrections for the recovery wording.

The init_project refusal for a server without a module version now says to
install a release, stop the running project server with surla stop, and
restart the coding agent before calling init_project again: the server keeps
the version it started with, and a new surla refuses to attach to it.

Management errors shared by the CLI and surla stdio's guide attachment say
"try again" instead of "run surla again", so a guide whose first tool call
fails is told to call it again.

A project_state failure on the views page now names the affected file and
its repair: a permission or owner change on that one file, a restore for a
missing or damaged one, or a writable folder for a failed write. Steps that
know only the cause scope their advice the same way and never prescribe a
recursive permission change.

A stopping server's steps name a fresh page, which the coding agent's
open_views or the companion's Start Surla opens, then Team → Start workers.
The guide instructions use refresh_story instead of surla preview, which the
same skill forbade.
A save Surla could not write now names the folder to make writable, even
when the system refused it, instead of suggesting a mode change on a record
whose mode is already right. Only a path that failed Surla's own privacy
check gets a mode and owner change on that path; a read the system refused
names the folders that hold it.

The start_build step for unusable project state no longer promises that
Team will name the file, since an unreadable build assignment names none
and Team hides Start workers until assignments can be read. It says which
state to make readable and writable, then to start the team agents once the
views page can read the build again.
A read the system refused now says the account must be able to read the
file and open the folders that hold it, since a file with no permissions
fails before Surla's own privacy check.

start_build's project_state step covers every saved state that cause can
mean, including saved verification requests, so it asks for read and write
access to the project's Surla state and a restore of anything missing or
damaged, without naming two files as the only culprits or a control the
page may hide.
The eligible-history page test created a second change just before clicking
Merge. Its list update wakes the page's change wait, and the refresh that
follows briefly disables Merge, so the click could land in that window and
send nothing. The change is now created after the merge is pending, which is
the only time the test needs it, and the test checks that the update leaves
the merge pending.
@raphael
raphael merged commit dcde777 into main Nov 20, 2026
25 checks passed
@raphael
raphael deleted the s4b-recovery-truth branch November 20, 2026 03:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant