Skip to content

Bind Herdr pane adoption to OS lineage, pre-authorize worker trust, and clarify browser handoff - #263

Merged
raphael merged 6 commits into
mainfrom
ux-herdr-trust-handoff
Nov 20, 2026
Merged

raphael merged 6 commits into
mainfrom
ux-herdr-trust-handoff

Conversation

@raphael

@raphael raphael commented Nov 20, 2026

Copy link
Copy Markdown
Member

When a developer ran /surla ($surla) inside an existing Herdr terminal tab whose coding agent stripped child environment variables or spawned surla stdio from a shared background daemon, attach_guide received either no HC_TERMINAL_ID or a stale terminal ID, reported herdr_mode: "available" as if the session were outside Herdr, and opened a second Herdr window when starting a build. Once a build started, newly launched builder and test-writer sessions paused on interactive folder-trust dialogs for .surla-build and .surla-tests and per-tool MCP approval prompts (get_builder_assignment and related Surla or Chorus tools). In addition, the initial open_views handoff and status copy relied on the internal "Guide" term and did not explain how to reopen Surla's browser window without a URL token.

This change ties Herdr pane adoption to OS process lineage, pre-populates user-scoped folder trust and Surla/Chorus MCP tool approvals while preserving explicit client restrictions and clean Git worktrees, branches chat handoff guidance on observed browser-opener results with Open Surla Window, and replaces user-facing "Guide" wording with "your coding agent".

Resulting behavior

  • Session-bound Herdr coding-agent pane adoption: surla setup -global adds "HC_TERMINAL_ID" to env_vars in TOML MCP server configuration (supporting both plain strings and structured env_vars entries) so direct TUI sessions forward their pane identifier. surla stdio also passes its OS ancestor PIDs (ancestor_pids)—while dropping inherited daemon terminal IDs and declining unproved shared app-server daemon attaches so remote or multiplexed sessions stay external—and AttachGuide revalidates the project directory, client family, and invoking process lineage on the final terminal read before labeling so live Herdr tabs are adopted and reused on Build while external terminal sessions and stale terminal IDs remain unattached.
  • Scoped worker trust and preserved client policies: Because .surla-build and .surla-tests enforce clean Git status including untracked files, Surla refuses any configuration destination or symlink resolving inside a worker tree. surla setup -global configures surla (and chorus when present) MCP tool approvals across supported TOML and JSON client locations (preserving existing tool filters such as includeTools and excludeTools, supporting alternate CLI home and trusted-folders override environment variables, and updating deny-only cli-config.json files), while PrepareWorkerTrust writes only missing folder-trust entries under a context-bounded operator file lock without touching MCP settings files during Build. Explicit user restrictions (untrusted or DO_NOT_TRUST folders, explicit prompt/writes/trust: false modes, and wildcard deny/ask rules matching an operation required by the selected worker role) are never overwritten and surface a bounded actionable step on both Build and Team → Start workers; headless worker invocations scope flags to --trust and mcp__surla__* without approving unrelated MCP servers.
  • Truthful browser handoff and plain "coding agent" copy: open_views, skills/surla/SKILL.md, and roleFirstMessage("guide") branch on opened: true versus opened: false, avoid claiming foreground focus beyond browser-opener dispatch, keep #link fragments out of chat, and name both reopen routes: asking the coding agent or clicking Open Surla Window (Cmd+Alt+Shift+S on macOS) in the Herdr companion. Companion, status, refusal, and documentation prose now say "Coding agent" / "your coding agent" (keeping unknown external pane state at "status unknown" rather than claiming live attachment).

Verification

Proven in Goa regeneration (goa gen), node ui/checkpoint/build.mjs --check, unit, race, and served-transport tests across cmd/surla, internal/project, and internal/controlplane (covering OS-lineage Herdr adoption and Build space reuse, conflicting-label and stale-terminal rejection, external-session non-adoption, preserved client restrictions and malformed-setting preflight refusals across both Build and Team, concurrent shared-config writes and worktree symlink refusals, structured env_vars and alternate home paths, Herdr companion Node tests, and herdr-app check). Live desktop coding-client startup and Herdr pane adoption are verified through deterministic TeamHost fixtures rather than a live GUI harness, and shared app-server daemon sessions without per-requester lineage remain unbound.

@raphael
raphael merged commit 96337db into main Nov 20, 2026
25 checks passed
@raphael
raphael deleted the ux-herdr-trust-handoff branch November 20, 2026 08:40
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