sessionmap

package
v0.42.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package sessionmap is the hook-written state that binds a Claude Code process to its Brigade session (plan 3.2, 6.5): the by-pid map at ${stateDir}/sessions/by-pid/<claude_pid>.json, from which the session-bound commands and the watcher resolve EVERYTHING (profile, config dir, adapter argv, Brigade session id, team, socket path), and the by-native map at ${stateDir}/sessions/by-native/<claude_session_id>.json, which lets a later `claude --resume` re-open the same Brigade session (3.7). Neither map ever holds the messaging token (3.2).

Trust: the by-pid map is an unauthenticated trust boundary guarded by filesystem permissions alone (E0-7) — whoever can write it decides which profile and team a session acts as. The reader therefore applies every check available and refuses anything else with `config`, details.reason "map_not_private": a regular file opened without following a symlink, mode granting nothing to group or other, owned by the current uid, within the size cap, valid JSON of the expected shape whose claude_pid matches its file name. A hook that rewrites the map on every SessionStart (E0-8: it re-fires on /clear) is what keeps a planted map from surviving to the first Bash call; this package supplies the overwrite semantics that idempotence needs.

Every side effect here is a file under the caller's Store.StateDir; the clock is the caller's (RegisteredAt/UpdatedAt are set by the hook) and the owner check is injectable through Store.Stat, so tests stay hermetic.

Index

Constants

View Source
const (
	// ReasonMapNotPrivate: the file failed the privacy checks (mode, owner,
	// symlink, regular file). details.check names which.
	ReasonMapNotPrivate = "map_not_private"
	// ReasonMapMalformed: the file is not a JSON object of the expected
	// shape, or exceeds MaxMapBytes.
	ReasonMapMalformed = "map_malformed"
	// ReasonMapInvalid: the JSON parsed but a member fails Validate;
	// details.field names it.
	ReasonMapInvalid = "map_invalid"
	// ReasonMapMismatch: the by-pid file's claude_pid is not the pid in its
	// file name (a copied or planted file).
	ReasonMapMismatch = "map_mismatch"
	// ReasonMapUnreadable: an I/O failure other than "missing" — the
	// underlying error is never echoed.
	ReasonMapUnreadable = "map_unreadable"
	// ReasonStateDirRelative: the Store's StateDir is empty or relative;
	// the harness always computes an absolute one (3.2).
	ReasonStateDirRelative = "state_dir_relative"
)

The details.reason values of the `config` errors this package returns.

View Source
const MaxEntrypointChars = 64

MaxEntrypointChars bounds the entrypoint token the map carries.

View Source
const MaxMapBytes = 64 << 10

MaxMapBytes caps what the strict reader will read of a map file. A real map is well under 2 KiB; anything larger is not one.

View Source
const MaxNativeIDLen = 80

MaxNativeIDLen is the length cap of a native session id used as a file name.

Variables

This section is empty.

Functions

func CheckAdapterCommand

func CheckAdapterCommand(argv []string) error

CheckAdapterCommand validates a resolved adapter argv prefix: every element non-empty and, when there is one, the first an absolute path. An empty argv is valid and means the bundled adapter. A relative executable is refused because a planted map must not be able to make the harness exec a path relative to whatever the cwd happens to be.

func CheckHost added in v0.31.0

func CheckHost(host string) error

CheckHost validates a host name before it becomes a path component: a short lower-case token. The two hosts Brigade knows are claude-code and muse; the check is on shape, not on a list, so the config package (which imports this one) owns the list.

func CheckNativeID

func CheckNativeID(id string) error

CheckNativeID validates a native session id before it becomes a path component: 1–80 characters from [A-Za-z0-9_-]. Claude Code's ids are UUIDs, which pass; anything with a separator, a dot or a non-ASCII rune is refused, so a hostile id in hook stdin cannot escape the by-native directory. The offending value is never echoed.

func SameReceiver added in v0.35.0

func SameReceiver(a, b *ByPID) bool

SameReceiver excludes mutable monitor observations, retaining the exact ownership binding.

