Skip to content

feat(cli): agent run reads the scope token from a descriptor or a private file - #155

Merged
harshsaver merged 3 commits into
october-dev:mainfrom
omsherikar:agent-run-scope-token-fd
Nov 13, 2026
Merged

harshsaver merged 3 commits into
october-dev:mainfrom
omsherikar:agent-run-scope-token-fd

Conversation

@omsherikar

Copy link
Copy Markdown
Contributor

Refs #154.

Summary

october-bus agent run gains two ways to receive the scope token without it ever being in the launcher's environment:

  • --scope-token-fd <n> (Unix): reads the token from an inherited descriptor (3 or more, typically the read end of a pipe), up to the first newline or end of file. It closes the descriptor before the managed command starts.
  • --scope-token-file <path>: reads the token once from an owner-only regular file. It uses the same checks as the existing mcp stdio --scope-token-file.

--scope-token-env and the default OCTOBER_BUS_SCOPE_TOKEN behave exactly as before.

Motivation

A launcher that holds a scope token today has two routes:

  • agent run --scope <id>. This requires local discovery and the protected scope cache, and it refuses --address.
  • An environment variable. This is the only route for a launcher that holds the token itself, such as an operator or host app with its own daemon, an explicit address, or a scope it created through the API.

The environment is a poor place for a secret that lives as long as the agent:

  • Removing it after start does not help. agent run already strips the variable from its child. But the operating system keeps reporting the environment the launcher was started with for the launcher's whole life: /proc/<pid>/environ on Linux, KERN_PROCARGS2 on macOS. Neither Go's os.Unsetenv nor libc's unsetenv changes that record.
  • It reaches further than files or memory. It is often readable by same-user processes that cannot read the launcher's files or memory. On macOS, a process confined by a Seatbelt profile that denies the bus folders can still read another process's KERN_PROCARGS2. No sandbox rule stops it for a same-user process with a readable record (measured).
  • It leaks by accident. Environments end up in diagnostics, crash reports and ps eww output.

October Bus already keeps tokens out of process arguments, and the threat model asks hosts not to place scope credentials where they spread. This closes the matching gap for the environment on the launcher that holds the most authority. The managed child receives only its execution-bound agent token, as before.

Threat

Before After
A same-user reader of the agent run process's launch record sees OCTOBER_BUS_SCOPE_TOKEN (or the --scope-token-env variable) for as long as the agent runs. That is scope authority: it can register agents, link peers and resolve escalations. With --scope-token-fd the token is never in the launcher's environment, arguments or on disk. With --scope-token-file it is in a private file the launcher's caller controls.

Not addressed here, and unchanged:

  • The agent token in the managed child's environment. It is execution-bound. Handing it off without the environment could reuse the existing managed connection file, but that is a larger, opt-in change, so it is better discussed in an issue first (see "Follow-up").
  • Same-user process memory. As the threat model already says, October Bus is not a sandbox against the local user account.

Design

  • One source of scope authority. --scope, --scope-token-file and --scope-token-fd are mutually exclusive.
    • The file and fd forms also refuse to run while the --scope-token-env variable is set. That mirrors --scope's existing refusal of mixed authority, and it surfaces a token still being exported by mistake.
    • The descriptor is not read when a launch is refused.
  • --scope-token-fd
    • It refuses descriptors 0 to 2, which are the managed command's standard streams, and it is refused on Windows.
    • It reads at most 128 bytes, ending at the first newline or at end of file. A writer therefore never has to close its end, and a write end that leaked to another process cannot hang the launcher. Anything after the newline is ignored.
    • The descriptor is closed on success and on failure, before the command starts. Callers normally leave it inheritable, so this is what keeps it from reaching the agent.
  • --scope-token-file
    • The path must be a regular file, not a symlink. It must have no group or other permission bits on Unix and be at most 128 bytes.
    • After opening, the file must still be the one that was inspected, which refuses a swap between the check and the open.
  • Validation.
    • Both forms accept only the canonical 32-byte unpadded base64url form that every authority mints, which is the existing validExecutionToken check. The canonical check also refuses a value with a line break inside it, which base64.RawURLEncoding would otherwise skip over.
    • Error messages name the source, never the content.
  • Address resolution is unchanged: --address, then OCTOBER_BUS_ADDRESS, then local discovery.
  • The child environment is unchanged. --scope-token-env, OCTOBER_BUS_SCOPE_TOKEN and OCTOBER_BUS_ADMIN_TOKEN are still stripped, and the child still gets OCTOBER_BUS_ADDRESS, _MCP_URL, _AGENT_ID, _EXECUTION_ID and _AGENT_TOKEN.
  • One file reader for both commands. remoteScopeClient (mcp stdio --remote --scope-token-file) now uses the same reader as agent run, so the two cannot drift apart.

Example, with nothing in the environment, arguments or on disk:

october-bus agent run --id worker --name Worker --address "$ADDR" --scope-token-fd 3 -- claude 3< <(token-source)

From a program: create a pipe, map its read end to descriptor 3 in the child, write the token and a newline, then close the write end.

Compatibility

  • No protocol, schema or storage change. --scope-token-env, its default and --scope behave as before.
  • The error for a missing scope source now lists the new flags: use --scope <local-scope-id>, --scope-token-file, --scope-token-fd, or provide OCTOBER_BUS_SCOPE_TOKEN.
  • mcp stdio --remote --scope-token-file gets two stricter checks: it refuses a token file swapped between the check and the open, and it refuses a non-canonical token, for example one with an embedded line break. Every token the runtime mints (randomValue(32)) is canonical, so valid files are unaffected.

