Human console, approvals and logging
This page covers how a headless session gets an answer from a person, and where Luna records what happened. It describes the human console (a filesystem rendezvous between a headless requester and an interactive operator session), the approvals the tool firewall remembers, every log and state file the extensions write, how tool-capture stores and prunes tool input and output, and how the join keys tie the logs together. The four diagrams show where state lives (split into two maps), how capture stores and prunes data, the broker round trip, and one tool call end to end.
The human console is not a UI. A headless requester drops an approval or question request into a pending directory and an interactive operator session writes the answer into a resolved directory. The ask_human tool, the tool firewall and engagement governance all use this broker, so a headless subagent can ask a question or request an approval that a person sitting in another session answers.
Retention and join keys
Every subsystem writes its own log, most of it JSONL, and the retention rules differ. tool-capture self-prunes against a disk budget and rotates its segments. firewall-judgements.jsonl is rotated at 4 MiB with a single .1 backup. The firewall audit, the human-console audit, the trace ledger and the engagement hash chain are append-only with no automatic rotation, so an operator manages them and they grow until someone trims them. firewall-feedback.jsonl is append-only too, apart from /auto forget, which rewrites it. The per-session firewall-sessions/<id>.json files and the approvals file are rewritten atomically on every save. The firewall creates its decision logs and state files (feedback, judgements, learned profile, session files and its audit log) with mode 0600, and the state directories it creates under the agent directory (pi-kit/, firewall-sessions/) with mode 0700. Existing files keep their mode until the firewall rewrites them atomically (tests/tool-firewall-smoke.ts).
Firewall decision records carry a toolCallId and an actionHash. Capture call records carry their own actionHash and argsHash, the trace ledger uses its own argsHash and toolCallId, and the learning-state FeedbackRecord carries a hash and a sig but no toolCallId. The keys let an operator correlate the logs; there is no single universal join key.
Components and where state lives
The firewall and the capture and trace extensions write into different trees. The firewall audit, the human-console files and the trace ledger sit in the project's .pi/ directory, the firewall's learning state, approvals and the capture store sit under the agent directory's pi-kit/, and engagement governance writes under PENTEST_DATA_ROOT. Two console surfaces exist: the human-console file broker described here, and the optional web UI (/console, extension web-console). The web-console extension spawns packages/web-ui/server/server.ts and appends that server's stdout and stderr to <webUiRoot>/.runtime/server.log. The server reads pi session JSONL from the sessions directory (PI_CODING_AGENT_SESSION_DIR, default <agentDir>/sessions) and never reads or writes the human-console pending and resolved directories.
Every profile except lite loads human-console and tool-capture; trace-ledger is in all of them.
The first map covers the firewall, the broker and the engagement audit. Solid arrows are writes and dotted arrows are reads.
flowchart LR
A["pi agent process"]
FW["tool-firewall"]
HC["human-console"]
PG["engagement governance"]
A --> FW
A --> HC
A --> PG
subgraph proj["Project .pi directory"]
FAUD[("tool-firewall-audit.jsonl")]
FCON[("human-console-audit.jsonl")]
PEND["human-console/pending"]
RES["human-console/resolved"]
end
subgraph kit["Agent directory pi-kit"]
FCFG[("firewall.json")]
FAPP[("firewall-approvals.json")]
FFB[("firewall-feedback.jsonl")]
FJ[("firewall-judgements.jsonl")]
FPROF[("firewall-profile.json")]
FSESS[("firewall-sessions/ID.json")]
end
PAUD[("PENTEST_DATA_ROOT/audit/audit.jsonl")]
FW --> FAUD
FW --> FAPP
FW --> FFB
FW --> FJ
FW --> FPROF
FW --> FSESS
FW --> PEND
FCFG -.-> FW
FAPP -.-> FW
RES -.-> FW
HC --> RES
HC --> FCON
PEND -.-> HC
PG --> PEND
PG --> PAUD
RES -.-> PG
The second map covers capture, the trace ledger and the web UI.
flowchart LR
A["pi agent process"]
TC["tool-capture"]
TL["trace-ledger"]
CND["conductor, agent-synth and validator"]
WC["web-console extension"]
WUI["web UI server"]
A --> TC
A --> TL
A --> WC
WC -->|spawns| WUI
subgraph cap["Agent directory pi-kit/capture"]
SEG[("segments/*.jsonl and *.jsonl.gz")]
BLOB[("blobs/aa/sha256.gz")]
RET[("retention.jsonl")]
end
TRACE[("project .pi/trace.jsonl")]
LOG[("webUiRoot/.runtime/server.log")]
SESS[("pi sessions directory")]
TC --> SEG
TC --> BLOB
TC --> RET
TL --> TRACE
CND --> TRACE
WC -->|"redirects stdout and stderr"| LOG
SESS -.-> WUI
The table lists every log and state file these subsystems touch with its writer, the record kinds it holds, and its rotation or retention behaviour.
The .pi/trace.jsonl call and result record kinds describe only trace-ledger's records. Conductor, its synthesiser and its validator also append their own result-style entries to the same shared file, with an FNV 8-hex argsHash (trace-ledger uses sha256). That is why trace-ledger's header warns that this file must never be truncated.
| File | Writer | Record kinds | Rotation / retention |
|---|---|---|---|
.pi/tool-firewall-audit.jsonl (override PI_KIT_FIREWALL_AUDIT_LOG) |
tool-firewall audit, and the shared refusal helper (tool-firewall and secret-guard) |
tool_seen, tool_approved, tool_blocked, tool_refused (one per refusal: guard, cause, matched token, tool, command digest when the call carries a command, session id; no command text or secret), tool_escalated, human_console_pending, human_console_resolved, human_console_timeout, auto_mode_check_start, auto_mode_approved, auto_mode_blocked, auto_mode_judge_unavailable, approvals_malformed, approval_store_error, ssh_config_changed, policy_rule_warnings, policy_load_error |
append-only; renamed to <file>.1 before an append once over 4 MiB, keeping one old copy |
.pi/human-console/pending/ and resolved/ (override root with PI_KIT_HUMAN_CONSOLE_DIR) |
requester writes pending/<id>.json; the console watcher writes resolved/<id>.json |
one JSON request or answer per file | the requester removes both files when it finishes; a malformed pending file is renamed <file>.invalid and at most 50 of those are kept |
.pi/human-console-audit.jsonl (always cwd-relative) |
human-console audit |
ask_human_pending, ask_human_resolved, ask_human_timeout, human_console_invalid_pending_json, human_console_invalid_pending_id, human_console_invalid_pending_kind |
append-only; no built-in rotation, operator-managed |
.pi/trace.jsonl |
trace-ledger (and conductor's own transition entries) | trace-ledger's call and result entries; conductor, agent-synth and validator append their own result-style entries with an FNV 8-hex argsHash |
append-only; trace-ledger renames it to trace.jsonl.1 before an append once over 4 MiB, keeping one old copy (other writers rotate nothing); /trace shows a bounded tail; shared file, never truncate |
<agentDir>/pi-kit/firewall.json (override PI_KIT_FIREWALL_CONFIG) |
the profile installer, /auto and /firewall revoke host:<name> |
mode, policy, source, judgeModel, learn, knownHosts, untrustedHosts |
latest-only, rewritten atomically |
<agentDir>/pi-kit/firewall-approvals.json (override PI_KIT_FIREWALL_APPROVALS) |
tool-firewall approvals.ts (addApproval, revokeApprovals) |
session approvals (given by the operator, bound to one action, workspace, working directory and root session, 24 hours), persistent approvals (learned exact actions, 30 days) and revocation floors |
one versioned file (schemaVersion 1), rewritten atomically under a short lock; expired entries are dropped on write and at most 200 are kept; a file with unreadable entries is also copied to <file>.rejected-<hash> |
<agentDir>/pi-kit/firewall-feedback.jsonl (override PI_KIT_FIREWALL_FEEDBACK) |
tool-firewall appendFeedback |
operator decision precedents | append-only; /auto forget rewrites it to drop matches |
<agentDir>/pi-kit/firewall-judgements.jsonl (override PI_KIT_FIREWALL_JUDGEMENTS) |
tool-firewall appendJudgement |
judge verdicts | rotates at 4 MiB, keeps one old copy as .1 |
<agentDir>/pi-kit/firewall-profile.json (override PI_KIT_FIREWALL_LEARNED_PROFILE) |
tool-firewall profile distiller | stats, principles, cautions | latest-only, rewritten in the background |
<agentDir>/pi-kit/firewall-sessions/ (override PI_KIT_FIREWALL_SESSIONS_DIR) |
tool-firewall trajectory | one <id>.json per session (recent actions, credential reads, downloads, judge cache, counters) |
rewritten atomically on every save; files older than 14 days are swept |
<agentDir>/pi-kit/capture/ (override PI_KIT_CAPTURE_DIR) |
tool-capture store | call, result, attachment, session, gap records plus blobs and retention.jsonl |
rotates at PI_KIT_CAPTURE_SEGMENT_BYTES, gzips rotated segments, prunes to budget |
<PENTEST_DATA_ROOT>/audit/audit.jsonl (default .pi/pentest) |
engagement governance audit |
session_start, tool_allowed, tool_blocked, approval_requested, tool_approved, human_console_pending, human_console_resolved, human_console_timeout, policy_metadata_load_error |
hash-chained and append-only; no built-in rotation, operator-managed |
<webUiRoot>/.runtime/server.log (PI_KIT_WEBUI_ROOT locates the root) |
the web UI server process spawned by web-console startServer |
plain text lines: the server's stdout and stderr | append-only; no built-in rotation, grows unbounded |
Approvals, refusal labels and unattended mode
What the operator allows is remembered in one file, <agent dir>/pi-kit/firewall-approvals.json. An approval is never broader than the choice that created it: it is bound to one exact action (tool plus action hash) in one workspace and working directory, under the policy it was given in. A session approval also belongs to the root session, which its subagents share, and expires after 24 hours. A persistent approval is an exact action the operator approved repeatedly (three approvals in two sessions within 30 days, with no denial since) and expires after 30 days. The file is treated as untrusted input. A file of another schemaVersion, invalid JSON, or an entry of an unknown shape is ignored, never treated as an allow, and reported. The decision reads the file on every call, so /firewall revoke takes effect on the next tool call. A firewall-sessions/<root>.grants.json file left by an older release is not read, so it cannot authorise anything.
Every refusal carries exactly one label, in the text the agent reads and in the audit record's outcome:
| Label in the refusal text | Audit outcome |
Meaning |
|---|---|---|
[HARD DENY] (also [HARD DENY: unattended run] and [HARD DENY: outside the unattended zone]) |
hard_deny |
policy says never, or the action needs authority outside the unattended zone; no approval and no judge overrides it |
[UNCERTAIN: no operator decision] (also [UNCERTAIN: no operator in this unattended run]) |
uncertain |
the automatic layers could not settle it, or nobody could be asked before the deadline; it fails closed with a message the agent can relay |
[OPERATOR DECISION: denied] |
operator_decision |
a person declined it; an allow is recorded as operator_decision too |
[AUTO-MODE BLOCK: judge, high confidence] |
judge_block |
the auto-mode judge blocked it with high confidence; the block is final and carries the reason |
Unattended mode (packages/extensions/src/tool-firewall/unattended.ts) is decided once, when the firewall loads, from the supervisor's environment (PI_KIT_UNATTENDED=1, a known PI_KIT_UNATTENDED_BOUNDARY and a read-only PI_KIT_UNATTENDED_CONTRACT file). Nothing inside a session can switch it on, and a changed or unreadable contract switches it off for the rest of the process. Inside the zone there are no approval prompts and no judge calls. Critical and hard-denied classes, and anything that needs authority outside the zone (a host that is not in the contract's egress list, a git remote that is not listed, publishing, cloud and cluster APIs), are still refused. Audit records for these runs carry mode: "unattended", the boundary and a short contract digest.
Tool-capture pipeline and join keys
Capture opens one segment per process and appends five kinds of record around a tool call: a call record on tool_execution_start, a result record and an optional attachment record on tool_execution_end, a session record on start and shutdown, and a gap record that says how many records were dropped once disk pressure eases. Values too large to inline are written to content-addressed gzip blobs and referenced from the record, and rotated segments are compressed in the background. Each record lists the secret kinds it contains; values are stored byte-exact unless PI_KIT_CAPTURE_REDACT=1, and PI_KIT_CAPTURE=0 turns capture off. The join keys are toolCallId plus actionHash and argsHash, which connect a capture record to the firewall audit and the trace ledger.
flowchart LR
H1["tool_execution_start"]
H2["tool_execution_end"]
H3["session start and shutdown"]
SCAN["scanSecrets: list the secret kinds, redact only in redact mode"]
ENC["encode values: large strings and bytes become blobs"]
RCALL["call record: args, actionHash, argsHash, toolCallId, tool"]
RRES["result record: result, isError, durationMs"]
RATT["attachment record: pi's full-output temp file, copied into a blob"]
RSESS["session record: event start or shutdown"]
RGAP["gap record: dropped count, reason disk_pressure"]
BLOB["putBlob: sha256 content address, gzip"]
FBLOB[("blobs/aa/sha256.gz, mode 0600")]
SEG[("active segment: host-pid-start-NNNN.jsonl, mode 0600")]
ROT["rotate when over segmentBytes"]
GZIP["gzip the rotated segment in the background"]
PRUNE["prune to the disk budget and minimum free space"]
RET[("retention.jsonl: deleted file, kind, bytes, reason")]
JOIN["join keys: toolCallId, actionHash, argsHash"]
FWAUD["firewall audit records"]
TLED["trace-ledger entries"]
H1 --> SCAN
H2 --> SCAN
SCAN --> ENC
ENC --> RCALL
ENC --> RRES
H2 --> RATT
H3 --> RSESS
RCALL --> SEG
RRES --> SEG
RATT --> SEG
RSESS --> SEG
ENC --> BLOB
RATT --> BLOB
BLOB --> FBLOB
SEG --> ROT
ROT --> GZIP
GZIP --> PRUNE
FBLOB --> PRUNE
PRUNE --> RET
PRUNE -->|"low free space: records dropped"| RGAP
RGAP --> SEG
RCALL --> JOIN
RRES --> JOIN
JOIN --> FWAUD
JOIN --> TLED
Broker round trip: headless requester to interactive operator
A headless requester (the firewall, or engagement governance) writes <id>.json into the pending directory and polls the resolved directory once a second until its deadline. The deadline is PI_KIT_HUMAN_CONSOLE_TIMEOUT_MS (15 minutes by default), or the end of the turn if it is aborted first. An interactive session's human-console watcher, which only runs in a session that has a UI, reads the pending directory every 1000 ms, shows the menu, writes <id>.json into the resolved directory and removes the pending file. If the operator answers after the request's deadline, the watcher only removes the pending file, so no orphan answer is left. The requester's audit gets human_console_pending, then human_console_resolved once it reads the answer, or human_console_timeout if nothing arrives by the deadline; engagement governance records the same three kinds in its hash-chained audit. The requester removes both files when it finishes.
sequenceDiagram
participant R as headless requester
participant FS as pending and resolved directories
participant HC as human-console watcher
participant O as interactive operator
participant A as requester audit file
R->>FS: write pending/ID.json with the card and choices
R->>A: append human_console_pending
loop every 1000 ms
HC->>FS: scan the pending directory
end
FS-->>HC: pending request
HC->>O: menu of the request's choices, or a yes or no confirm
O-->>HC: chosen label, plus a note for Deny and tell
HC->>FS: write resolved/ID.json with approved, answer and note
HC->>FS: remove pending/ID.json
loop poll every 1000 ms until the deadline
R->>FS: read resolved/ID.json
end
alt answered in time
FS-->>R: resolved outcome
R->>A: append human_console_resolved
else no answer before the deadline, or the turn is aborted
R->>A: append human_console_timeout
end
R->>FS: remove pending/ID.json and resolved/ID.json
The approval choices come from the firewall card: Allow once, Deny, and Deny and tell the agent why…. The session choice is offered in two forms: Allow for this session (similar steps: judge checks them against this) when the judge will check similar steps, and Allow for this session (exact repeats only) when only exact repeats are allowed. Under the engagement policy no session choice is offered. A request without choices (engagement governance's) is shown as a yes or no confirm. A question request instead shows the caller's options plus an Other (type an answer) entry. An operator's session allow is stored as a session approval and is also recorded with the grant source in the feedback log.
A run end to end
This sequence shows one tool call from the model through the firewall's decision, the possible operator detour, capture and the trace ledger. pi emits tool_execution_start first (capture writes its call record), then runs the tool_call handlers in load order (the profiles list protected-paths, then tool-firewall, then later extensions such as trace-ledger), stopping at the first block. A blocked call therefore gets no trace-ledger entry and no tool_result event. For an immediate decision (low allows, critical denies, and every unattended outcome) the firewall appends exactly one tool_seen record that carries the decider. The deferred path appends tool_seen with decision: ask and then tool_approved or tool_blocked. The tool runs only after every handler has returned, and tool_execution_end fires for every call, blocked or not.
sequenceDiagram
participant M as model
participant PE as pi agent loop
participant TC as tool-capture
participant PP as protected-paths
participant FW as tool-firewall
participant OP as operator
participant TL as trace-ledger
participant T as tool
participant F as log files
M->>PE: assistant message with a tool call
PE->>TC: tool_execution_start
TC->>F: append call record with toolCallId and actionHash
PE->>PP: tool_call
PP-->>PE: continue, or block a protected path
PE->>FW: tool_call
FW->>FW: classify the call, place it in a tier, add session history
alt critical, or an unattended run refuses it
FW->>F: one tool_seen with decision deny and the decider
FW-->>PE: block with HARD DENY or UNCERTAIN
else low, or an unattended run allows it
FW->>F: one tool_seen with decision allow and the decider
else medium or high, a decision is needed
FW->>F: append tool_seen with decision ask
alt an exact approval covers it, or the judge allows it
FW->>F: append tool_approved with the decider
else the judge blocks it with high confidence
FW->>F: append tool_blocked
FW-->>PE: block with AUTO-MODE BLOCK
else the operator is asked
alt interactive session
FW->>OP: approval card
else headless
FW->>OP: broker request through the human console
end
OP-->>FW: choice, or no answer before the deadline
FW->>F: append tool_approved or tool_blocked
FW-->>PE: block with OPERATOR DECISION or UNCERTAIN when refused
end
end
alt allowed
PE->>TL: tool_call
TL->>F: append call entry
PE->>T: execute
T-->>PE: result
PE->>TL: tool_result
TL->>F: append result entry
else blocked
PE->>PE: error result carrying the block reason
end
PE->>TC: tool_execution_end
TC->>F: append result record, and an attachment record for a truncated output
PE-->>M: tool result
Source files
packages/extensions/src/human-console/index.ts— file-broker watcher; pending and resolved directories;ask_humantool; cwd-relative audit; the.invalidquarantine.packages/extensions/src/tool-firewall/index.ts—auditPath,audit,brokerApproval,decide, the labelled outcomes and/firewall; writes.pi/tool-firewall-audit.jsonl.packages/extensions/src/tool-firewall/approvals.ts— the approvals file: schema, validation, expiry, scope matching, revocation and floors.packages/extensions/src/tool-firewall/unattended.ts— the run contract, unattended state, egress and remote checks, hard and outside-the-zone denials.packages/extensions/src/tool-firewall/card.ts— approval choice constants andsessionChoice/choicesFor.packages/extensions/src/tool-firewall/config.ts—kitStateDir,configPath,feedbackPath,sessionsDir; env precedence.packages/extensions/src/tool-firewall/profile.ts—judgementsPath,profilePath; 4 MiB rotation and the distilled profile.packages/extensions/src/tool-firewall/feedback.ts—firewall-feedback.jsonlrecord shape, learning thresholds and/auto forgetcompaction.packages/extensions/src/tool-firewall/trajectory.ts—firewall-sessions/<sessionId>.json; 14-day sweep; root-session sharing.packages/extensions/src/tool-capture/index.ts— capture hooks,captureDir,actionHash,argsHash, secret scanning, blob and attachment handling.packages/extensions/src/tool-capture/store.ts— segments, blobs andretention.jsonl; rotation, gzip and budget pruning.packages/extensions/src/trace-ledger/index.ts— subscribes to pi'stool_call/tool_resultevents and appendscall/resultentries to the shared.pi/trace.jsonl(conductor also appends there); sha256argsHash; bounded/tracetail.packages/extensions/src/web-console/index.ts—/consolecommand; locatespackages/web-ui, spawns the bundled server and appends its stdout and stderr to<webUiRoot>/.runtime/server.log.packages/web-ui/server/config.ts,packages/web-ui/server/sessions.ts,packages/web-ui/server/tailer.ts— session directory (PI_CODING_AGENT_SESSION_DIR), discovery and tailing of pi session JSONL; none of them touch the human-consolepending/resolveddirectories.packages/extensions/src/engagement-governance/index.ts—dataRoot, the hash-chainedaudit/audit.jsonl, and its ownhuman_console_*pending / resolved round trip.packages/extensions/third_party/protected-paths/index.ts— refuses agent writes to the human-console files, the approvals file and the firewall state.