ace-hitl 0.24.3 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d4e7dd5c819e98ea18006c02d1d6e587857d4889f91bd4d42fc2d0e26461d9d
-  data.tar.gz: 4a05d425d80b079f03800fa9f7277412d8a2218f4b56d11a624df50baf4325eb
+  metadata.gz: f9115490bffe274fbc591fc0c0c3efb826c70fe549b17e7d57b5928e298ffe23
+  data.tar.gz: e14fa6ef9c4251fcad792f2c8cbdd362fe642b9c66dc7060fa621e6785f65d0a
 SHA512:
-  metadata.gz: 292cafb6c572d818b1c0a3988a36bd588303dacfa357a585fa0166430db74e61c682ad1d45242dc44be9943110c3cf45546f9f965aee7861e75b10862b2559b2
-  data.tar.gz: 03b92ef04274f643f84f2868d19f021ff4e72f0add38d164e4e11657ee1c532571aeb6751ab29b5fe67d8475a23352e195cf8f284b347985554a02f881c8d984
+  metadata.gz: b8f52aef4b90d868a62e1966523282ea1a74eabe20930034736e1a73a941c701df4c4580297659ea8c5255dc45676cf3f37b466c934faa5ce7d71e10cc2d4a5f
+  data.tar.gz: 202ca6825f02dcaec4da9fce88aaeef2ca66c33f98ef6cf51daa6585ec552dc7eeff8cfb3556ad35881aa0ccfa3cb13fc7653b68077a0ffbfcddbbf5b6e6f686

data/CHANGELOG.md

@@ -5,7 +5,61 @@ All notable changes to `ace-hitl` 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.25.0] - 2026-10-30
+
+### Fixed (review rounds 3/3b + re-review R2)
+
+- Case writes are crash-atomic under a stable sidecar lock (`<case>.lock`)
+  through the shared `Molecules::CaseFileWriter`: every writer path (reply,
+  suggestion, lesson, lifecycle, field updates, delivery persistence,
+  resume notes) holds the sidecar across tmp+fsync+rename — the
+  flock+rename lost-update race, the in-place `truncate(0)` field update
+  (a killed process could zero the case and lose the answer; SIGKILL
+  regression test added), and unlocked writer paths are closed. Terminal
+  cases (closed/cancelled) refuse new answers, suggestions and lessons;
+  history capture is section-scoped; `history --format table`/`--quiet`
+  are real. Case files are created 0600 and every tmp write
+  is 0600 before rename; corrupt-file parses refuse with a named error
+  (Psych::Exception aligned across paths).
+
+### Added
+
+- `ace-hitl lesson` + `HitlManager#add_lesson` and `ace-hitl history` +
+  `#decision_history` (task 8xs.t.pu0.c): learning from real decisions — one
+  Lesson section per case citing exact question/suggestion/decision
+  revisions (idempotent, never overwriting history, requiring a suggestion
+  to compare against), and a citable, scope-local, secret-free decision
+  history for the next suggestion.
+
+- `ace-hitl suggest` and `HitlManager#add_suggestion` (task 8xs.t.pu0.b): the
+  Second Captain's marked advisory proposal — own section before the Answer
+  (survives answer rewrites), author/rationale/grounds recorded, one per case
+  (identical repeat = duplicate), refused on answered or secret cases, never
+  an answer or approval.
+
+- `ace-hitl ask --secret` (task 8xs.t.pu0.9): the expected answer (e.g. an
+  OTP) is marked secret AT CREATION — no title heuristics; the case carries
+  `secret: true` and the armed wake request flags the bridge to wake with the
+  case reference only, never the value.
+
+- Case lifecycle (task 8xs.t.pu0.6): `ace-hitl apply CASE --ref OWNER_REF`
+  records the applied effect with its owner reference (idempotent per
+  reference, conflicting references rejected), `ace-hitl close CASE` is
+  terminal only after the applied proof (duplicate no-op, closed cases never
+  re-open), `cancel_case` terminates without application, and
+  `ace-hitl sweep [--apply]` lists/removes ONLY the ask-wake request
+  leftovers of terminally closed/cancelled cases — active cases, unknown
+  ids and the canonical decision history are always preserved. Lifecycle
+  state lives in the canonical case file (receipt pending/received,
+  application pending/applied/closed/cancelled); transitions are locked and
+  conflict-rejecting.
+
+- `ace-hitl reply CASE_ID --stdin` (task 8xs.t.pu0.5): receiver-side answer
+  delivery on the owner's machine. Output carries only the case and its state
+  (`received`/`duplicate`); the reference must be the exact case id (no
+  shortcut/latest resolution), identical redelivery is idempotent without a
+  rewrite, a conflicting answer never overwrites the decision, and empty
+  answers/reports/unknown references fail as explicit non-deliveries.
 
 ## [0.24.3] - 2026-10-29
 

