session

type Action int

type ActionHandler interface {
	HandleCondense(state *State) error
	HandleCondenseIfFilesTouched(state *State) error
	HandleDiscardIfNoFiles(state *State) error
	HandleWarnStaleSession(state *State) error
}

type CondensationAttempt struct {
	CheckpointID    id.CheckpointID `json:"checkpoint_id"`
	RecoveryPending bool            `json:"recovery_pending,omitempty"`
}

type Event int

type Kind string

type NoOpActionHandler struct{}

type Phase string

type State struct {
	// SessionID is the unique session identifier
	SessionID string `json:"session_id"`

	// CLIVersion is the version of the CLI that created this session
	CLIVersion string `json:"cli_version,omitempty"`

	// BaseCommit is the commit the session's pending work sits on top of.
	// Initially set to HEAD when the session starts, then moved to HEAD when it
	// moves (commit, pull, rebase, reset) and after condensation.
	BaseCommit string `json:"base_commit"`

	// WorktreePath is the absolute path to the worktree root
	WorktreePath string `json:"worktree_path,omitempty"`

	// WorktreeID is the internal git worktree identifier (empty for main worktree)
	// Derived from .git/worktrees/<name>/, stable across git worktree move
	WorktreeID string `json:"worktree_id,omitempty"`

	// AdoptedIntoWorktreePath marks a source-side tombstone left behind after
	// `entire session adopt` moves this session into another repository/worktree.
	// Hook TurnStart must not reactivate tombstoned source records, otherwise the
	// same session ID can diverge in two session stores.
	AdoptedIntoWorktreePath string `json:"adopted_into_worktree_path,omitempty"`

	// AdoptedIntoWorktreeID is the target worktree ID paired with
	// AdoptedIntoWorktreePath when available.
	AdoptedIntoWorktreeID string `json:"adopted_into_worktree_id,omitempty"`

	// Branch is the git branch HEAD pointed at the last time this session took a
	// turn. Captured on each turn start so it tracks branches created or renamed
	// after the session began. Empty when HEAD was detached or for sessions
	// recorded before this field existed (callers derive it from commit trailers
	// as a fallback). Lets `entire resume` map a stopped session back to its
	// branch without the user remembering it.
	Branch string `json:"branch,omitempty"`

	// StartedAt is when the session was started
	StartedAt time.Time `json:"started_at"`

	// EndedAt is when the session was explicitly closed by the user.
	// nil means the session is still active or was not cleanly closed.
	EndedAt *time.Time `json:"ended_at,omitempty"`

	// Phase is the lifecycle stage of this session (see phase.go).
	// Empty means idle (backward compat with pre-state-machine files).
	Phase Phase `json:"phase,omitempty"`

	// Kind tags the session's purpose. Empty for normal agent sessions;
	// set to KindAgentReview when the session was started by `entire review`.
	Kind Kind `json:"kind,omitempty"`

	// ReviewSkills is the snapshot of configured review skills at session start.
	// Preserved so checkpoint metadata records which skills were run. May be
	// empty when a review was attached post-hoc and skills were not declared;
	// ReviewPrompt is the ground truth in that case.
	ReviewSkills []string `json:"review_skills,omitempty"`

	// ReviewPrompt is the actual text of the review request — the composed
	// prompt sent to the agent (spawn path) or the session's first user
	// prompt (attach path). Always populated when Kind is a review kind.
	ReviewPrompt string `json:"review_prompt,omitempty"`

	// InvestigateRunID is the 12-hex-char ID of the parent investigation
	// run when Kind is an investigate kind. Multiple sessions across rounds
	// share this ID so the loop driver can correlate them. Empty for
	// non-investigate sessions.
	InvestigateRunID string `json:"investigate_run_id,omitempty"`

	// InvestigateTopic is the human-readable topic the investigation was
	// asked to investigate. Snapshot at session start so checkpoint
	// metadata records what the agent was investigating. Only meaningful
	// when Kind is an investigate kind.
	InvestigateTopic string `json:"investigate_topic,omitempty"`

	// TurnID is a unique identifier for the current agent turn.
	// Lifecycle:
	//   - Generated fresh in InitializeSession at each turn start
	//   - Shared across all checkpoints within the same turn
	//   - Used to correlate related checkpoints when a turn's work spans multiple commits
	//   - Persists until the next InitializeSession call generates a new one
	TurnID string `json:"turn_id,omitempty"`

	// TurnCheckpointIDs tracks all checkpoint IDs condensed during the current turn.
	// Lifecycle:
	//   - Set in PostCommit when a checkpoint is condensed for an ACTIVE session
	//   - Consumed in HandleTurnEnd to finalize all checkpoints with the full transcript
	//   - Cleared in HandleTurnEnd after finalization completes
	//   - Cleared in InitializeSession when a new prompt starts
	//   - Cleared when session is reset (ResetSession deletes the state file entirely)
	TurnCheckpointIDs []string `json:"turn_checkpoint_ids,omitempty"`

	// LastInteractionTime is updated on agent-interaction events (TurnStart,
	// TurnEnd, SessionStop, Compaction) but NOT on git commit hooks.
	// Used for stale session detection in "entire doctor".
	LastInteractionTime *time.Time `json:"last_interaction_time,omitempty"`

	// CaptureDegradedAt records when the session's most recent turn degraded
	// capture because a worktree status scan breached its budget (new-file
	// detection skipped, or the checkpoint itself skipped). Set at turn end,
	// cleared by the next turn whose scans stay within budget. Surfaced as a
	// warning by `entire status`.
	CaptureDegradedAt *time.Time `json:"capture_degraded_at,omitempty"`

	// StepCount is the number of checkpoints/steps created in this session.
	// JSON tag kept as "checkpoint_count" for backward compatibility with existing state files.
	StepCount int `json:"checkpoint_count"`

	// CheckpointTranscriptStart is the transcript line offset where the current
	// checkpoint cycle began. Set to 0 at session start, updated to current
	// transcript length after each condensation. Used to scope the transcript
	// for checkpoint condensation: "everything since last checkpoint".
	CheckpointTranscriptStart int `json:"checkpoint_transcript_start,omitempty"`

	// TokenTranscriptStart is the transcript position up to which this
	// session's tokens are already stored in a checkpoint. Carry-forward and
	// adopt move CheckpointTranscriptStart back to 0 so the next checkpoint
	// shows the whole conversation; they never reset this offset, so that
	// checkpoint still counts only new tokens. It moves back only when a
	// condensation or attach finds the transcript shorter (rewritten or
	// compacted) and records its new end. Nil in state written before the
	// field existed; NormalizeAfterLoad fills it. Read it through TokenStart.
	TokenTranscriptStart *int `json:"token_transcript_start,omitempty"`

	// CheckpointTranscriptSize is the byte size of the transcript at last condensation.
	// Used for fast "has new content?" checks in PostCommit: compare the git blob size
	// against this value without reading the full transcript content.
	CheckpointTranscriptSize int64 `json:"checkpoint_transcript_size,omitempty"`

	// TranscriptOffsetPending records that the turn-end advance of
	// CheckpointTranscriptStart could not run because a late-transcript agent
	// (agent.LateTranscriptWriter, e.g. Antigravity) had not flushed its
	// transcript by the Stop hook. Everything the flush will eventually write
	// is already condensed, so the next mid-turn condensation resolves the
	// pending advance against the by-then-flushed file — without this, prompts
	// and the scoped transcript for the next checkpoint would start inside the
	// previous (already-condensed) turn, attributing the wrong prompt to it.
	TranscriptOffsetPending bool `json:"transcript_offset_pending,omitempty"`

	// Deprecated: CondensedTranscriptLines is replaced by CheckpointTranscriptStart.
	// Kept for backward compatibility with existing state files.
	// Use NormalizeAfterLoad() to migrate.
	CondensedTranscriptLines int `json:"condensed_transcript_lines,omitempty"`

	// UntrackedFilesAtStart tracks files that existed at session start (so they are
	// not attributed to the session)
	UntrackedFilesAtStart []string `json:"untracked_files_at_start,omitempty"`

	// FilesTouched tracks files modified/created/deleted during this session
	FilesTouched []string `json:"files_touched,omitempty"`

	// TouchedFileHashes records the content a turn-end step left for each file
	// it changed: repo-relative path → git blob hash (hex) of the worktree file
	// at that turn end, with clean filters applied as `git add` would. A path
	// the step deleted maps to "" (a recorded deletion). A later step
	// overwrites an earlier one's entry. Entries exist only for paths in
	// FilesTouched; a FilesTouched path with no entry has no recorded content
	// (hashing failed, a symlink, or it arrived via a task record or per-tool
	// hook), and commit-time decisions fall back to its name.
	//
	// Commit hooks compare a committed or staged blob hash with this map to
	// tell "the human committed what the agent wrote" from "the human replaced
	// it". It replaced the shadow-branch snapshot those decisions used to
	// read, and records no content.
	TouchedFileHashes map[string]string `json:"touched_file_hashes,omitempty"`

	// LastCheckpointID is the checkpoint ID from the most recent condensation.
	// Used to restore the Entire-Checkpoint trailer on amend and to identify
	// sessions that have been condensed at least once. Cleared on new prompt.
	LastCheckpointID id.CheckpointID `json:"last_checkpoint_id,omitempty"`

	// CondensationAttempt is saved before a persistent checkpoint write so a
	// retry after process death keeps both the intended ID and recovery mode.
	CondensationAttempt *CondensationAttempt `json:"condensation_attempt,omitempty"`

	// FullyCondensed indicates this session has been condensed and has no remaining
	// carry-forward files. PostCommit skips fully-condensed sessions entirely.
	// Set after successful condensation when no files remain for carry-forward
	// and the session phase is ENDED. Cleared on session reactivation (ENDED →
	// ACTIVE via TurnStart, or ENDED → IDLE via SessionStart) by ActionClearEndedAt.
	FullyCondensed bool `json:"fully_condensed,omitempty"`

	// AttachedManually indicates this session was imported via
	// `entire session attach` rather than being captured by hooks during
	// normal agent execution.
	AttachedManually bool `json:"attached_manually,omitempty"`

	// ContextInjectionDecided records that the once-per-session model-context
	// injection (e.g. the `entire trail` pointer) has been handled for this
	// session, so the dispatcher does not re-inject on later turns. Set on the
	// first normal turn regardless of whether anything was injected: the prompt
	// path reads only clone-local cached trail enablement, and a missing/stale
	// false cache fails closed (miss the hint) rather than retrying/spamming.
	// Review/investigate sessions leave this false because they skip injection.
	ContextInjectionDecided bool `json:"context_injection_decided,omitempty"`

	// AgentType identifies the agent that created this session (e.g., "Claude Code", "Codex", "Cursor")
	AgentType types.AgentType `json:"agent_type,omitempty"`

	// ModelName is the LLM model used in this session (e.g., "claude-sonnet-4-20250514", "gpt-4o").
	// Set from hook data when the agent provides it.
	ModelName string `json:"model_name,omitempty"`

	// Token usage tracking (accumulated across all checkpoints in this session).
	//
	// DECISION: SubagentTokens is "latest snapshot wins", not summed. Subagent
	// usage arrives as a cumulative-since-session-start total (each subagent
	// transcript is re-read from line 0 every call), so accumulateTokenUsage
	// replaces rather than adds it (see cmd/entire/cli/strategy). Tradeoff: if
	// the main transcript resets or rotates mid-session (compaction writing a
	// fresh file, or a resume that truncates), a subsequent snapshot can be
	// SMALLER than a previous one, so this session-wide total regresses
	// (undercounts) for the rest of the session. This is accepted: undercounting
	// after a transcript reset is preferable to the multiplicative overcount the
	// summing approach produced, and the alternative (a session-wide high-water
	// mark) would mask genuine subagent-transcript cleanup. Checkpoint deltas do
	// not share this exposure — CheckpointTokenUsage.SubagentTokens is derived as
	// (this total - SubagentTokensBaseline) and floored at 0 by clampSubtract, so
	// a shrunk snapshot yields 0, never a negative or stale delta.
	TokenUsage *agent.TokenUsage `json:"token_usage,omitempty"`

	// CheckpointTokenUsage tracks hook-provided token usage since the last condensation.
	// This is checkpoint-scoped; TokenUsage remains the session-wide total.
	CheckpointTokenUsage *agent.TokenUsage `json:"checkpoint_token_usage,omitempty"`

	// SubagentTokensBaseline is a snapshot of TokenUsage.SubagentTokens captured
	// at the last condensation reset. Subagent token usage is always re-read
	// from the start of each subagent transcript (agent IDs are discovered from
	// the full main transcript so subagents spawned before the checkpoint
	// window are still found), so it arrives as a cumulative-since-session-start
	// total rather than a per-checkpoint delta. This baseline lets
	// CheckpointTokenUsage.SubagentTokens be rescoped to "since last
	// condensation" via SubtractTokenUsage instead of re-adding the same
	// cumulative total on every checkpoint.
	SubagentTokensBaseline *agent.TokenUsage `json:"subagent_tokens_baseline,omitempty"`

	// SubagentTokensBaselineComplete records whether the baseline is exact.
	SubagentTokensBaselineComplete *bool `json:"subagent_tokens_baseline_complete,omitempty"`

	// SkillEvents records explicit native skill signals observed during this session.
	// Stored as sidecar metadata so consumers can collapse skill-related transcript events
	// without mutating the raw agent transcript.
	//
	// This grows for the life of the session and is deliberately uncapped. It is
	// also the durable half of the exactly-once contract for skill telemetry:
	// extraction re-derives events from transcript offset 0 on every pass and
	// dedupes against this ledger (strategy.appendNewSkillEvents), so an event
	// whose entry never reached disk is announced twice. Trimming it therefore
	// re-enables double-reporting for exactly the long sessions a cap would
	// target.
	//
	// The cost is real but bounded, and it is paid on EVERY MutateSessionState —
	// i.e. every hook, including PostToolUse — because state is read and written
	// whole. Measured JSON round-trip: 0 events / 106 B / 1.6us; 10 / 6.0 KB /
	// 42us; 50 / 29.7 KB / 201us; 200 / 119 KB / 785us, i.e. ~594 B per event
	// and sub-millisecond at any realistic N. The steady-state dedupe rebuild is
	// cheap by comparison: 13us at 200 existing events.
	//
	// So a 100 KB session state is expected, not a leak. If the envelope ever
	// does need shrinking, the move is a narrower ledger — persist only the
	// dedupe keys (~40 B/event) and keep the full events transient — not a
	// truncation, which would break exactly-once.
	SkillEvents []agent.SkillEvent `json:"skill_events,omitempty"`

	// CommitCondensedSignalCheckpointID is the checkpoint ID of the last
	// cli_commit_condensed telemetry signal this session snapshotted, the
	// durable half of that signal's at-most-once contract. A `git commit
	// --amend` re-runs PostCommit with the SAME trailer checkpoint ID (an
	// ACTIVE session re-condenses unconditionally), so without this ledger one
	// logical commit is counted twice in both halves of the miss-rate ratio.
	// Persisted by the same state save that gates the emit, so a failed save
	// retries cleanly; a crash between save and emit loses the row, which is
	// the signal's accepted best-effort posture.
	CommitCondensedSignalCheckpointID string `json:"commit_condensed_signal_checkpoint_id,omitempty"`

	// Hook-provided session metrics (for agents like Cursor that report via hooks)
	SessionDurationMs int64 `json:"session_duration_ms,omitempty"`
	SessionTurnCount  int   `json:"session_turn_count,omitempty"`
	ContextTokens     int   `json:"context_tokens,omitempty"`
	ContextWindowSize int   `json:"context_window_size,omitempty"`

	// PromptWindowBase is the SessionTurnCount value at the start of the current
	// checkpoint window. The number of prompts attributed to the next checkpoint is
	// SessionTurnCount - PromptWindowBase (floored at 1 when written). It is only
	// advanced (deferred reset) the next time a turn is counted after a checkpoint
	// was written, so two checkpoints with no prompt between them report the same
	// count. Zero-value safe on old state files: base 0 ⇒ window = SessionTurnCount,
	// i.e. "all prompts so far" (correct first-checkpoint semantics).
	PromptWindowBase int `json:"prompt_window_base,omitempty"`

	// PromptWindowResetPending indicates a checkpoint was just written and the
	// window base must be re-anchored to the current SessionTurnCount the next time
	// a turn is counted. Deferred so back-to-back checkpoints share a count.
	PromptWindowResetPending bool `json:"prompt_window_reset_pending,omitempty"`

	// Deprecated: TranscriptLinesAtStart is replaced by CheckpointTranscriptStart.
	// Kept for backward compatibility with existing state files.
	TranscriptLinesAtStart int `json:"transcript_lines_at_start,omitempty"`

	// TranscriptIdentifierAtStart is the last transcript identifier when the session started.
	// Used for identifier-based transcript scoping (UUID for Claude, message ID for Gemini).
	TranscriptIdentifierAtStart string `json:"transcript_identifier_at_start,omitempty"`

	// TranscriptPath is the path to the live transcript file (for mid-session commit detection)
	TranscriptPath string `json:"transcript_path,omitempty"`

	// AgentHome is the agent's home directory (for example CLAUDE_CONFIG_DIR or
	// CODEX_HOME) whose session stores held TranscriptPath when it was last set
	// at session initialization or turn start, in whichever spelling (as the
	// environment sets it, or canonical) contains TranscriptPath. A home set by
	// an earlier turn is kept while its stores still hold TranscriptPath. It is
	// "" when the agent has no home layout or the transcript lies in none of
	// the home's stores. It grants no trust: readers pass it to
	// agent.ResolveTrustedHome before relying on it.
	AgentHome string `json:"agent_home,omitempty"`

	// LastPrompt is the most recent user prompt for this session (truncated for display).
	// Updated on every turn start (UserPromptSubmit). JSON tag kept as "first_prompt"
	// for backward compatibility with existing state files.
	LastPrompt string `json:"last_prompt,omitempty"`

	// Owner fingerprints the process that owns this session's agent turn,
	// captured at each turn start via proclive.ResolveOwner. It lets liveness
	// checks detect an ACTIVE session whose agent has exited (clean /exit,
	// crash, kill, terminal close, reboot) without a SessionStop hook firing —
	// see OwnerExited. nil for legacy sessions or when the owner couldn't be
	// resolved, in which case liveness falls back to the StuckActiveThreshold
	// timeout. Only meaningful on Owner.Host.
	Owner *proclive.Identity `json:"owner,omitempty"`

	// TaskRecords tracks subagents dispatched by this session — the durable
	// pointer ledger for subagent work. See TaskRecord.
	TaskRecords []TaskRecord `json:"task_records,omitempty"`

	// SubagentInventory retains Codex child identities independently of task
	// records so follow-up turns remain discoverable after materialization.
	SubagentInventory []SubagentInventoryEntry `json:"subagent_inventory,omitempty"`
	// SubagentLedgerVersion advances on a new child identity or non-empty turn.
	SubagentLedgerVersion uint64 `json:"subagent_ledger_version,omitempty"`
	// SubagentInventoryComplete distinguishes exact empty from legacy unknown.
	SubagentInventoryComplete *bool `json:"subagent_inventory_complete,omitempty"`
}

