/**
 * Session-state helpers — per-session structured state that lives alongside
 * the `read_state` / `write_state` JSON files but is owned by the runtime
 * (not authored by packs).
 *
 * G.5 introduces the per-turn `tool_ledger`: an append-only list of tool
 * names observed by the `PreToolUse` hook during the current turn. The
 * ledger is the data source for the `session_tool_history` primitive
 * (`src/functions/session_tool_history.ts`), which feeds the freshness /
 * state-verification drift rule.
 *
 * Persistence model:
 *
 *   - Storage key: `sessionStateFile(sessionId, 'tool-ledger')`.
 *   - JSON shape: `{ turn: string[]; session: string[] }` where
 *     `turn` = tool names since the last `UserPromptSubmit` (reset on every
 *     prompt arrival) and `session` = up to 200 most-recent tool names
 *     across the whole session (sliding window).
 *   - ENOENT / malformed JSON → fresh empty ledger (eventual-consistency
 *     model lifted from `destination_scheduler.ts` — losing a few entries
 *     never blocks a tool call, which is the priority inside a hook bin).
 *
 * Trim policy: `session.length` is capped at 200 via a sliding window
 * applied on every `appendTool` write. This bounds the disk + parse cost
 * for long-running sessions without coordinating a separate trim job.
 *
 * Concurrency: hook bins run as short-lived subprocesses, one per host
 * tool-call. FC.1 (2026-06-01): all session-state writes publish atomically via
 * `atomicWriteFile` (tmp + rename) so concurrent writers (e.g. the active-task
 * mirror touched on overlapping events) can never tear/lose state — readers see
 * old-or-new, never partial.
 *
 * Imports from: node:fs/promises, node:path, ./atomic_write.js, ./paths.js.
 * Imported by: src/functions/session_tool_history.ts (read path);
 *   src/runtime/hooks/pre-tool-use.ts (append path);
 *   src/runtime/hooks/user-prompt-submit.ts (turn-reset path).
 */
import type { Event } from './types.js';
import type { TickState } from './unload_conditions.js';
/** Max number of session-wide entries retained; trimmed on every write. */
export declare const SESSION_LEDGER_CAP = 200;
export interface ToolLedger {
    turn: string[];
    session: string[];
}
/**
 * Conservative, fail-closed: true only if EVERY pipeline/sequence segment is an allowlisted
 * read-only verb with no mutating flag AND the command has no output redirection. Anything
 * unrecognized → false (it simply doesn't count toward the SCOPE depth floor).
 */
export declare function isReadOnlyBash(command: string): boolean;
/**
 * Append a tool name to both the current-turn list and the session-wide list. For a
 * read-only Bash command, an ADDITIVE `Bash:read-only` token is recorded alongside the
 * `Bash` token — the SCOPE depth filter counts it while every `Bash`-filtering consumer is
 * unaffected (the `Bash` token is still emitted). Session list is trimmed to the most-recent
 * `SESSION_LEDGER_CAP` entries on every write so it never grows unbounded.
 */
export declare function appendTool(sessionId: string, toolName: string, command?: string): Promise<void>;
/** Record the session's working directory (called by PreToolUse on tool_call). */
export declare function recordSessionCwd(sessionId: string, cwd: string): Promise<void>;
/** Read the session's recorded cwd, or `null` if absent/unreadable/empty. */
export declare function readSessionCwd(sessionId: string): Promise<string | null>;
/**
 * Reset the current-turn list on `UserPromptSubmit`. The session-wide list
 * carries forward across turn boundaries — only the turn slice resets.
 * A missing ledger is created with an empty `turn` (no-op semantically).
 */
export declare function resetTurnLedger(sessionId: string): Promise<void>;
/**
 * Read the tool ledger for the given scope. `current_turn` returns names
 * since the last `UserPromptSubmit`; `session` returns up to the most-recent
 * 200 names across the whole session. Returns `{ tools: [] }` on missing
 * or unreadable state.
 */
export declare function readSessionToolLedger(sessionId: string, scope: 'current_turn' | 'session'): Promise<{
    tools: string[];
}>;
export interface ActiveTask {
    /** Harness numeric id (e.g. "15"). */
    id: string;
    subject: string;
    /** ISO timestamp the task became active. */
    started_at: string;
    /** Track id from the harness `metadata.taskId` (e.g. "AP.1"); Gate A (AP.5) keys on this. */
    taskId?: string;
    /** `docs/tasks` spec ref from `metadata.spec`, if the generator stamped it. */
    spec?: string;
}
/** Write the active-task signal (called by the AP.1 PreToolUse mirror). */
export declare function writeActiveTask(sessionId: string, task: ActiveTask): Promise<void>;
/** Read the active-task signal, or `null` if absent/unreadable/malformed (no throw). */
export declare function readActiveTask(sessionId: string): Promise<ActiveTask | null>;
/** Clear the active-task signal (task completed / none in progress). Ignores ENOENT. */
export declare function clearActiveTask(sessionId: string): Promise<void>;
/**
 * Archive the active-task signal on SessionEnd (rule #16): rename rather than
 * delete, so an abandoned/in-progress task at session close leaves a trace
 * instead of vanishing. No-op when there is no active task. Best-effort.
 */
export declare function archiveActiveTask(sessionId: string): Promise<void>;
/** Per-skill tick map: skill name → its current `TickState`. */
export type SkillTicks = Record<string, TickState>;
/**
 * Read the per-skill tick map. Returns `{}` on an absent/unreadable/malformed
 * file (no throw — same best-effort model as the ledger). Each entry is
 * shape-validated; a malformed per-skill value is dropped (the others survive).
 */
export declare function readSkillTicks(sessionId: string): Promise<SkillTicks>;
/**
 * Advance every CURRENTLY-LOADED skill's tick by one `event` and persist the
 * new map. The map after this call holds EXACTLY the skills in
 * `loadedSkillIds` — any skill no longer loaded (dropped from the set this
 * event, e.g. it unloaded or went out of scope) is removed.
 *
 * Per-skill base state:
 *   - no prior tick OR id ∈ `reactivated` → `createTick()` (fresh activation),
 *   - otherwise the prior persisted tick (carried forward),
 * then `advanceTick(base, event)` applies the event transition.
 *
 * `reactivated` = ids whose `when_to_load` freshly matched this event (CU.2
 * supplies the set); a re-activated skill restarts its idle counter from zero.
 */
export declare function advanceSkillTicks(sessionId: string, event: Event, loadedSkillIds: readonly string[], reactivated?: ReadonlySet<string>): Promise<SkillTicks>;
/** Clear the per-skill tick map (e.g. on SessionEnd). Ignores ENOENT. */
export declare function clearSkillTicks(sessionId: string): Promise<void>;
//# sourceMappingURL=session_state.d.ts.map