tutti/packages/agent/daemon/AGENTS.md

AGENTS.md

Scope

This file applies to packages/agent/daemon/*. Read the root AGENTS.md, packages/AGENTS.md, and docs/architecture/windows-platform-support.md before changing this runtime.

Cross-platform runtime contract

Agent runtimes launch external programs and exchange host filesystem paths with provider protocols. Treat every change in this directory as platform-sensitive unless it is provably platform-neutral.

• Construct host paths with Go's filepath APIs and injected workspace, state, home, or temporary roots. Do not use POSIX-rooted literals as host paths.
• For path-bearing provider fields such as cwd, writable roots, executable paths, sockets, and configuration locations, preserve the base required by the receiving schema and validate the fully materialized value before launch.
• Keep provider virtual paths separate from host paths. A virtual path may cross the boundary only when the provider contract explicitly defines its namespace and translation semantics on Windows.
• Resolve commands through the runtime command adapter. Do not assume a bare command, Unix executable bit, shebang, .exe, .cmd, .ps1, PATH layout, or shell quoting behaves identically across platforms.
• Prefer argv-based process launch. Do not add sh -c, cmd /c, or PowerShell string construction without an owning adapter and focused quoting tests.
• Cover platform-sensitive changes with POSIX and Windows cases. Tests must exercise the receiving schema, parser, command resolver, or process boundary; asserting only the emitted map or JSON string is not sufficient.

When a real Windows boundary cannot run in the local environment, add the closest deterministic contract test, ensure the applicable Windows CI lane owns the scenario, and state the remaining verification gap in the change summary.