func TightenInbound added in v0.36.0

func TightenInbound(decided, request string) string

TightenInbound is the effective policy of card 126: the stronger of the hook's decision and the session's runtime request, accept < hold < refuse. A request of "" (none), accept or an unknown word leaves the decision as it is; a decision that is not one of the three reads as accept, which Validate refuses before any reader sees it.

func ValidEntrypoint added in v0.27.0

func ValidEntrypoint(s string) bool

ValidEntrypoint reports whether s is an entrypoint token the map may carry: 1 to MaxEntrypointChars ASCII letters, digits, '-', '_' or '.', the shape of every value Claude Code is known to set ("cli", "sdk-cli", "claude-vscode"). The hook blanks anything else rather than write it.

func ValidSyncScope added in v0.16.0

func ValidSyncScope(s string) bool

ValidSyncScope reports whether s can be a folder id's scope: a repository name as teamfile.RepoName writes one — a label that sanitising leaves unchanged — with no "/", because the bundled adapter splits a folder's label "<scope>/<folder>" at its first one. The hook asks before it freezes a scope, so a name that fails is left out rather than costing the session its map.

Types

type ByHost added in v0.31.0

type ByHost struct {
	HostPID          int       `json:"host_pid"`
	BrigadeSessionID string    `json:"brigade_session_id"`
	UpdatedAt        time.Time `json:"updated_at,omitzero"`
}

ByHost is the by-host pointer (card 88): keyed by a host's name and the session's native id, it names the host pid the by-pid map is keyed by, for a host whose shell tool knows the native id but not the pid. Muse Code is the one such host today: its hooks, its shell tool and its monitors carry MUSE_SESSION_ID (a UUID), and the hook's parent is the Muse process. The pointer is written on every SessionStart and removed at SessionEnd; it carries no identity of its own — the by-pid map stays the trust boundary, and config.Session refuses a pointer whose map does not name the same native id, harness and Brigade session.

func (*ByHost) Validate added in v0.31.0

func (m *ByHost) Validate() error

Validate requires the two members a lookup cannot do without.

type ByNative

type ByNative struct {
	BrigadeSessionID string    `json:"brigade_session_id"`
	TeamRef          string    `json:"team_ref"`
	SessionName      string    `json:"session_name"`
	UpdatedAt        time.Time `json:"updated_at,omitzero"`
}

ByNative is the by-native map (plan 3.2, 3.7): keyed by the native Claude Code session id, it survives session end so that `claude --resume <id>` finds the Brigade session to re-open. It is OVERWRITTEN on every write: a native id RECURS within one process (E0-5 item 6: `/clear` then `/resume` returns the id to its pre-clear value), so the map tolerates a returning id by design rather than assuming ids are monotonic.

func (*ByNative) Validate

func (m *ByNative) Validate() error

Validate requires the one member a resume hint cannot do without.

type ByPID

