ace-herdr 0.3.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6c7f32e364c4df76447fd6d4356f2117007cf920dc3f2f420bd4dd1e21f8242
-  data.tar.gz: 783dd62904dd12e952528d80d9956511c052fcf23a53551b390f5817bbe93c8c
+  metadata.gz: 03bb080ee7010378787d8e6e05033330cddf0a03405f9bdb321f95b3021395b1
+  data.tar.gz: 7b935435b107aeafe1023139a526135131f600711800afbbde4f7cc6de61e5d8
 SHA512:
-  metadata.gz: bd865086e653b9f8bed7434073707fb733f0f9f0f08c6d979046476ee955a65a2938e7efbad966942fe2a55b68b80c7bbc6a53076601bdaac4cb0ff94029e099
-  data.tar.gz: '08c29e0f0cfb5fa1857959c1fd0ef05376ce3dcc895e6ee6a056e2b3be58c00311e5d0b397e07f063bc94151bb3567441c9e1213bf11e6ea16ea570e8e3fa010'
+  metadata.gz: ad76243e13f3abc8656f2e6d443dc0d12e2b878849716fde11d4ca55152537f11595ff01e029e08b69c122e2863476e2fb734f733cfd0bfb91115e1758611630
+  data.tar.gz: 51735a6becc55d04ab97c0ee83ec735933705674d0fcf6a8c27833a219c9b71e7fa1e132733061f27d557b1914fc9aada318a9b06f09c7c43902ff339b185242

data/.ace-defaults/herdr/config.yml

@@ -19,10 +19,6 @@ timeouts:
 # Delivery record root (ADR-029 short-name layout), relative to project root
 deliveries_dir: .ace-local/herdr/deliveries
 
-# Absolute path to the supervisor-managed receipt verification key. Configure
-# before enqueue; each event pins this key's fingerprint for reconciliation.
-inbox_receipt_public_key:
-
 # Tidy (spec 8wq.t.1w0): archive delivered records strictly older than this
 # many days (age = record updated_at); failed/retryable/pending are never
 # touched

data/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-08
+
+### Changed
+
+- Submit Codex answers through the existing Herdr prompt command to the original live terminal. A successful send means submitted, not read; retain unknown sends without automatic resend.
+- Remove dedicated Codex app-server selection, message-read observation, signing keys and consumed/superseded reconciliation APIs.
+- Keep authenticated original-context admission and actual scoped effects without a second current-state projection.
+
+### Fixed
+
+- Load bounded process/error primitives directly and preserve bounded cleanup of the original process after execution uncertainty.
+
+## [0.4.0] - 2026-10-05
+
+### Fixed
+- Use the shared typed reverse-reference pair at CLI, Inbox and delivery boundaries, refusing malformed persisted targets and noncanonical serialized files before claim or native observation.
+- Pin managed delivery to the accepted original native target under the event lock and reject secret-bearing payloads even without a nested message.
+
+### Changed
+
+- Declare the required direct dependencies and minimum producer versions for this coordinated release: `ace-hitl-contract ~> 0.2`, `ace-runtime ~> 0.2`.
+- Bind protected control to the canonical per-attempt server/socket identity while retaining the fixed native executable view selected by installation verification.
+- Validate and preserve the shared managed delivery envelope at Inbox enqueue, rejecting mismatched scope/digest/correlation and changed replay metadata.
+
+### Added
+
+- Add protected Herdr control pinned to the installed server/socket and fixed workspace, creating one fresh bootstrap pane with exact child observation and no default shell.
+
+- Expose verified native process/session ownership and allow identical signed inbox proof re-verification after settlement without duplicate transitions.
+
 ## [0.3.2] - 2026-10-04
 
 ### Changed

data/docs/usage.md

@@ -14,7 +14,7 @@ ace-docs:
 ## Command Surface
 
 - `ace-herdr deliver [OPTIONS]`
