@with-logic/elwood 0.2.0 → 0.2.2

package/prd/12-e2e.md

@@ -17,6 +17,87 @@ CLIs, it is intentionally separate from `npm run check`. E2E coverage should be
 reported separately and made as high as practical; unit/conformance tests remain
 responsible for hard-to-force error paths and 100% default coverage.
 
+Neither gate may write the developer's own Codex home or read its state; the e2e
+suite only copies its `auth.json`. By default, every `test:e2e` process runs with
+`CODEX_HOME` pointed at a private directory seeded with only a 0600 copy of that file,
+removed when the process exits. A single e2e file run on its own gets the same default.
+A test that needs its own Codex config uses another private home, seeded the same way,
+for its duration. Whichever private home is active receives the project trust entries,
+model selections, sessions, and logs Codex persists while the suite drives it, so none
+of them reach the developer's config. The default gate runs each test file with `HOME`
+and `CODEX_HOME` pointed at a private directory. Both gates refuse to create these
+homes when the temp directory is inside the developer's Codex home.
+
+The e2e suite may not write the developer's own Claude config either. By default,
+every `test:e2e` process, and a single e2e file run on its own, runs Claude with
+`CLAUDE_CONFIG_DIR` pointed at a private directory, removed when the process exits.
+It is seeded with three copies: a 0600 `.credentials.json` holding the developer's
+Claude login without its refresh token, so the copy can never rotate and so
+invalidate the developer's own login. The login is read from where the developer's
+own Claude reads it. On macOS that is the keychain item Claude names for the developer's
+`CLAUDE_SECURESTORAGE_CONFIG_DIR` when it is set, else for their `CLAUDE_CONFIG_DIR`,
+set or not, and their `.credentials.json` only when there is no such item. On other
+platforms it is the `.credentials.json`. The suite removes
+`CLAUDE_SECURESTORAGE_CONFIG_DIR` from its own environment, so the Claude it runs
+reads the private copy, never the developer's item. The second copy is the developer's
+global config without its per-project entries, MCP servers, or bypass-permissions
+acceptance, and the third is Claude's cached model catalog. The global-config
+entry Claude writes for each scratch project, its transcripts, and its history land
+there, never in the developer's `~/.claude.json` or `~/.claude/`, which are only read.
+The private directory holds none of the developer's settings, so the suite runs Claude
+with Claude's defaults rather than the developer's permission mode, hooks, or plugins.
+The suite refuses to create it when the temp directory is inside the developer's Claude
+config dir.
+Each such process also points `CLAUDE_CODE_TMPDIR`, Claude's temp root, at a second
+private directory, removed when the process exits. Claude otherwise keeps its temp files
+under the shared `/tmp`: a directory per working directory, holding each session's
+scratchpad, which outlives the session, and its messaging socket. So no scratch project
+leaves a directory there. The suite keeps that variable when it drops the other
+`CLAUDE_CODE_` variables a parent Claude session set.
+A test that needs its own Claude config dir copies the login the same way, without the
+refresh token.
+
+Both CLIs start through the developer's login shell, whose startup files run after
+Elwood hands over its environment and could replace, unset, or unexport `CODEX_HOME`,
+`CLAUDE_CONFIG_DIR`, or `CLAUDE_CODE_TMPDIR`. So the suite registers each private CLI home
+and Claude temp root it creates in
+`ELWOOD_E2E_PRIVATE_HOMES`, a JSON array of absolute paths holding each home's given and
+real path, which the Elwood processes it starts inherit. Each e2e process discards the
+list it inherited and registers only the homes it creates, so an inherited entry, such as
+the developer's own home, is never accepted. Each of these variables that
+Elwood's own environment sets to a registered home is guarded. Every login shell Elwood
+starts, for a session or a probe, checks after its startup files that each guarded
+variable is still exported and that the real path of the directory it names, relative
+names resolved against the shell's working directory, is a registered home. If one is
+not, the shell writes a stop line with why and exits 97 before running its command, so
+no CLI starts against another home, the developer's own included. A value that is not
+such an array stops every launch the same way. Unset or empty, as outside the suite, the
+variable changes nothing.
+
+The stop line starts with a token Elwood draws once per process, so neither a startup
+file nor a command can print it. It is never written to stderr, which a startup file can
+redirect. A session's shell writes it to its terminal, which the session's PTY captures
+however the startup files redirected the shell's input and output, and falls back to
+stdout only when it cannot open the terminal. A probe's shell runs in a session of its
+own, with no terminal, so it writes the line where it wrote its start line (§9.2): on the
+probe's private channel, which a startup file's redirection of stdout cannot hide, or, from
+a shell that closed that channel at startup, on stdout. In that shell, a startup file that
+hid stdout hid the start line too, so the probe is the login shell's own failure.
+Elwood counts a launch as stopped by the guard only when its shell exited 97 and wrote
+that line. A command that itself exits 97 is the command's own failure. A session's
+startup check (§9.1) finds the line however much startup output came before it. Since a
+PTY's last output can arrive after its exit (§9.4), once the check sees a status-97 exit
+of a launch the guard checks, it waits up to one second more for the line; a launch the
+guard does not check fails at once.
+
+A probe runs the check after its start line (§9.2). A probe the guard stops after that
+line is a login-shell failure (C-PERF-05) whose only diagnostic is the guard's fixed
+reason: like any login-shell failure, its stderr is withheld. A login shell that exits
+before the start line is still the login shell's own failure. A session whose login
+shell the guard stops during startup (§9.1) fails with the adapter's `*_start_failed`,
+whose message names the guard instead of repeating the shell's output. A session stopped
+later exits with status 97, its terminal showing the stop line and the guard's reason.
+
 The repository should also provide `npm run check:all`, an opt-in convenience
 gate that runs the default `npm run check` gate and then `npm run test:e2e`.
 `check:all` does not change the composition of `npm run check`; the default gate