type ByPID struct {
	// Grok binds monitor state to one direct TUI incarnation; absent on other hosts.
	Grok *GrokReceiver `json:"grok,omitzero"`
	// ClaudePID is the Claude Code process id; it is also the file name.
	ClaudePID int `json:"claude_pid"`
	// ClaudeSessionID is the native session id from the hook's stdin; it
	// is never sent to any backend (T10).
	ClaudeSessionID string `json:"claude_session_id"`
	// BrigadeSessionID is the adapter-assigned session id (4.4.3).
	BrigadeSessionID string `json:"brigade_session_id"`
	// TeamRef and TeamName are the profile's team binding at registration.
	TeamRef  string `json:"team_ref"`
	TeamName string `json:"team_name"`
	// SessionName is the display name registered (6.5).
	SessionName string `json:"session_name"`
	// WorkspaceLabel is the label registered with the session (P11-5):
	// the repository name the hook derived, or the user's own; "" when
	// sharing is off. The watcher carries it on a re-open, because a
	// resume that omits it clears it at the backend.
	WorkspaceLabel string `json:"workspace_label,omitempty"`
	// LabelOption is the `label` option as the hook resolved it (card 24,
	// part C): config.LabelAccount, config.LabelNone, or a literal the
	// member gave. The OPTION rides here, never a label — the account
	// email is read at the point of use by the watcher, exactly as
	// StartFacts does it, so this file never carries a member's email.
	// The watcher sends the resolved label on every registration, so a
	// membership whose label is empty is filled at the next session start
	// and at every watcher replacement.
	LabelOption string `json:"label_option,omitzero"`
	// DoingMode is the RESOLVED doing mode of card 25 (plan 5.2): one of
	// doing.ModeUnsupported, ModeOff, ModeUnasked, ModeAllowed and
	// ModeQuiet, frozen here by the SessionStart hook from the adapter's
	// capabilities, the `share_doing` option and the permission rules in
	// the settings it can read. `brigade doing` reads it to decide whether
	// to publish (the Bash-tool verb never sees CLAUDE_PLUGIN_OPTION_*);
	// the prompt hook reads it to decide whether a line may be printed. It
	// is safe on disk because it is one of five fixed words — never a
	// sentence, never a rule, never a byte of a settings file. Absent
	// (omitzero) in a map written before the mode existed; a reader treats
	// absent as "publish, print nothing" until the prompt hook resolves it
	// once.
	DoingMode string `json:"doing_mode,omitzero"`
	// PermissionMode is the hook stdin's permission_mode as last seen. The
	// inbound policy reads it for one rule (card 50): a bypassPermissions
	// session whose user settings carry no crossSessionInbound accept is
	// refused, because Claude Code would hold every post for a dialog.
	PermissionMode string `json:"permission_mode"`
	// NonInteractive is true for a `claude -p` session (CLAUDE_CODE_ENTRYPOINT
	// sdk-cli, 6.5); diagnostics only.
	NonInteractive bool `json:"non_interactive"`
	// Inbound is the EFFECTIVE policy the session runs under: accept, hold
	// or refuse (6.8) — the stronger of InboundDecided and InboundRequest
	// (card 126). It is the one member the watcher, the prompt hook's poll,
	// `inbox` and `whoami` read; nothing reads the other two to decide.
	Inbound string `json:"inbound"`
	// InboundDecided is the policy the hook decided (policy.Decide: the
	// team_inbound option, the native scan, the parity rule) — the
	// CEILING a runtime request can tighten below and return to, never
	// rise above (card 126). The SessionStart hook writes it and the
	// prompt hook rewrites it at every re-decision. Absent (omitzero) in a
	// map from before the member existed, where Decided reads Inbound.
	InboundDecided string `json:"inbound_decided,omitzero"`
	// InboundRequest is the runtime request `brigade inbound hold|refuse`
	// recorded for this one session (card 126): "" for none, else hold or
	// refuse. It is never accept — `brigade inbound accept` clears it —
	// so a request can only tighten. It lasts for the session's process:
	// the continue path of SessionStart (/clear) and the compact refresh
	// carry it, a fresh registration starts without one.
	InboundRequest string `json:"inbound_request,omitzero"`
	// FrameLevel is the instruction paragraph the frame carries: open,
	// guarded, strict, or custom for a user-supplied clause (P5-12). The
	// hook resolves it ONCE at SessionStart and freezes it here, so the
	// watcher never re-reads a user file minutes or hours later.
	FrameLevel string `json:"frame_level"`
	// FrameText is the resolved custom clause, EMPTY unless FrameLevel is
	// custom: a named level's text is a Go constant and is never carried
	// here, so a rewritten map cannot smuggle a different paragraph in
	// under a level's name.
	FrameText string `json:"frame_text"`
	// SocketPath is CLAUDE_CODE_MESSAGING_SOCKET as the hook saw it, or ""
	// on a host without an inbox socket. The token is NOT here.
	SocketPath string `json:"socket_path"`
	// TranscriptPath is the native transcript path from the hook's stdin,
	// read by the watcher for the model and context facts; it is never
	// sent to any backend (T10). "" when the hook document carried none
	// (or a relative one); omitted from the file then, so a map from
	// before it existed still reads.
	TranscriptPath string `json:"transcript_path,omitzero"`
	// Profile is the resolved profile name.
	TeamKey string `json:"team_key"`
	// ConfigDir is the resolved absolute Brigade config directory.
	ConfigDir string `json:"config_dir"`
	// AdapterCommand is the resolved argv prefix prepended verbatim to
	// every adapter invocation; [] means the bundled adapter, which the
	// adapterclient resolves through os.Executable() at spawn time and
	// which is deliberately never pinned to a path here.
	AdapterCommand []string `json:"adapter_command"`
	// PluginBin is the bootstrap's resolved realpath when the hook knows
	// it (the shadowing check of 6.2), else "".
	PluginBin string `json:"plugin_bin"`
	// SyncAdapter, SyncFolders and SyncRoot are file sync as the hook
	// resolved it at SessionStart (folder-sync plan §4.3) and froze it for
	// the watcher, which drives the adapter, and for `brigade sync
	// status`: the NAME of the sync adapter the team file's `sync` member
	// gives (never a path — foldersync resolves it), the folders it lists
	// exactly as written (relative to the checkout), and the canonical
	// repository toplevel they are relative to. All three are set together
	// — a usable member with at least one folder and the `sync` option on —
	// or none is, and then this session syncs nothing. Absent (omitzero)
	// in a map from before file sync existed, which reads as "off".
	SyncAdapter string   `json:"sync_adapter,omitzero"`
	SyncFolders []string `json:"sync_folders,omitzero"`
	SyncRoot    string   `json:"sync_root,omitzero"`
	// SyncScope is the repository's name as the hook derived it
	// (teamfile.RepoName), frozen beside the three above: the part of a
	// folder's id that keeps two repositories of one team apart (card
	// 42). It is never the `workspace_label` option, which a member may
	// set to anything: an id must be the same on every checkout. Absent
	// (omitzero) with sync off, in a map from before it existed, and for
	// a checkout with no name to derive — then the folders keep the ids
	// of 0.11.0 to 0.15.0 (foldersync.LegacyFolderID).
	SyncScope string `json:"sync_scope,omitzero"`
	// MessageSound is the `message_sound` option as the hook resolved it
	// (card 35): true when this session's watcher plays one quiet sound
	// as a message arrives. The watcher re-reads it on every liveness
	// tick, so a SessionStart that flips the option takes effect without
	// a respawn. Absent (omitzero) when off, so a map from before the
	// option existed reads as off.
	MessageSound bool `json:"message_sound,omitzero"`
	// MessageNotification is the `message_notification` option the same
	// way (card 36): a desktop notification as a message arrives.
	MessageNotification bool `json:"message_notification,omitzero"`
	// MessageIntervalSeconds is the `message_interval` option as the hook
	// resolved it (card 38): the seconds between two sounds, or two
	// notifications, within notify's bounds. Absent (omitzero) in a map
	// from before the option existed, which Interval reads as the default.
	MessageIntervalSeconds int `json:"message_interval_seconds,omitzero"`
	// HeartbeatSeconds and RosterSeconds are the team file's `polling`
	// member as the hook froze it (card 53): how often the watcher
	// heartbeats — its lease is polling.LeaseBeats of them — and how often
	// folder sync reads the roster, each within package polling's bounds.
	// The watcher reads them once, when it starts, so the hook respawns it
	// when either changes. Absent (omitzero) for a value the member leaves
	// out, a team file without one, or a map from before it existed, all
	// read as the default.
	HeartbeatSeconds int `json:"heartbeat_seconds,omitzero"`
	RosterSeconds    int `json:"roster_seconds,omitzero"`
	// IdleCloseHours is the team file's `idle_close_hours` as the hook
	// froze it (card 61): nil for a member left out (polling's default), 0
	// for off. Entrypoint is the session's CLAUDE_CODE_ENTRYPOINT as the
	// hook saw it (else the registry's `entrypoint`), a short token the
	// hook validated; "" when neither had one. Together they decide
	// IdleClose: the watcher closes a session for want of activity only
	// when its host keeps the process after the conversation is closed
	// (polling.IdleCloseHost). Both read once at the watcher's start.
	IdleCloseHours *int   `json:"idle_close_hours,omitzero"`
	Entrypoint     string `json:"entrypoint,omitzero"`
	// HarnessVersion is the Claude Code version from the registry's
	// `version` member when present, else "unknown".
	HarnessVersion string `json:"harness_version"`
	// Harness is the host the session runs in (card 88): "muse" for a Muse
	// Code session, whose pid is the hook's parent and whose native id is
	// MUSE_SESSION_ID; "codex" for a Codex CLI session (card 107); absent
	// (omitzero) for a Claude Code session and for every map written before
	// the member existed, which read as claude-code. The watcher and the
	// commands key their host-specific behaviour (the sink, the queue, the
	// frame's prose) on it.
	Harness string `json:"harness,omitzero"`
	// HostProcessPID is the process whose life is the session's when that
	// process is NOT the map's key (card 107): a Codex CLI session is keyed
	// by a number derived from its thread id, because Codex runs its hooks
	// from the shared app-server daemon, whose pid every Codex session on
	// the machine would otherwise share; the hook's parent — the TUI in
	// embedded mode, the daemon in daemon mode — goes here, and the watcher
	// polls it instead of the key. Absent (omitzero) for every other host,
	// where the key is the process.
	HostProcessPID int `json:"host_process_pid,omitzero"`
	// Model is the model the host named in the hook's stdin (Muse Code
	// does; Claude Code's comes from the transcript instead), sanitised,
	// for the heartbeat's `model` member. Absent (omitzero) when the host
	// named none.
	Model string `json:"model,omitzero"`
	// RegisteredAt is when the Brigade session was registered; UpdatedAt
	// when this file was last rewritten. Both are the hook's clock.
	RegisteredAt time.Time `json:"registered_at,omitzero"`
	UpdatedAt    time.Time `json:"updated_at,omitzero"`
}