-- `ace-herdr inbox enqueue|status|deliver|reconcile [OPTIONS]`
+- `ace-herdr inbox enqueue|status|deliver [OPTIONS]`
 - `ace-herdr dispatch [OPTIONS]`
 - `ace-herdr list [--panes|--tabs|--workspaces] [--workspace ID] [--quiet]`
 - `ace-herdr send [--cmd TEXT] [--msg TEXT...] [--key NAME...] --pane ID [--quiet]`
@@ -48,45 +48,35 @@ Native `agent_blocked` becomes `SendRejectedError`; `agent_prompt_stalled` becom
 
 Use a stable event ID for one message and the assignment attempt that owns it. The reverse-address JSON contains `session` and `pane`, as with `deliver`.
 
+Reverse references use the shared `ace.hitl.ref/v1` pair contract. Herdr token names
+remain valid; the codec also preserves paired native tmux IDs (`$0`/`%0`) when
+carried by managed metadata. Mixed native/token or cross-field IDs refuse.
+Wire and persisted references must be canonical. Syntax acceptance does not add
+tmux execution to this Herdr controller or replace its exact native ownership,
+target and submission checks.
+
 ```bash
 ace-herdr inbox enqueue --event inb-12345678 --attempt ATTEMPT --ref ref.json --file prompt.txt
 ace-herdr inbox status --event inb-12345678 --format json
 ace-herdr inbox deliver --event inb-12345678
 ```
 
-`enqueue` checks the live pane, durable terminal, agent kind, and native thread identity. Repeating the same event, attempt, target, and payload returns its existing record; a changed value is an error. `deliver` claims the record once. Idle and busy Codex or Pi agents receive an exact-session native queue submission. After an accepted idle submission, Herdr sends a generic wake prompt without the inbox payload. A pane replacement can receive at most that generic wake, never the payload. The JSON result includes `state`, `claim_generation`, `binding`, `last_error`, and any submission receipt.
-
-`queued` can be retried after a proven pre-submission rejection. `delivered` means native submission was accepted; it does not mean the agent consumed the message. A crash after claim, changed target identity, or a native result without a verified acceptance receipt is `uncertain`; another `deliver` call does not resend it. A `completed` record has a positively verified consumption receipt. A superseded uncertain record can return to `queued` only after positive nonconsumption proof.
-
-```bash
-ace-herdr inbox reconcile --event inb-12345678 --receipt proof.json
-```
-
-The receipt is a file supplied from an operator or supervisor observation of the native outcome. Codex and Pi expose submission but no queryable consumption or eviction proof, so `reconcile` never polls the native queue or infers an outcome from age. Before enqueue, the supervisor sets `inbox_receipt_public_key` in `.ace/herdr/config.yml` to the absolute path of its trusted RSA public key. Each event pins that key's fingerprint; a later process cannot substitute a different key. Protect this configuration from delivery requesters. The receipt file must have a detached SHA-256 RSA signature at `FILE.sig`. The private key stays with the operator or supervisor. Its JSON must include the recorded event, attempt, claim generation, payload digest, and complete binding, plus an outcome (`consumed` or `superseded`), an identified observer, and a native observation reference:
-
-```json
-{
-  "event_id": "inb-12345678",
-  "attempt_id": "ATTEMPT",
-  "claim_generation": 1,
-  "payload_sha256": "<digest from inbox status>",
-  "binding": {"session": "<exact binding from inbox status>"},
-  "outcome": "consumed",
-  "observer": {"role": "operator", "id": "operator-id"},
-  "evidence": {"kind": "consumed_acknowledged", "native_reference": "session-log:42", "observation": "message consumed and acknowledged"}
-}
-```
+`enqueue` checks the live pane, terminal and original agent-session identity.
+Managed callers supply `expected_target` from the accepted runtime owner. Reusing
+an event with identical attempt, target and payload returns its original record;
+changed input refuses. `deliver` records one submission intent before sending.
 