type StateStore struct {
	// contains filtered or unexported fields
}

type SubagentInventoryEntry struct {
	AgentID                string   `json:"agent_id"`
	DeclaredTranscriptPath string   `json:"declared_transcript_path,omitempty"`
	ResolvedTranscriptPath string   `json:"resolved_transcript_path,omitempty"`
	ObservedTurnIDs        []string `json:"observed_turn_ids,omitempty"`
	FinalizedTurnIDs       []string `json:"finalized_turn_ids,omitempty"`
}

type TaskRecord struct {
	// ToolUseID is the Task tool invocation's tool_use_id — the same ID used
	// to key TaskMetadataDir. Dedup key for AddTaskRecord. For a Claude Code
	// Workflow agent it is the agent ID instead: those agents have no tool call
	// of their own (the Workflow's tool_use_id is shared by every agent in the
	// run), so the record is keyed by the subagent, and AgentID equals it.
	ToolUseID string `json:"tool_use_id"`

	// AgentID is the subagent identifier (tool_response.agentId at launch
	// time), used to resolve the subagent's own transcript file.
	AgentID string `json:"agent_id,omitempty"`

	// StartedAt is when the background launch was observed.
	StartedAt time.Time `json:"started_at"`

	// Background marks a record created at a background launch, which runs
	// until a later SubagentStop instead of completing at launch. Its stop
	// captures no worktree scan, so another background task overlapping its
	// run makes new untracked files ambiguous between the two.
	Background bool `json:"background,omitempty"`

	// SubagentType and TaskDescription are captured at launch time because
	// SubagentStop payloads carry no tool_input — a Final-path capture has no
	// way to derive them from the event itself (ParseSubagentTypeAndDescription
	// yields empty strings on a nil ToolInput). The Final handler reads these
	// from the record to label the task step, falling back to the event's own
	// fields only when the record is absent.
	SubagentType    string `json:"subagent_type,omitempty"`
	TaskDescription string `json:"task_description,omitempty"`

	// DeclaredTranscriptPath is the subagent transcript path an agent's stop
	// hook declared (e.g. Claude Code's agent_transcript_path, or the
	// equivalent Codex/Cursor field) — the path #2058 says must not be lost
	// between mid-turn capture and condensation-time materialization. Empty
	// when no declared path was available; the materializer falls back to
	// ResolveAgentTranscriptPath in that case.
	DeclaredTranscriptPath string `json:"declared_transcript_path,omitempty"`

	// TranscriptUnavailable is set when the agent stores child activity only in
	// the parent transcript. It prevents generic layout fallback from attaching
	// an unrelated file to this record during condensation.
	TranscriptUnavailable bool `json:"transcript_unavailable,omitempty"`

	// Files is the set of files touched by this subagent, merged into the
	// session's FilesTouched at completion time. Populated when the record
	// is completed; empty for a still in-flight record and for a completed
	// read-only subagent.
	Files []string `json:"files,omitempty"`

	// TokenUsage is this subagent's token usage, when the completing hook
	// payload provided one or the agent computed it from the subagent's
	// transcript. nil when unavailable.
	TokenUsage *agent.TokenUsage `json:"token_usage,omitempty"`

	// TokenUsageFromTranscript records that TokenUsage was computed from the
	// subagent's transcript at completion (or would have been, had that read
	// found usage) rather than reported by the agent. Condensation recomputes
	// such usage from the transcript it stores, which by then holds API calls
	// the agent had not yet written when it stopped.
	TokenUsageFromTranscript bool `json:"token_usage_from_transcript,omitempty"`

	// CompletedAt is when this record was completed (CompleteTaskRecord).
	// Zero means the record is still in flight. See the type doc comment.
	CompletedAt time.Time `json:"completed_at,omitempty"`
}

type TransitionContext struct {
	HasFilesTouched    bool // len(FilesTouched) > 0
	IsRebaseInProgress bool // .git/rebase-merge/ or .git/rebase-apply/ exists
}

type TransitionResult struct {
	NewPhase Phase
	Actions  []Action
}