ByPID is the by-pid map (plan 3.2): everything a session-bound command or the watcher needs, resolved by the hook once at SessionStart. It carries RESOLVED values only — the profile after its default applied, the config dir as an absolute path, the adapter as the argv prefix ResolveAdapter produced — never a raw option value and never the token.

func (*ByPID) Decided added in v0.36.0

func (m *ByPID) Decided() string

Decided is the hook's decision — the ceiling — reading Inbound itself for a map written before InboundDecided existed (which carried the decision alone, no request being possible then).

func (*ByPID) GrokAlive added in v0.35.0

func (m *ByPID) GrokAlive(lookup func(int) (procutil.Info, error)) bool

GrokAlive uses the actual TUI process and start identity, never a leader or shell parent.

func (*ByPID) GrokLiveness added in v0.35.0

func (m *ByPID) GrokLiveness(lookup func(int) (procutil.Info, error)) (GrokLiveness, error)

func (*ByPID) Heartbeat added in v0.25.0

func (m *ByPID) Heartbeat() time.Duration

Heartbeat is the heartbeat interval this map asks for: the member's seconds, or polling's default when the member is absent.

func (*ByPID) IdleClose added in v0.27.0

func (m *ByPID) IdleClose() time.Duration

IdleClose is the idle close this map asks for (card 61): the team's hours, else polling's default, as a duration — and zero, which the watcher reads as never, when the member is 0 or when the entrypoint is not a host that keeps its process after the conversation is closed.