-Copy the **entire** `binding` object from `inbox status`; the shortened object above only illustrates the field. `consumed` requires `evidence.kind: consumed_acknowledged`. `superseded` requires `queue_evicted`, `queue_expired`, or `thread_replaced`, with an observation that the old queue entry cannot be consumed. A matching receipt changes `uncertain` to `completed` for consumption, or to `queued` for proven supersession. The original target binding stays pinned. To authorize a replacement native session, include `replacement_target` in the signed receipt with the complete target identity from a fresh Herdr pane observation; reconciliation verifies its session, pane, terminal, agent, and thread against that live replacement address before saving it. Without that field, a new claim can only use the original target. A missing or mismatched receipt returns JSON with unchanged `state: uncertain` and `reconciliation_refusal`; it does not resend. Keep the observation record with the receipt. Signature validation authenticates the configured key; the operator or supervisor remains responsible for checking the cited native outcome before signing.
+Codex delivery uses the existing Herdr terminal prompt; Pi uses its maintained
+queue boundary. `delivered` means the submission was accepted, not that the
+agent read it or completed the task. A known pre-submission refusal stays queued.
+A lost response, process interruption after intent, or changed target is uncertain;
+a later `deliver` does not automatically resend or select a replacement terminal.
 
-After inspecting the native outcome and writing `proof.json`, the trusted operator signs the exact bytes:
-
-```bash
-openssl dgst -sha256 -sign operator-private.pem -out proof.json.sig proof.json
-ace-herdr inbox reconcile --event inb-12345678 --receipt proof.json
-```
-
-The command verifies the detached signature against the configured public key before any transition. Missing, malformed, or self-signed receipts leave the event uncertain and return a machine-readable refusal. Keep the signed receipt and source observation for audit.
+Inspect current progress directly through `ace-herdr capture` or the native pane.
+Inbox status is transport history, not a cached projection of current agent state.
+No agent-read proof, signing key, reconciliation command or dedicated Codex
+app-server is required. Actual task results and scoped service effects retain
+their independent authorization and verification.
 
 ## tmux-intent ↔ herdr-command parity
 
@@ -364,3 +354,46 @@ Commands raise a CLI error (non-zero exit) carrying herdr's machine code where o
 - Invalid send shapes: usage error **before any transport call** (nothing is sent)
 
 Exit `0` means success (including an explicit empty `list` result or a satisfied wait).
