Oko
Oko/Docs

Command reference

oko sessions interrupt

Stops the tool call a session's harness is running, so a command that hangs no longer holds an executor still and the message its supervisor typed with `oko sessions send` is read next, and reports what the call left unfinished in the checkouts it worked in.

Invocation#

Command
oko sessions interrupt ID [--defect ID] [--socket PATH]

Inputs and options#

  • ID is an agent session a live process holds, or its broker terminal. A supervised executor requires --defect ID before the call is stopped; use `oko defects record` first.

Output and state effect#

  • A session in a broker terminal: types the harness's own interrupt, Escape, into that terminal; OMP, Claude Code and Codex end the running call as interrupted and read what is typed to them next (how `escape`).
  • A session outside Oko's broker, which cannot be typed into: the processes its harness runs under it whose kernel birth is at or after the call's record are the call's (its shell and language servers, started before, are not), and each is sent SIGTERM, the request to terminate, after its birth is matched again so a reused pid is never signalled (how `signal`, with processes [{pid, command, signalled, failure} or {pid, command, gone}]). The harness answers the call with its command's end and the session goes on.
  • Either way the working directory of each of the call's processes is read while it still runs, and each checkout among them is read for an operation git leaves unfinished when its program is stopped — git's own state files rebase-merge, rebase-apply, MERGE_HEAD, CHERRY_PICK_HEAD, REVERT_HEAD, BISECT_LOG and index.lock (https://git-scm.com/docs/gitrepository-layout). Each one found is under repositories [{checkout, gitDir, operations [{state, operation, finish}], branch, unpushed {commits} or {unread}, defect}]: the branch a rebase names (else HEAD's), the commits it holds that its upstream does not (`git rev-list <branch>@{upstream}..<branch>`), git's commands to finish or abandon it, and the defect recorded against the workshop product whose checkout it is (title “<product> is left mid-<operation> by an agent call that hung and was ended”, outcome `recorded <id>`, or `noted <id>` on the open one, `no product: …` for a checkout the workspace does not hold, `not recorded: <cause>`). A directory or checkout that cannot be read is listed with its cause (directoriesUnread, {checkout, unread}).
  • Prints `{interrupted: {at, session, by, how, terminal | signal, tool, input, since, seconds, shape, norm, processes, directories, directoriesUnread, repositories}}` and retains the stopped call in ~/.oko/interrupts.jsonl; `oko sessions agents` shows the newest one on the session's row as lastInterruption (printed `last interruption at <time> by <who>: …` with a line per process and checkout), and `interruptionFailure` when the file cannot be read. With --defect, Oko also records the observed result or refusal on the defect and raises priority when the same shape needs another intervention.
  • The model policy pass (the one Oko's service runs every minute, and `oko sessions policy run`) settles the call of every session whose running call is stalled — executors, supervisors and sessions with no role alike — and lists each under interrupted: a session in a terminal of Oko's broker is interrupted, and one outside it has its call's processes ended, both as {session, interrupted: {…}} printed `interrupted: <session> at … by …: typed Escape in broker terminal <terminal>` or `…: ended its processes with SIGTERM` with the same process and checkout lines. Only a call outside the broker that started no process of its own, or whose processes still run after an earlier pass's SIGTERM, is put to the operator on his channels as `oko asks ask` puts a question (asked by `oko model policy`, subject `session <id>`, the question naming the shape and why Oko could not end it, the detail its start, seconds, norm, transcript and processes), {session, asked: {ask, new, shape, seconds, norm}}, printed `asked the operator to stop <session> outside Oko's broker, `<shape>`: ask <id>` — a later pass that finds it still stalled delivers the same waiting ask again where it has not landed (`(delivered again)`) instead of asking twice; and one none of it could be done for is {session, refused: <cause>}, printed `neither interrupted nor asked: <session>: <cause>`. The wait watch (`oko sessions waits`) ends an outside call that waits on a terminal or another session the same way before it asks.
  • For example: `oko sessions interrupt EXECUTOR --defect DEFECT`; then `oko sessions send EXECUTOR --text 'take the assigned repair' --defect DEFECT --intervention redirect --submit`. A new assignment uses `--assign` on the send and is visible in `oko defects show DEFECT`. Oko Desktop's Agent sessions offers Interrupt the running call on every session that runs one — outside the broker without the message controls, which cannot be typed there — and shows each row's last interruption with its processes and checkouts. `tests/sessions/hung/outside.rs` hangs a real OMP call outside the broker on an editor-waiting `git rebase -i` in a repository of its own and reads the pass end it and report the rebase.

Refusals and safe exits#

  • Missing ID, unknown flags, a supervised executor without --defect, or a defect that is closed, withdrawn or already repaired refuses before the call is stopped (exit nonzero).
  • “<id> is neither a session a live process holds nor the broker terminal of one; `oko sessions agents` lists them”, “session <id> runs no tool call now (its state is <state>); there is no call to interrupt” or “… there is no call to end” (a model answering or a stopped turn is not a hung call), “session <id> runs outside Oko's broker and the call started no process of its own, so only its harness can end it; stop it in that session's terminal” and “… and its processes <pids> still run after an earlier SIGTERM, so the request to terminate did not end it; …”, a running call that records no start or names a process without a pid, the broker's own answer when the keystroke cannot be typed, and “the call of session <id> was interrupted in terminal <terminal>, but it was not kept: <cause>” or “… was ended with SIGTERM, but it was not kept: <cause>”. All of these exit 1.

CLI reference#