ace-herdr 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3c832e03a65b1e294f84d843966554e2018db81ec39a13ed508d4f68bb8ae07
-  data.tar.gz: 2c7170d346c932c50c2d881fb528733bee63b2fa79073340ad64a8c2036f8e9e
+  metadata.gz: 204e5cf8135c02f3feea7086b05a2b3dad61470261dbd526a05b900dd1f5e558
+  data.tar.gz: b362791611a61f9340055ad044383dd4585b2d5821ffc1d28a4e7356dd6ab6b1
 SHA512:
-  metadata.gz: c9c513a7de5c8224c73e597f133b70ed6a99aa70f70292d7c1774b789ac3a2b570f5452f19e35cbd780c29fb392edd683da46ddf2a3256035bd911bc16533cbd
-  data.tar.gz: 071d1908f3bd701b9b516d5d7100f68a830b7eb2cd153129660c66afb08730e2f135127daf68326186479c93e6a58d4de294361293f07d561fb156aa6d19881a
+  metadata.gz: 8c564329116783969ae79dc7256f8a414591e308d18b3b8772b751ac1efea5d07b8f4758ee34b23134b50631a571e01d48d7872b20c8510fb637d019f6889b42
+  data.tar.gz: 7a1be61896fff3f5ca58c7ee00d2c4fa0633e935805c2cd466ceaad12b4a4a3bf04cbf02d7cca7bd43bf3edf28196feb190b14e3282fe736a8e6137e5918a45f

data/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to `ace-herdr` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.10.0] - 2026-11-10
+
+### Added
+
+- Launch ordinary agents with an explicit private JSON environment file, without exposing credentials in terminal commands. Preserve real pane/session identity and refuse cold auto-resume without the original environment. Retain protected installed extensions and package reproducible native source builds for Linux ARM64, including cross-building on macOS.
+
 ## [0.9.0] - 2026-10-30
 
 ### Changed

data/docs/native-source.md

@@ -0,0 +1,44 @@
+# Building the selected native Herdr
+
+`ace-herdr native-source selection` reports the source commit, tree and patch
+digest packaged with this gem. The patch retains ordinary prompt/terminal
+identity fixes and adds explicit process environments. It does not install an
+issuer, systemd session launcher or separate operating-system identity.
+
+Build with the public owner command:
+
+```sh
+ace-herdr native-source build --source /absolute/clean/herdr-checkout \
+  --output /absolute/new/artifact-directory --target aarch64-unknown-linux-musl
+ace-herdr native-source verify --artifact /absolute/new/artifact-directory
+```
+
+The build runs as a nonroot user on Linux or macOS. Install the selected Rust
+toolchain, its target standard library, and the selected Zig version first.
+Use actual tool executables in `PATH`, rather than shims which resolve another
+version. The packaged linker invokes that same pinned Zig for the selected
+Linux target; a VM and a separate cross compiler are unnecessary. Output
+contains the ELF executable and its source/toolchain/byte provenance. A failed
+build retains its output directory for diagnosis and never overwrites it.
+
+The selected native CLI accepts `herdr agent start … --env-file /absolute/env.json`.
+The file must be a regular, non-symlink file owned by the process user with mode
+`0600`, containing a JSON object of environment variable names and string values.
+The ordinary child process receives that environment, plus native terminal
+identity (`HERDR_*` pane/workspace/socket fields and the ACE pane/session aliases).
+Ambient credentials are cleared. File contents are never submitted to the
+terminal or returned in the start response. The caller removes the file after
+startup returns. With `ACE_SESSION_CREDENTIALS_DIRECTORY` equal to
+`PI_CODING_AGENT_DIR`, a same-user `0700` directory named `ace-session-*`, the
+ordinary helper waits for the child and removes only `auth.json` on exit or
+failed startup. Session evidence remains. TERM/HUP are forwarded to the child;
+terminal Ctrl-C reaches its existing foreground process group. An uncatchable
+kill can leave credentials behind, so the assignment/coordinator owner must
+reconcile them before replacing a dead session. This is cleanup between trusted
+processes, not isolation between hostile processes sharing the same user.
+
+Cold server restoration keeps such a pane visibly unavailable until its
+coordinator supplies a fresh environment. It never resumes an agent through
+an ambient shell. Live terminal handoff preserves the already-running process.
+
+Host tests and a cross-built ELF do not establish live ARM64 lab acceptance.