+
+Runtime recovery exposes the read-only `process_binding(pane:, caller_pid:)`
+adapter operation, which checks OS ancestry, foreground ownership and the
+original agent-session identity. Message submission is never task completion.
+
+## Packaged guarded native source
+
+`ace-herdr native-source selection` describes the source selection and patch shipped by this gem. These assets live under `lib/ace/herdr/native_source`; installed consumers do not need task directories. This source retains native version 0.9.3 and protocol 22; its exact source commit and patch digest identify the guarded producer. No upstream release or publication is implied.
+
+An explicit nonroot build owner can run:
+
+```sh
+ace-herdr native-source build --source /absolute/clean/local/herdr-checkout --output /absolute/new/artifact-directory --target x86_64-unknown-linux-musl
+ace-herdr native-source verify --artifact /absolute/artifact-directory
+```
+
+The build requires a matching native Linux host (x86_64 or aarch64), the selected Rust and Zig versions, and a native `musl-gcc` toolchain already provisioned by the build owner. Cross builds are unsupported. The output must be new. The builder reproduces the exact baseline plus shipped patch in an isolated checkout, checks the commit/tree/lock/toolchain bytes, pins resolved Rust/Zig/linker paths, invokes the locked release build, and records observed executable/tool digests. It never runs the resulting Herdr binary, changes global tool defaults, contacts a running Herdr server, or publishes an artifact. Locked dependency fetching by Cargo may require network access. Failed builds retain their output claim; a partial directory does not verify.
+
+Verification checks bounded strict provenance against this gem's source selection and the observed ELF bytes/architecture. It provides byte provenance, not deployment authorization. The trusted Lab deployment owner separately selects the gem, source selection, artifact and receipt digests before installing the fixed Lab binary. Protected runtime replacement must also use the canonical maintenance admission/release owner. That operational installer join remains required source work; these commands alone do not activate the producer or complete installed acceptance.
+
+The selected source also provides `terminal.inhibit_input` for an exact original terminal/origin. Its successful `terminal_input_drained` reply proves permanent input inhibition and zero queued input, including terminal replies; it does not prove child exit or canonical scope cleanup. Lost acknowledgement may be retried only against the same original actor. Source fixtures validate this contract without running a native binary; actual Lab installation and N2 consumption remain required.
+
+The inbox context source owner supplies durable operation admission and exclusive key rotation through a fixed authenticated exchange. A lost begin reply recovers the same original process's grant; unknown effects, owner restart and incomplete installation retain blocking state. Replacement and rollback each require an attestation from the actual configured signer plus protected public/config readback. This core does not yet activate a context CLI/server, migrate Assign/private-store consumers, or authorize orphan reclamation. Existing protected mutations must all be migrated before this becomes an accepted end-to-end rotation path; installation and private-key pair handling remain the trusted provisioner's responsibility.
+
+### Trusted bounded descriptor handoff
+
+Internal source installers using `BoundedProcess.call` may supply
+`descriptor_mapping: {4 => authenticated_readonly_file}` together with bounded
+`stdin_data` carrying exact selected source bytes. The mapping has at most16
+entries; child descriptor keys are strict Integers3..63 and handles must be live
+read-only regular files. Stdio overwrite, writable/closed/nonregular handles and
+ambient descriptor/path fallback refuse before spawn. Standard Open3 spawn maps
+only explicit descriptors; `close_others: true` excludes all other descriptors.
+The supplying verification owner keeps the handle scoped and authenticates the
+selected inode; the runner does not confer authority or authenticate arbitrary
+files. Actual installed privilege-transition/PAM preservation is a separate
+installed acceptance check, not established by controlled file/child tests.
+
+### Bounded subprocess cleanup
+
+`BoundedProcess.call` retains capped stdout/stderr and uses an execution deadline plus at most one additional second of cleanup. `stderr_limit:` defaults to `output_limit:`. Unconfirmed cleanup raises `PostLaunchError` and transfers only the still-owned original child to an eventual reaper; no success or absence proof follows. Generic successful calls do not newly signal process groups.
+
+The fixed protected handler selects `cleanup_group: true`: stream EOF alone never triggers termination. Nonreaping observation must establish the original leader exited before its group is signalled and the leader reaped. Loss of original child ownership refuses further signalling. Controlled source checks cover ownership/IO boundaries; installed native/descendant effectiveness belongs to gad.2.

data/lib/ace/herdr/cli/commands/inbox.rb

@@ -4,6 +4,10 @@ require "json"
 require "openssl"
 require "ace/support/cli"
 require_relative "support"
+require_relative "../../molecules/protected_inbox_selection"
+require_relative "../../molecules/inbox_context_client"
+require_relative "../../molecules/inbox_cli_input"
+require_relative "../../molecules/inbox_direct_effect_binding"
 
 module Ace
   module Herdr
@@ -13,29 +17,43 @@ module Ace
           include Ace::Support::Cli::Base
           include Runtime
 
-          desc "Enqueue, inspect, deliver, or reconcile a durable agent inbox event"
-          argument :operation, desc: "enqueue, status, deliver, or reconcile"
+          desc "Enqueue, inspect, or deliver a durable agent inbox event"
+          argument :operation, desc: "enqueue, status, or deliver"
+          option :project, type: :string, desc: "Installed project ID"
+          option :mapping, type: :string, desc: "Installed mapping ID"
+          option :inbox_context, type: :string, desc: "Installed inbox context ID"
+          option :claim_generation, type: :integer, desc: "Original expected claim generation"
+          option :assignment, type: :string, desc: "Original assignment ID"
           option :event, type: :string, desc: "Stable event ID"
           option :attempt, type: :string, desc: "Assignment attempt ID"
           option :ref, type: :string, desc: "Herdr reverse-address JSON file"
           option :file, type: :string, desc: "Payload file"