Tests

New tests:

File Tests
cmd/october-bus/scope_token_test.go (all OSes) TestReadScopeTokenFileRequiresPrivateRegularFile: empty, malformed, embedded line break, oversized, missing, a directory, group- or world-readable, and a symlink are all refused, and no error contains the token.
TestAgentRunReadsScopeTokenFromPrivateFile: registers and retires through a file token. The managed child has no privileged variable and no variable containing the token (the child is given only its SHA-256). It refuses --scope together with a file, an exported token beside a file, and a shared file.
cmd/october-bus/scope_token_unix_test.go TestAgentRunReadsScopeTokenFromDescriptor: registers and retires through a pipe token. The managed child did not inherit the descriptor (checked by device and inode, not just number), and agent run closed its own copy.
TestAgentRunRefusesMixedScopeTokenSources: covers every combination. A refused launch leaves the descriptor unread.
TestReadScopeTokenFDBoundsAndCloses: descriptors 0 to 2 are refused and stdin stays open. Empty, malformed and oversized input is refused and the descriptor is closed. A newline-terminated token is returned without waiting for end of file.
cmd/october-bus/scope_token_launch_test.go (Linux and macOS) TestAgentRunLaunchRecordHoldsNoDescriptorScopeToken reads the real launch record of a separate agent run process, from /proc/<pid>/{cmdline,environ} or KERN_PROCARGS2, while its command runs. The control is an environment-launched agent run, whose record does show the token, so the check is known to read something. The --scope-token-fd launch's record does not.

Two small helpers read the launch record on each OS: launch_record_darwin_test.go and launch_record_linux_test.go.

Results on macOS 26 (arm64), Go 1.27.0, with every bus folder, HOME and TMPDIR redirected to a scratch directory:

  • go vet ./... passes, and so does GOOS=linux and GOOS=windows go vet ./cmd/october-bus/.
  • go test -race -count=1 ./... passes in all 10 packages; cmd/october-bus takes 67s.
  • The test binaries cross-compile for linux and windows on amd64 and arm64.
  • Mutation checks. Not closing the descriptor fails TestScopeTokenFDChild ("inherited") and TestReadScopeTokenFDBoundsAndCloses ("left open"). Leaking the token into the child under another variable name fails the child audit in both the file and descriptor tests.
  • CLI smoke with the built binary against a scratch daemon. With the token in the environment, the agent run record shows it. With --scope-token-fd 3 it does not, the agent registers and retires, and the daemon stops cleanly.
  • Not run here: the Linux and Windows test runs themselves (CI covers them).

Docs

  • adapters/README.md: under "Existing managed launchers", a paragraph on the two flags.
  • docs/threat-model.md: the credential-disclosure row, plus a paragraph on why the environment is a wider disclosure channel than it looks.

Proposed release note

There is no CHANGELOG file, so this is a line for the next release notes:

agent run accepts the scope token from an inherited descriptor (--scope-token-fd, Unix) or an owner-only file (--scope-token-file), so launchers no longer have to export it. --scope-token-env is unchanged.

Follow-up (not in this PR)

The execution token without the environment. The managed child still receives OCTOBER_BUS_AGENT_TOKEN in its environment, so its launch record exposes that execution's authority. The bridge can already read a managed connection file (mcp stdio --connection-file, OCTOBER_BUS_CONNECTION_FILE).

An opt-in agent run --connection-dir <private-dir> could:

  • write that version-1 file (endpoint, scopeId, agentId, executionId, agentToken, expiresAt) into an owner-only directory;
  • export only OCTOBER_BUS_CONNECTION_FILE instead of OCTOBER_BUS_ADDRESS and OCTOBER_BUS_AGENT_TOKEN;
  • renew expiresAt on each heartbeat;
  • remove the file when the session ends.

It changes what the child sees, which matters to children that read OCTOBER_BUS_AGENT_TOKEN directly or run message receipt, so it deserves an issue first.

🤖 Generated with Claude Code

https://claude.ai/code/session_015f6iGxVJzudUSNWEjQvemb

…vate file

agent run could only receive a scope token it was handed through an
environment variable, and the OS keeps reporting a process's starting
environment for its whole life (/proc/<pid>/environ, KERN_PROCARGS2),
where same-user processes can often read it even when they can't read
the launcher's files or memory.

Add --scope-token-fd (Unix: read from an inherited descriptor, up to a
newline or EOF, 128 bytes at most, closed before the command starts) and
--scope-token-file (one read of an owner-only regular file, not a
symlink, still the inspected file after open). They are exclusive with
--scope and with an exported --scope-token-env variable; the existing
routes and the child environment are unchanged. mcp stdio --remote
--scope-token-file shares the same reader.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015f6iGxVJzudUSNWEjQvemb
Copilot AI balanced review requested due to automatic review settings October 20, 2026 11:19

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

@harshsaver harshsaver left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Agentbox PR audit: changes requested

What needs to change

Please apply the fix plan above.

n/a