func (*ByPID) Instruction

func (m *ByPID) Instruction() frame.Instruction

Instruction is the frame instruction the map carries, for the two injectors (the watcher and the prompt-hook poll) to hand to inbound.Config. It is built, never validated, here: ReadByPID has already validated the members, and inbound.New validates it again as its own layer.

func (*ByPID) Interval added in v0.14.0

func (m *ByPID) Interval() time.Duration

Interval is the interval between two message sounds, or two notifications, this map asks for: the member's seconds, or notify.DefaultInterval when the member is absent.

func (*ByPID) LivenessPID added in v0.32.0

func (m *ByPID) LivenessPID() int

LivenessPID is the process the watcher polls for the session's life: the host process the map names when it is not the key (card 107), else the key itself.

func (*ByPID) MonitorCommand added in v0.35.0

func (m *ByPID) MonitorCommand() string

MonitorCommand is shell text for the native monitor tool, not a subprocess spawn. The bootstrap is always one quoted absolute argument, including quotes/newlines in paths.

func (*ByPID) MonitorDescription added in v0.35.0

func (m *ByPID) MonitorDescription() string

MonitorDescription is an exact correlation token; clipped descriptions cannot prove readiness.

func (*ByPID) Roster added in v0.25.0

func (m *ByPID) Roster() time.Duration

