Archive — history, not state. Kept for its reasoning and its evidence; its plan is closed.

Canonical CLI one-shot contract

Decision

The terminal is transport and presentation, not an actor-vocabulary parser. It sends {} for a bare invocation and {type:"cli", args:[text...], cwd, context?} for nonempty argv. The public cli_args.cm adapter lives with CLI-aware actors, maps this envelope through their HELP descriptor, and mutates the received message in place so its hidden reply continuation survives. Typed actor-to-actor protocol messages are unchanged.

Only the literal first argument help requests descriptor rendering. There is no implicit help request, no --help actor alias, no two-second probe, and no terminal-side descriptor packer. Exact JSON is deliberately separate via --request.

--detached (with -d retained as a short spelling) is start-only. It rejects argv rather than pretending to deliver a fire-and-forget request. One-shot reply timeout is fixed at 600 seconds at terminal creation; HELP metadata can no longer alter transport policy.

Presentation and logs

The canonical message has no terminal presentation field. Owned actors now return neutral structured data plus optional lines; the terminal alone chooses human or JSON rendering. Machine shell /logs quiet|off|verbose changes subscriptions without replay. Verbose broadens the subscription but excludes the target root from the broad stream, preventing duplicate target records.

Cost and benefit

The adapter adds one shared boot module and a small call at the front of each CLI-aware receiver. It removes the terminal’s duplicate descriptor parser and all probe timers/requests. The important benefit is semantic: long-running bare programs are no longer killed after two seconds, argv always has one wire shape, actors can be tested without a terminal, and presentation no longer leaks into application protocol.

Required regression coverage

  • bare {} and nonempty canonical-envelope delivery;
  • explicit help, descriptor groups, flags and positional coercion;
  • exact --request JSON and JSON-looking ordinary argv;
  • start-only detached mode and argument rejection;
  • fixed long one-shot transport lifetime;
  • human/JSON/blob rendering from neutral replies;
  • all three machine-shell log modes, no replay and no duplicate verbose log.

Source: plans/archive/perf-2026-07/cli-one-shot.md