package/prd/12a-cli.md

@@ -28,7 +28,13 @@ A new session defaults to the invocation directory; `-C`/`--cwd` overrides it.
 When no flag, environment variable, or configuration key selects an agent, a
 new session auto-detects one: Elwood tries `claude` first, then `codex`, and
 uses the first whose command resolves in the user's login shell — the same
-resolution the agent launch itself uses (§4.2) — without running either agent.
+resolution the agent launch itself uses (§4.2), from the effective workspace — without
+running either agent.
+Before this unselected new-session auto-detection, including `config effective`,
+Elwood MUST validate the effective workspace under §12A.5, whether it comes from
+`--cwd` or the invocation directory. A workspace usage error takes precedence over
+`no_agent_found` or a probe failure. Explicit-agent and resume validation order is
+unchanged; resume never probes.
 Both probes run concurrently; the order only decides the winner. The resolved
 agent reports the source `auto-detected`. When neither command resolves, the
 invocation fails before any launch with the stable code `no_agent_found` and
@@ -106,12 +112,27 @@ setup turn and discards that turn's response before observing the user turn. It
 is a real agent turn: tools and other side effects performed during persona setup
 remain even though its assistant response is omitted from CLI output. Explicit
 persona plus resume is a usage error. An agent process exit before
-CLI-requested cleanup is `agent_exited`, including a zero-status exit. Response
-data already collected remains available on later failure.
+CLI-requested cleanup is `agent_exited`, including a zero-status exit. A Claude or Codex
+turn the agent rejects (§5.8), including the persona setup turn, is `turn_failed`
+rather than a successful result. Response data already collected remains
+available on later failure.
 
 Cleanup runs exactly once. A cleanup failure never masks a primary usage,
 agent, timeout, or interruption outcome, and it changes an otherwise successful
-invocation to failure.
+invocation to failure. Its diagnostic names only the typed Elwood failures behind
+it. Each always appears as its error code, followed by its errno token and then
+`reap` and its reap's errno token (§10 `termination_failed`) when those are valid
+errno names, then `process groups` and the ids in its
+`unconfirmedProcessGroupIds` (positive integers, at most 16) when it has any: for
+example `Cleanup failed (termination_failed EPERM).`, `Cleanup failed
+(termination_failed reap EPERM).`, or `Cleanup failed (termination_failed EAGAIN
+process groups 4242 4243).` Those ids are for diagnosis only and may already
+belong to other groups. For a failed teardown those are its failed
+steps', in order (§10 `teardown_failed`). The diagnostic never carries their
+messages or paths, and a failure with no typed cause reads `Cleanup failed.` In
+text mode, a cleanup failure behind a different primary failure is its own stderr
+line after the primary error's; a combined `models` listing (§12A.10) prefixes it
+with the agent, as it does that agent's error.
 
 ### 12A.3 Output protocols
 