-          option :receipt, type: :string, desc: "Native proof JSON file"
           option :format, type: :string, desc: "Output format (json)"
 
-          def initialize(executor: nil, native: nil)
+          def initialize(executor: nil, native: nil, selection: Molecules::ProtectedInboxSelection.new,
+            context_client_factory: Molecules::InboxContextClient.method(:selected),
+            kernel: Ace::Runtime::Molecules::ProtectedLinux.new)
             @executor = executor
             @native = native
+            @selection, @context_client_factory, @kernel = selection, context_client_factory, kernel
           end
 
           def call(operation: nil, **options)
             inbox = nil
             translate_errors do
+              cli_error("unsupported inbox operation") unless %w[enqueue status deliver].include?(operation)
               cli_error("--event is required") if options[:event].to_s.empty?
               cli_error("only --format json is supported") if options[:format] && options[:format] != "json"
-              inbox = Organisms::Inbox.new(executor: executor,
+              protected = false
+              @selection.with(options) do |selected|
+                next unless selected
+                puts JSON.generate(protected_call(operation, options, selected))
+                protected = true
+              end
+              next if protected
+              inbox = Organisms::Inbox.from_config(config: config, executor: executor,
                 native: @native || Molecules::NativeQueueExecutor.new,
-                deliveries_dir: deliveries_dir,
-                receipt_public_key: %w[enqueue reconcile].include?(operation) ? receipt_public_key : nil)
+                root: Dir.pwd)
               result = case operation
               when "enqueue"
                 %i[attempt ref file].each { |key| cli_error("--#{key} is required") if options[key].to_s.empty? }
@@ -45,24 +63,8 @@ module Ace
                 inbox.status(event: options[:event])
               when "deliver"
                 inbox.deliver(event: options[:event])
-              when "reconcile"
-                path = options[:receipt]
-                begin
-                  bytes = path.to_s.empty? ? nil : File.binread(path)
-                  receipt = bytes && JSON.parse(bytes)
-                  signature = bytes && File.binread("#{path}.sig")
-                rescue SystemCallError, JSON::ParserError => e
-                  # Receipt input is caller-owned: unreadable or malformed
-                  # proof files surface as the documented refusal, never as
-                  # command failures.
-                  puts JSON.generate(inbox.status(event: options[:event]).merge(
-                    "reconciliation_refusal" => "invalid receipt: #{e.message}"))
-                  return
-                end
-                inbox.reconcile(event: options[:event], receipt: receipt,
-                  signed_bytes: bytes, signature: signature)
               else
-                cli_error("operation must be enqueue, status, deliver, or reconcile")
+                cli_error("operation must be enqueue, status, or deliver")
               end
               puts JSON.generate(result)
             end
@@ -70,17 +72,65 @@ module Ace
             raise Ace::Support::Cli::Error, e.message
           end
 
+
           private
 
