Halofy agent lifecycle installer

Status: @halofy/[email protected] was published and its registry artifact verified on 2026-10-05 through the release workflow. The registry tarball matches the attested build from commit 96ef56f1: SHA-256 2450e89fbc3a99b11889e843c78ea13fa019ba47d4d5fa643f5868ba4a9675b6. The production console supplies the command for the verified package pinned by the deployment workflow. Publication, deployment and native host capture are separate checks: the live 0.16.3 Pi probe exposed a concurrent tool-result capture gap, and the Muse probe retained events in its local queue when hosted requests exceeded the callback deadline.

The 0.16.4 source preparation retains the exact reviewed host/version/mode boundaries. It does not establish publication, production activation or support for newer hosts. Muse Code 1.4.3-R5018.1 has reviewed tool and foreground-turn usage adapters; the existing 1.4.2-R4684.1 text-only profile and older installation consent remain unchanged.

The 0.16.8 source preparation stops long sessions from staying uncommitted: commits go in bounded prefixes (at most 500 events, halved when the server reports a range too large, and reconciled on a stable-prefix conflict), and a failed final commit no longer blocks the close. Codex subagent sessions open only once their stop hook carries the child's final reply or rollout, and closing a host session that captured nothing no longer creates an empty archive row. Publication and installed-runtime activation require separate verification.

The 0.16.7 source preparation fixes false managed-reference restart notices when a delivery check retries unchanged verified files. Prior synced receipts are preserved only when the verified copies before and after refresh agree; changed or unverifiable references retain the existing restart/failure behavior. Publication and installed-runtime activation require separate verification.

This package contains the host-neutral client pieces for installation-bound agent connections:

• Ed25519 installation keys and signed canonical HTTP requests;
• a bounded AES-256-GCM pending queue with a mode-0600 key/file fallback;
• deterministic session hashes, JSONL cursoring, exact supported UTF-8 text, stable structured tool events, explicit digest-only capture-gap records, prefix acknowledgement, and suffix retry;
• signed heartbeat, open, append, recall, context-use, commit, status, and close transport methods;
• a stdio-to-signed-Streamable-HTTP MCP proof proxy; and
• one local claim consumer and proof runtime shared by every packaged adapter.

Hook-driven recall injection is disabled in this release (RECALL_INJECTION_ENABLED in src/session.mjs): the runtime captures conversations and serves the agent-invoked MCP memory tools, but does not push recalled memory into host sessions on session start or prompt submit. The bounded recall block formats stay in place and tested for when it returns.

Host and mode verification inventory (2026-10-06)

This is a source and local-host inventory, not a statement that every listed host is connected in production. “Configured” means the installer has an adapter; fixture tests are not a native application run. Terminal TUI, headless CLI, editor extension, browser UI and desktop application are separate boundaries. All rows use the same Halofy Connect enrollment and signed app.halofy.ai backend; Halofy Workstation remains a separate product. No adapter below establishes universal prompt/spend capture or Workstation provider privacy enforcement.

| Host / current local executable | Packaged boundary and native evidence | App/editor boundary and remaining limits | | --- | --- | --- | | Claude Code 2.1.291 | CLI hook/transcript adapter at user scope (0.16.6); declared text/tools/failures and host-reported usage. A real claude -p in a never-trusted folder ran the user-scope hooks and MCP without approval (test/claude-user-scope-native.test.mjs). Fresh native skill-load/withdrawal proof passes seven phases and 14 local-provider requests, including preserved employee skills and denied retired definitions. This is not a fresh full capture proof. | Separate Claude desktop application is unsupported by this installer. Editor launches require their own hook/profile proof. Binary bodies and context-use evidence unavailable. | | Codex 0.160.1 | Fresh codex exec --skip-git-repo-check with disposable profile: default untrusted hooks emitted no capture and hooks/list reported them untrusted; explicit --dangerously-bypass-hook-trust confined to the fixture produced 24 signed requests: user/tool/usage events, the turn's final assistant reply and one session close. Separate fresh instruction and skill-withdrawal probes produced 10 and three signed requests. | Codex TUI/app/editor invocation not verified. 0.16.5 captures only the final reply per turn (Stop last_assistant_message); intermediate replies and tool failures remain unavailable. SessionEnd is best effort within Codex's three-second hook limit. From 0.16.6 the installer approves its own hooks through Codex App Server (as /hooks does) and reports hostTrust; if Codex refuses, the user trusts them with /hooks. | | Cursor (launcher found; --version timed out) | Cursor hook/settings adapter with callback fixtures for user/assistant/tools/failures. Separate Cursor Agent CLI invocation not verified. | Editor configuration supported; no fresh native editor session in this run. Token usage unavailable. A launcher on PATH is not a connected editor. | | Gemini CLI 0.58.0 | Fresh headless CLI probe invoked the installed adapter and produced 24 valid signed requests with user/assistant text and a compaction checkpoint. Tool/failure coverage remains callback fixtures. | Gemini web/mobile applications and separate editor integrations unverified; no usage capability. | | Kimi Code CLI 2.1.1 | Fresh headless CLI probes each produced 17 valid signed requests with prompt/metadata capture. Reviewed wire lacks vendor/endpoint evidence and reports a model alias; 0.16.2 emits provider_unknown usage gaps instead of attributing custom endpoints to Moonshot. | Kimi web/app versions unverified. Assistant-message hook and binary bodies unavailable. | | VS Code (not on PATH) | VS Code/Copilot editor hook/settings adapter; fixtures cover prompts, tools and supported checkpoints. code is an editor launcher, not a separate headless agent adapter. | Native editor capture not run. Assistant-message, native session-end and usage capabilities unavailable. | | Cline (CLI not on PATH) | Installer detects its VS Code/Cursor extension folder or ~/Documents/Cline; configuration and callback fixtures cover prompts/tools. This is not proof of Cline CLI support. | Native extension/app session not run. Assistant messages, tool failures, session end, usage, subagents and compaction unavailable. | | Hermes 0.21.4 installed; adapter pins 0.21.3 | Reviewed 0.21.3 selected-profile native plugin captures final uninterrupted text and completed tools. The detected newer version is rejected pending native review. | Separate desktop/browser/remote modes unverified. Usage, interrupted/intermediate output, compaction and managed instruction/skill delivery unavailable. | | Pi 0.87.1 | Fresh native TUI, print, JSON and RPC probes passed all 15 success, denial, delayed-response and invalid-budget scenarios. Native tests cover text/tools/failures/usage/MCP/instruction loading. Submitted-turn budget admission is supported. | SDK and desktop wrappers unverified. Shutdown is a checkpoint, not a native session end; no binary bodies, thinking, subagent or compaction claim. | | Muse Code 1.4.3-R5018.1 | New source native exec and TUI signed tests pass tool success/failure and final cumulative foreground usage; two-turn TUI proves counter reset and stable distinct identities. Old 1.4.2-R4684.1 remains text-only; its binary is unavailable for a fresh rerun. | serve/MSP is explicitly denied; SDK/desktop applications unverified. Native TUI is a terminal interface. No interrupted/auxiliary usage, privacy or mechanical budget enforcement claim. | | OpenCode 1.18.34 | Fresh native TUI, run, local serve and actual web browser-UI probes passed all four lanes. Browser proof recorded eight signed message/tool/result/usage events across two local-provider requests; native lanes also verify profile instruction/skill loading. | Separate desktop/remote clients unverified. Session end, compaction, subagents, privacy and mechanical budget enforcement unavailable. | | Grok 1.0.13 (5e9a58528b76) installed; adapter pins 1.0.46 (2765805b9442) | Reviewed Linux direct terminal/headless hooks capture text/session boundaries and signed MCP. Current PATH binary is rejected because it does not match the reviewed version. | ACP/leader modes denied; Grok web/mobile/desktop not covered. Tools, usage, privacy and mechanical budget enforcement unavailable. | | OpenClaw 2026.9.8 (fc23bc8) in isolated fixture, not PATH | Fresh native agent --local, gateway run and actual gateway browser Control UI passed. Gateway proof recorded 39 signed message/tool/result/checkpoint/usage events across six local-provider requests, including the UI turn. Native lanes also verify MCP/plugin instructions. Requires explicit conversation-access consent. | Separate desktop/mobile companions unverified. Current isolated binary version detected, not globally installed. Native session end, privacy and mechanical budget enforcement unavailable. |

