feat(cli): expose a one-shot Cloud Session activation protocol #1554

Parent umbrella: #1286

Depends on:

• feat(cli): split bundled session state root from injected config root #1338 / feat(cli): split portable session state from host config (#1338) #1349 — explicit state/config roots;
• fix(runtime): identify workspaces by UUID marker instead of fs dev/ino/path #1337 / fix(runtime): identify workspaces by UUID marker #1369 — portable Workspace identity.

Outcome

Expose one machine-readable operational entry point that executes exactly one Cloud Session Activation using explicit state, Workspace, and injected-config roots.

This must extend the nearest existing CLI/runtime bootstrap seam. It must not introduce another agent runtime or reuse the evaluation-oriented headless harness as a parallel product path.

Whether the command is named maka activate or implemented as a strict mode of maka run should be decided from the current command ownership before implementation. The protocol contract, not the spelling, is authoritative.

Input

User content and secrets must not be placed in shell arguments.

Conceptually:

type ActivationRequest = {
  schemaVersion: 1;
  activationId: string;
  cloudSessionId: string;
  stimulus:
    | { type: 'message'; payload: unknown }
    | { type: 'schedule'; payload: unknown }
    | { type: 'system'; payload: unknown };
};

The command accepts:

• an explicit prepared Session state root;
• an explicit Workspace root;
• an explicit injected config root;
• an input JSON file or stdin stream;
• JSONL output;
• bounded timeout and step policy;
• a deterministic permission mode suitable for non-interactive execution.

Output

The output stream must include a versioned start event, bounded runtime events required by the control plane, and exactly one terminal outcome:

type ActivationOutcome =
  | { status: 'completed'; response: unknown }
  | {
      status: 'blocked';
      reason: BlockedReason;
      requiredAction?: RequiredAction;
    }
  | { status: 'retryable_failure'; reason: string }
  | { status: 'fatal_failure'; reason: string };

BlockedReason and RequiredAction must be small, stable, and versioned. Internal RecoveryPlanner phases, cwd fingerprints, and replay taxonomy must not become cloud protocol fields.

Streaming deltas are provisional. This command does not claim that output has been committed by the control plane.

Runtime behavior

• Reuse the existing runtime bootstrap, stores, backend wiring, tools, permissions, and event ledger.
• Return the created or resumed Maka session identity structurally.
• Enable safe-boundary resume by default for the cloud execution mode.
• Map internal terminal states onto the public Activation outcome without exposing internal planner structure.
• Close runtime resources before emitting successful terminal completion.
• Treat malformed input, identity mismatch, unsafe roots, and unsupported schema as bounded fatal failures.
• Keep provider connections and credentials in the injected config root or environment/credential-vault boundary, never in the portable state root.

Acceptance criteria

• One command/mode executes exactly one Activation and then exits.
• State, Workspace, and config roots are explicit and non-overlapping.
• Input arrives through JSON rather than shell arguments.
• Output is versioned JSONL with exactly one terminal outcome.
• Created/resumed Maka session identity is structured, not inferred from text.
• Existing runtime bootstrap and product tools are reused.
• Safe-boundary resume is enabled and exercised.
• completed, blocked, retryable_failure, and fatal_failure mappings are deterministic.
• A stable BlockedReason/RequiredAction schema is defined without exposing RecoveryPlanner internals.
• No output claims commit success; commit authority remains in the Activation coordinator.
• Secrets do not appear in argv, JSONL, fixtures, or logs.
• Tests cover new Session, resumed Session, malformed input, blocked outcome, retryable failure, fatal failure, timeout, and clean shutdown.

Out of scope

• Session Bundle packing or hydration;
• SessionRepository/KV/CAS;
• activation deduplication, leases, or response routing;
• OpenSandbox lifecycle;
• image construction;
• a complete cross-Activation approval-resume workflow;
• Cloud Session fork.