-          def receipt_public_key
-            path = config["inbox_receipt_public_key"]
-            return nil unless path.is_a?(String) && path.start_with?("/")
+          def protected_call(operation, options, selected)
+            %i[event attempt assignment].each { |key| cli_error("--#{key} is required") if options[key].to_s.empty? }
+            unless %w[enqueue status deliver].include?(operation)
+              cli_error("protected operation requires its maintained direct handler")
+            end
+            allowed = %i[project mapping inbox_context event attempt assignment format]
+            allowed += %i[ref file] if operation == "enqueue"
+            allowed += %i[claim_generation] if %w[deliver].include?(operation)
+            if options.any? { |key, value| !value.nil? && !allowed.include?(key) }
+              cli_error("protected inbox operation options differ")
+            end
+            context = selected.fetch("context")
+            client = @context_client_factory.call(context_id: selected.fetch("inbox_context_id"),
+              socket_path: context.fetch("control_socket_path"), owner_credentials: context.fetch("owner_credentials"))
+            if operation == "status"
+              return client.request("status_context", {"event_id" => options.fetch(:event), "attempt_id" => options.fetch(:attempt), "original" => direct_original(selected, options)}).fetch("record")
+            end
+            if operation == "deliver"
+              unless options[:claim_generation].is_a?(Integer) && options[:claim_generation] >= 0
+                cli_error("--claim-generation must be an explicit nonnegative integer")
+              end
+              admission = direct_admission(client, selected, options, "deliver")
+              result = client.request("deliver_context", {"operation_id" => admission.fetch("operation_id"),
+                "key_generation" => admission.fetch("key_generation"), "event_id" => options.fetch(:event),
+                "attempt_id" => options.fetch(:attempt), "original" => direct_original(selected, options), "expected_claim_generation" => options.fetch(:claim_generation)})
+              unless %w[idle unknown].include?(result["admission_state"])
+                cli_error("direct delivery admission observation differs")
+              end
+              client.request("end_context_operation", {"operation_id" => admission.fetch("operation_id")}) if result.fetch("admission_state") == "idle"
+              return result.fetch("record").merge("admission_state" => result.fetch("admission_state"))
+            end
+            %i[ref file].each { |key| cli_error("--#{key} is required") if options[key].to_s.empty? }
+            reverse = Molecules::InboxCliInput.reverse(options.fetch(:ref))
+            payload = Molecules::InboxCliInput.read(options.fetch(:file), limit: 65_536).dup.force_encoding(Encoding::UTF_8)
+            cli_error("payload encoding differs") unless payload.valid_encoding? && !payload.include?("\0")
+            admission = direct_admission(client, selected, options, "enqueue")
+            result = client.request("enqueue_context", {"operation_id" => admission.fetch("operation_id"),
+              "key_generation" => admission.fetch("key_generation"), "event_id" => options.fetch(:event),
+              "attempt_id" => options.fetch(:attempt), "original" => direct_original(selected, options), "reverse" => reverse, "payload_bytes" => payload.bytesize,
+              "payload_sha256" => Digest::SHA256.hexdigest(payload)}, payload: payload)
+            client.request("end_context_operation", {"operation_id" => admission.fetch("operation_id")})
+            result.fetch("record").merge("admission_state" => result.fetch("admission_state"))
+          end
+
+          def direct_original(selected, options)
+            value = selected.slice("project_id", "mapping_id", "inbox_context_id").merge("assignment_id" => options.fetch(:assignment))
+            Molecules::InboxDirectEffectBinding.original!(value)
+          end
 
-            key = OpenSSL::PKey.read(File.read(path))
-            key if key.is_a?(OpenSSL::PKey::RSA) && !key.private?
-          rescue SystemCallError, OpenSSL::PKey::PKeyError
-            nil
+          def direct_admission(client, selected, options, purpose)
+            peer = @kernel.capture(Process.pid)
+            client.request("begin_context_operation", {"context_id" => selected.fetch("inbox_context_id"),
+              "purpose" => purpose, "event_id" => options.fetch(:event), "process_binding" => peer,
+              "original" => direct_original(selected, options).merge("attempt_id" => options.fetch(:attempt))})
           end
+
         end
       end
     end

data/lib/ace/herdr/cli/commands/native_source.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+require_relative "support"
+require_relative "../../molecules/native_source"
+require_relative "../../organisms/native_source_builder"
+
+module Ace
+  module Herdr
+    module CLI
+      module Commands
+        class NativeSource < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include Runtime
+
+          desc "Describe, build, or verify the packaged guarded native source without running Herdr"
+          argument :operation, desc: "selection, build, or verify"
+          option :source, type: :string, desc: "Clean local Git checkout containing the pinned baseline"
+          option :output, type: :string, desc: "New build artifact directory"
+          option :target, type: :string, desc: "Selected Linux target"
+          option :artifact, type: :string, desc: "Build artifact directory to verify"
+
+          def initialize(selection: nil, builder: nil)
+            @selection = selection
+            @builder = builder
+          end
+
+          def call(operation: nil, **options)
+            selection = @selection || Molecules::NativeSource.new
+            supplied = options.select { |key, value| %i[source output target artifact].include?(key) && !value.nil? }.keys
+            result = case operation
+            when "selection"
+              cli_error("selection accepts no build/artifact options") unless supplied.empty?
+              selection.description
+            when "verify"
+              cli_error("verify requires only --artifact") unless supplied == [:artifact] && !options[:artifact].empty?
+              selection.verify_artifact(directory: options.fetch(:artifact))
+            when "build"
+              unless supplied.sort == %i[output source target] && supplied.all? { |key| !options[key].empty? }
+                cli_error("build requires --source, --output and --target")
+              end
+              builder = @builder || Organisms::NativeSourceBuilder.new(selection: selection)
+              builder.build(source: options.fetch(:source), output: options.fetch(:output), target: options.fetch(:target))
+            else
+              cli_error("native-source operation must be selection, build, or verify")
+            end
+            puts JSON.generate(result)
+          rescue Molecules::NativeSource::Error => error
+            raise Ace::Support::Cli::Error, error.message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/herdr/cli/commands/support.rb

