[aitrawog]

Summary

Adds the human-in-the-terminal surface to the jetkvm: verb, over the shared,
transport-neutral console engine merged in opencharly/sdk#296 + #304
(github.com/opencharly/sdk v0.2026269.1433, which this PR requires):

• open-terminal / run-command / close-terminal — drive an OPEN shell on
  the controlled machine, reading each command's result by OCR. run-command
  supports sudo, expect assertions, close_terminal, and prompt_anchors
  (a shell-prompt preflight that refuses to type into a pager/menu/login screen).
• luks-unlock — enter a disk-encryption passphrase at the initramfs prompt;
  a wrong passphrase FAILS fast.
• flow — a BOUNDED state machine: continuous OCR-until-condition with NAMED
  outcomes, if/then/else + case/switch, bounded while, reference-screenshot
  outcomes, and auto-resume. A flow's wall-clock budget is derived from the
  dispatch deadline so it stops CLEANLY before the host's never-hang kill.
• boot-order — set the UEFI boot order from inside the OS via efibootmgr
  (list / next / set).

Implemented ONCE in sdk/kit (console_actions.go); this plugin supplies only its
USB-HID ConsoleTransport and the CUE→Go decode (R3).

Schema (SDD) — and the review fixes

• New surface is CUE in schema/jetkvm.cue; params regenerated with
  cue exp gengotypes + the retag transform (byte-reproducible from the schema;
  verified).
• Review fix: the action: doc listed set-audio as action-bearing, but
  set-audio uses int_value (no action). Corrected the doc (and the regenerated
  params comment).
• Review fix: TestSessionMethodsAreMutating now includes flow and
  boot-order.
• Review fix: added pure decode tests (sessionTerminalOpen,
  sessionBootOrder) and refactored those decodes out of the run* wrappers so
  the param→neutral mapping is unit-locked without a device.

How tested

Gate (this repo), from the committed tree at head 839f524:

$ gofmt -l .            # (no output)
$ go build ./...        # exit 0
$ go vet ./...          # exit 0
$ go test ./... -count=1
ok  	github.com/opencharly/plugin-jetkvm/candy/plugin-jetkvm	2.5s
ok  	github.com/opencharly/plugin-jetkvm/candy/plugin-jetkvm/internal/kvmclient	0.0s
$ charly box validate   # OK — 0 warnings, 0 errors

Build is against the PUBLISHED sdk tag (no local replace).

Live — the paths that ran on the real machine. Target: the physical machine
behind the JetKVM (an operator resource, NOT destroyed; the kind:check bed's
local: side is disposable: true). The plugin was host-built from this branch
(CHARLY_REPO_OVERRIDE=…; the host-build stamp names the source path).

Proven live:

• run-command typed into a real shell and read output by OCR:

Local deploy: zk-run-command-live [host (local)]
  PASS  check run a command in the open root shell and read its output via OCR  [zrc-id]  command "cat /etc/os-release | grep ID=" ->
Onarchy 7.2.4-archi-Watanare-T2-3-t2 (tty3)
root@archiso ~ # cat setc/os-release | grep ID=; echo CHARLY_DONE_1_END
1D=…
2 steps: 2 passed, 0 failed, 0 skipped

• flow logged in as root and ran efibootmgr, reading the output
  (zk-flow-live2: flow completed at node "listboot" after 3 step(s)).
• a flow triggered on a reference screenshot with no OCR (zk-ref-match).
• auto-resume detected step2 and started there (zk-resume2).
• the prompt-preflight fix refused a non-shell screen with
  no shell prompt ([~ # $]) is on screen — refusing to type into "".
• the flow wall-clock budget stopped a long flow CLEANLY with evidence rather
  than a mid-node SIGKILL.

Shipped bed GREEN live (head 839f524, against sdk v0.2026269.1433):

$ charly check run jetkvm-console-session
Local deploy: jetkvm-console-session [host (local)]
  PASS  check run-command types into the shell and reads the OS id by OCR (marker-line completion)  [jkcs-run-command]  command "clear; cat /etc/os-release | grep ^ID=" ->
ID=omarch
  PASS  check a flow runs a command and reads its output (marker-line completion; the node acts without a prompt-glyph wait)  [jkcs-flow]  flow completed at node "run" after 1 step(s):
2 steps: 2 passed, 0 failed, 0 skipped

Not proven live (unit-tested only): open-terminal, close-terminal (a bare
Linux console has no GUI terminal to open), the luks-unlock SUCCESS path (the
failure path was proven live), the boot-order dispatch (its decode is unit-
tested; the flow efibootmgr run exercises the flow command action, not
RunBootOrder), and the run-command sudo branch.

Rulebook compliance

• R0 — skills loaded first.
• R1 — the review's action-doc divergence fixed; the install RCA (OCR anchor,
  blind typing, stale marker) fixed in the sdk this consumes.
• R2/R3 — one shared implementation in sdk/kit; the plugin holds only its
  transport + decode.
• R4 — no unbounded retry; the prompt preflight fails fast; the flow is
  bounded. R5 additive. R6 no force-push.
• R8/R9 — params/cue_types_gen.go is reproducible from the schema (verified);
  the plugin was host-built from this branch.
• R10 — the live paths above; the destructive install is an explicit operator
  action.
• ADE — the candy carries its plan:/check: acceptance and a shipped bed.
• B17 — the physical machine is an operator resource; the disposal exception
  is stated above.
• SDD — the schema is the source of truth; the Go params are generated.

Change classification

• Change class: feature (new verbs + CUE schema + regenerated params) +
  check-coverage bed.
• Verification gate: full gofmt/go build/go vet/go test ./... +
  charly box validate green at head 839f524; run-command + flow +
  reference + resume + prompt-preflight executed live (transcripts above).
• Attribution tier: analysed on a live system — the changed runtime path ran
  live with retained output, but several changed paths (open-terminal,
  close-terminal, boot-order, the luks success path, sudo) have unit coverage
  only.

Assisted-by: opencode ollama-cloud/deepseek-v4.1-flash (analysed on a live system)

[github-actions]

Review — BLOCK

Head SHA: dbffa600e80a80a10ee6bac2004e5fe63bb8c0e5 (branch: feat/jetkvm-console-session-v2)
Change class: feature (new verbs + CUE schema + regenerated params) + check-coverage bed.

Blocks

1. A1 / T3 — body makes a false claim about a diff item (sdk version). The Summary states the PR requires
   github.com/opencharly/sdk v0.2026269.700 ("which this PR requires"), but the diff's
   candy/plugin-jetkvm/go.mod pins github.com/opencharly/sdk v0.2026269.1433 (and spec v0.2026269.212),
   and the body's own How tested / Shipped bed GREEN text says "against sdk v0.2026269.1433". The summary
   is stale and contradicts both the diff and the rest of the body. Fix: state the version actually required
   (v0.2026269.1433), or explain the .700 reference. A description↔code mismatch is a BLOCK.

2. A1 / R1 — body contradicts itself on whether the required coverage bed passed. The Live section says of
   the shipped bed jetkvm-console-session: "its live run on the physical console was blocked by the target's
   display-blanking (DPMS/ATX not wired), so it is not pasted as green here." The very next paragraph pastes
   the same bed as "Shipped bed GREEN live … 2 steps: 2 passed, 0 failed, 0 skipped". The two statements cannot
   both be current. (The display-blanking line is also an environmental-dismissal framing, which the rulebook
   forbids as a reason a gate did not run.) Fix: delete/reconcile the stale "not pasted as green" claim so the
   body states one coherent result for the bed that is the check-coverage for the new surface.

3. R1 / R5 — stale/misleading doc comment in candy/plugin-jetkvm/session.go. The doc comment attached to
   sessionBootOrder opens with // runBootOrder decodes boot-order into the shared action. — a leftover
   comment for a different function, merged onto sessionBootOrder. A comment that describes the wrong function
   is a divergence from reality and should be swept in the same commit. Fix: remove the runBootOrder line.

4. R1 — test comment diverges from the code it pins. session_test.go TestSessionBootOrder_Decodes claims
   it pins "the schema-enum type conversion", but sessionBootOrder does string(in.BootOrderAction) where
   BootOrderAction is generated as a plain string (inline union → string, not a named enum type as with
   Action JetkvmAction) — i.e. a no-op conversion, not an enum conversion. Fix the comment (or the field type)
   so it matches the generated shape.

Notes (not the basis of the block): the shipped bed in charly.yml (jkcs-run-command, jkcs-flow) is
internally consistent with the pasted green output and with the diff's run-command/flow params; the
architecture placement (capability in the plugin-jetkvm candy = transport + CUE→Go decode, shared mechanism
in sdk/kit) is CORRECT; no security-screen finding (no secrets/egress/guardrail weakening in the diff).
The body honestly limits its tier to analysed on a live system for the unit-only paths (open-terminal,
close-terminal, luks success, boot-order dispatch, sudo), which is not inflated.

Verdict: BLOCK

---

ollama-cloud/deepseek-v4.1-flash — action-review.

View action run

[github-actions]

Review — PASS

Head SHA: ca614d1b64dd66605452917ef4791d98840c9ee4 (branch: feat/jetkvm-console-session-v2)
Change class: feature (new console verbs + CUE schema + regenerated params) + check-coverage bed.

Security screen: PASS — no added secrets, no egress/new endpoints, no guardrail weakening. The new verbs are classified mutating (pinned by TestSessionMethodsAreMutating) and gated behind allow_control; the secret literals are documented as preferring the credential store, and provider.go resolves *_secret over the reverse channel exactly like the device password (no exfiltration).

Checklist: All applicable rules PASS or NA.

• A1/A2/A3 — body accounts for every diff item, names the gate + disposable target + host-build + pasted bed output, and honestly caps the tier at analysed on a live system (not inflated: open-terminal/close-terminal/luks-success/boot-order/sudo are declared unit-only). Footer is the required italic *Assisted-by: opencharly-harness model (tier)* form.
• SDD (B13) — schema/jetkvm.cue and params/cue_types_gen.go change together; every new field, the named #JetkvmAction enum, and the #JetkvmSessionCommand/#JetkvmFlowNode/#JetkvmFlowOutcome defs map 1:1 to the generated structs/tags. No @go(-), no hand-written schema-shaped types.
• B4–B12 — R0 skills, R1 (no surviving warning; the "refused" line is intended preflight behavior, not a failure), R2/R3 (one shared implementation in sdk/kit; plugin holds only transport + decode), R4 (bounded flow; flowDeadlineMargin is a named, documented budget, not a sleep-retry), R5 additive, R10 bed jetkvm-console-session genuinely exercises the touched dispatch/decode path and matches the pasted output.
• B16 placement: CORRECT — the capability lives in the plugin-jetkvm candy (USB-HID ConsoleTransport + CUE→Go decode); the shared console engine stays in sdk/kit. No core/sdk pull-in, no alias growth.

Comment intake: the single github-actions[bot] comment (head dbffa600e80a) is stale-superseded — all four of its blocks are resolved in the CURRENT state:

1. sdk-version mismatch — current body now says sdk v0.2026269.1433, matching go.mod/go.sum.
2. contradictory bed-passed / display-blanking line — absent from the current body; the bed is pasted green.
3. stale sessionBootOrder doc comment — current session.go carries the correct comment.
4. TestSessionBootOrder_Decodes enum-conversion comment — current test comment describes the plain-string shape (commit 839f524).

Verdict: PASS

---

ollama-cloud/deepseek-v4.1-flash — action-review.

View action run