Roster is the interval between two folder-sync roster reads this map asks for: the member's seconds, or polling's default.

func (*ByPID) SetInboundDecision added in v0.36.0

func (m *ByPID) SetInboundDecision(decided string)

SetInboundDecision records the hook's decision and derives the effective policy from it and the request in force: what SessionStart does when it builds the map and the prompt hook at every re-decision.

func (*ByPID) SetInboundRequest added in v0.36.0

func (m *ByPID) SetInboundRequest(request string)

SetInboundRequest records a runtime request — hold, refuse, or "" to lift it — and derives the effective policy: what `brigade inbound` does. A map without a decided member gains one here, from Inbound, so the file it writes is consistent under Validate.

func (*ByPID) ValidGrokReceiver added in v0.35.0

func (m *ByPID) ValidGrokReceiver() bool

ValidGrokReceiver refuses unknown or incomplete receiver bindings.

func (*ByPID) Validate

func (m *ByPID) Validate() error

Validate checks the members every by-pid map must carry before it is written or trusted: a positive pid, a Brigade session id, a valid profile name, an absolute config dir, an inbound value this harness implements (accept, hold or refuse) — with, when the decided policy is present, the effective value equal to the stronger of it and the request, so a map can neither loosen a request nor carry a request of accept (card 126) — a well-formed adapter argv, an absolute or empty socket path, an absolute or empty transcript path (the watcher opens it; a relative one would name a file relative to whatever its cwd is), an absent or valid doing mode (one of the five words of package doing; absent is a map from before the mode existed), and the frame members of P5-12 (a level among the four; a text only under custom, and then a non-empty one within frame.MaxCustomBytes that passes frame.CheckClause). The failure is `config` with details.field naming the member; the value is never echoed.

type GrokLiveness added in v0.35.0

type GrokLiveness int

GrokLiveness is Dead when the TUI is gone or the binding is not a Grok receiver, Live when the pid is that TUI, and Unknown when the lookup itself failed. Unknown is not death: a blip must not retire, rotate or steal the receiver.

const (
	GrokDead GrokLiveness = iota
	GrokUnknown
	GrokLive
)

type GrokReceiver added in v0.35.0

type GrokReceiver struct {
	Cwd string `json:"cwd"`
	// LaunchCwd is the hook document's cwd, with symlinks unresolved. Grok
	// names the session directory from that spelling. Cwd stays the
	// canonical path the receiver binding uses. Empty on a map written
	// before it existed; the reader then uses Cwd.
	LaunchCwd     string `json:"launch_cwd,omitzero"`
	ProcessStart  string `json:"process_start"`
	Incarnation   string `json:"incarnation"`
	MonitorState  string `json:"monitor_state"`
	MonitorTaskID string `json:"monitor_task_id,omitzero"`
}

GrokReceiver is local state, never a protocol-v1 registration member.

type StartFacts added in v0.3.0