data/docs/usage.md

@@ -326,8 +326,13 @@ HITL event 8xhkep sent through 1 route(s):
 8xhkep
 ```
 
-The final stdout line is always the bare case id. ask never blocks and never
-polls, carries no urgency language, and has no asker-side timeouts — the
+The final stdout line is always the bare case id. `--secret` marks the
+EXPECTED answer as a secret (e.g. an OTP) at creation — the armed wake then
+carries the CASE REFERENCE ONLY (the value never passes through the model;
+the executor reads it from the case file through its secure channel), and a
+rejected or expired secret answer needs a NEW case, never a replay. ask
+never blocks and never polls, carries no urgency language, and has no
+asker-side timeouts — the
 Captain replies whenever he wants. The answer is delivered TO the agent as
 an ace-wake wake carrying the answer content (see the ace-wake README's ask
 bridge contract); on wake, the agent acts immediately.
@@ -339,6 +344,102 @@ asynchronous). Exit 1 only for genuine rejects (a route refusing the
 frame, or a concrete configuration error); no wake request is dropped for
 a rejected ask.
 
+## Reply
+
+`ace-hitl reply CASE_ID --stdin` (task 8xs.t.pu0.5) is the receiver-side
+half of answer delivery: the transport (Hermes) runs it ON THE OWNER'S
+MACHINE, in the owner's directory, with the answer text on stdin — never
+as a shell command or an argv element:
+
+```bash
+echo "Proceed with batch 2" | ace-hitl reply 8xhkep --stdin
+{"case":"8xhkep","state":"received"}
+```
+
+- The output names ONLY the case and its state: `received`, or `duplicate`
+  when the identical answer is redelivered (idempotent — the case file is
+  never rewritten). Success means ace-hitl confirmed the DURABLE write; a
+  reply frame sitting in a transport is not delivery.
+- The reference must be the case's EXACT id from the ask — no shortcut or
+  latest-match resolution, so a reply can never land in a foreign case on
+  collision.
+- Every failure is an explicit non-delivery with no side effects: an empty
+  answer, a report instead of a question, a conflicting (different)
+  answer — a reply never overwrites a human decision — or an unknown
+  reference all exit 1 without writing.
+- The receiver does not need to be running: the answered case file is the
+  durable record; the armed ask wake consumes the change whenever the
+  asking session returns.
+
+## Suggest (Second Captain)
+
+`ace-hitl suggest CASE_ID --by AUTHOR --text ... --rationale ... [--refs a,b]`
+(task 8xs.t.pu0.b): the advisory Second Captain's MARKED proposal — its own
+`## Suggestion` section in the exact case, with author, timestamp, grounds,
+proposal and rationale, inserted BEFORE the `## Answer` section so an answer
+rewrite can never remove it. It is not an Answer, never satisfies a gate,
+and never acts in the human's name: the human decision always outranks it.
+
+- One proposal per case: an identical repeat reports `duplicate` (no-op); a
+  different second proposal is refused.
+- A case the human already answered refuses the suggestion ("discard the
+  late suggestion") without writing; a case marked `secret` (OTP) is never
+  delegated to the advisor.
+- Shortcuts/unknown ids are refused exactly like `reply`.
+
+## Lesson & History (Second Captain learning)
+
+`ace-hitl lesson CASE_ID --by AGENT --relation accepted|rejected|modified
+--takeaway ...` (task 8xs.t.pu0.c): after the human answers a case that
+carried a suggestion, the advisory agent writes ONE `## Lesson` section at
+the same case — its comparison takeaway with references to the exact
+question/suggestion/decision revisions, its own author and time. The lesson
+never overwrites the question, suggestion or decision, never changes the
+answer's author, and reprocessing is idempotent (an identical repeat is a
+`duplicate`; a second different lesson is refused). A case without a
+suggestion has nothing to compare — refused, never a fabricated agreement.
+
+`ace-hitl history [--scope current] [--limit N]`: the citable decision
+history for the NEXT suggestion — answered, NON-SECRET question cases of
+this scope, each row with its checkable references (case id, suggestion,
+decision, lesson+relation). Secret/OTP cases are filtered out before
+anything reaches a model; there is no embedding store, decision index, or
+corpus copy — HITL stays the single source, and the wider lab overseer's
+access is not a license to share other projects' history.
+
+## Case lifecycle
+
+The canonical case file carries the whole lifecycle (task 8xs.t.pu0.6) —
+there is no second registry:
+
+- receipt: `pending` → `received` (the answer was durably delivered);
+- application: `pending` → `applied` → `closed`, or `cancelled` (terminal
+  without application). Reports stay `recorded` — they never await an
+  answer or application.
+
+```bash
+ace-hitl apply 8xhkep --ref pr:398   # the effect owner reference verified by the consumer
+ace-hitl close 8xhkep                # terminal, only after the applied proof
+ace-hitl sweep                       # list transport leftovers of terminal cases
+ace-hitl sweep --apply               # remove ONLY the proven leftovers
+```
+
+Exactly-once belongs to the EFFECT, not the notification count: after a
+crash between effect and `applied`, the consumer first re-checks the effect
+at its owner (PR/release/assignment); an undecidable outcome is an explicit
+reconciliation block, never a blind retry. Re-applying the same effect
+reference is a no-op (`duplicate`); a different reference for an applied
+case is a conflict. A duplicate close is a no-op. A late different answer
+was already rejected at delivery, and a closed case never re-opens — an
+explicit decision change needs a NEW case.
+
+`ace-hitl sweep` qualifies the ask-wake request files against the canonical
+cases: deletion candidates are ONLY requests whose case is terminally
+`closed` or `cancelled`. Active cases (pending/received/applied), unknown
+ids, unparseable requests and the canonical decision history (including the
+history Second Captain learns from) are always preserved; without `--apply`
+the command only lists.
+
 ## Lifecycle event names
 
 HITL lifecycle signals use this namespace:

data/lib/ace/hitl/cli/commands/apply.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # `ace-hitl apply CASE --ref OWNER_REF` (task 8xs.t.pu0.6):
+        # record that the answer's effect was applied, WITH the
+        # reference to the effect owner (task/assignment/PR) the
+        # consumer verified first. Exactly-once belongs to the effect:
+        # after a crash the consumer re-checks the effect at its owner
+        # before calling this; an undecidable outcome is an explicit
+        # reconciliation block, never a blind retry. Close happens only
+        # after this proof exists.
+        class Apply < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Record the answer's applied effect with its owner reference"
+
+          example ['ace-hitl apply 8xhkep --ref pr:398']
+
+          argument :case_id, required: true, desc: "Exact HITL case id"
+
+          option :ref, type: :string, required: true,
+            desc: "Effect owner reference (task/assignment/PR) verified by the consumer"
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+
+          def call(case_id:, ref:, **)
+            state = Ace::Hitl::Organisms::HitlManager.new.apply_answer_effect(case_id, ref)
+            puts JSON.generate({"case" => case_id, "state" => state.to_s})
+          rescue Ace::Hitl::Organisms::HitlManager::UnknownCaseError,
+            Ace::Hitl::Organisms::HitlManager::AmbiguousReferenceError,
+            Ace::Hitl::Organisms::HitlManager::NotAnswerableError,
+            Ace::Hitl::Organisms::HitlManager::LifecycleTransitionError => e
+            raise Ace::Support::Cli::Error.new("not applied: #{e.message}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli/commands/ask.rb

@@ -36,6 +36,8 @@ module Ace
           option :question, type: :string, repeat: true, aliases: %w[-Q], desc: "Question line (repeatable)"
           option :task, type: :string, desc: "Task reference"
           option :tags, type: :string, aliases: %w[-T], desc: "Comma-separated tags"
+          option :secret, type: :boolean, default: false,
+            desc: "The expected answer is a secret (e.g. OTP): the wake carries the case reference only, never the value"
 
           option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
           option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
@@ -78,7 +80,8 @@ module Ace
               type: "question",
               task: options[:task],
               questions: Array(options[:question]).map(&:strip).reject(&:empty?),
-              tags: parse_tags(options[:tags])
+              tags: parse_tags(options[:tags]),
+              secret: options[:secret] == true
             )
           end
 
@@ -111,8 +114,11 @@ module Ace
 
           # Drop the wake request the ace-wake extension consumes through its
           # own reconcile pass and turns into a scoped watch on the case file:
-          # when the answer lands, the wake carries the answer content. The
-          # atomic replace keeps the consumer from reading a torn request.
+          # when the answer lands, the wake carries the answer content —
+          # EXCEPT for a secret ask (8xs.t.pu0.9), where the wake carries the
+          # case reference only and the executor reads the value from the
+          # case file through its secure channel. The atomic replace keeps
+          # the consumer from reading a torn request.
           def arm_wake(event, manager)
             requests_dir = File.join(File.expand_path(manager.root_dir), "wake-requests")
             FileUtils.mkdir_p(requests_dir)
@@ -122,6 +128,7 @@ module Ace
               "case_id" => event.id,
               "case_path" => File.expand_path(event.file_path)
             }
+            request["secret"] = true if event.metadata["secret"] == true
             temporary = File.join(requests_dir, ".#{event.id}-#{SecureRandom.hex(8)}.tmp")
             final = File.join(requests_dir, "#{event.id}.json")
             File.write(temporary, JSON.generate(request))

data/lib/ace/hitl/cli/commands/close.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # `ace-hitl close CASE` (task 8xs.t.pu0.6): terminal close, only
+        # after the proven applied effect. A duplicate close is a no-op;
+        # a late different answer was already rejected at delivery and a
+        # closed case never re-opens — an explicit decision change needs
+        # a NEW case.
+        class Close < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Close a case terminally after its applied effect"
+
+          example ['ace-hitl close 8xhkep']
+
+          argument :case_id, required: true, desc: "Exact HITL case id"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+
+          def call(case_id:, **)
+            state = Ace::Hitl::Organisms::HitlManager.new.close_case(case_id)
+            puts JSON.generate({"case" => case_id, "state" => state.to_s})
+          rescue Ace::Hitl::Organisms::HitlManager::UnknownCaseError,
+            Ace::Hitl::Organisms::HitlManager::AmbiguousReferenceError,
+            Ace::Hitl::Organisms::HitlManager::LifecycleTransitionError => e
+            raise Ace::Support::Cli::Error.new("not closed: #{e.message}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli/commands/history.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # `ace-hitl history` (task 8xs.t.pu0.c): the citable decision
+        # history for the NEXT Second Captain suggestion — answered,
+        # NON-SECRET question cases of THIS project scope, each row with
+        # its checkable references (case id, suggestion, decision,
+        # lesson). Secret/OTP cases never reach the model; no wider
+        # lab-wide sharing. No embedding store or decision index: HITL
+        # stays the single source.
+        class History < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "List the citable decision history (answered, non-secret cases of this scope)"
+
+          option :scope, type: :string, default: "current", desc: "current or all linked worktrees"
+          option :limit, type: :integer, default: 50, desc: "Maximum rows"
+          option :format, default: "json", desc: "Output format (json, table)"
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+
+          def call(scope: "current", limit: 50, format: "json", quiet: false, **)
+            rows = Ace::Hitl::Organisms::HitlManager.new
+              .decision_history(scope: scope, limit: limit)
+            return if quiet
+
+            if format == "table"
+              puts render_table(rows)
+            else
+              puts JSON.pretty_generate({"history" => rows, "count" => rows.size})
+            end
+          rescue ArgumentError => e
+            raise Ace::Support::Cli::Error.new(e.message)
+          end
+
+          private
+
+          # One row per decided case: the case id, the decision (truncated
+          # to one line for the terminal) and the citable lesson relation.
+          def render_table(rows)
+            return "no decided cases in this scope" if rows.empty?
+
+            lines = ["CASE               DECISION                                     LESSON"]
+            rows.each do |row|
+              decision = row["decision"].to_s.gsub(/\s+/, " ")
+              decision = decision.length > 44 ? "#{decision[0, 43]}…" : decision
+              lesson = row["lesson_relation"].to_s.empty? ? "-" : row["lesson_relation"].to_s
+              lines << format("%-18s %-44s %s", row["id"], decision, lesson)
+            end
+            lines.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli/commands/lesson.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # `ace-hitl lesson CASE_ID --by AGENT --relation accepted|rejected|
+        # modified --takeaway ...` (task 8xs.t.pu0.c): the advisory
+        # agent's takeaway from comparing the accepted human decision
+        # with its own suggestion — one `## Lesson` section at the same
+        # case, referencing the exact question/suggestion/decision
+        # revisions. Never a new decision; never changes the answer's
+        # author; identical repeats are no-ops.
+        class Lesson < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Write the lesson drawn from the human decision vs the suggestion"
+
+          example ['ace-hitl lesson 8xhkep --by second-captain --relation rejected ',
+                   '         --takeaway "Captain prioritized rollout safety over speed"']
+
+          argument :case_id, required: true, desc: "Exact HITL case id"
+
+          option :by, type: :string, required: true, desc: "Advisory agent author identity"
+          option :relation, type: :string, required: true,
+            desc: "accepted | rejected | modified (decision vs suggestion)"
+          option :takeaway, type: :string, required: true, desc: "What the next suggestion should learn"
+          option :refs, type: :string, desc: "Comma-separated extra references"
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+
+          def call(case_id:, by:, relation:, takeaway:, refs: nil, **)
+            state = Ace::Hitl::Organisms::HitlManager.new
+              .add_lesson(case_id, by: by, relation: relation, takeaway: takeaway,
+                refs: refs.to_s.split(",").map(&:strip).reject(&:empty?))
+            puts JSON.generate({"case" => case_id, "lesson" => state.to_s})
+          rescue Ace::Hitl::Organisms::HitlManager::UnknownCaseError,
+            Ace::Hitl::Organisms::HitlManager::AmbiguousReferenceError,
+            Ace::Hitl::Organisms::HitlManager::LessonRefusedError => e
+            raise Ace::Support::Cli::Error.new("lesson refused: #{e.message}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli/commands/reply.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # `ace-hitl reply CASE_ID --stdin` (task 8xs.t.pu0.5): the
+        # receiver-side half of HITL answer delivery. Hermes runs this
+        # command on the OWNER's machine, in the owner's directory, with
+        # a structured payload on stdin — the answer text never becomes
+        # a shell command or an argv element. The output names ONLY the
+        # case and its state: `{"case": ..., "state": "received"}` (a
+        # redelivered identical answer reports `"duplicate"`). Success
+        # means ace-hitl CONFIRMED the durable write — a reply frame
+        # sitting in a transport is not delivery.
+        #
+        # Every failure is an explicit non-delivery with no side effects
+        # on any other case: an empty answer, a report instead of a
+        # question, a conflicting answer, or a reference that is not the
+        # EXACT case id (no shortcut or latest resolution) all fail
+        # without writing.
+        class Reply < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Receive a delivered human answer for one exact case; answer on stdin"
+
+          example [
+            'echo "Proceed with batch 2" | ace-hitl reply 8xtab1cd --stdin'
+          ]
+
+          argument :case_id, required: true, desc: "Exact HITL case id from the ask"
+
+          option :stdin, type: :boolean, required: true, desc: "Read the answer text from stdin"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
+          option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
+
+          def call(case_id:, stdin: nil, **options)
+            unless stdin
+              raise Ace::Support::Cli::Error.new("reply reads the answer from stdin; pass --stdin")
+            end
+
+            answer = $stdin.read.to_s
+            if answer.strip.empty?
+              raise Ace::Support::Cli::Error.new("empty answer; nothing was written")
+            end
+
+            state = Ace::Hitl::Organisms::HitlManager.new.receive_answer(case_id, answer)
+            # Only the case and the outcome — never the answer text.
+            puts JSON.generate({"case" => case_id, "state" => state.to_s})
+          rescue Ace::Hitl::Organisms::HitlManager::UnknownCaseError,
+            Ace::Hitl::Organisms::HitlManager::AmbiguousReferenceError,
+            Ace::Hitl::Organisms::HitlManager::NotAnswerableError,
+            Ace::Hitl::Organisms::HitlManager::AnswerConflictError,
+            Ace::Hitl::Organisms::HitlManager::TerminalCaseError => e
+            raise Ace::Support::Cli::Error.new("not delivered: #{e.message}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli/commands/suggest.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # `ace-hitl suggest CASE_ID --by AUTHOR --text ... --rationale ...`
+        # (task 8xs.t.pu0.b): the Second Captain's ADVISORY proposal —
+        # one marked section in the exact case, with author, rationale
+        # and grounds. Never an Answer, never a human approval, never a
+        # gate release. Identical repeats are no-ops; a second different
+        # proposal, a secret case, or a case the human already answered
+        # are explicit refusals without side effects.
+        class Suggest < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Write the Second Captain's marked advisory suggestion into one exact case"
+
+          example ['ace-hitl suggest 8xhkep --by second-captain --text "Proceed" ',
+                   '         --rationale "tests green, review accept at same head" --refs pr:398']
+
+          argument :case_id, required: true, desc: "Exact HITL case id"
+
+          option :by, type: :string, required: true, desc: "Advisory author identity"
+          option :text, type: :string, required: true, desc: "Proposed answer text"
+          option :rationale, type: :string, required: true, desc: "Why this proposal is defensible"
+          option :refs, type: :string, desc: "Comma-separated grounds references"
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+
+          def call(case_id:, by:, text:, rationale:, refs: nil, **)
+            state = Ace::Hitl::Organisms::HitlManager.new
+              .add_suggestion(case_id, author: by, text: text, rationale: rationale,
+                refs: refs.to_s.split(",").map(&:strip).reject(&:empty?))
+            puts JSON.generate({"case" => case_id, "suggestion" => state.to_s})
+          rescue Ace::Hitl::Organisms::HitlManager::UnknownCaseError,
+            Ace::Hitl::Organisms::HitlManager::AmbiguousReferenceError,
+            Ace::Hitl::Organisms::HitlManager::SuggestionRefusedError,
+            Ace::Hitl::Organisms::HitlManager::TerminalCaseError => e
+            raise Ace::Support::Cli::Error.new("suggestion refused: #{e.message}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli/commands/sweep.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # `ace-hitl sweep [--apply]` (task 8xs.t.pu0.6): qualify transport
+        # leftovers against the CANONICAL case files, list-first. The
+        # only deletion candidates are ask-wake request files whose case
+        # is terminally closed or cancelled; active cases (pending /
+        # received / applied), unknown ids, unparseable requests and the
+        # canonical decision history are always preserved. Without
+        # --apply nothing is deleted.
+        class Sweep < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "List (and with --apply, remove) transport leftovers of terminally closed cases"
+
+          option :apply, type: :boolean, default: false,
+            desc: "Remove the qualified leftovers (default: list only)"
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+
+          def call(apply: false, **)
+            report = Ace::Hitl::Organisms::HitlManager.new.sweep(apply: apply)
+            puts JSON.pretty_generate(report)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli.rb

@@ -4,6 +4,13 @@ require "ace/support/cli"
 require_relative "../hitl/version"
 require_relative "cli/commands/create"
 require_relative "cli/commands/ask"
+require_relative "cli/commands/reply"
+require_relative "cli/commands/apply"
+require_relative "cli/commands/close"
+require_relative "cli/commands/sweep"
+require_relative "cli/commands/suggest"
+require_relative "cli/commands/lesson"
+require_relative "cli/commands/history"
 require_relative "cli/commands/send"
 require_relative "cli/commands/operator_question"
 require_relative "cli/commands/read"
@@ -43,7 +50,14 @@ module Ace
         ["cancel", "Cancel one HITL relay request with an audited reason"],
         ["pending", "List answerable HITL relay requests (transport)"],
         ["states", "List public HITL lifecycle projections (transport)"],
-        ["duty", "Project pending and escalated HITL requests (transport)"]
+        ["duty", "Project pending and escalated HITL requests (transport)"],
+        ["reply", "Receive a delivered human answer for one exact case (stdin)"],
+        ["suggest", "Write the Second Captain's marked advisory suggestion into one exact case"],
+        ["lesson", "Write the lesson drawn from the human decision vs the suggestion"],
+        ["history", "List the citable decision history (answered, non-secret cases)"],
+        ["apply", "Record the answer's applied effect with its owner reference"],
+        ["close", "Close a case terminally after its applied effect"],
+        ["sweep", "List (and with --apply, remove) transport leftovers of terminal cases"]
       ].freeze
 
       HELP_EXAMPLES = [
@@ -67,6 +81,13 @@ module Ace
       register "observe", CLI::Commands::Observe
       register "update", CLI::Commands::Update
       register "ask", CLI::Commands::Ask
+      register "reply", CLI::Commands::Reply
+      register "apply", CLI::Commands::Apply
+      register "close", CLI::Commands::Close
+      register "sweep", CLI::Commands::Sweep
+      register "suggest", CLI::Commands::Suggest
+      register "lesson", CLI::Commands::Lesson
+      register "history", CLI::Commands::History
       register "send", CLI::Commands::Send
       register "wait", CLI::Commands::Wait
       register "deliver", CLI::Commands::Deliver