@@ -30,12 +30,8 @@ module Ace
           # fail closed (spec 8wm.t.vrz §3)
           def resolve_ref(session, pane)
             Ace::Hitl::Providers::Ref.new(
-              session: Ace::Hitl::Providers::Ref.validate!(
-                session || ENV["HERDR_SESSION"], "HERDR_SESSION"
-              ),
-              pane: Ace::Hitl::Providers::Ref.validate!(
-                pane || ENV["HERDR_PANE"], "HERDR_PANE"
-              )
+              session: session || ENV["HERDR_SESSION"], pane: pane || ENV["HERDR_PANE"],
+              session_source: "HERDR_SESSION", pane_source: "HERDR_PANE"
             )
           end
 

data/lib/ace/herdr/cli.rb

@@ -15,6 +15,7 @@ require_relative "cli/commands/capture"
 require_relative "cli/commands/workspace"
 require_relative "cli/commands/tab"
 require_relative "cli/commands/list_presets"
+require_relative "cli/commands/native_source"
 
 module Ace
   module Herdr
@@ -29,6 +30,7 @@ module Ace
         ["deliver", "Push an answer to an agent pane (ace-hitl delivery contract)"],
         ["inbox", "Durable agent message queue and reconciliation"],
         ["dispatch", "Start an agent in one command: tab + agent + prompt"],
+        ["native-source", "Describe, build, or verify the packaged guarded native source"],
         ["list", "List live panes, tabs, or workspaces as one JSON line"],
         ["send", "Send a command, raw text, or named keys to a pane"],
         ["capture", "Print recent pane output as raw text"],
@@ -69,6 +71,7 @@ module Ace
       register "deliver", CLI::Commands::Deliver.new
       register "inbox", CLI::Commands::Inbox.new
       register "dispatch", CLI::Commands::Dispatch.new
+      register "native-source", CLI::Commands::NativeSource.new
       register "list", CLI::Commands::List.new
       register "send", CLI::Commands::Send.new
       register "capture", CLI::Commands::Capture.new

data/lib/ace/herdr/errors.rb

@@ -2,6 +2,29 @@
 
 module Ace
   module Herdr
+    class Error < StandardError; end
+
+    # Raised when the caller's herdr workspace/session/pane cannot be resolved
+    class TargetResolutionError < Error; end
+
+    # Raised when arguments or refs fail validation
+    class ValidationError < Error; end
+
+    # Raised when a bounded wait exceeds its timeout
+    class WaitTimeoutError < Error; end
+
+    # Raised when a preset tab was created natively but a later
+    # materialization step (splits, commands, agents) failed; carries the
+    # created tab id so the owner can roll back exactly that tab.
+    class TabMaterializationError < Error
+      attr_reader :tab_id
+
+      def initialize(tab_id:, message:)
+        @tab_id = tab_id
+        super(message)
+      end
+    end
+
     # Base for herdr CLI executor failures; retry classification drives the
     # ace-hitl DeliverResult state mapping (retryable vs terminal).
     class ExecutorError < Error