data/docs/usage.md

@@ -70,6 +70,24 @@ by the number of deliveries.
 
 ## Dispatch, send, capture, wait, close
 
+`dispatch` starts an ordinary process in `--cwd`. For an explicitly selected
+environment, pass `--env-file` with an absolute path to a private (`0600`) JSON
+object of string variables. The native launcher clears ambient variables and
+reads this file without placing its values in terminal commands or prompts.
+`--role` labels the commission; it does not grant operating-system privileges.
+
+```sh
+ace-herdr dispatch --label review-task --role verifier --cwd /lab/ace/.ace-wt/task-1 --env-file /private/role-environment.json --prompt-file commission.md
+```
+
+Installed Linux deployments use the protected extensions configured by
+`ace-lab`. Missing required runtime or extension files block startup. Sessions
+of the same user are trusted peers, not a hostile-code sandbox. For task work,
+use `ace-overseer work-on` or `handoff`: these own commission identity, duplicate
+protection and report-driven retirement. A low-level dispatch alone is not an
+assignment lifecycle.
+
+
 ```bash
 ace-herdr dispatch --label t.123 --kind pi --prompt-file prompt.md
 ace-herdr dispatch --label review --pane p7 --cwd /Users/me/project
@@ -87,6 +105,11 @@ prompt semantics: text becomes one self-submitting agent prompt, and a single
 trailing Enter is dropped and reported. A command must be declared before any
 key.
 
+For the native `herdr agent prompt` command, `--wait` without `--until`
+waits for a settled state. Use `--wait --until working --until blocked` to
+wait for observed activity instead. A stalled or timed-out prompt has an
+uncertain delivery outcome; inspect the existing agent before retrying.
+
 ## Workspaces, tabs, and presets
 
 Presets resolve through the ADR-022 cascade (`.ace/herdr/` > `~/.ace/herdr/` >

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

@@ -26,6 +26,8 @@ module Ace
           ]
 
           option :label, type: :string, desc: "Agent and pane label (typically the task id)"
+          option :role, type: :string, desc: "Executor role label"
+          option :env_file, type: :string, desc: "Private JSON file containing the executor environment"
           option :kind, type: :string, desc: "Agent kind (default: config default_agent_kind)"
           option :workspace, type: :string, desc: "Target workspace (default: caller's workspace)"
           option :pane, type: :string, desc: "Existing pane (default: create a new tab)"
@@ -50,7 +52,7 @@ module Ace
               outcome = dispatcher.dispatch(
                 label: options.fetch(:label), prompt: prompt,
                 kind: options[:kind], workspace_id: options[:workspace],
-                pane: options[:pane], cwd: options[:cwd]
+                pane: options[:pane], cwd: options[:cwd], role: options[:role], env_file: options[:env_file]
               )
               puts JSON.generate(outcome.to_h)
             end

data/lib/ace/herdr/molecules/herdr_executor.rb

@@ -5,6 +5,7 @@ require "open3"
 require "json"
 require "timeout"
 require_relative "bounded_process"
+require_relative "installed_pi_extensions"
 
 module Ace
   module Herdr
@@ -23,6 +24,10 @@ module Ace
           @process = process
         end
 
+        def agent_list
+          run!([@binary, "agent", "list"])
+        end
+
         # Probe the agent living in a pane (raises AgentNotFoundError when none)
         def agent_get(pane)
           run!([@binary, "agent", "get", pane])
@@ -55,9 +60,13 @@ module Ace
         # `args` are harness passthrough arguments forwarded verbatim
         # after `--` (e.g. pi's --model/--thinking/--append-system-prompt;
         # the overseer start contract, 8xs.t.pu0.1).
-        def agent_start(name:, kind:, pane:, timeout_ms:, args: [])
+        def agent_start(name:, kind:, pane:, timeout_ms:, args: [], env_file: nil)
+          managed = kind == "pi" ? InstalledPiExtensions.arguments : []
+          InstalledPiExtensions.reject_override!(args) unless managed.empty?
+          args = managed + args
           cmd = [@binary, "agent", "start", name, "--kind", kind,
             "--pane", pane, "--timeout", timeout_ms.to_s]
+          cmd += ["--env-file", env_file] if env_file
           cmd += ["--", *args] unless args.empty?
           run!(cmd)
         end
@@ -66,12 +75,14 @@ module Ace
         # rejects blocked agents pre-send with agent_blocked. With
         # wait: herdr's activity gate applies — a prompt sent from a
         # non-working state must produce observed working/blocked
-        # activity, so success confirms the turn actually began
-        # (agent_prompt_stalled / timeout otherwise; timeout_ms bounds
-        # the wait).
-        def agent_prompt(pane:, text:, wait: false, timeout_ms: nil)
+        # activity before waiting for the requested state. With no explicit
+        # states the native default waits for idle, done or blocked.
+        def agent_prompt(pane:, text:, wait: false, timeout_ms: nil, until_states: nil)
+          raise ArgumentError, "until_states requires wait" if until_states && !wait
+
           cmd = [@binary, "agent", "prompt", pane, text]
           cmd += ["--wait"] if wait
+          Array(until_states).each { |state| cmd += ["--until", state] }
           cmd += ["--timeout", timeout_ms.to_s] if timeout_ms
           run!(cmd)
         end

data/lib/ace/herdr/molecules/installed_pi_extensions.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "find"
+require "yaml"
+require "ace/runtime"
+require "ace/runtime/molecules/protected_socket"
+require_relative "../errors"
+
+module Ace
+  module Herdr
+    module Molecules
+      # Installed Linux lab agents load only host-managed Pi extensions.
+      # The existing root-owned lab manifest declares their location; no
+      # second registry or agent-writable discovery path is introduced.
+      module InstalledPiExtensions
+        MANIFEST_DIR = "/etc/lab/ace-lab"
+        MANIFEST = "#{MANIFEST_DIR}/install.yml"
+        module_function
+
+        def arguments(env: ENV, manifest: MANIFEST, manifest_dir: MANIFEST_DIR, platform: RUBY_PLATFORM)
+          return [] unless env["ACE_TOOLCHAIN"] == "installed" && platform.include?("linux")
+          return [] unless File.exist?(manifest_dir) || File.symlink?(manifest_dir)
+
+          guard = Ace::Runtime::Molecules::ProtectedSocket
+          guard.root_path!(manifest, directory: false)
+          raise ExecutorUnavailableError, "installed lab manifest is not a regular file" unless File.file?(manifest)
+          document = YAML.safe_load(File.read(manifest), permitted_classes: [], aliases: false)
+          rows = document.is_a?(Hash) && document.dig("gemset", "extensions")
+          matches = rows.is_a?(Array) ? rows.select { |row| row.is_a?(Hash) && row["gem"] == "ace-wake" } : []
+          raise ExecutorUnavailableError, "installed lab must declare exactly one ace-wake extension path" unless matches.size == 1
+          root = matches.fetch(0)["path"]
+          guard.root_path!(root, directory: true)
+          wake = File.join(root, "ace-wake")
+          guard.root_path!(wake, directory: true)
+          Find.find(wake) do |path|
+            stat = File.lstat(path)
+            unless (stat.file? || stat.directory?) && !stat.symlink? && stat.uid.zero? && (stat.mode & 0o022).zero?
+              raise ExecutorUnavailableError, "installed ace-wake contains an unsafe path"
+            end
+          end
+          entry = File.join(wake, "index.js")
+          integration = File.join(root, "herdr-agent-state.ts")
+          [entry, integration].each do |path|
+            guard.root_path!(path, directory: false)
+            raise ExecutorUnavailableError, "installed Pi extension is not a regular file" unless File.file?(path)
+          end
+          ["--no-extensions", "--extension", entry, "--extension", integration]
+        rescue Ace::Runtime::Error, SystemCallError, Psych::Exception, TypeError, ArgumentError
+          raise ExecutorUnavailableError, "installed Pi extension configuration is unavailable or unsafe"
+        end
+
+        def reject_override!(args)
+          return if args.none? { |arg| arg.is_a?(String) && (arg == "--no-extensions" || arg == "-ne" || arg.start_with?("--extension=") || arg == "--extension" || arg.start_with?("-e")) }
+
+          raise ExecutorUnavailableError, "installed lab Pi extension arguments cannot be overridden"
+        end
+      end
+    end
+  end
+end