type StartFacts struct {
	// ClaudePID is the Claude Code process id; it is also the file name.
	ClaudePID int `json:"claude_pid"`
	// ClaudeSessionID is the native session id from the hook's stdin.
	ClaudeSessionID string `json:"claude_session_id"`
	// ConfigDir is the resolved absolute Brigade config directory.
	ConfigDir string `json:"config_dir"`
	// PluginBin is the bootstrap's resolved realpath when the hook knows
	// it, else "".
	PluginBin string `json:"plugin_bin"`
	// LabelOption is the `label` option as the hook resolved it (card 24,
	// part B): "account", "none", or the member's own sanitised text.
	// Plugin options never reach the Bash tool, so this is the only way an
	// in-session `team create` or `team join` can learn it — exactly the
	// reason ConfigDir is here. It is the OPTION, not a label: the account
	// email is read from Claude Code's own config at the point of use, so
	// no member's email is ever written to this file. Omitted when the
	// option is absent, so a map written before it existed still reads.
	LabelOption string `json:"label_option,omitzero"`
	// WrittenAt is the hook's clock at the write.
	WrittenAt time.Time `json:"written_at"`
}

StartFacts is what the SessionStart hook knows about a Claude Code process BEFORE it knows whether the session attaches to a team (P7-11): the resolved Brigade config directory (the config_dir option applied — plugin options never reach the Bash tool, so a command run inside the session has no other way to learn it), the bootstrap's realpath and the native session id. It is written on every SessionStart, joined or not, and removed at SessionEnd, so an in-session `team create`/`team join` in a not-yet-attached session writes its credential and pin into the SAME store the hooks read. It carries no identity: the by-pid map stays the only thing that says which Brigade session a process is, and its Validate is untouched.

func (*StartFacts) Validate added in v0.3.0

func (f *StartFacts) Validate() error

Validate checks the members a reader relies on.

type StartPointer added in v0.34.0

type StartPointer struct {
	HostPID   int       `json:"host_pid"`
	WrittenAt time.Time `json:"written_at,omitzero"`
}

A StartPointer is the start-time pointer of a pointed host (card 116): keyed by the host's name and the session's native id, it names the key the session's START FACTS are filed under, before the session attaches. The by-host pointer (ByHost) exists only once a map does, and a session that has not joined its team has no map; but the model's shell on Muse Code and Codex CLI knows the native id and not the key, and an in-session `team join` must find the start facts — above all the resolved config directory — to write the credential and the pin where the hooks read them (P7-11). SessionStart writes it beside the start facts, joined or not; SessionEnd removes it with them. It carries no identity: the start facts it points at carry none either.

func (*StartPointer) Validate added in v0.34.0

func (p *StartPointer) Validate() error

Validate requires the one member a lookup cannot do without.

type Store

type Store struct {
	// StateDir is ${BRIGADE_STATE_DIR} as resolved by the caller.
	StateDir string
	// Stat, when non-nil, replaces the fstat of the opened file in the
	// privacy check. It exists for tests: a foreign-uid file cannot be
	// created without privileges, so the foreign-owner refusal is
	// exercised through a FileInfo whose Sys reports another uid. Leave
	// it nil everywhere else — the fstat on the open descriptor is what
	// makes the check free of a check-then-open race.
	Stat func(path string) (fs.FileInfo, error)
}

A Store reads and writes the two maps under one state directory. The zero Store is not usable: StateDir must be absolute (the harness always computes it, 3.2; config.BrigadeStateDir applies the in-session rule).

func (Store) ByHostDir added in v0.31.0

func (s Store) ByHostDir(host string) string

ByHostDir is ${stateDir}/sessions/by-host/<host>.

func (Store) ByHostPath added in v0.31.0

func (s Store) ByHostPath(host, id string) (string, error)

ByHostPath is the pointer file for (host, id), after validating both as path components.

func (Store) ByNativeDir

func (s Store) ByNativeDir() string

ByNativeDir is ${stateDir}/sessions/by-native.

func (Store) ByNativePath

func (s Store) ByNativePath(id string) (string, error)

ByNativePath is the by-native map file for id, after validating id as a path component (CheckNativeID).

func (Store) ByPIDDir

func (s Store) ByPIDDir() string

ByPIDDir is ${stateDir}/sessions/by-pid.

func (Store) ByPIDPath