The remaining console catalog entries are explicit limits:

| Catalog entry | Installer / app status | | --- | --- | | Antigravity | not_supported_yet; no packaged lifecycle adapter or CLI/app proof. | | Claude Desktop | not_supported_yet; an OAuth/MCP connection does not establish desktop conversation capture. | | ChatGPT | not_supported_yet; an OAuth/MCP connection does not establish web/desktop/mobile conversation capture. | | Manual MCP URL | not_supported / not_observed for lifecycle installation; MCP tool activity is not host prompt or usage evidence. |

Evidence: src/client-registry.mjs, src/installer-cli.mjs, the per-host config, hook, native-parent and transcript adapters, test/host-config.test.mjs, test/host-hook.test.mjs, opt-in test/*native*.test.mjs / test/*host*.test.mjs, and the console registry in kernel/src/http/adapter.ts. The official Muse hook reference describes the upstream callback surface; only the exact native probes above establish this adapter's supported boundary.

Native adapters (0.16.0)

The source adds Pi, Muse Code, OpenCode, Grok and OpenClaw to the existing external-agent installer. Halofy Workstation remains its own product. This package installs adapters into existing agents; it does not install or launch those agents. New installations use Halofy Connect and the same app.halofy.ai services. The source activation gate accepts matching reviewed stable installer/plugin pairs 0.16.0, 0.16.1, 0.16.2, 0.16.3 and 0.16.4; source and native tests do not establish publication or production activation.

| Host | Native integration | Observed evidence and limits | | --- | --- | --- | | Pi 0.87.1 | Native extension in PI_CODING_AGENT_DIR, default ~/.pi/agent; TUI, print, JSON and RPC | User/final assistant text, tools/results/failures, reported usage, signed MCP and submitted-turn budget admission. Shutdown is a checkpoint. SDK/desktop, images, thinking, artifacts, subagents and compaction are unverified. | | Muse Code 1.4.2-R4684.1 | Linux native TUI and exec; <XDG_CONFIG_HOME>/muse, default ~/.config/muse | User/final assistant text, session start/end, signed MCP and native instruction/skill loading. OS parent identity binds the actual profile before proof use; copied profiles and serve/MSP are denied. Tools, usage, privacy and budget enforcement are unavailable. | | OpenCode 1.18.34 | Native plugin in OPENCODE_CONFIG_DIR, otherwise <XDG_CONFIG_HOME>/opencode or ~/.config/opencode; TUI, run, local serve and web browser UI | User/final assistant text, tools/results/failures, reported usage, signed MCP and native instruction/skill loading. Desktop/remote, session end, compaction, subagents, privacy and budget enforcement are unavailable. | | Grok 1.0.46 | Linux direct TUI/headless; GROK_HOME, default ~/.grok | User/final assistant text, session start/end, signed MCP and instruction/skill loading. Copied profiles, leader and ACP are denied. Tools, usage, privacy and budget enforcement are unavailable. | | OpenClaw 2026.9.8 | Native plugin in the selected state profile; agent --local, gateway run and its browser Control UI | After-turn user/assistant text, tools/results/failures, reported usage, signed MCP and plugin instructions/skills. Explicit native conversation-access consent is required. Separate desktop/mobile companions, session end, privacy and budget enforcement are unavailable. |

The reviewed 0.16.2 and 0.16.3 releases also accept Muse 1.4.3-R5018.1 on Linux TUI and exec. Its native PostToolUse/PostToolUseFailure callbacks provide completed tool inputs/results/failures. PostLLMCall exposes cumulative counters: only a successful foreground turn emits its usage snapshot, never intermediate cumulative totals. Input counts exclude separately reported cache reads/writes; reasoning remains a subset of output. The aggregate has no provider request ID. A direct native user submission must admit the matching session, turn and capture generation first; reminder/auxiliary sessions are excluded. Missing counters, failed calls and unknown providers produce a usage gap. Interrupted or continuing turns, background/subagent usage and missing model prices are not complete spend evidence. Reconnect to grant these additional categories; an existing text-only consent cannot silently expand.

Muse 1.4.3-R5018.1 truncates startup rules above 32,000 bytes. This source checks the complete composed profile AGENTS.md, including personal text, and reports unavailable / host_rules_limit with a local warning when it exceeds that limit. The full policy and personal bytes remain on disk; Halofy does not shorten the policy or treat a restart as a remedy. Authorized removal remains possible. Smaller files still report pending_restart, not proof of loading or obedience; other rules and host precedence may affect loading. The official Muse configuration reference provides no reviewed startup-rule size override. An isolated native exec probe with a synthetic provider verifies that an oversized policy's head reaches model context but its tail does not, even with context_compaction.provider_context_limit_tokens set to 1,000,000. That model window setting does not raise the rules limit. The matching under-limit probe loads both markers. These checks do not certify desktop/SDK modes.

Owned configuration and frozen instruction/skill destinations are checked before proof use. Personal files are preserved; modified owned files, copied profiles, unsupported versions and ambiguous configuration fail closed. Runtime files live outside the transient NPX cache. Delivered file changes require the host's reviewed reload/restart; delivery alone does not prove that a running agent used them. These adapters reuse existing consent, learning and write-path rules. When Workstation also supplies usage, exact Pi/OpenCode native identities are reconciled with collected copies before report and budget slicing. Unverifiable overlap remains unavailable; other agent families retain per-session observations and the existing financial-source selection. Missing prices are never zero.

CLI support does not establish desktop/editor support. No new adapter claims provider-egress privacy, MCP-wide policy enforcement or an exact monetary ceiling. Pi checks the signed budget service before submitted input, including while capture is paused. Exhausted or unavailable decisions block submissions; autonomous continuations and internal provider requests are outside that boundary. Privacy-required Connect workspaces remain blocked until an actual pre-egress boundary is implemented and reviewed. Never assert a false Workstation capability or disable organization protection to enroll.

The 0.16.1 source gives Pi signed requests, including budget checks, a 15-second deadline. Pi's budget child has 35 seconds (36 seconds in the parent bridge), allowing native host verification before the request; lifecycle callbacks have 90 seconds (91 seconds in the bridge) for configuration, replay, open and heartbeat. A failed budget check still blocks the turn. Capture remains durably queued for replay when delivery times out. These bounds do not change Claude's deadlines, add cached admission or broaden supported host modes. Pi rechecks its installation/profile before each signed request and after a delayed budget decision. Capture callbacks retain their pause generation; already-queued evidence can replay through a fresh authorized callback.

Runtime storage locks retain a live owner's exclusivity regardless of age and recover ordinary locks left by a dead process. A process killed during the short dead-lock recovery step can leave a .recovery directory and keep that lock busy. In this case, stop all Halofy adapter processes using that runtime root before removing the empty recovery directory for the reported lock, then restart the host. Keep the encrypted queue and its key; deleting them loses pending capture. Recovery never guesses that a live owner is abandoned.

Detected subscriptions (source; not yet published)

While the existing MCP proxy runs, Codex and Claude Code installations can report their local account's detected plan through signed /v1/agent-runtime/subscriptions. This shares only provider, subscription/API-key/ unavailable status, a normalized plan code and observation time. It does not report email, account IDs, tokens, raw CLI output or account billing. Detection does not prove a company seat assignment, payer, cost or provider entitlement. Installations enrolled before the server recorded immutable custody need an explicit reconnect before this optional reporting lane can accept observations. Updating the runtime alone does not establish the missing person binding.

The runtime probes only the enrolled host, using Codex App Server account/read with refreshToken: false, or claude auth status --json. It does not open a model turn or extract credential files. The current host configuration root must match the installation's saved profile. Missing profiles, different roots, unsupported CLI versions, missing executables and failed probes report unavailable. Other installed agents do not probe Codex or Claude. Unknown tiers normalize to unknown; they are not guessed from the model or API key.

Probes have a four-second deadline and a combined 64 KiB stdout/stderr limit. Only normalized observations enter the private local cache; they are refreshed at most every 15 minutes. Reporting runs independently of heartbeat, capture and MCP requests, stops with the proxy, and skips paused or replaced installations. There is no device-wide scanner or hook-only probe. Old servers returning 404 back off for 24 hours; other reporting failures back off for 15 minutes. Publication, server deployment and real installed-host reporting still require separate release verification.

AI budget delivery and controlled submissions (0.14.0 source)

Installation, session-start and explicit sync refresh the installation's own structured budget state through signed /v1/agent-runtime/budget/check. Claude UserPromptSubmit checks again before each submitted turn, even with capture paused. Every configured limit applies automatically: recorded spend and outstanding reservations reaching a limit return a mechanical blocking decision. Incomplete usage alone does not block a turn; complete spend and remaining balances still show as unavailable. Zero blocks new work, and removing a limit removes that restriction. Cached balances never grant work. The check has a three-second network deadline for Claude; Pi and interactive installation use 15 seconds in 0.16.1. Failed checks cannot silently disable a previously enforced budget. An older kernel without this endpoint cannot enforce limits until upgraded.

This requires trusted execution of the installed hook. It limits new submitted turns based on observed API-equivalent estimates; it cannot stop every internal model call or subagent, bound subscription invoices, or control a user who removes the hook. Kimi, Codex, Cursor, Gemini, Cline, VS Code and Hermes report budgets without blocking submissions through this package until their blocking boundaries are separately verified. The account/team budget applies across all captured models; no model choice is inferred from an agent label. See the Claude hook decision contract.

The local budget-<installation-id>.json file is diagnostic configuration, not financial authority. sync and installer results report budget status separately from instruction/skill delivery. Publication, server deployment and real-host enforcement still require release verification.

Headless host limits and explicit refresh

Codex hook behavior depends on the installed host version and hook trust. The earlier 0.154.0 probe did not invoke configured SessionStart or UserPromptSubmit hooks. The current 0.160.1 disposable-profile probe above verified supported exec events only after explicit fixture hook trust; its untrusted control emitted no capture. A hooks.json file alone proves neither host loading nor complete conversation coverage. Existing installations can refresh configuration explicitly:

node "/absolute/path/to/runtime/0.13.1/bin/halofy-agent.mjs" sync --connection <installation-id>

The installer prints syncCommand with the exact executable, argument array and HALOFY_AGENT_HOME environment for this installation. Use those values (the example path above is a placeholder); an npx installation does not put halofy-agent on your shell PATH. Run it before starting headless work. It refreshes instructions, policies, knowledge references and assigned skills through the same signed, authorized delivery path without creating a host session or capturing messages. It exits nonzero if instructions or acknowledged file delivery are unavailable. A successful refresh proves file delivery only; start a new host session to load changes. The refresh command does not establish hook trust or capture support for an unreviewed host. Installations predating this command need the reviewed package upgrade.

From 0.16.6 Claude is configured at user scope: hooks and the exact context Read rule go to <CLAUDE_CONFIG_DIR or ~/.claude>/settings.json and the signed MCP proxy to the user-scope mcpServers in .claude.json. Claude gates project hooks and project .mcp.json servers behind folder trust and approval prompts; user scope needs neither, so capture starts in every project with no manual step. Halofy entries an earlier project-scoped install left in the current project are removed; personal content is preserved. The Read rule covers only the exact installation's halofy-context-<hash> directory (earlier installations' rules are replaced), never the whole skills tree, runtime keys, shell commands or MCP tools. Existing ask/deny rules remain authoritative. Assigned skill folders and MCP tools may still need separate host permission. No trust markers or permission-bypass flags are set. See Claude permissions.

Guarded Claude installations give managed skills immutable version aliases and check current eligibility before native Skill expansion. Approved calls keep normal host permissions; retired, replaced or unverifiable managed versions are denied, including bodies Claude cached before its startup sync. Unrelated employee skills outside reserved halofy-managed-* aliases and legacy tombstone names remain unchanged when ownership history is intact. This requires the installed trusted hook to execute and a reachable Halofy server. It cannot recall earlier conversation content, downloaded copies or arbitrary file reads. Other trusted hooks that rewrite Skill input are incompatible with this guard: Claude can apply their rewritten input after Halofy's check. Installer compatibility diagnostics inspect project, project-local and user settings. An empty overlap list does not verify plugin, managed or command-line hooks, or hooks introduced after installation.

If ownership history is missing or corrupt, all native Skill calls pause because the runtime cannot safely distinguish employee skills from legacy managed names. An administrator must restore verified claude-skill-guard ownership state or review a reconnect migration that preserves legacy tombstones. Do not delete or recreate an empty history to bypass the pause. Ordinary reinstall does not reset initialized history.

The isolated real-host regression is opt-in (no global configuration or real credentials): HALOFY_CLAUDE_HOST_TEST=1 node --test test/claude-host-skills.test.mjs. Set HALOFY_CLAUDE_BINARY if claude is not on PATH. It verifies current managed and employee skill expansion, native deny preservation and cached retired-body denial, including whitespace around legacy names. It also reproduces the trusted input-rewrite limitation in both hook registration orders.

For Codex, HALOFY_CODEX_HOST_TEST=1 node --test test/codex-host-skills.test.mjs verifies signed explicit synchronization removes a retired skill's catalog and explicitly requested body from the first fresh host request while preserving an employee skill. Set HALOFY_CODEX_BINARY if needed. A running conversation can retain already-loaded content; publication alone does not refresh installed runtimes or their managed copies.

Halofy Connect sign-in

Workstation remains Halofy's AI workstation. This package keeps the employee's existing supported agent and installs its adapter. Both use Halofy Connect for identity and the same app.halofy.ai workspace/backend. Connecting an external agent does not make it a Workstation runtime or add unsupported host controls.

The no-claim install and login paths in this source use Connect's existing device authorization, with the same public halofy client as Workstation. The kernel advertises its configured HTTPS issuer through /auth/sso/config. This Connect path trusts only the exact https://app.halofy.ai backend and https://connect.halofy.ai issuer. Discovery cannot authorize another bearer destination. Custom servers continue to use the existing manual claim path. Missing Connect enrollment support stops with an upgrade/enable message; it never silently switches to a separate console login. This change requires a reviewed package release and matching backend deployment; source changes do not upgrade already published packages or installed runtimes.

For source testing with a matching backend, from the repository root:

node kernel/integrations/agent-runtime/bin/install.mjs install claude-code \
  --server https://app.halofy.ai

The installer opens only that Connect issuer's /device page and displays its public verification code. After sign-in, the existing Workstation configuration endpoint resolves the person, organization and team. --team <team-id> uses that same authorized selector when an explicit team is needed. The terminal prints one line naming the server-selected organization/team; from 0.16.6 there is no capture disclosure or typed CONNECT, and sign-in approves the external agent enrollment. Existing personal host content is preserved through the reviewed adapter's ownership rules.

The ordinary external enrollment uses a privately saved Ed25519 key; approval claims remain bound to that original key. Device secrets and Connect bearers stay only in memory, never in browser URLs, logs, host settings or saved runtime files. The temporary Connect session is signed out on success, cancellation or failure where a token was obtained; an unavailable sign-out is reported. Retry expired/failed enrollment with the same command; the pending key survives.

Manual --claim <one-time-claim> installation keeps its existing behavior. Use the production console's verified, version-pinned command for released packages. --team is only a Connect sign-in selector and cannot be combined with an already scoped manual claim. Setup sharing retains its separate consent. The capability table below still applies: sign-in alone proves no capture, host loading, enforcement, privacy protection or full Workstation parity. If the workspace requires provider privacy protection, the existing shared configuration gate can refuse NPX enrollment: these external adapters do not advertise Workstation privacy capability. The installer stops before approval or host changes and retires the temporary session; it does not bypass that requirement. Workspace membership denials also remain fail-closed.

The server, not the browser, selects the exact published package version and permits only these reviewed client kinds:

| Client kind | Adapter coverage | Explicit current gaps | |---|---|---| | claude-code | complete for declared text/tool lifecycle hooks | image bodies, artifact bodies, context-use evidence | | cursor | complete for declared text/tool lifecycle hooks | image bodies, artifact bodies, context-use evidence | | gemini-cli | complete for declared text/tool lifecycle hooks | image bodies, artifact bodies, subagents, context-use evidence | | kimi-cli | partial | assistant responses, provider-attributed token usage, image and artifact bodies, context-use evidence | | codex | partial | assistant responses, tool failures, session end, binary bodies | | vscode | partial | assistant responses, binary bodies, context-use evidence | | cline | partial | assistant responses, tool failures, subagents, compaction, session end, binary bodies | | hermes-agents | partial; Hermes 0.21.3 (2026.9.14) only | interrupted/intermediate assistant output, compaction, tokens/thinking, subagents, binary bodies, managed instructions/skills/context |

Other catalog entries remain Not supported yet or Not observed; the installer refuses them before claim consumption. A knowledge connector, OAuth-only MCP connection, legacy bearer, or manual MCP URL is never upgraded to conversation-capture evidence by its name.

Run the server-returned command in the operating-system terminal from the computer where the selected client runs, never in agent chat. The installer displays one line naming the organization the claim binds to, fetched from the named server (or that the server did not identify it), generates the Ed25519 private key locally, consumes the one-use claim in a JSON body, copies the reviewed runtime out of the transient npx cache, and installs the signed MCP proxy and lifecycle hooks together. It replaces an existing Halofy bearer MCP entry where the host exposes one and installs its reviewed hooks while preserving unrelated settings. It never runs both Halofy capture paths for one host session.

The current storage backend is the explicitly reported mode-0600 file fallback (or the closest Windows ACL), not hardware-backed storage. No bearer or claim is stored in the runtime queue or host configuration.

The request canonicalization in src/crypto.mjs follows AL4's strict raw path and query rules. Publication is fail-closed until the package tarball, current Claude fixtures, cross-implementation signature fixtures, and deployed server protocol have all passed for the exact version. Server versions configured with the Claude-only 0.1.x artifact keep every additional client fenced as Not supported yet; 0.2.x keeps Kimi fenced until its 0.3.x adapter.

Every packaged adapter advertises archive protocol v1 explicitly. The Claude adapter's current body capabilities are user/assistant text, structured tool inputs/results and failures, and host artifact references. Inline images and artifact bodies are represented by digest-only placeholders and make coverage partial; images/artifactBodies remain false until the signed chunk-upload protocol, encrypted retry queue, and real-host fixtures are verified. The adapter never opens an arbitrary transcript-referenced local file to fill that gap.

Since 0.6.0, reviewed transcript drivers extend host-reported token usage and content-free session metadata to Codex CLI (rollout files) and Kimi Code CLI (session wire files). In 0.16.2, Kimi wire records without proven provider identity produce explicit provider_unknown usage gaps; protocol and model labels cannot establish a billing vendor. Previously acknowledged records are not rewritten. The same containment commitment applies: a driver never opens a hook-supplied path. It derives the session file from a validated session id ([A-Za-z0-9_-]{1,128}) under the host's own root (CODEX_HOME/~/.codex, KIMI_CODE_HOME/~/.kimi-code), and every index-supplied or cached path must realpath-resolve inside that root or the read is skipped. Capture additionally requires the installation's frozen tokenUsage capability — installations consented before 0.6.0 never have their transcripts read until reinstalled under the current disclosure. A single install all --claims <kind>=<claim>,… invocation sweeps the claimed, detected hosts without a prompt, printing the explicitly listed set; each host keeps its own installation, capabilities, and status.

Run focused checks from this directory:

npm test
npm run check

Content-free local queue/version evidence is available without printing any pending event body or proof key:

node kernel/integrations/agent-runtime/bin/halofy-agent.mjs diagnostics

Pass --connection <installation-id> to inspect a specific installation. Diagnostics shows installed and running runtime versions, local hook/pause health, frozen capture capabilities, queue depth, oldest pending time and expired batch count. It makes no server request, and neither active local hooks nor an empty queue proves that a particular conversation reached the archive.

Conversation return reliability (0.13.1 source)

Append acknowledgement is now mandatory and bounded to the submitted batch. An empty, non-JSON or malformed success response cannot discard queued events. Only explicitly accepted or duplicate events advance the cursor; a server sequence ahead of an event conflict cannot acknowledge the rejected local body. An unchanged transcript retries its already durable queue, including after a lost append response, without requiring another user message. Hook messages without a native event id receive an id per invocation, so multiple prompts in one Cline task and repeated identical prompts remain separate events. Queue retries preserve that id; native event ids still deduplicate host retries.

Retries run at supported hooks, explicit runtime replay and the existing MCP proxy's 60-second health tick. Each background tick attempts at most one pending batch, with the proxy's five-second request timeout and cancellation on exit. Heartbeat reporting continues when replay fails. Paused or replaced installations skip background replay; resume permits queued work to retry. The pause result reports an incomplete flush while any unacknowledged batch remains. No new monitoring process is installed. Abrupt host shutdown can leave pending data until the next proxy start or supported hook, subject to the existing seven-day queue limit. This release does not widen host capabilities or add assistant responses to the partial adapters listed above. Hosts without native event ids cannot distinguish two host invocations from a duplicated host callback.

The npm 0.12.1 tarball was downloaded and matched the deployment workflow's SHA-256 pin on 2026-09-17. These 0.13.1 fixes require a new reviewed publication, server pin promotion and a recipient-confirmed reinstall. Existing runtimes do not auto-upgrade. Public health responses and package integrity do not verify authenticated production conversation capture.

Version 0.8.0 additionally refreshes authorized organization and team policy and knowledge-base references at installation and SessionStart for the seven pre-Hermes hosts above. Hermes does not support this managed delivery. Each installation gets a private halofy-context-* skill folder containing SKILL.md and canonical content references. The content is extracted directives and ingested knowledge, not original uploaded files or live backend rows. Host skill discovery makes the references available; copying files is not evidence that a host loaded or obeyed them. The runtime does not insert the whole knowledge base into a prompt or report policy compliance acknowledgements.

The signed context route pages the entire eligible set, enforces source access, current source/file/base state, namespace ancestors, validity/TTL and export residency. General agent bulk export stays disabled. Updates replace only the installation's managed context; withdrawal or failed refresh removes it from host discovery. Offline local copies already read by a host cannot be remotely erased. Setup reports context availability separately from the connection heartbeat. Older backends report context unavailable until the matching backend release is deployed. Reconnect to install this runtime on existing connections. Reconnection retires the previous active installation's owned context. Older project hooks consult the active host marker and cannot restore that retired copy.

Scoped badge delivery receipts (0.9.0)

This version adds signed /v1/agent-runtime/delivery/check and /v1/agent-runtime/delivery/receipt requests. Installation and session-start refreshes report a content-free version calculated from the complete activated policy/knowledge set and installed skill manifest. Incomplete discovery, local conflicts, unavailable downloads and unsupported hosts cannot acknowledge synced. Updates and removals use the existing scoped delivery routes and native folders.

Supported user-turn hooks check current eligibility before continuing. An unchanged version avoids content downloads. A changed version refreshes the managed copies and reports restart_required; supported hook output includes a fixed notice asking for a new session. Cursor's before-submit hook has no reviewed context-injection output, so it receives manager-visible receipt status without an injected notice. A successful subsequent session-start refresh clears the restart requirement. All delivery passes serialize per installation, including separate hook processes; replaced installations cannot restore managed copies.

Manager statuses are Not connected, Synced, Sync pending and Needs attention. Receipts confirm file delivery only, never host loading or policy compliance. Older servers retain installation/session-start refresh behavior but cannot confirm delivery status. Existing offline skill limits remain; context refresh failures withdraw the managed references. These are source capabilities; package publication, installed-client upgrades and production deployment require separate release verification.

Connection health and local pause (0.11.0 source)

This source version adds a signed heartbeat immediately and every 60 seconds while the existing MCP proxy runs. It inspects the installation's managed hook and MCP configuration without repairing it. Health contains only a state; local paths stay on disk. Legacy installations without inspection metadata report unknown. Missing contact may mean an idle host, sleep, or network loss, and cannot establish that an employee uninstalled the integration.

Use the installed runtime executable with pause --connection <installation-id> or resume --connection <installation-id>. Pause persists for that installation, attempts a bounded flush of already queued events, and skips subsequent capture hooks. It does not block MCP. Resume reports inspected health and excludes older transcript bodies from catch-up, so paused content is not backfilled. A failed state report is retried by the next running-proxy heartbeat or session start.

JSON configuration checks require every managed hook registration and MCP entry. Changed Kimi/Codex TOML is conservative: removed/disabled managed configuration reports hooks_missing; other changes report unknown pending reinstallation. This package does not add a TOML parser or a device-wide monitoring daemon.

The 0.11.0 source is not proof of a published or deployed artifact. Release must publish the exact reviewed npm package, verify its integrity, update the server's pinned installer artifact through its existing release process, and prove an updated disposable installation. Existing local runtimes do not auto-upgrade.

Organization instructions (0.10.0)

Version 0.13.2 includes an MCP policy validator extension. It accepts one final generated Required MCP access policy document in the connection's exact namespace, alongside ordinary authored instructions. That document may exceed 16 KiB; the complete instruction bundle still cannot exceed 64 KiB. Ordinary documents keep their 16 KiB limit and unique, ordered ancestor scopes. Content hashes, bundle digest, UTF-8 and managed-marker checks still apply. Existing installed 0.13.1 runtimes without this extension reject same-scope authored/generated pairs and generated policies above 16 KiB. They need an upgraded runtime. The exact 0.13.2 publication and artifact verification are recorded in release evidence. Publication does not upgrade existing installations. Invalid bundles leave existing local files untouched.

This source adds Govern instruction delivery alongside the existing skill, policy, knowledge and delivery-receipt paths. Activation requires the reviewed 0.10.0 npm publication, matching server deployment and a fresh confirmed installation. Source versioning alone is not publication evidence. Existing connections without the new local instruction consent/profile snapshot do not gain global file-writing authority.

The installer discloses global rule management alongside existing capture and MCP behavior. It freezes the selected profile and server-provided namespace in the local connection and fetches instructions with the installation proof. Subsequent supported session-start hooks refresh them independently of disabled memory recall. There is no resident instruction daemon; an offline device or a host session without an installed startup hook does not fetch updates. Claude's existing hook installation is project-scoped even though its rule file is global.

Instruction GET and its best-effort status receipt share an 8-second default deadline at startup or direct refresh. The 0.16.1 source gives interactive installation a shared 35-second deadline and Pi lifecycle instruction requests 15 seconds each within its bounded callback. A failed GET preserves current instructions; a receipt timeout does not undo a completed local update or prove server acknowledgement. Other hosts' request and hook limits are unchanged; this is not a deadline guarantee for the whole startup sequence. Startup runs instruction sync alongside skill/reference delivery, including while capture is paused, so slow reference downloads or receipts do not hold up the instruction fetch. Replay and heartbeat still follow both refreshes.

| Host | Local target | Boundaries | |---|---|---| | Codex | CODEX_HOME or ~/.codex, active nonempty AGENTS.override.md else AGENTS.md | Marked section; changing the active target reports a conflict | | Claude Code | CLAUDE_CONFIG_DIR or ~/.claude, dedicated rules/halofy-*.md | Existing personal/project CLAUDE.md remains untouched | | Gemini CLI | GEMINI_CLI_HOME or home, then .gemini/GEMINI.md | Marked section; custom discovery excluding GEMINI.md is unsupported | | Cursor | ~/.cursor/rules/halofy-*.mdc with alwaysApply: true | Agent Chat only; no claim for Tab, Inline Edit, or cloud hosts | | Other packaged hosts | No instruction writes | Reports unsupported; existing capture/MCP continues |

Host mechanisms were checked against official documentation on 2026-09-10: Codex, Claude Code, Gemini CLI, and Cursor. These are file-format adapters, not real-host loading certification. Host precedence, context limits, project configuration and exclusion settings still apply. Receipts say pending_restart, never loaded or obeyed. Other local OS accounts, containers and remote/cloud profiles require their own installation.

Codex instruction delivery verification

On 2026-09-17, source runtime 0.12.2 was tested against Codex CLI 0.154.0 on Linux with disposable profiles and a loopback model endpoint. The actual host's outgoing request contained the published instruction after signed prelaunch sync, then its replacement, then no managed instruction after authorized removal. Personal instruction bytes survived. This verifies that tested host's loading path, not model obedience or delivery to an existing employee device. The protocol server in this test is synthetic; it does not replace the kernel's signed HTTP, scope, publication, or receipt tests.

The probe also runs the actual installer in a second fresh disposable profile: organization disclosure and fixture confirmation, claim exchange, generated installation proof, signed heartbeat, profile configuration, instruction write, ownership manifest, and receipt. The first real Codex request loads that instruction. Executing the returned syncCommand from the installed runtime then replaces it in the first following fresh session. This uses synthetic claim authority and confirmation; it is not production enrollment or employee consent evidence.

The same probe established two independent startup limits:

• With trusted hooks, SessionStart refreshed the file and sent a receipt, but Codex had already discovered the instructions for that session. The new text appeared on the following fresh launch. pending_restart is accurate even when the startup fetch succeeded.
• Without trust for the hook definition, Codex skipped the hook and made no instruction request. Installing hook configuration does not establish that the host executes it. Review and trust the installed hooks through Codex's own workflow; do not disable the host's trust checks as a production remedy.

For a published instruction with no verified host delivery:

1. Where authorized evidence is available, correlate the device, OS account, Codex profile (CODEX_HOME), badge namespace, active installation, and executable runtime version. A newer staged package or a different signed-in console workspace proves none of these. Never share private keys, claims, or complete connection files.
2. If the installation predates instruction support or lacks the consented instructionProfile, have its recipient complete the currently verified setup/reconnect command for that host and badge. Do not manufacture a profile by editing the connection JSON. A release must publish and activate a reviewed runtime before using capabilities absent from the current pin.
3. For a reviewed installed version that provides syncCommand (0.12.2 source and later), run its exact executable, arguments, and HALOFY_AGENT_HOME environment before starting Codex. Check successful exit and ready:true. This performs signed file refresh; it neither starts capture nor upgrades an older installed runtime. Source 0.12.2 alone is not publication evidence.
4. Start a fresh session in the intended profile and workspace. Correlate the effective instruction digest, owned-file manifest, server receipt, and host load evidence. A receipt alone does not establish that the model loaded or followed the instruction. Keep representative workflow verification separate from claims about an affected installation that has not been inspected.

Release acceptance requires the coordinator to verify the reviewed package's published version and integrity, the deployed installer pin, and the exact installed version. In an authorized disposable installation, use normal scoped publication and enrollment to repeat the first-fresh-session check, then the replacement and removal checks through the installed syncCommand. Retain only the installation/version/scope identifiers, effective bundle digest, owned-file manifest metadata, receipt outcome, and host-load assertion. Personal content must survive each change. A content SHA is not the effective bundle digest. These checks can establish a supported delivery remedy without access to an end user's device; historical incident repair remains unconfirmed until that device's delivery is observed.

The opt-in smoke test requires a local Codex executable, uses no model API key, and leaves user profiles untouched. It exercises the real source hook and explicit CLI sync, fresh installer, and installed runtime with synthetic signed responses. The hook-trust bypass is limited to the disposable fixture; a separate run verifies untrusted hooks are skipped. No raw model requests or private fixture keys are retained.

cd kernel/integrations/agent-runtime
HALOFY_CODEX_HOST_TEST=1 node --test test/codex-host-instructions.test.mjs

Set HALOFY_CODEX_BINARY to select another executable. The test reports its version and observed startup timing; it is skipped in the default hermetic suite. See the official Codex instruction discovery, hook trust, and provider configuration references for the host mechanisms used by the fixture.

Sync validates exact content and bundle digests, scope ancestry/order and size before writing. Personal bytes outside a managed block are preserved exactly. An isolated ownership manifest, exclusive profile lock, no-follow reads, component symlink checks, private backups, concurrent-edit checks and atomic replacement protect local content. Unexpected edits, broken/duplicate markers, linked files or changed target selection fail without replacing host content. Request failure leaves the current installation’s instructions unchanged. A confirmed reconnect first retires only verified predecessor-owned instruction bytes; old hooks cannot restore them. Conflicting predecessor edits prevent new instruction activation while preserving all user content. Otherwise, only a verified empty bundle removes managed content; an empty file and removal manifest remain so a future authorized re-enable can be recognized safely. Backup files stay outside host rules directories, under the runtime instructions directory.

A stale lock is deliberately not automatically deleted; after confirming no sync is running, an operator may remove .halofy-instructions.lock in the selected profile. Local filesystem errors and receipt failures do not interrupt capture or MCP. Neither instruction text, filesystem paths nor backups are sent in status receipts. Existing policy/knowledge/skill operations and runtime queue files are not changed by instruction sync.

Hermes pinned adapter (since 0.13.0)

This source supports Hermes Agent v2026.9.14, package version 0.21.3, upstream commit 345cd2b057a452236de401d3534b8502a7465e8d. The installer executes hermes --version and rejects other versions before consuming a claim. The server offers Hermes only with a verified stable installer at least 0.13.0. Publication, server activation and each employee installation require separate verification. Existing runtimes do not upgrade automatically.

Installation targets the selected HERMES_HOME, otherwise ~/.hermes, after the browser sign-in or console claim. One owned plugins/halofy-lifecycle directory contains a native Python observer (capture) and a portable MCP plugin (memory). Both exact discovery keys are enabled. Unrelated YAML/comments/plugins remain; ambiguous YAML, symlinks, disabled plugins, namespace collisions and edited owned files stop installation. A known conflict is checked before claim consumption. The portable plugin uses the native namespaced server key, not a generic mcp_servers.halofy command. No credentials are stored in either plugin.

The capture plugin records submitted user text, final uninterrupted assistant text and native tool call/results. Native end-of-turn commits a checkpoint; only finalize closes the session. Missing, multimodal, oversized or interrupted content produces explicit gaps. No transcript files are read. Recall remains agent-invoked through signed MCP tools; no recalled context is injected. Managed instructions, skills and knowledge references remain unsupported.

Before starting a new MCP proxy, the runtime validates native portable PLUGIN_ROOT, independently profile-derived PLUGIN_DATA, the working directory, the exact host version and owned configuration. Config-only copies have no executable memory plugin. Profile clones, moves and symlinked plugin subtrees must reconnect explicitly. A whole-home alias to the same canonical directory is the same profile, not a newly enrolled profile. These checks prevent accidental authority inheritance; they are not attestation against a process that deliberately forges its environment and command under the same OS account that can already read the installation proof.

The package bundles [email protected] under its original ISC license. Release CI installs locked dependencies with scripts disabled; the durable runtime copy includes the bundled dependency and license so it works after the transient package directory is removed. test/hermes-package.test.mjs packs the real artifact and verifies that offline copy. Setting HALOFY_HERMES_PYTHON to an isolated pinned Hermes interpreter additionally runs native discovery and synthetic local-model turns, checks signed lifecycle/MCP requests, and exercises rejected profile copies. This is host/protocol verification, not real-provider inference or production connection evidence.

Manual bearer MCP remains a separate existing memory-tools-only alternative; see the official Hermes MCP configuration reference. A manual MCP connection is not lifecycle capture evidence.

Current setup sharing for playbooks (0.15.0)

Conversation capture does not authorize configuration collection. Version 0.15.0 adds separate setup-enable, setup-status and setup-disable commands to the installed halofy-agent runtime. The deployed installer must select the verified 0.15.0 package, and the host must update; older installations do not acquire this feature.

For local verification from this source, use an explicitly selected test installation:

node kernel/integrations/agent-runtime/bin/halofy-agent.mjs setup-enable \
  --connection <installation-id> --project <project-directory> --label "Project setup"
node kernel/integrations/agent-runtime/bin/halofy-agent.mjs setup-status --connection <installation-id>
node kernel/integrations/agent-runtime/bin/halofy-agent.mjs setup-disable --connection <installation-id>

Enable displays its destination and exact local scope and requires affirmative terminal consent. --include-profile selects the current Codex/Claude profile; --profile selects an explicit profile directory. Neither is implied by selecting a project. Automation can explicitly pass --consent current-setup-v1 after reviewing the disclosure. The command itself does not request a model call or collect content.

Signed consent advertises up to eight opaque scope ids, labels and host kinds. Local paths stay on the device. A later playbook request arrives through the existing heartbeat and reads the selected roots afresh. Results contain at most 16 files, 16 KiB per file and 20 KiB of file content in total. There is one current server report per installation, not a historical configuration timeline. Requests expire; missing/offline/unconsented scopes stay unavailable. Disabling denies collection locally first, then clears server state; an offline clear is retried by heartbeat.

The collector supports Codex/Claude instructions and bounded Markdown/text skills. Settings are projected through an allowlist. Raw config, credentials, auth stores, environment/header values, commands and command arguments are not uploaded. Known credential patterns in authored text are removed, but this is not a guarantee that all private information was found; review/vetting still applies. Links, hard links, special files, large files, ancestor/nested-project rules, imports and unselected profiles remain excluded with explicit gaps. Files are installation-reported current copies, not proof a host loaded them. It executes nothing and changes no host setup.

Workstation uses the identical dependency-free collector and consent helper until its package runtime catches up. From this repository run node kernel/scripts/sync-current-setup-workstation.mjs --workstation-root <checkout>; add --check to verify byte parity. The mirror adds no model instructions or tools.