What this PR changes

  • What it does: Lets a launching tool supply the scope credential through a pipe on Unix or a private file, keeping it out of the agent launcher's starting environment. The pipe is closed before the agent's command starts.
  • What changes in the product: Nothing visible for existing users unless they choose the new options. Missing-credential errors list the new choices, and the remote bridge checks credential files more carefully.
  • Why it exists: A process's starting environment can remain readable to other programs even after it removes a variable. These alternatives reduce exposure of a credential that can register agents, connect peers and resolve escalations.
  • Why merge (or why not yet): The implementation is small and shares existing validation. One invalid descriptor value is silently ignored, allowing a launch with another credential source. The proposed fix addresses that without changing normal launches.
  • What to expect after merging: Launching tools can adopt either option without protocol changes. Windows operators remain responsible for restricting access to credential files. The child's own agent credential still travels through its environment; changing that remains separate work. Harsh may also want to decide separately whether the environment route for agent run should be retired now that the threat model discourages it.
Full audit (Claude (fable, xhigh) × Codex (gpt-6-astra, xhigh), 5 turns, commit 8e6f2f7)

PR audit: #155 — feat(cli): agent run reads the scope token from a descriptor or a private file

Head: 8e6f2f7

Sign-off

  • Claude (fable, xhigh): ✅ satisfied — blocking finding, fix plan and Codex's corrected before/after test table all verified against the code and Go 1.27 source; decision fix stands with no further changes.
  • Codex (gpt-6-astra, xhigh): ❌ not satisfied — the implementation fix is sound, but its required before/after test results were incorrect; the corrected validation plan needs re-checking.

Decision

fix — distinguish an explicitly supplied --scope-token-fd from its default so an invalid value is refused instead of silently falling back to another credential source; no additional blocking code defects found.

What changes (plain language)

  • What it does: Lets a launching tool supply the scope credential through a pipe on Unix or a private file, keeping it out of the agent launcher's starting environment. The pipe is closed before the agent's command starts.
  • What changes in the product: Nothing visible for existing users unless they choose the new options. Missing-credential errors list the new choices, and the remote bridge checks credential files more carefully.
  • Why it exists: A process's starting environment can remain readable to other programs even after it removes a variable. These alternatives reduce exposure of a credential that can register agents, connect peers and resolve escalations.
  • Why merge (or why not yet): The implementation is small and shares existing validation. One invalid descriptor value is silently ignored, allowing a launch with another credential source. The proposed fix addresses that without changing normal launches.
  • What to expect after merging: Launching tools can adopt either option without protocol changes. Windows operators remain responsible for restricting access to credential files. The child's own agent credential still travels through its environment; changing that remains separate work. Harsh may also want to decide separately whether the environment route for agent run should be retired now that the threat model discourages it.

Findings

Blocking

  • An explicit --scope-token-fd=-1 (or --scope-token-fd -1) is treated as “flag not given” and silently falls back to another credential source. cmd/october-bus/main.go:881 uses -1 as the default, and main.go:904, main.go:912 and main.go:931 infer presence by comparing the value with that default. Go's flag parser accepts both spellings: for -flag value it consumes the next argument even when it starts with a dash (Go 1.27 src/flag/flag.go:1130-1134), and -1 parses as an integer. With OCTOBER_BUS_SCOPE_TOKEN exported, the invocation skips descriptor validation and the mixed-environment refusal, then launches using the environment token (main.go:958, main.go:989). Combined with --scope or --scope-token-file, the descriptor flag is silently ignored instead of producing the mixed-source error. With no other source, the user receives a missing-source error despite supplying the descriptor flag. This is a contract and misconfiguration-hiding defect, not privilege escalation: it uses authority already available to the launcher. It contradicts the advertised exclusivity (adapters/README.md:57) and descriptor minimum (cmd/october-bus/scope_token.go:82). The existing negative-descriptor test calls the reader directly (scope_token_unix_test.go:134), bypassing the faulty CLI selection. Record presence with flags.Visit, following cmd/october-bus-conformance/main.go:73-78.