func (s Store) ByPIDPath(pid int) (string, error)

ByPIDPath is the by-pid map file for pid, after checking the Store and the pid.

func (Store) DeleteByHost added in v0.31.0

func (s Store) DeleteByHost(host, id string) error

DeleteByHost removes the pointer at SessionEnd. A missing file is not an error.

func (Store) DeleteByPID

func (s Store) DeleteByPID(pid int) error

DeleteByPID removes the by-pid map at SessionEnd (3.8). A missing file is not an error; the by-native map is deliberately left in place.

func (Store) DeleteStart added in v0.3.0

func (s Store) DeleteStart(pid int) error

DeleteStart removes the start facts at SessionEnd. A missing file is not an error.

func (Store) DeleteStartPointer added in v0.34.0

func (s Store) DeleteStartPointer(host, id string) error

DeleteStartPointer removes the pointer at SessionEnd. A missing file is not an error.

func (Store) ReadByHost added in v0.31.0

func (s Store) ReadByHost(host, id string) (*ByHost, error)

ReadByHost reads the pointer through the strict reader and validates it. A missing file satisfies errors.Is(err, fs.ErrNotExist).

func (Store) ReadByNative

func (s Store) ReadByNative(id string) (*ByNative, error)

ReadByNative reads the by-native map for id through the strict reader. A missing file satisfies errors.Is(err, fs.ErrNotExist): no resume hint. Other failures are `config` as for ReadByPID.

func (Store) ReadByPID

func (s Store) ReadByPID(pid int) (*ByPID, error)

ReadByPID reads the by-pid map for pid through the strict reader and validates it. A missing file is returned as an error for which errors.Is(err, fs.ErrNotExist) holds (the caller maps it to `not_registered`); every other failure is a *protocol.Error with the `config` code and one of this package's Reason* details.

func (Store) ReadStart added in v0.3.0

func (s Store) ReadStart(pid int) (*StartFacts, error)

ReadStart reads the start facts for pid through the strict reader (the map's own privacy rule: regular, 0600, owned by the caller, no symlink) and validates them. A missing file satisfies errors.Is(err, fs.ErrNotExist).

func (Store) ReadStartPointer added in v0.34.0

func (s Store) ReadStartPointer(host, id string) (int, error)

ReadStartPointer reads the pointer through the strict reader and returns the key it names. A missing file satisfies errors.Is(err, fs.ErrNotExist).

func (Store) StartPath added in v0.3.0

func (s Store) StartPath(pid int) (string, error)

StartPath is the start-facts file for pid: ${stateDir}/sessions/by-pid/ <pid>.start.json, beside the map it precedes.

func (Store) StartPointerPath added in v0.34.0

func (s Store) StartPointerPath(host, id string) (string, error)

StartPointerPath is the start pointer for (host, id), after validating both as path components.

func (Store) WriteByHost added in v0.31.0

func (s Store) WriteByHost(host, id string, m *ByHost) error

WriteByHost validates m and writes the pointer atomically (0600 in a 0700 chain), overwriting any previous one for the same (host, id).

func (Store) WriteByNative

func (s Store) WriteByNative(id string, m *ByNative) error

WriteByNative validates m and writes the by-native map for id, overwriting any previous entry (a native id recurs, E0-5).

func (Store) WriteByPID

func (s Store) WriteByPID(m *ByPID) error

WriteByPID validates m and writes it atomically (0600 in a 0700 directory chain), overwriting any previous file for the same pid: the hook rewrites the map on every SessionStart, including the one `/clear` re-fires (E0-8). A nil AdapterCommand is written as [].

func (Store) WriteStart added in v0.3.0

func (s Store) WriteStart(f *StartFacts) error

WriteStart validates f and writes it atomically (0600 in a 0700 chain), overwriting any previous file for the same pid.

func (Store) WriteStartPointer added in v0.34.0

func (s Store) WriteStartPointer(host, id string, pid int, now time.Time) error

WriteStartPointer writes the pointer atomically (0600 in a 0700 chain), overwriting any previous one for the same (host, id).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL