Crate locode_host 

locode-host — the one place the system touches the OS (ADR-0008).

Every side effect funnels through the Host: a path jail, shell execution with a timeout + output cap, jailed filesystem helpers, and the shared post-processes. Tools never call std::fs/Command directly — they go through a Host. This crate is a sibling of locode-tools, so it defines its own plain error types; the harness pack (which depends on both) maps them to ToolError::Respond.

Structs

DirEntry

One entry in a directory listing.

ExecLimits

Limits on shell execution. Defaults mirror Grok Build (the primary model).

ExecOutput

The captured result of a command (completed, timed out, or cancelled).

ExecRequest

A command to run through the host’s shell.

FileRead

A file’s contents plus its stat (the stat is the freshness token edits compare).

FileStat

A file’s size and last-modified time.

FrontBackCapture

The combined front/back capture (present when the request asked for it).

FrontBackSpec

Opt-in combined-stream retention (Task 26 Slice 0b; grok’s bash capture shape): keep the first and last halves of a char budget, stream the full output to a host-owned spill file. The pack renders separators/headers — the host returns structure only.

GitMeta

Git provenance for the header (grok summary.json’s git fields).

Host

The injectable side-effect seam (ADR-0008). Construct once per session, share behind an Arc; holds the jail root + policy and the exec/truncation limits.

HostConfig

Construction-time configuration for a Host.

RolloutContents

A parsed rollout: the header plus the replayable message history.

SessionMeta

Line-1 payload: the session header (ADR-0024 §2.3). An open, growing record — every field beyond the identity core is optional-with-default so old and new binaries share one on-disk population (§2.3 rules).

Settings

The typed view of the merged settings (v1 fields, ADR-0024 §1.4). Unknown keys are tolerated at every layer; absent keys are None/empty.

SettingsLoad

The loader result: the merged settings plus human-readable warnings the caller surfaces on stderr (this crate never prints).

ShellSpec

A harness’s shell invocation shape (plan-finalization Q5, 2026-07-21): the choice rides the request; execution stays behind the host door. Grok’s shape is { detect_program: true, login_arg: false, login_path_probe: true }.

TraceExtras

Construction-time inputs the Event::Init event doesn’t carry.

TraceWriter

The rollout writer: feed it every engine Event; it materializes the file on Init (header + preamble message lines) and appends one message line per appended Message. All other event types are ignored — deltas are display-only and the report already has its own artifact (ADR-0014).

WalkEntry

One traversal entry (the root itself is not reported).

WalkOptions

Options for Host::walk.

Enums

ExecError

A failure to spawn or capture — not a failed command (that is a successful capture with a non-zero exit_code).

FsError

A filesystem operation failure.

PathError

A path-jail failure.

PathPolicy

Whether the filesystem tools are jailed to the workspace root (ADR-0008 amendment).

SkillsExtraEntry

One validated skills.extra entry (ADR-0024 §1.4).

Constants

SPILL_RETAIN_MAX

Hard cap on bytes written to a spill file (grok retains ≤ 64 MiB).

TRACE_SCHEMA_VERSION

The trace schema version (session_meta.schema_version). Bumped only by a breaking change the §2.4 rules exist to make unnecessary.

Functions

decode_cwd_dirname

Decode a session-directory name back to the cwd it encodes, or None for a hash-fallback name (recover via the .cwd sidecar) or a malformed escape.

default_locode_home

The default home ($HOME/.locode), ignoring any $LOCODE_HOME override — so a caller can detect “am I on the default” (grok’s default_grok_home split).

encode_cwd_dirname

Encode a (canonicalized, absolute) cwd into its session-directory name.

find_latest_rollout

The newest resumable rollout for cwd (--continue): list the one encoded directory, take rollouts newest-first by filename (the timestamp prefix sorts chronologically), and return the first whose header parses with kind == "main" — unknown kinds are not listed (§2.4 rule 3), but remain reachable by id.

find_rollout_by_id

Locate a rollout by session id (--resume <id>): the cwd’s directory first, then every other session directory (Claude’s scoped-then-global resolver). Any kind is resumable by id.

find_root_from_markers

Ascend from start; the nearest ancestor containing any markers entry or whose absolute path matches stop_pattern is the root (ADR-0023 rules 1+2). No hit up to the filesystem root ⇒ cwd-only (returns start). The filesystem root is only a backstop, never itself the project root.

load_settings

Load and merge the five layers for cwd. flag is the raw --settings value (a path, or inline JSON when it starts with {).

load_settings_from

The env-free core of load_settings: user_dir is the resolved ~/.locode (or None), home_for_tilde backs ~ expansion.

locode_home

The resolved home, memoized for the process (env is read once).

read_rollout

Read a rollout tolerantly (ADR-0024 §2.4 rules 1-2): unknown record types and unknown payload fields are skipped/ignored; an unparsable line (the torn tail) is skipped; a compacted record replaces all prior messages with its replacement_history.

resolve_home_from

The env-free core of locode_home: resolve the home from explicit environment values instead of the process environment.

rg_program

The ripgrep program to invoke: the LOCODE_RG_PATH override, else bare rg on PATH (invoked by name — PATH-hijack hygiene, per Claude Code).

update_user_setting

Write key = value into the user settings file, preserving every other key.