@@ -213,13 +234,18 @@ symlinks, non-regular files, wrong ownership, and non-private permissions.
 CLI-owned state defaults to `$XDG_STATE_HOME/elwood` when that base is absolute,
 otherwise `~/.local/state/elwood`. It never defaults to the invocation
 workspace. CLI state directories and records MUST be private, owner-matched,
-regular where applicable, symlink-safe, and atomically written. One session
+regular where applicable, symlink-safe, and atomically written. A new session's
+state root is made only while its workspace exists, and one at or under the
+workspace only below it (§8.1, C-STATE-14). A workspace removed after it was
+validated fails the launch with the adapter's `*_start_failed` (C-API-61)
+instead of being recreated. One session
 identity supports at most one live owner; concurrent exact resumes may fail on
 the adapter's underlying startup conflict in v1.
 
-Exit status is 0 for success or consumer closure, 1 for agent or cleanup
-failure, 2 for usage or configuration failure, 124 for timeout, and 130 for
-interruption. A primary nonzero status survives cleanup failure. Text errors are
+Exit status is 0 for success or consumer closure, 1 for agent failure
+(including `agent_exited` and `turn_failed`) or cleanup failure, 2 for usage
+or configuration failure, 124 for timeout, and 130 for interruption. A primary
+nonzero status survives cleanup failure. Text errors are
 concise and go to stderr while structured protocols retain stable error codes.
 Unknown long options identify the token and suggest the nearest documented
 option when the match is unambiguous. Validation messages identify relevant
@@ -229,6 +255,29 @@ include sanitized event detail but never weakens §12A.3. Static arguments, envi
 compatibility MUST be validated before session creation whenever validation
 does not require a stored resume record.
 
+The effective workspace, new or resumed, MUST be an absolute, existing directory
+owned by the current user that no other user can replace before the agent
+launches in it. An OS directory-search permission check MUST also confirm the
+current user can enter it; refusal is a path-specific `invalid_arguments` usage
+error. This is a bounded check, not an atomic launch guarantee.
+Resolving its path as given, name by name and through every
+symlink, every directory a name is looked up in MUST be owned by root or the
+current user and MUST NOT be writable by group or others unless it is sticky,
+and every directory and symlink passed MUST be owned by root or the current
+user. A group-writable directory is accepted when its group is the user's
+private group: the user's primary group, with the same number as the user, as
+Debian, Ubuntu, and Fedora create it. Root's group 0 is a shared system group and
+never counts as private, even for root. Anything else is a usage error that names
+the directory or link and how to fix it. The replacement check reads owners and mode bits
+only: an ACL that grants another user write access, or another member added to
+the user's private group, is not detected, and where the platform reports no user
+id neither the ownership nor this check applies. The path is launched and
+stored as given. A link whose target is not UTF-8, or a path that follows more
+than 40 links, fails as uninspectable, naming the link.
+Workspaces under `/tmp` and the macOS temporary directories pass, those being
+sticky or the user's own; `/tmp` itself, owned by root, fails the ownership
+rule for every user but root.
+
 ### 12A.6 Same-terminal head mode
 
 `--head` is an opt-in, view-only terminal mirror for a run. It requires both a
@@ -402,7 +451,12 @@ Listing sessions resolves only state-directory and output settings. Adapter,
 model, permission, trust, and turn-lifecycle environment defaults are irrelevant
 and MUST NOT prevent listing. Config files still undergo strict schema decoding.
 Interactive foreground launches MUST resolve the executable in the same
-interactive login-shell environment used by auto-detection. If the shell exits
+interactive login-shell environment and effective workspace used by auto-detection, through the same
+bounded probe, so the user's startup files get the login shell's launch bound and
+the lookup the command bound (§9.2, C-PERF-05). The frame carries the login
+shell's own `$PATH`, printed by `/bin/sh`, which loads no startup file, so a
+`printf` function or alias in the user's startup files cannot print another
+PATH in its place. If the shell exits
 successfully without returning a complete PATH probe frame, the foreground
 launch MUST preserve the inherited PATH. A complete frame containing an empty
 PATH remains authoritative. C-CLI-24/25.