History usage audit

Contract

Field	Bound contract
Trigger	User explicitly audits what recall fed agents.
Authority	Read-only. No file, VCS, credential, paid, published, deployed, or remote mutation.
Side effect	None.
Done	A bounded event table reports kind, time, session count, bytes, and empty-result flag, or a null object when absent; model-facing digest replay is refused.

Inputs

• deja CLI installed and reachable via PATH. Required; absent tool yields an explicit error object.
• harness filter (optional). Passed as --harness <name> to the CLI. A harness name string such as "claude" or "cursor". When omitted, events from all harnesses are included.
• limit (optional). Passed as --limit <n> to the CLI. Maximum events to return, an integer >= 1. Defaults to 50 when omitted.

Procedure

1. Verify deja is in PATH. Run command -v deja. If absent, return { "error": "deja CLI not found in PATH", "hint": "install or rebuild deja" }. Do not conflate a missing CLI with an empty log. Done when: the CLI is confirmed present or the error object is returned.

2. Run deja log --json --limit 50 with the harness filter if supplied: deja log --json --harness <name> --limit 50. When the user supplies a custom limit, use that value instead of 50. Done when: the command is executed.

3. Capture stdout and exit code. Done when: stdout and exit code are captured.

4. If exit code is non-zero, return { "error": "deja log failed", "hint": "install or rebuild deja" }. Done when: the error is returned.

5. If stdout is the exact string null\n, return null. Done when: null is returned.

6. Parse stdout as JSON. If parse fails, return { "error": "malformed JSON from deja log" }. Done when: the JSON is parsed or the error is returned.

7. The parsed value is a JSON array of event objects or null. Done when: the value type is determined.

8. If the parsed value is null, return null. Done when: null is returned.

9. If the parsed value is an empty array, return null. Done when: null is returned.

10. For each event object, extract the following fields into an audit row:

    • t -> time as the RFC3339 string from the source.
    • kind -> kind.
    • bytes -> bytes as the integer from the source.
    • sessions (absent -> 0) -> sessions.
    • empty (absent -> false) -> empty.

11. Build an array of row objects with keys time, kind, bytes, sessions, empty.

12. Sort the array by time descending (newest first) before returning. Done when: rows are sorted by time descending.

13. Digest text fields (digest, policy, into, terms, ids) are never read, never included in output, and never surfaced to the model. Done when: digest text exclusion is confirmed.

Failure and recovery

Failure class	Condition	Result
tool-missing	deja not in PATH	{ "error": "deja CLI not found in PATH", "hint": "install or rebuild deja" }
command-failed	deja log --json exits non-zero	{ "error": "deja log failed" }
malformed-response	stdout does not parse as JSON	{ "error": "malformed JSON from deja log" }

Partial-result rule: if deja log produces a partial list (due to a cap or clock skew), return exactly what was returned. Do not extrapolate, impute, or estimate missing events. Non-mutation rule: no file, directory, index, or state is written or altered.

Output

Newest-first event rows sorted by time descending, with keys time, kind, bytes, sessions, and empty; return null when the log is absent or empty; return an explicit error object when deja is unavailable. Never include digest text, policy, terms, session IDs, or injection targets.