Non-blocking

  • CI is awaiting maintainer approval. The status rollup is empty, and workflow run 39414106980 states "This workflow is awaiting approval from a maintainer in #155" with status "Action required" (independently confirmed by both auditors). Harsh should approve the workflow for the final revision and require the configured checks to pass, including the ubuntu/macos/windows runtime matrix and the ubuntu race run (.github/workflows/ci.yml:18, ci.yml:26-29). The author reports macOS execution and Linux/Windows cross-compilation and vet checks, not Linux/Windows test execution. Workflow run

  • Windows file privacy is an operator responsibility. cmd/october-bus/scope_token.go:35 skips Unix permission checks on Windows and does not inspect Windows access-control lists, matching the previous remote-file behavior. The supplied path need not be in the user's profile. docs/threat-model.md:46 documents the limitation; main.go:880 and adapters/README.md:57 would be clearer with the same qualification.

  • Flag help omits the Unix-only qualification. cmd/october-bus/main.go:881 and the usage at main.go:44 do not identify the descriptor option as Unix-only. adapters/README.md:57 does, and cmd/october-bus/scope_token.go:78 provides a clear Windows error. Cosmetic.

  • An explicit empty --scope-token-file= is treated as unset. cmd/october-bus/main.go:904 and main.go:925 follow the CLI's existing empty-string convention for options such as --scope. Empty paths can arise accidentally, including through empty variable expansion. With the environment credential unset (the normal state for a file-route launcher) the result is the missing-source error, which names the file option. This audit retains the existing string-option convention rather than expanding the descriptor fix into a broader CLI behavior change.

  • Descriptor reads require a newline or EOF. cmd/october-bus/scope_token.go:90 can wait indefinitely when a writer sends a token without a newline and keeps the pipe open. This follows the documented framing contract (adapters/README.md:57); the caller should write a newline or close its end. A timeout is not required for this change.

  • The environment route remains available. cmd/october-bus/main.go:879 retains it while docs/threat-model.md:44 recommends the alternatives. Issue #154 proposes retaining it, and other commands still use environment credentials (main.go:555, main.go:617). That is not universal: local linking already reads the saved credential (cmd/october-bus/admin_operations.go:143). No compatibility framework or migration was added. Retiring the environment route can be considered separately.

  • Inherited agent authority is handled differently from local-scope mode. cmd/october-bus/main.go:917 rejects an inherited agent token with --scope; the file and descriptor branches do not, mirroring the environment route. main.go:987 replaces that token in the child's environment. No new credential-selection defect was found here.

  • Remote-bridge validation is stricter, but replacement protection is platform-dependent. cmd/october-bus/remote_scope.go:23 shares the bounded reader and canonical validator at cmd/october-bus/mcp_connection.go:85. Minted scope credentials already satisfy it (bus/store.go:152, bus/store.go:208, bus/scope_admin.go:34). The comparison at scope_token.go:58 catches replacement between inspection and opening on Unix; it does not freeze file contents during reading. On Windows, Go 1.27's ordinary Lstat fast path saves the pathname and loads the file identity only when SameFile runs (os/stat_windows.go:34-47, os/types_windows.go:287, os/types_windows.go:353), so a swap between inspection and opening is not detected there. This does not undo the environment-disclosure improvement or regress the previous Windows reader; trusted storage remains necessary.

  • Tests are substantial but not exhaustive. Besides the blocking CLI gap, there is no explicit successful EOF-without-newline descriptor case, Windows CLI descriptor-rejection test, or deterministic replacement-race test (cmd/october-bus/scope_token_test.go:50, scope_token_unix_test.go:132). None independently blocks the change.

  • The launch-record test reports early failures slowly. cmd/october-bus/scope_token_launch_test.go:93 polls until registration or the 30-second deadline without checking whether the wrapper has exited, then reports stderr at scope_token_launch_test.go:103. The control launch skips the test when the OS refuses the launch-record probe (scope_token_launch_test.go:108). This is a diagnostics limitation.

Fix plan

