Record a single autonomous action taken during a self-directed dev loop.

Use this to log any action the agent takes on its own initiative, tagged with a tier indicating how consequential it was.

Args: tier (int): Impact tier. Must be 0 (routine/info), 1 (notable), or 2 (high-impact, e.g. irreversible or user-facing). category (str): Short category label, e.g. "refactor", "deploy", "file_write", "dependency_change". Must be non-empty. description (str): Human-readable description of what was done. Must be non-empty. project (Optional[str]): Project/repo name this action belongs to.

Returns: dict: {"id": int} — the new action's row id.

Errors: Raises ValueError if tier is not in {0,1,2} or category/description are empty, with a message explaining the valid values.

Record a subagent dispatch (e.g. via the Agent tool) for audit and retry tracking.

Call this every time a subagent is dispatched for a task, so retries of the same task can be counted and budget-limited via ledger_task_status.

Args: task (str): Stable identifier/description of the task being dispatched. Use the SAME string across retries of the same underlying task so retry counting works. agent_type (str): Subagent type used (e.g. "fork", "general-purpose"). model (str): Model used for the dispatch (e.g. "sonnet", "opus"). brief_summary (str): One-line summary of what the dispatch was asked to do.

Returns: dict: {"id": int, "retry_count": int} where retry_count is the number of PRIOR dispatches recorded under the same task (0 for the first).

Errors: Raises ValueError if any field is empty.

Attach a verification verdict to a previously logged dispatch.

Use this after independently verifying a subagent's work, to record whether its claims were confirmed, refuted, or partially true.

Args: dispatch_id (int): The id returned by ledger_log_dispatch for the dispatch being verified. verdict (str): One of "CONFIRMED", "REFUTED", "PARTIAL". notes (Optional[str]): Optional free-text notes on the verification.

Returns: dict: {"ok": true, "task": str} — the task string of the dispatch the verdict was attached to.

Errors: Raises ValueError with an actionable message if dispatch_id does not exist, or if verdict is not one of the three allowed values.

Look up dispatch/retry/verdict status for a given task string.

Use this BEFORE dispatching a subagent to check whether the same task has already been retried too many times (budget enforcement).

Args: task (str): The exact task string used with ledger_log_dispatch.

Returns: dict: { "dispatch_count": int, # total dispatches recorded for this task "retry_count": int, # dispatch_count - 1, floored at 0 "last_verdict": str | None, # verdict of most recent dispatch, or null "over_retry_limit": bool # true when retry_count >= 2 }

Generate a markdown report of actions and dispatches from the last N hours.

Actions are grouped by category; dispatches are listed with their resolved verdict or PENDING if not yet verified. Useful for a human-readable audit summary of recent autonomous activity.

Args: since_hours (int): How many hours back to include. Defaults to 24.

Returns: str: Markdown report, or a short "no entries" message if nothing was logged in the window.

Aggregate statistics over actions and dispatches from the last N days.

Args: days (int): How many days back to include. Defaults to 7.

Returns: dict: { "actions_by_tier": {"0": int, "1": int, "2": int}, "actions_by_category": {category: int, ...}, "dispatch_count": int, "verdicts": {"CONFIRMED": int, "REFUTED": int, "PARTIAL": int, "PENDING": int} }

Record the outcome of an approach tried (or considered) for a task.

Record every failed approach IMMEDIATELY after it fails, and every deliberate NO-GO decision, so future attempts (by you or another agent) skip them instead of re-discovering the same dead end.

Args: task (str): Stable identifier/description of the task. Use the SAME string across approaches to the same underlying task so ledger_check_approaches can find them. approach (str): Short description of the specific approach tried or considered. Must be non-empty. outcome (str): One of "DEAD_END" (tried and failed), "NO_GO" (decided against without trying), or "WORKS" (confirmed working). reason (str): Why the approach failed, was rejected, or worked. Must be non-empty.

Returns: dict: {"id": int} — the new approach record's row id.

Errors: Raises ValueError if task/approach/reason are empty, or outcome is not one of DEAD_END/NO_GO/WORKS, with a message naming the valid values.

Call this BEFORE retrying or re-planning a task. Never re-attempt an approach listed in dead_ends or no_gos unless you have new information that invalidates its reason.

Args: task (str): The exact task string used with ledger_log_approach.

Returns: dict: { "task": str, "dead_ends": [{"approach": str, "reason": str, "ts": str}, ...], "no_gos": [{"approach": str, "reason": str, "ts": str}, ...], "works": [{"approach": str, "reason": str, "ts": str}, ...], "total": int } Each list is ordered newest first. Empty lists when nothing has been recorded for the task.