Finalize star-process-port for supervised long-lived external tool actors #53

New issue

Open

opened 2026-09-02 17:26:05 +00:00 by nsaspy · 0 comments

nsaspy commented

2026-09-02 17:26:05 +00:00

Owner

Parent

Epic: #56
Production runtime epic: #47
Related subprocess foundation: #45

Goal

Make star-process-port the final generic external-process lifecycle boundary required by long-lived StarLang actor hosts.

Hackmode needs this for supervised tools such as mitmdump/mitmproxy, browser/CDP helpers, scanners and other provider processes. Application actors should request a typed process capability; they should not own ad-hoc shell/process implementation details.

Required process contract

At minimum:

explicit executable identity and argv list; no shell interpolation by default;
explicit environment allowlist/additions and working directory policy;
stable process instance/generation identity;
spawn/start result with typed failure classification;
readiness contract when an adapter requires it;
bounded stdout/stderr observation with backpressure/truncation policy;
deadline and cancellation;
graceful stop followed by bounded escalation/reap;
exit status/signal classification;
unconditional reap on normal stop, failure, cancellation and runtime shutdown;
provenance describing adapter/executable/version/config identity without secret leakage;
no process object/file descriptor/implementation object in portable StarLang IR.

Actor composition

The expected shape is:

ProcessSupervisor
   |
   +-- ProcessActor(instance)
          |
          `-- star-process-port -> OS process

star-supervisor owns actor restart policy. star-process-port owns OS process lifecycle primitives. Host/provider adapters own application-specific readiness/protocol parsing.

Relationship to #45

#45 may establish the minimum process lifecycle necessary for the SWI-Prolog MQI worker. Reuse and generalize that final primitive; do not create a second process implementation for generic actors.

Mandatory RED-first tests

spawn deterministic fixture process through final port;
argv is passed without shell reinterpretation;
bounded stdout/stderr does not grow without limit;
cancellation terminates and reaps child;
deadline terminates and reaps child;
child exits unexpectedly and returns typed failure;
runtime shutdown reaps an otherwise-live child;
restart creates a new process generation and old handle is stale;
secret environment value is not emitted in normal result/provenance;
no orphan remains after each test.

Use a deterministic local fixture executable/script under test control; tests about actor semantics must still execute through the real final actor runtime per #42 when actor ownership is under assertion.

Non-goals

no arbitrary shell primitive exposed to .star;
no Hackmode-specific provider API;
no process scheduling/cron;
no application-level scan retry policy;
no browser/CDP protocol implementation in this slice.

Definition of done

A service host can represent an external tool as a supervised actor backed by star-process-port, cancel/restart/shutdown it deterministically, and prove no child process/resource leaks without host-specific process runners.

## Parent - Epic: #56 - Production runtime epic: #47 - Related subprocess foundation: #45 ## Goal Make `star-process-port` the final generic external-process lifecycle boundary required by long-lived StarLang actor hosts. Hackmode needs this for supervised tools such as mitmdump/mitmproxy, browser/CDP helpers, scanners and other provider processes. Application actors should request a typed process capability; they should not own ad-hoc shell/process implementation details. ## Required process contract At minimum: - explicit executable identity and argv list; no shell interpolation by default; - explicit environment allowlist/additions and working directory policy; - stable process instance/generation identity; - spawn/start result with typed failure classification; - readiness contract when an adapter requires it; - bounded stdout/stderr observation with backpressure/truncation policy; - deadline and cancellation; - graceful stop followed by bounded escalation/reap; - exit status/signal classification; - unconditional reap on normal stop, failure, cancellation and runtime shutdown; - provenance describing adapter/executable/version/config identity without secret leakage; - no process object/file descriptor/implementation object in portable StarLang IR. ## Actor composition The expected shape is: ```text ProcessSupervisor | +-- ProcessActor(instance) | `-- star-process-port -> OS process ``` `star-supervisor` owns actor restart policy. `star-process-port` owns OS process lifecycle primitives. Host/provider adapters own application-specific readiness/protocol parsing. ## Relationship to #45 #45 may establish the minimum process lifecycle necessary for the SWI-Prolog MQI worker. Reuse and generalize that final primitive; do not create a second process implementation for generic actors. ## Mandatory RED-first tests - spawn deterministic fixture process through final port; - argv is passed without shell reinterpretation; - bounded stdout/stderr does not grow without limit; - cancellation terminates and reaps child; - deadline terminates and reaps child; - child exits unexpectedly and returns typed failure; - runtime shutdown reaps an otherwise-live child; - restart creates a new process generation and old handle is stale; - secret environment value is not emitted in normal result/provenance; - no orphan remains after each test. Use a deterministic local fixture executable/script under test control; tests about actor semantics must still execute through the real final actor runtime per #42 when actor ownership is under assertion. ## Non-goals - no arbitrary shell primitive exposed to `.star`; - no Hackmode-specific provider API; - no process scheduling/cron; - no application-level scan retry policy; - no browser/CDP protocol implementation in this slice. ## Definition of done A service host can represent an external tool as a supervised actor backed by `star-process-port`, cancel/restart/shutdown it deterministically, and prove no child process/resource leaks without host-specific process runners.

nsaspy referenced this issue

2026-09-02 17:26:05 +00:00

EPIC: Hackmode dogfood — service-grade StarLang actor/runtime #55

nsaspy referenced this issue

2026-09-02 17:26:05 +00:00

Browser evidence actor system for bounded screenshot/DOM acquisition #56