The implementation and test edits below are unchanged since turn 3; the expected results and validation instructions were corrected in turn 4 and verified in turn 5. Approximately 15 changed lines, comfortably below 50. maintainerCanModify is confirmed true; no edits were applied during the audit.

  1. cmd/october-bus/main.go — insert after the flags.Parse error check, before commandArgs := flags.Args():

    // flag.Visit tells an explicit --scope-token-fd apart from its default, so
    // an invalid number such as -1 is refused rather than silently routed to
    // another credential source.
    scopeTokenFDSet := false
    flags.Visit(func(value *flag.Flag) { scopeTokenFDSet = scopeTokenFDSet || value.Name == "scope-token-fd" })

    Replace the three presence checks:

    • At line 904, use []bool{*localScope != "", *scopeTokenFile != "", scopeTokenFDSet}.
    • At line 912, use if (*scopeTokenFile != "" || scopeTokenFDSet) && scopeToken != "" {.
    • At line 931, use case scopeTokenFDSet:.

    Leave the flag default and readScopeTokenFD unchanged. The reader continues to enforce platform and range restrictions; source conflicts still fail before any descriptor is touched.

  2. cmd/october-bus/scope_token_test.go, in TestAgentRunReadsScopeTokenFromPrivateFile:

    After the mixed file/local-scope assertion at line 112, add:

    err = runAgent(args("--scope-token-file", path, "--scope-token-fd=-1"))
    require(t, err != nil && strings.Contains(err.Error(), "use only one of"), "an explicit --scope-token-fd=-1 was ignored beside a file: %v", err)

    After the environment-conflict assertion at line 115, while the environment token remains set (line 116 clears it), add:

    err = runAgent(args("--scope-token-fd=-1"))
    require(t, err != nil && strings.Contains(err.Error(), "unset OCTOBER_BUS_SCOPE_TOKEN"), "an explicit --scope-token-fd=-1 fell back to the environment token: %v", err)
  3. cmd/october-bus/scope_token_unix_test.go, append these rows to the table in TestAgentRunRefusesMixedScopeTokenSources (after line 114):

    {args: []string{"--scope-token-fd", "-1"}, want: "3 or more"},
    {args: []string{"--scope-token-fd", "0"}, want: "3 or more"},

    The preceding rows clear their environment variables at line 123. After the fix, both new cases reach the reader and return before os.NewFile, preserving stdin and the existing test pipe, so the final "descriptor unread" assertion at lines 127-129 still holds.

  4. Validate the correct before/after behavior:

    Added case Original head, when reached After the fix
    Valid file plus --scope-token-fd=-1 Uses the file and performs the normal launch; no mixed-source error “use only one of”
    Exported token plus --scope-token-fd=-1 Uses the environment token and performs the normal launch; no environment-conflict error “unset OCTOBER_BUS_SCOPE_TOKEN”
    --scope-token-fd -1, no other source Missing-source error “3 or more”
    --scope-token-fd 0, no other source Already returns “3 or more” Still returns “3 or more”

    The three -1 cases are regression assertions; the 0 case preserves existing behavior. With the tests added before the implementation change, the two affected test functions should fail on their first new -1 assertion. require calls t.Fatalf (cmd/october-bus/assert_test.go:12-17), so later assertions are not all observable in that run. After the implementation change, both test functions should pass, including all four new checks. Do not require four pre-fix failures: the descriptor-0 assertion already passes on the original head.

Message to the developer

Please apply the fix plan above.

n/a

Questions for Harsh

n/a

Verification

  • Static review only throughout the audit. No contributor code, installs, tests, builds, vet commands or repository scripts were executed. No GitHub mutations or checkout modifications were made.
  • Repository state: HEAD 8e6f2f7c1e14cf9f5144e435315a57e1174ced8e, clean working tree, clean git diff --check. The complete ten-file diff and surrounding implementation were reviewed in turns 1 and 2; later turns concentrated on the proposed edits, test fixtures and disputed claims.
  • PR context: gh pr view --json confirmed unchanged head, empty discussion comments and status rollup, REVIEW_REQUIRED, maintainerCanModify: true, isCrossRepository: true, and the Copilot quota notice. Workflow run 39414106980 reads "This workflow is awaiting approval from a maintainer in #155", status "Action required" (checked by both auditors).
  • Source-selection fix: Re-read main.go:872-960, the reader, both affected test functions (scope_token_test.go:100-122, scope_token_unix_test.go:97-130) and the flags.Visit precedent at cmd/october-bus-conformance/main.go:73-78. The proposed boolean accumulates presence correctly and replaces all three sentinel comparisons; every existing test that passes a real descriptor still counts as set.
  • Flag semantics: Go 1.27 src/flag/flag.go: integer parsing at line 163, explicit-flag enumeration (Visit) at line 470, next-argument consumption regardless of a leading dash at lines 1130-1134, and recording at line 1145. Both =-1 and space-separated -1 are parsed and recorded as supplied flags.
  • Before/after test predictions (turn 5 re-check): descriptor 0 already satisfies 0 != -1 at main.go:931, reaches readScopeTokenFD and is rejected at scope_token.go:82-84. The file and environment fixtures provide a valid address and credential, so their pre-fix -1 paths register and launch normally (the fixture at line 112 runs before the environment token is set at line 113). The standalone -1 case hits main.go:937-938 before address resolution. Static control-flow conclusions, not executed reproductions.
  • Descriptor handling: 129-byte io.LimitReader under bufio.Reader.ReadSlice('\n') returns data plus io.EOF without a delimiter and can never hit ErrBufferFull; a 129-byte line is rejected; the descriptor is closed by defer on every path before exec.Cmd.Start. os.NewFile, ReadSlice and exec.Cmd.ExtraFiles behaviour confirmed on pkg.go.dev; the test clears close-on-exec at scope_token_unix_test.go:41-43, making the closure check meaningful.
  • File handling: Lstat, private-mode check, open, fstat, os.SameFile, re-check, bounded read, canonical parse, same shape as mcp_connection.go:102-119; error strings for the permission and malformed cases unchanged. Go 1.27 Windows Lstat/SameFile implementation inspected (os/stat_windows.go:34-47, os/types_windows.go:287, os/types_windows.go:353); replacement detection before open is effectively Unix-only.
  • Library APIs and token shape: pkg.go.dev for golang.org/x/sys@v0.49.0/unix (darwin) confirms SysctlRaw(name string, args ...int) ([]byte, error), FcntlInt(fd uintptr, cmd, arg int) (int, error) and F_SETFD; golang.org/x/sys is already a direct dependency. Scope creation and rotation mint randomValue(32) credentials (32 random bytes, unpadded base64url, 43 chars); the test token at scope_token_unix_test.go:133 is canonical.
  • Tests: imports used, no shadowing errors, the os.Exit helper-process pattern matches main_test.go:24-40 and hook_test.go:312-314, child audits report presence by SHA-256 digest only, and the launch-record control proves the probe reads something before asserting absence. Linux /proc/<pid>/environ is the initial environment behind a ptrace permission check, satisfied by the parent-of-child relationship under the default Yama scope; the test skips otherwise.
  • Required final checks: apply the listed tests and implementation change, verify the before/after behavior in the fix-plan table, then approve and run the configured CI workflow on the revised head. Require the Linux, macOS and Windows runtime checks and the ubuntu race run to pass. Contributor-reported results remain independently unverified.

Audit log

  • Turn 1 (Claude (fable, xhigh)): Read PR body, issue #154, full diff and surrounding code; verified x/sys, bufio, os and exec APIs on pkg.go.dev; checked token minting shape; found no blocking issues; recorded seven non-blocking notes (CI not run on fork PR, env route kept, help-text nit, no fd timeout, agent-token consistency nit, stricter remote validation, slow test failure mode). Decision: merge.
  • Turn 2 (Codex (gpt-6-astra, xhigh)): Independently reviewed the full diff, surrounding credential and session code, tests, PR context and library behavior. Found that explicit --scope-token-fd=-1 bypasses source selection and can silently use environment authority; changed the decision to fix with a small presence-tracking change and regression tests. Qualified Windows privacy, CI-gate assumptions, replacement protection and test-coverage claims. No contributor code executed.
  • Turn 3 (Claude (fable, xhigh)): Re-verified the blocking finding against main.go:904/912/931 and Go 1.27 flag.go:1130-1134, 1145, 470-474 (both --scope-token-fd -1 and =-1 parse and count as set for Visit); confirmed the Visit precedent at cmd/october-bus-conformance/main.go:73-78 and that maintainers can push to the fork branch; agreed with fix and rewrote the fix plan as exact edits (about 12 lines, four new assertions); refined the blocking impact wording (launcher's own token, misconfiguration hidden, not escalation); updated the CI note with the checks-page evidence; added the --scope-token-file= convention note; corrected two launch-test line references.
  • Turn 4 (Codex (gpt-6-astra, xhigh)): Verified the exact implementation and test edits; retained the blocking finding and fix decision. Corrected the fix plan's validation requirements: descriptor 0 already passes, the file/environment -1 cases launch normally before the fix, and fatal assertions prevent observing every case in one failing run. Confirmed workflow approval is pending; qualified Windows replacement protection and corrected unsupported claims about accidental empty paths and universal environment-token use. No contributor code executed.
  • Turn 5 (Claude (fable, xhigh)): Verified every turn-4 correction: the before/after table against main.go:904-938 and the fixtures at scope_token_test.go:111-116; require as t.Fatalf at assert_test.go:12-17; Windows Lstat/SameFile lazy file-ID loading in Go 1.27 source; workflow run 39414106980 awaiting maintainer approval; link using the saved local credential at admin_operations.go:143. Accepted all of them; no changes to the decision, blocking finding or fix plan; tightened wording in the CI, empty-path and Windows notes and the fix-plan line references.

Automated review by Harsh's agentbox: two AI reviewers audited this PR against the project ruleset and agreed on it.

Carry the scope-token file/descriptor launch path across the
october-bus -> agentintercom rename, including the review fix that tracks
--scope-token-fd presence with flag.Visit so an explicit invalid value is
refused instead of silently falling back to another credential source.
@harshsaver

Copy link
Copy Markdown
Member

Applied the review fix on this branch: agent run now tracks --scope-token-fd presence with flag.Visit, so an explicit invalid value like -1 is refused instead of silently falling back to another credential source, with four new regression assertions (verified they fail without the fix). Also merged current main across the october-bus to agentintercom rename, carrying the file/descriptor launch path, its tests, and the docs additions forward. gofmt, go vet, and the full cmd/agentintercom race suite pass on the merged tree. Ready for re-review; CI still needs a maintainer approval run for this fork.

@harshsaver harshsaver added the agentbox: ready to merge Audited by Claude and Codex; Harsh can merge label Nov 13, 2026
@harshsaver
harshsaver dismissed their stale review November 13, 2026 04:14

Resolved: the audit of b8368ea found the requested changes in place.

@harshsaver

Copy link
Copy Markdown
Member

🤖 Agentbox PR audit: ready to merge

What this PR changes

  • What it does: Lets a launching tool supply the scope credential through a pipe on Unix or a private file, keeping it out of the agent launcher's starting environment. The pipe is closed before the agent's command starts.
  • What changes in the product: Nothing visible for existing users unless they choose the new options. Missing-credential errors list the new choices, and the remote bridge checks credential files more carefully.
  • Why it exists: A process's starting environment can remain readable to other programs after startup. These alternatives reduce exposure of a credential that can register agents, connect peers and answer escalations.
  • Why merge (or why not yet): The implementation shares existing validation and removes duplicated file-reading code. The invalid-descriptor fallback found last round is fixed and covered by tests. CI approval, passing checks and resolution of the earlier review remain outstanding.
  • What to expect after merging: Launching tools can adopt either option without protocol changes. Windows operators remain responsible for restricting access to credential files. The child's own agent credential still travels through its environment; changing that and retiring the existing environment route are separate decisions.
Full audit (Claude (fable, xhigh) × Codex (gpt-6-astra, xhigh), 2 turns, commit b8368ea)

PR audit: #155 — feat(cli): agent run reads the scope token from a descriptor or a private file

Head: b8368ea

Sign-off

  • Claude (fable, xhigh): ✅ satisfied — the previous round's fix is applied exactly as planned, the merge across the october-bus to agentintercom rename carries the change cleanly, and no blocking findings remain; CI still needs approval and a green run.
  • Codex (gpt-6-astra, xhigh): ✅ satisfied — independently verified the descriptor fix, regression assertions and rename integration on this head; no additional blockers found.

Decision

merge — the previous blocking defect is fixed and the merge preserves credential handling; merge once the configured checks pass and the earlier changes-requested review is cleared or superseded.

What changes (plain language)

  • What it does: Lets a launching tool supply the scope credential through a pipe on Unix or a private file, keeping it out of the agent launcher's starting environment. The pipe is closed before the agent's command starts.
  • What changes in the product: Nothing visible for existing users unless they choose the new options. Missing-credential errors list the new choices, and the remote bridge checks credential files more carefully.
  • Why it exists: A process's starting environment can remain readable to other programs after startup. These alternatives reduce exposure of a credential that can register agents, connect peers and answer escalations.
  • Why merge (or why not yet): The implementation shares existing validation and removes duplicated file-reading code. The invalid-descriptor fallback found last round is fixed and covered by tests. CI approval, passing checks and resolution of the earlier review remain outstanding.
  • What to expect after merging: Launching tools can adopt either option without protocol changes. Windows operators remain responsible for restricting access to credential files. The child's own agent credential still travels through its environment; changing that and retiring the existing environment route are separate decisions.

Findings

Blocking

  • None. The previous defect—explicit --scope-token-fd=-1 being treated as omitted—is resolved. Presence is recorded with flags.Visit at cmd/agentintercom/main.go:940 and used in source counting, environment-conflict checking and source selection (main.go:955, main.go:963, main.go:982). The agreed assertions are present at cmd/agentintercom/scope_token_test.go:113, scope_token_test.go:118 and cmd/agentintercom/scope_token_unix_test.go:115. Both auditors verified the implementation against the previous fix plan.

Non-blocking

  • CI awaits approval, and the earlier review still blocks merging. Workflow run 43328433093 for this revision explicitly awaits maintainer approval and has no completed job results. The PR reports an empty status rollup, CHANGES_REQUESTED and BLOCKED; the changes-requested review concerns the old 8e6f2f7 revision. Harsh should approve the current workflow, require the configured checks to pass, and clear or supersede that review. The runtime matrix includes Linux, macOS and Windows, plus the ubuntu race run (.github/workflows/ci.yml:18, ci.yml:26). Workflow run

  • Windows execution remains an important verification gap. The shared reader adds an os.SameFile comparison to the remote bridge's existing file route (cmd/agentintercom/remote_scope.go:23, scope_token.go:58). The ordinary Windows path is exercised by TestRemoteScopeCredentialValidationAndRedirectRefusal at remote_scope_test.go:67 and the new file-reader test at scope_token_test.go:55. No Windows execution results for this head were available to the auditors. Passing those tests in the Windows job supplies the missing evidence; static review found no demonstrated Windows failure.

  • Windows privacy and replacement protection remain limited. cmd/agentintercom/scope_token.go:35 skips Unix permission checks on Windows and does not inspect access-control lists. The supplied path need not be in the user's profile. docs/threat-model.md:46 documents the operator's responsibility, while main.go:926 and adapters/README.md:57 describe an owner-only file without that qualification. Go 1.27's ordinary Windows Lstat implementation saves the pathname and loads file identity later during SameFile (os/stat_windows.go:41, os/types_windows.go:287, os/types_windows.go:353), so the Unix check/open replacement guarantee should not be claimed there. Neither platform's check freezes contents during the read.

  • Flag help omits the Unix-only qualification. cmd/agentintercom/main.go:927 and the usage at main.go:77 do not identify the descriptor option as Unix-only. adapters/README.md:57 does, and scope_token.go:78 returns a clear Windows error. Cosmetic.

  • An explicit empty --scope-token-file= remains equivalent to omission. cmd/agentintercom/main.go:955 and main.go:976 follow the existing empty-string convention used by --scope. An empty variable expansion can therefore select the environment route when a credential is exported. Both auditors accepted this convention last round; the approved descriptor fix does not change it. Any future change should define and test empty-file-option behavior explicitly.

  • Descriptor reads require a newline or EOF. cmd/agentintercom/scope_token.go:90 can wait indefinitely if a writer sends a token without a newline and keeps its end open. This follows the documented framing contract in adapters/README.md:57. The caller should write a newline or close its end; a timeout is not required for this change.

  • The environment route remains available. cmd/agentintercom/main.go:925 retains it while docs/threat-model.md:44 recommends the alternatives. Issue agent run: accept the scope token from a descriptor or a private file, not only the environment #154 explicitly proposes retaining it, and other commands still read environment credentials (main.go:599, main.go:661). No compatibility framework or migration was added. Its eventual removal is separate from the now-fixed explicit-descriptor fallback. Issue #154

  • Inherited agent authority is handled differently from local-scope mode. cmd/agentintercom/main.go:968 rejects an inherited agent token with --scope; the file and descriptor branches do not, matching the existing environment route. main.go:1038 replaces that token in the child. No new credential-selection defect was found.

  • Related credential readers retain different contracts. This PR shares readScopeTokenFile between the launcher and remote bridge, removing the latter's inline implementation. The cached reader at bus/local_credentials.go:109 and managed-connection reader at cmd/agentintercom/mcp_connection.go:90 remain separate. The cached reader uses a looser validator (local_credentials.go:22) and lacks the open-then-compare check, but also checks its private directories. These differences predate the PR. Further consolidation should preserve their distinct contracts rather than introduce a general abstraction solely to reduce reader count.

  • Remote-bridge token validation is intentionally stricter. The shared reader uses the canonical check at cmd/agentintercom/mcp_connection.go:85, rejecting embedded line breaks and noncanonical encodings. Scope creation and rotation mint canonical values through randomValue(32) (bus/store.go:165, bus/store.go:225, bus/scope_admin.go:34). Credentials produced by those paths remain accepted.

  • Tests are substantial but not exhaustive. There is no explicit successful EOF-without-newline descriptor test, Windows CLI descriptor-rejection test, or deterministic replacement-race test (cmd/agentintercom/scope_token_test.go:50, scope_token_unix_test.go:134). None independently blocks the change.

  • The launch-record test reports early failures slowly. cmd/agentintercom/scope_token_launch_test.go:93 polls until registration or the 30-second deadline without checking whether the wrapper has exited, then reports stderr at line 103. The control launch skips when the OS refuses the probe at line 108. This is a diagnostics limitation.

Fix plan

n/a

Message to the developer

n/a

Questions for Harsh

n/a

Verification

  • Static review only. Neither auditor executed contributor code, installs, tests, builds, vet commands or repository scripts. No GitHub mutations or tracked-file changes were made. Codex ran read-only Git checks; git diff --check passed and the working tree remained clean.
  • Current revision and scope: Confirmed HEAD b8368ea29ec07ddefe3fa8b11571568e109f1e49, with parents 8e6f2f7 and 2604d00. The latter is also the merge base. Read the complete ten-file contribution against 2604d00 (+583/−21), examined changes since the previously audited revision, and checked the affected integration points brought in from main.
  • PR discussion: The requested plain gh pr view --comments failed on the CLI's deprecated Projects Classic query; the JSON query succeeded. Read the description, new maintainer comment and review state. Harsh reports applying the fix, merging the rename, and passing gofmt, vet and the CLI race suite. Those reported executions were not reproduced by this audit. Maintainer comment
  • Regression claims: The comment calls all four additions regression assertions that fail without the fix. The code supports the more precise previous audit conclusion: three -1 assertions detect the defect; descriptor 0 already reached the reader and was rejected before the fix. This reporting distinction does not affect the implementation or merge decision.
  • Fix independently traced: Read all of runAgent at cmd/agentintercom/main.go:918. File plus explicit =-1 returns the mixed-source error at line 960; exported token plus explicit =-1 returns the environment-conflict error at line 963; standalone -1 reaches the reader and fails its range check. Omitted descriptor flags retain the old source selection. Invalid descriptors return before os.NewFile, preserving stdin and the test pipe.
  • Flag semantics: Re-read locally available Go 1.27 src/flag/flag.go, including integer parsing at line 163, FlagSet.Visit at line 470, argument consumption at line 1130 and explicit-flag recording. Both =-1 and space-separated -1 count as supplied. The existing repository precedent remains at cmd/agentintercom-conformance/main.go:73.
  • Merge integrity: The PR uses the new module path and command directory, with no leftover cmd/october-bus files. Main's expanded child-environment filtering remains intact at main.go:901 and main.go:1033, including service credentials and the Stripe prefix. OCTOBER_BUS_* remains the actual environment naming convention. Reviewed the current session-registration and remote-MCP call paths for compatibility.
  • Readers and helpers: Direct blob comparisons confirm scope_token.go and both platform launch-record helpers are unchanged from the previously reviewed revision. Re-read the shared reader, canonical validator, remote client/tests and cached reader on the current tree. The bounded reads and descriptor closure still occur before child launch. The pinned golang.org/x/sys version remains v0.49.0; no dependency was added by this PR.
  • Tests and isolation: Read the new tests and four added assertions, including environment setup/reset ordering and the final unread-descriptor assertion. Verified helper names and environment markers do not introduce a conflicting test entry point. The deliberate close-on-exec clearing remains at scope_token_unix_test.go:43; the child audit checks descriptor identity and credential absence. The launch-record control establishes that the probe can observe an environment-supplied credential before testing descriptor absence.
  • Ruleset: The change adds the requested capability without a protocol, storage or migration change; shares an existing reader; and uses the standard library plus an already-pinned dependency. No speculative framework or additional compatibility layer was introduced. No further architectural change is necessary to complete this feature.
  • Final checks: Approve and run the configured workflow on this head, particularly Windows file/remote-bridge tests, the macOS launch-record helper and the ubuntu race run. Resolve the earlier changes-requested review after those checks pass. The live workflow still awaits approval. Workflow run

Audit log

  • Turn 1 (Claude (fable, xhigh)), round 2 on head b8368ea: Re-audited from scratch after the merge of main and the rename to agentintercom. Read the new PR comment, the merge commit, the full ten-file diff against the new base, the complete current runAgent, both readers, the remote-scope client and its tests, the cached-credential reader in bus/local_credentials.go, token minting, CI config and the live workflow run. Confirmed the previous blocking finding is fixed exactly per the agreed plan with its four assertions, that the merge preserved main's newer environment stripping, and that test APIs and helper names are intact with no collisions. No blocking findings; carried the non-blocking notes forward with current line numbers and added two (Windows job as the proof for the shared reader behind the remote bridge; three remaining private-file readers as a possible follow-up). Decision: merge, gated on CI approval and a green run.
  • Turn 2 (Codex (gpt-6-astra, xhigh)), round 2 on head b8368ea: Independently read the current contribution, changes since 8e6f2f7, new maintainer comment and review state. Verified the presence-tracking fix, all four assertions, unchanged readers/helpers and preservation of main's credential filtering through the rename. Confirmed pending workflow approval. Agreed with merge; refined non-blocking wording about Windows evidence, reader consolidation and empty-file options, and distinguished three regression assertions from the already-passing descriptor-0 check. No material changes and no contributor code executed.

Final checks

Not run here: this PR is from an outside contributor, so its code is never executed on this machine. Rely on CI before merging.

Automated review by Harsh's agentbox: two AI reviewers audited this PR against the project ruleset and agreed on it.

@harshsaver harshsaver left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved after the Claude x Codex audit agreed it is ready (audited head b8368ea, current; CI green).

@harshsaver harshsaver left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved after the Claude×Codex audit agreed it is ready (audited head b8368ea; this head only adds a merge of main).

@harshsaver harshsaver left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved after the Claude×Codex audit agreed it is ready (audited head b8368ea; this head only adds a merge of main).

@harshsaver
harshsaver merged commit 93c1cd7 into october-dev:main Nov 13, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agentbox: ready to merge Audited by Claude and Codex; Harsh can merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants