TypeScript control plane

Status: the design below was executed on develop; the Python tree (python/, behave, pytest) is deleted (Kanbus chatticus-f27222). Development runs the TypeScript control plane. Staging and production run Python until the develop to main promotion and the migration runbook in this document. Read the body as the plan the code was built from; where it says "design only" or "on develop today" it describes the state before the cutover. This was the plan for the one hard cutover that moved the Python control plane to TypeScript on Pi.

Related: Pi harness, Messaging, Design challenges, Voice, and SESSION_NAMESPACE.md (design branch claude/session-namespace-design, not on develop; its path namespace is orthogonal and changes nothing here).

Decisions already made (inputs, not up for debate)

• Chatticus moves to TypeScript to align with Pi. No new Python.
• One hard cutover moves everything that remains: auth, identity, organizations, membership, invitations, operator routes, /me, the spend ceiling; channels, messages, turns, the turn stream, voice messages; the worker protocol, the turn deadline, tasks, the capability policy, grants and approvals; the computer (host routes, computer start, the container host worker, snapshots). The Python front door and ControlPlane are then deleted. The waitlist and contact intake is not ported; it moves to a private repo.
• The Pi session (pi-durable, one per bot per channel) is the only transcript. Chatticus is the UI for Pi.
• Gherkin stays the spec and runs under cucumber-js with TypeScript steps.
• No parallel implementations, no backward compatibility, no fallbacks.
• Serverless rules stand: no sockets, the stream is scoped to one turn, no relational database, no load balancer.
• The web /api contract is preserved. Every deliberate change is listed in section 0.3.

0. Summary

0.1 The shape in six sentences

1. One Node 22 arm64 FrontDoor Lambda (Hono, response streaming on a Function URL) serves every HTTP route, including the one-turn SSE stream.
2. One TurnExecutor Lambda (SQS-triggered) is the Pi owner for exactly one turn at a time: it claims the turn, takes the storage fence, opens the bot's Pi session, runs, and closes.
3. A TurnProbe Lambda (SQS delay queue) replaces EventBridge Scheduler deadlines and drives recovery; a ComputerStarter Lambda starts the computer host.
4. Conversation content lives only in Pi sessions (S3 commit objects plus a DynamoDB index, the conversation/ storage already on develop). Everything that a non-owner must write while no owner is live (turn control record, mailbox, events, organizations, policy, computer actions) is plain DynamoDB in the existing Messaging table layout.
5. The computer container runs a Node host worker that executes tool actions only. It never opens a Pi session. A parked computer tool is a durable action record; the host fills in its result over a nine-route HTTP protocol, and a normal executor resumes the Pi session.
6. About 40 small tickets, built dormant on develop, then one flip PR.

0.2 What is on develop today and is reused

• conversation/src/storage/ : the production IndexedStorage (S3 commit objects plus a DynamoDB LSI index), table-definition.ts, and the fence methods. 23 of 23 storage conformance cases pass in CI against moto (PI_HARNESS.md).
• conversation/src/budget/ : the budget rollup and alert recorder Lambdas' code and the vendor-ledger and rollup item codecs.
• conversation/features-support/ : the cucumber-js foundation (world.ts, hooks.ts, a moto-backed table) and features/cucumber-features.txt, the manifest that excludes ported features from behave.
• Reference only, not on develop: commit 50efa62c (prototype turn runner, Pi worker, SQS handler). Its good ideas are kept (per-turn requestId, section() system prompt, error classification); its channel sync through the front door is dropped because it made the front door a second transcript.

0.3 Web contract changes (every one is deliberate)

Unchanged on purpose: paths under /api/orgs/{tenant}, /api/me, /api/organizations, /api/health; SSE frames event:/id:/data: with integer seq per turn and Last-Event-ID; terminal kinds turn.completed|turn.failed|turn.reconciling; 404 for no active or latest turn; {messages:[]} with integer seq; Idempotency-Key on bots, channels and voice messages (and accepted on message posts); {detail} error bodies and the status mapping in _status_for_error.

1. Runtime layout

1.1 Lambdas

Not Lambdas: no computer work runs on Lambda (a Lambda cannot hold a browser, a display or a session-lifetime connection). The Node host worker runs in the computer container (section 4).

1.2 Framework

Hono with hono/aws-lambda streamHandle and hono/streaming streamSSE, validated bodies with zod. Reasons: it is ESM-native (Pi is ESM only), tiny to bundle (the whole Pi owner path is already 0.7 to 2 MB bundled), runs Lambda streaming without the Web Adapter layer, and its app.request() lets cucumber-js drive the real routes in-process with no sockets. Bundling is esbuild through CDK NodejsFunction (format: esm, target: node22, the createRequire banner from the Pi spike).

The Lambda Web Adapter layer, run.sh, Docker pip bundling and the SseSpike stack are deleted.

Prototype needed (ticket 5): streamHandle plus streamSSE through a Function URL and CloudFront with a 15 s heartbeat comment and abort on client disconnect. The Python SSE worked through exactly this path, so the risk is the Hono adapter, not the platform.

1.3 Inline versus queued turn execution

Queued. Inline execution would tie the turn to the POST or the stream invocation; closing the laptop, a CloudFront timeout or a 900 s stream end would then orphan work. SQS gives retry, a visibility timeout and a DLQ for free, and SQS is explicitly for turn jobs (AGENTS.md). Cost of queueing: about 100 ms to first claim, invisible next to the model call.

A turn longer than a Lambda: the executor watches context.getRemainingTimeInMillis(); under 30 s it yields (closes the harness without aborting, releases the claim, re-enqueues itself). The next owner resumes the same Pi session. This is the same mechanism as a crash recovery and as the computer handoff, so there is one resume path.

1.4 Queues

EventBridge Scheduler (per-turn one-shot schedules, the schedule group, its role and PassRole) is removed from the turn path. Deadlines are SQS delay messages. Reason: Python created, updated and deleted a schedule on every lease renewal; a self-checking delayed message removes all of that and removes a class of IAM. EventBridge Scheduler stays for the budget rollup cron.

2. Data model

2.1 The split, stated once

Pi holds what was said and done. DynamoDB holds who is allowed, what is running, and what is waiting.

2.2 Why the turn control record is not in Pi

The record must be written by processes that are not the Pi owner and while no owner is live: the FrontDoor creates it when a message is posted, the TurnProbe reassigns it when an owner dies, the host result route un-parks it. Pi allows exactly one writer per storage (fenced). Putting the record in a Pi document would force every one of those writers to claim a fence first, which is the owner-free-admission path PI_HARNESS.md left open. A conditional DynamoDB item is the right tool for compare-and-set control state. It carries no message text, so it is not a second transcript. The final answer text exists once, in the Pi session.

2.3 Tables and buckets

New or changed items in Messaging (all keys carry the tenant):

Dropped at cutover (stay in place for 14 days as rollback insurance, then purged by the follow-up to ticket 40): message items msg#, old-shape turn items, chunk items, the Python-shape event items. Not read, not written, not migrated: WAITLIST, CONTACT items.

2.4 Channels, bots and sessions

• A channel is metadata plus the participant list. Participants are humans (one or more) and bots. There is no thread object.
• A session is one Pi storage per (tenant, bot, channel): storageId = "<tenant>#<bot>#<channel>", root conversation only. A direct channel has one session. A named channel with three bots has three sessions.
• Every bot on a channel reads the channel; only the addressed bot acts. In Pi terms: every committed channel message reaches every participating bot's session; only the addressed bot's session gets a model run.
  • the addressed bot's session receives it as an input submission;
  • every other bot's session receives it as a write entry (a user-role entry attributed to its author, no model call).
• A bot's own reply is an assistant entry in its own session. At finalization it is mirrored to the other bots' mailboxes as an attributed message.
• Bot memory stays on the bot item and is rendered into each model call as a Pi section() (live, not stored in the transcript), exactly the prototype's buildSystemPrompt.

The per-session channel log. Each session carries one Pi conversation document, chatticus.channel-log (scope conversation, history latest), whose value is an ordered list of {seq, messageId, authorKind, authorId, addressedToBotId, createdAt, entryId}. It holds metadata and a pointer to the Pi entry that holds the body; it never holds message text. It is updated in the same commit as the entry where the commit is ours (write entries), and by an idempotent reconcile at owner open where Pi commits the entry internally (input submissions). This is the cheap, ordered index the message list needs; scanning raw entries would read an S3 object per tool result.

Prototype needed (ticket 15): confirm the document, the write entry draft shape and an idempotent reconcile alongside submit({type:"input"}); confirm a read-only createSession(storage) can read the document and entries while another owner holds the fence. Fallback if a read-only session is not safe: the executor publishes the log to a plain DynamoDB item per commit. Do not adopt the fallback without the prototype failing.

2.5 How a human message enters a session (the mailbox)

Non-owners cannot commit to a Pi storage. So every inbound channel message takes the same single path:

sequenceDiagram
  participant W as Web
  participant FD as FrontDoor
  participant DB as Messaging
  participant SQS as TurnRuns
  participant EX as TurnExecutor
  participant PI as Pi session (addressed bot)

  W->>FD: POST /channels/{id}/messages
  FD->>DB: ADD next_seq (idempotency key checked first)
  FD->>DB: put mailbox item for each bot session
  FD->>DB: put turn control record + active_turn#bot pointer (if addressed and that bot has no active turn)
  FD->>SQS: run job; probe job (new turn only)
  FD-->>W: {message, turn_id}
  SQS->>EX: run
  EX->>DB: claim turn (CAS), allocate fence
  EX->>PI: open; drain mailbox in seq order
  Note over EX,PI: addressed message becomes input submission<br/>others become write entries. requestId = msg:{messageId}
  EX->>DB: delete drained mailbox items

• A second post addressed to the SAME bot during that bot's active turn steers. A post addressed to a different bot does not steer: it takes the ordinary path and starts that bot's own turn immediately (its own active_turn#{bot_id} conditional put), so several turns can run on one channel at once, each in its own Pi session. The FrontDoor allocates seq and writes the mailbox item exactly as above, but creates no turn: a TransactWrite puts the mailbox item under a condition that the addressed bot's active turn record (found through active_turn#{bot_id}) is active and not closing, and the response carries the existing turn_id. The owner drains the mailbox while the turn runs (at every tool-round boundary seen on watchEvents and at least every 2 s) and calls submit({type:"input", whenBusy:"steer", requestId:"msg:"+messageId}). Finalize first sets closing on the turn record (conditional on attempt_id), then drains once more; any addressed item found is steered in and the turn keeps running, so no steered message is stranded. A post that loses the race against closing fails the condition and takes the ordinary new-turn path, which waits for that bot's active_turn#{bot_id} pointer to clear and then creates the next turn.
• requestId = "msg:" + messageId makes the drain idempotent (a crash between commit and delete just re-drains to the same submission).
• A session that has no turn keeps its mailbox until its next owner opens it. This is the lazy per-session sync: the first thing every owner does is bring the session up to the channel.
• Mailbox items for the same message are written before the turn record, so a claim can never find a prompt message that is not yet durable.

2.6 Serving GET /channels/{id}/messages with integer seq from Pi

1. Load channel meta (participants).
2. For each participating bot session: read the channel log (document) and list that bot's mailbox. Filter by seq > after before fetching any body.
3. Merge by seq, dedupe by seq (a human message appears in every session; a bot reply is authoritative in its author's session; a mailbox item is authoritative only until it is drained).
4. Fetch bodies from the referenced Pi entries (parallel; commit objects are immutable so the FrontDoor keeps an in-memory LRU keyed by object key).
5. Return {messages:[{message_id, channel_id, tenant_id, seq, author_kind, author_id, body, addressed_to_bot_id, created_at}]}.

seq is allocated once, at the moment a message first exists: by the FrontDoor for human (and API-posted bot) messages, by the executor at turn completion for the bot's reply. The allocator is one atomic ADD on the channel item, so order is total across all sessions and gaps (a failed turn that never allocated) cannot occur. Cost: a long conversation costs one document read plus body fetches per listing. Mitigation is the LRU, the after query parameter (reconnect), and the session snapshot objects of ticket 37 (a prerequisite for staging and production, not for development).

2.7 Migration from the current layout

Tool phases:

1. copy (any time before the flip, repeatable, additive; Python keeps serving): for every channel and every bot participant, claim a fence, replay the old messages in seq order into that session. Human messages become user entries; the session's own bot's messages become assistant entries (a synthetic assistant message: provider openai, model migrated, stopReason stop, zero usage); other bots' messages become attributed user entries. The channel log is written with the original seq, message_id and created_at; the channel's next_seq is untouched. requestId = "migrate:" + messageId; a MIGRATED# marker per (channel, session) lets reruns skip.
2. latest turn per channel is rewritten into the new turn-record shape (status, terminal reason, prompt seq) so reload after the flip still shows a failed turn.
3. flip (the final PR): the new FrontDoor starts in MIGRATING (a state item) and answers every write route with 503 until phase 4 ends.
4. delta then verify: copy messages with seq above the last copied, then verify per channel that the set of seq values and the body hashes equal the old items. Set the state item to OPEN.
5. rollback until day 14: revert the flip commit and redeploy (the Python tree is in git; old items are untouched). After day 14 the purge follow-up of ticket 40 deletes the old items.

The tool is conversation/bin/migrate-transcripts.ts (library in conversation/src/migration/), every command taking --environment {development,staging,production} and optional --tenant and --channel:

• copy (and copy --dry-run, which writes nothing and prints, per channel, the old message count, the bots, and how many assistant and attributed entries would be written). Idempotent: a session that already holds every message is not opened and claims no fence. After the writes each session is read back and compared by checksum with the old items. Each session gets a MIGRATED#<tenant>#<bot>#<channel> marker (messages copied, last seq, checksum, phase, time).
• latest-turns rewrites turn records additively (the key and every old attribute stay, so the old system still reads them), adds prompt_author_id and the answer's message_seq, and writes latest_turn#{bot} and latest_turn_primary pointers (never over a pointer the new system wrote). A turn still active is failed with interrupted_by_transcript_migration only while the write gate is closed; otherwise it is reported and left alone.
• gate close|open|status sets the MIGRATION#write_gate state item. The HTTP application, given a writeGate, answers every non-read route with 503 and a Retry-After while it is MIGRATING.
• delta (gate closed only) copies what was posted since the last copy, converts the turns, then verifies.
• verify compares, per channel, what the new read paths serve (the production listing over the sessions) with the old items: counts, seq order, ids, authors, bodies, addressees, timestamps, and the latest turn's status and reason. Exit code 1 on any difference.

Rollback: no old item is deleted or rewritten destructively. Reverting the flip commit serves the old system again; the MIGRATED# markers, mailbox items and new pointers are inert to it. The purge follow-up removes the old items after day 14.

Pre-flight (a scripted check in the flip PR): no active turns, TurnJobs and ComputerTurnJobs empty, no host start in flight.

3. Turn lifecycle on Pi

3.1 The turn control record

{t}#turn#{id} / meta: turn_id, tenant_id, channel_id, bot_id, status (active|completed|failed|reconciling), prompt_message_seq, attempt_id, attempt (int), claimed_by, lease_expires_at, deadline_at, recovery_attempts, waiting_for, storage_fence, next_event_seq, terminal_reason, message_seq, logical_enqueue_ids. "Waiting" is still active with waiting_for set, as today.

3.2 Claim and fence

The turn's fence is the Pi storage fence, one number per session:

1. Claim (CAS on the turn record): status active, no waiting_for, and (no lease or lease expired); set attempt_id, attempt = attempt + 1, lease_expires_at = now + 60 s, deadline_at. Condition failure means a live owner exists: ack the SQS message and stop. This is the Python claim_turn_attempt CAS, ported.
2. Allocate the Pi fence: UpdateItem on the session's OWNER item, SET fence = if_not_exists(fence, 0) + 1, returning the new value (IndexedStorage.allocateFence, a new static beside claimOwnership). It is done after the CAS so a duplicate delivery can never raise the fence under a live owner. A stale owner is fenced out by this step, which is the desired effect.
3. Record storage_fence on the turn, open IndexedStorage with that fence, Harness.open, run.
4. Renew every 20 s (CAS on attempt_id). A failed renew or an OwnershipLost means this owner is stale: close the harness and return without writing a terminal state (a stale submission.wait() never settles, so the executor must close it itself).

CommitOutcomeUnknown is the one fatal storage error: the executor marks the turn reconciling (3.6) and stops.

3.3 One execution, end to end

flowchart TD
  A[run job] --> B[claim CAS + allocate fence]
  B -->|lost| Z[ack, stop]
  B --> C[open storage + Harness]
  C --> D[drain mailbox into the session]
  D --> E[submit input requestId turn:id]
  E --> F[watchEvents -> coalesce -> turn event items; steer posts drained mid-turn]
  F --> G{settled}
  G -->|done| H[finalize]
  G -->|unanswered model_error| I[fail with member-readable reason]
  G -->|tool parked| J[park: turn.waiting, release claim, close harness]
  G -->|near Lambda timeout| K[yield: release claim, re-enqueue]
  H --> L[alloc seq, channel log, mirror to other mailboxes, turn.completed]

Steering: while the turn runs, the executor also drains mailbox items that arrived after the first drain (section 2.5) and submits each with whenBusy: "steer". The turn's single turn_id, SSE stream and committed reply cover the steered messages too; the reply is one final assistant text (change 3).

runTurn is the prototype's: Harness.open with settings.retry, one root conversation, root.submit({type:"input", content, requestId:"turn:"+turnId}) (a re-run after a crash returns the same submission; no double prompt), await submission.wait. Differences from the prototype: the channel arrives through the mailbox drain (not the front door), and the answer is read from the settled submission instead of re-parsing.

Finalize (one fenced step, idempotent under a conditional update on status = active AND attempt_id = mine): allocate the reply seq, append the channel-log line, write the reply to the other bots' mailboxes, set the turn completed with message_seq, append turn.completed {message_seq, body}, delete the active_turn#{bot_id} pointer (and active_turn_primary if it names this turn), record spend (3.7).

Failure classification keeps the Python mapping (worker/model_provider_errors.py): permanent provider errors (insufficient_quota, 401, 403, 400/404) fail the turn with the readable reason; temporary ones are Pi's retry policy (maxRetries 2) and, past that, an SQS retry. The mapping runs on the settled submission's unanswered reason and detail.

3.4 SSE derived from watchEvents

watchEvents is live-only (a late joiner gets a snapshot, nothing is replayed), and there is no cross-process live watch. So the executor is the one watchEvents consumer, and it writes the result as durable turn event items that the FrontDoor streams. That keeps the invariant (the stream is a view, re-derivable from the store) and keeps integer seq and Last-Event-ID trivially.

Thinking deltas are not forwarded. snapshot, inbox_update and the rest are ignored.

Event writes are TransactWriteItems of [ConditionCheck turn.attempt_id = mine, Put evt#{seq}] (two items), so a stale owner cannot append. The executor owns seq locally; on a resume it starts at the highest existing seq plus one (one Query). Events have a 24 h TTL.

The stream route (FrontDoor): authenticate once at open; load the turn; cursor = Last-Event-ID (a non-numeric value is 400, as today); poll evt# items after the cursor with backoff 50 ms to 1 s; frames event: <kind>\nid: <seq>\ndata: <json>\n\n; : heartbeat comment every 15 s; close after a terminal kind; at 600 s idle with the turn not parked, emit the synthetic turn.reconciling; end before the Lambda limit and let the client reconnect. If Last-Event-ID is past the stored events and the turn is terminal (TTL expired), synthesize the single terminal event from the turn record. The 15-minute stream limit is already covered by the web's reconnect logic (EnabledWorkspace.tsx, four retries with backoff).

A new scenario, features/turn_stream_replay.feature, covers reconnect with Last-Event-ID, because no test covers it today.

3.5 Deadlines and recovery

A probe is an SQS message {tenant_id, turn_id, kind: "deadline", expect_attempt} delayed by the lease or deadline interval.

As built (turn/probes.ts, turn/yield.ts): the probe body is camel case like the run job, {tenantId, turnId, kind, expectAttempt}. The FrontDoor arms the first probe (delay 120 s, attempt 0) before it writes the turn record, the executor arms one at each claim (delay 60 s), recovery and yield arm one for the next claim, and parking arms one that fires every 60 s until the 15 minute waiting limit. A probe for an earlier attempt than the turn is on is dropped while the turn is owned or waiting, but still acts once the lease has run out, so a crash between a claim and its probe cannot strand a turn. A turn that no attempt holds (just recovered, or handed on) is owned until its deadline. When the recovery budget is spent a probe reads the Pi session without owning it (pi/submission-inspector.ts); if the prompt's submission is already done it queues one run that finalizes the turn, otherwise it fails the turn. The executor consumes a run job through consumeRunJob, which acknowledges the message only after executeTurn returns, so a crash before that leaves the message for redelivery. FaultPlan (turn/fault-plan.ts) keeps the Python crash window names and is read by the FrontDoor, the executor and the probe handler.

Default lease 60 s, deadline 120 s, one recovery attempt, as Python. Recovery is a plain resume: the next owner reopens the session; Pi resubmits an interrupted model call, reruns replay: "safe" tools and gives the model an "interrupted" result for unsafe ones (PI_HARNESS.md). That makes the Python "ambiguous provider call" machinery unnecessary.

Ported fault injection (turn_fault_hooks, crash windows) becomes an executor option faults?: FaultPlan so turn_fault_injection.feature and the recovery scenarios keep their steps.

3.6 Voice understanding

POST /channels/{id}/voice-messages is a FrontDoor route, unchanged in contract. The understand-the-user step is a single non-durable model call (gpt-5-nano, minimal reasoning, JSON), not a Pi turn: no session, no fence. Inputs: the transcript plus the ten most recent messages from the message list (2.6, limited to ten after the seq cursor), speaker labelled. Participant checks run before the paid call; replay by Idempotency-Key returns the earlier result with degraded:false; a filler-only line posts nothing; any other empty result posts the heard line (the VOICE.md rules, ported with voice/understanding.py and features/voice_messages.feature). Spend is recorded as a ledger row with turn_id = "voice:<uuid>" exactly as now. The resulting message then takes the ordinary admission path (2.5).

Prototype needed (ticket 22): the pi-ai call shape for a one-shot completion outside a Harness (or, if awkward, the openai package that pi-ai already depends on). The model id and prompt are unchanged.

3.7 Spend recording

Each model call is a keyed cost record (chatticus.cost, key entry-<entryId>) in the Pi session, derived from the assistant entry that answered it and priced from the versioned price book. At conclude, fail, yield, park and when an owner resumes a turn, the executor derives the records not yet written and then writes the turn's ledger row and monthly turn index item as absolute totals summed from those records. A recovered attempt, a takeover or a retry therefore never double-counts and never loses a committed call; there are no delta counters on the turn record. See docs/COST_ACCOUNTING.md section 3.8. Computer-work pausing by spend ceiling is checked when a computer action is created (4.4), as in Python's prepare_computer_tool.

4. The computer

4.1 What moves, what stays

Status: the table below is the computer image and the host worker. The host worker now serves customer-account computers only (section 9, decision 3). Computers in Anthus's own accounts run a Pi owner in the same image instead: the Lambda TurnExecutor runs Pi until the first computer tool call, which creates a ledger action, parks the turn and publishes a start job; the ComputerStarter runs the ChatticusComputerOwner Fargate task; the owner claims the parked turn, runs Pi's own tools locally, calls the model through the control plane gateway, publishes the workspace snapshot when content changed and exits. One owner runs per computer at a time. This is built and rehearsed on development only; staging and production do not run it yet. See Pi session handoff.

A host never fails to boot for a missing optional capability. Model and workspace readiness do not wait on the browser; when Xvfb or Chromium is absent the host reports the browser unavailable. A browse or request_computer_capability call on a computer so marked answers with a fixed message (the browser capability is not available on this computer) before any action is recorded or any host is started.

4.2 Why the host does not run Pi

Status: this section describes the customer-account path, which is unchanged. For computers in Anthus's own accounts, a Pi owner does run in the container (built and rehearsed on development; see Pi session handoff). The host-worker design in sections 4.3 to 4.6 below is the customer-account path; each of those sections opens with a status note saying what the own-account owner does instead.

An organization's computer can live in the customer's AWS account (assume-role, ChatticusOrganizationComputerRole). That account must not hold write access to Chatticus's transcript store. Today the host already reaches the control plane only over HTTP plus its own snapshot bucket. For customer accounts this boundary is kept permanently: the host executes tool actions; the Lambda owner (Chatticus account) is the only Pi writer. The own-account owner puts Pi and session credentials in a container that runs model-chosen shell commands, so it is built to limit the damage: the container holds no model key (calls go through a gateway with a per-turn token), its task role is empty, its storage credentials are scoped to one session, and the shell runs as an unprivileged user with a scrubbed environment.

4.3 Host protocol: 21 routes become 9

Status: these nine routes are the customer-account boundary and stay permanently (section 9, decision 3). Own-account computers do not use them: the owner claims the parked turn directly and runs the tools locally (section 4.4; Pi session handoff).

All under /orgs/{tenant}/host/..., bearer worker token (from POST /orgs/{tenant}/workers/register, invoke-key bootstrap, as today), X-Chatticus-Host-User-Id kept. Zod schemas live in a shared host-protocol/ package imported by both the FrontDoor and the host, so the wire cannot drift.

The reduction is possible because the policy decision moves to where the data is: the executor (Lambda) evaluates the grant, ceiling and approval before it creates the action, and writes the allowed envelope (paths, origins, tool, arguments) into the action item. The host enforces the envelope; only a navigation to an unforeseen origin needs route 8. Regate is evaluated against the same policy kernel the executor used.

4.3.1 Disk dirty tracking, the hydrate guard and the live-writer lock

These are data-loss protection, not readiness, and they live on the computer record (disk_dirty, hydrate_required, live_writer_host_id).

• Dirty. Posting the result of a write_workspace or run_terminal action (route 7, first answer only) sets disk_dirty with an in-place conditional update, so it cannot overwrite a concurrent host-start change. A snapshot publish or a hydrate clears it. relocate refuses while it is set. Reads and browse leave it alone.
• Hydrate guard. While hydrate_required is set, POST /actions/claim refuses (400, ComputerNotHydratedError) to hand out a write_workspace or run_terminal action, so the host never holds a write it must not run. A write now would land on a disk that the intended host is about to replace.
• Live-writer lock (the design was silent; decided minimally). One host holds live_writer_host_id, granted by a conditional update that succeeds only when the field is absent or already that host. A new host start generation (claimHostStartGeneration, which only succeeds once the previous lease expired) removes it in the same update, because the host that held it belongs to the wedged generation. The lock is not tied to action claims: the claim path does not acquire it, so a replacement host cannot be refused because a dead host still holds it. Nothing else clears it.
• Host loss reconciliation. A record can claim a host (disk_dirty set or live_writer_host_id present) after that host died without cleaning up. requestComputerHostStart settles this before it begins a generation. The host is gone when no worker with the computer capability for this computer has a heartbeat inside heartbeatTimeoutSeconds, or none is registered; a host with a fresh heartbeat is never touched. The settle is one conditional update, applied only while host_start_generation is unchanged and the record still claims a host. It marks the computer stopped, clears the readiness gates, disk_dirty and the lock, sets hydrate_required only when a snapshot exists to hydrate from, and records hostLostAt and hostLostGeneration as the audit trail. Computer actions the lost host left in flight are settled by the existing expireLostComputerActions, which runs before the start request.

4.4 The parked-tool handoff (Lambda owner to computer)

Status: on development, for computers in Anthus's own accounts, the parked call is no longer claimed by a host over HTTP. The Lambda still creates the action and parks the turn, but the ComputerStarter runs the owner task and the owner claims the parked turn (takeOverTurn, same session, new fence) and replays the call locally with Pi's own tools. The text below remains accurate for customer-account computers, which keep the host protocol. See Pi session handoff.

The Pi spike parked a tool by closing the owner and relying on crash replay, which left "A parked" indistinguishable from "B crashed mid-execution". Here the ambiguity is removed with an explicit, durable computer action keyed by the Pi tool call id.

Computer tools (read_workspace, write_workspace, run_terminal, browse, request_computer_capability) are registered on every owner with identical schemas and are declared replay: "safe", because their execute is a lookup-or-park and is idempotent by construction:

execute(args, api):
  action = actions.byCall(turn, api.callId)
  if action.done:  return action.result            // the effect already happened on the host
  if no action:    decide(policy, ceiling, approval)
                   denied -> return denial result
                   spend ceiling -> return "computer work paused" result
                   create action(requested, envelope)
  park()           // signals the executor; awaits abort; never completes

On park() the executor: sets waiting_for = gate, appends turn.waiting, enqueues ComputerStartJobs (if the computer's host is not live), releases the claim and closes the harness without aborting. The pi.tool task stays at its execute checkpoint; the generation stays waiting on tools.

sequenceDiagram
  participant EX as TurnExecutor (owner A)
  participant DB as Messaging
  participant CS as ComputerStarter
  participant H as Host worker
  participant FD as FrontDoor
  participant EX2 as TurnExecutor (owner B)

  EX->>DB: create action (requested) + envelope
  EX->>DB: turn waiting_for = workspace; release claim
  EX->>CS: ComputerStartJobs (if no live host)
  CS->>H: ECS run_task / assume-role
  H->>FD: POST /actions/claim
  FD-->>H: action + envelope + lease
  H->>H: execute tool on the live disk
  H->>FD: POST /actions/{id}/result
  FD->>DB: action done; turn active, unclaimed
  FD->>EX2: TurnRuns run job
  EX2->>EX2: claim, new fence, open session
  EX2->>EX2: pi.tool resumes; execute finds result
  EX2->>EX2: generation continues to the answer

Host crash mid-action: the action is claimed with a lease. A probe finds it expired. For tools whose envelope says idempotent (reads, browse GET) the action returns to requested; for the others (write_workspace, run_terminal) it is completed with the error result "interrupted and may have partially run", the same message Pi uses for unsafe replay, and the turn resumes. A computer that never claims an action is probed again (re-enqueue start) until the waiting limit.

As built (domain/actions.ts, domain/computers.ts, domain/computer-start.ts, pi/computer-tools.ts, turn/park.ts, http/routes/computers.ts; verified facts in PI_HARNESS.md): the tool's execute only looks the call up and, when it must park, hands the call to the executor (ComputerToolHandoff.park) and waits to be closed. The executor, not the tool, creates the action (so the crash windows computer_action, computer_park and computer_start are real), parks the turn with releaseForWaiting (the probe armed at the claim keeps watching and re-arms itself until the waiting limit), asks the worker registry for a live host (createTurnJob, assignTurn) and publishes a ComputerStartJob only when there is none (the job carries the computer's policy, so aws_only reaches the starter), and finally re-reads the action in case the host answered first. The spend ceiling is checked in execute before the action exists (refuseIfComputerWorkPaused through computerWorkPauseReason); a paused organization gets the refusal as the tool result and the turn goes on. A probe that finds a parked turn settles its actions first (settleParkedTurn): a claimed action whose lease ran out goes back to requested when it is idempotent and is answered "interrupted" when it is not, an answered action resumes its turn, and an action nobody claimed asks for a host start again. Host routes built here are routes 5 (claim) and 7 (result) of 4.3; the rest, with the zod schemas, are TS-30. The starter (handleComputerStartJob) deletes its message on success, as 4.5 says, so the Python scenarios that assert a job "remains queued" or that the queue Lambda returns a batch item failure are obsolete.

The computer is shared by the whole organization, so actions queue per computer. There is still no stop_computer. Host stop is the existing set_computer_stopped through route 2.

4.5 Computer start

Status: for computers in Anthus's own accounts the starter generates an owner id, mints the model gateway token bound to it, assumes ComputerOwnerScopedRole with session tags (its static policy reads them) and runs the ChatticusComputerOwner task. The ECS host start described below is what customer-account computers still use.

ComputerStarter is the old ComputerWorker Lambda without turn logic: it deduplicates by host_start_generation (the existing lease), assumes the cross-account role when the organization is in its own account, and calls ECS run_task (command override from the infra env). It deletes the SQS message on success and returns an item failure only when it could not start. The host discovers work by claiming actions on boot, so there is no start-to-turn coupling.

A start that fails always settles the parked turn; it is never left to redeliver until the dead-letter queue. The starter classifies every failure. A permanent refusal is one that retrying cannot cure: the organization is not enabled (suspended, pending or gone), has no AWS home, or has a customer-account home without its cross-account role. It fails the parked turn at once with a plain reason and the job is done, so there is exactly one attempt (the refusal is logged as computer_start_refused with a reason_class). The monthly spend ceiling is the third permanent refusal: it answers the turn's open actions with a denial and resumes the turn. Everything else (an ECS RunTask failure, an STS or CloudFormation error, a customer stack still being created, a missing image) is transient: the Lambda reports an item failure and the queue redelivers, but only for COMPUTER_START_MAX_DELIVERIES (3) deliveries, counted from the record's ApproximateReceiveCount. The last delivery fails the parked turn with "could not be started after several tries" and finishes the job (logged as computer_start_gave_up), so the queue's own redrive limit of 5 and its dead-letter queue are only a backstop for a starter that cannot even settle the turn. The person sees the reason as the turn's failure, with the wording in domain/computer-start.ts.

Customer-account provisioning, the CloudFormation template asset (moved into infra/) and the snapshot bucket naming are ported mechanically.

4.6 Host worker internals (Node)

Status: the host worker now serves customer-account computers. The owner program for own-account computers lives beside it in computer/host/src/ (owner.ts, owner-main.ts, owner-deps.ts).

computer/host/src/: main.ts (loop and shutdown: hydrate on boot, run until the deadline, publish before exit), boot.ts (capability readiness gates), protocol-client.ts (the nine routes, fetch), executors/{workspace,terminal,chromium}.ts, browser-profiles.ts, workspace-paths.ts, snapshot/*. ChatticusWorker no longer exists: the loop is "claim, execute, report".

5. Auth

6. Test strategy

6.1 The World

One cucumber-js project (control-plane/, currently conversation/), TypeScript steps, the existing manifest features/cucumber-features.txt. The World (ChatticusWorld, extending what is on develop) is built from ports with exactly one implementation each:

There is deliberately no in-memory store: DynamoDB conditions, transactions and the fence are the behavior under test, and a second implementation would be a parallel implementation. Isolation: each scenario gets a unique tenant_id and storage prefix, so tables are shared and never dropped mid-run (the current per-scenario CreateTable/DeleteTable is replaced).

6.2 Keeping about 500 scenarios fast

• Shared moto and shared tables; unique tenant per scenario; no per-scenario DDL.
• cucumber-js --parallel 4 (workers each get their own moto-backed table pair; the run starts one moto server on a fixed port).
• Tags: @indexed (real fenced IndexedStorage on moto, about 30 ms per Pi commit) for fence, crash, handoff, and storage scenarios; all other scenarios use the same IndexedStorage but a scripted model that commits few entries. Target: p95 scenario under 1.5 s, full suite under 3 minutes on 4 workers, tracked as a CI number from ticket 3. If the target slips, the lever is Pi's MemoryStorage for scenarios that never reopen a session, chosen by tag, not a second store of ours.
• Pure helpers (scoring-style functions, URIs, pack format, keys, error maps) are vitest unit tests, per AGENTS.md; behavior stays in Gherkin.
• Structural gates in vitest: route-principal coverage, route-to-feature spec coverage, ported-features manifest, cucumber-js --dry-run reports zero undefined and zero ambiguous steps for every manifest feature.

6.3 Mapping the existing step texts

Rule: step text does not change unless the behavior changed. A diff in a .feature file is then a review signal.

• Parameters: behave parse placeholders become Cucumber expressions ({string}, {int}, {word}); one custom parameter type ({text}) accepts the unquoted free text some Python steps used. A small converter (ticket 3) prints the Cucumber expression for each Python pattern; humans review the output.

• The Python steps drive an in-process ControlPlane or the HTTP test server. TypeScript steps call world.api (HTTP) for anything that was an HTTP step and world.services (the same functions the routes call) for anything that was a direct plane call. Neither may reach into a store.

• No giant step file. The shared Python files (control_plane_steps 60 features, capability_policy_steps 16, messaging_steps 15, organization_steps 13) are split by the subject of each step, not by feature, into files of at most about 400 lines (a vitest line-count guard):

  TS step file	Subject
  steps/org.steps.ts, steps/membership.steps.ts, steps/invitation.steps.ts, steps/me.steps.ts	organizations, members, invitations, /me
  steps/principal.steps.ts, steps/operator.steps.ts	auth
  steps/channel.steps.ts, steps/message.steps.ts, steps/mailbox.steps.ts	channels, admission, listing
  steps/turn.steps.ts, steps/stream.steps.ts, steps/recovery.steps.ts	turns, SSE, probes
  steps/model.steps.ts	the scripted provider
  steps/policy.steps.ts, steps/grant.steps.ts, steps/approval.steps.ts	capability policy
  steps/task.steps.ts, steps/voice.steps.ts, steps/ledger.steps.ts	tasks, voice, spend
  steps/worker.steps.ts, steps/computer.steps.ts, steps/action.steps.ts, steps/snapshot.steps.ts, steps/host.steps.ts	workers, computer, host
  steps/web-harness.steps.ts	the four existing web/test-support harnesses, now direct imports instead of tsx subprocesses

• The web harnesses that drive the API under test (membership-ui-harness.ts) point at the in-process app through a fetch adapter instead of a base URL.

• New features, written first (AGENTS.md): pi_session_ownership.feature (fence, lost owner, yield), channel_mailbox_and_log.feature, turn_stream_replay.feature, turn_probes.feature, computer_action_handoff.feature, host_protocol.feature, transcript_migration.feature.

• Behave is removed from a feature when it lands in the manifest, which is the mechanism already on develop.

7. Cutover mechanics

7.1 Phases

1. Dormant build (tickets 1 to 38): many small PRs, each green on develop. Code lands in control-plane/, host-protocol/, computer/host/. Infra PRs deploy the new resources unrouted: Conversations, PiSessions, the new queues, FrontDoor, executor, probe and starter Lambdas with their own Function URL. CloudFront still points at the Python FrontDoor.
2. Port per feature: when a feature's TypeScript lands, it is added to cucumber-features.txt and its Python steps are deleted in the same PR (the behave exclusion is automatic). Shared step files shrink; the last consumer deletes them.
3. Rehearsal: run the full suite and the black-box acceptance runner against the dormant TypeScript stack deployed in development (real AWS, real Pi table and bucket, real SQS), on the ts Function URL.
4. The flip (ticket 40), one PR: CloudFront /api* origin to the new FrontDoor; producers use the new queues; delete the Python FrontDoor, ComputerWorker, ComputerlessWorker, TurnDeadline, the scheduler group, the Lambda Web Adapter layer, the SseSpike stack, the old queues (after the drained check), python/, behave.ini, the CI python job and the pins; update AGENTS.md "Quality gates", README "What is live today" and CONTRIBUTING_AGENT.md. Run order: development, then staging and production together on the normal develop to main promotion (the CI/CD in AGENTS.md), with the migration phases in 2.7.
5. Purge (follow-up of ticket 40, bin/purge-legacy-items.ts, kind M), 14 days later.

7.2 The risky window and how it is bounded

While a feature is in the manifest, its spec runs only against TypeScript, and production still runs Python. Consequences: Python can regress with no spec watching it; a Gherkin change made in the window is proven only on TypeScript.

Bounds, in order of strength:

1. Time. Every ticket after 5 is ordered so the whole phase is one push, with a target of three weeks of wall clock from the first manifest addition to the flip. A burndown (ported scenarios over total) is posted in Kanbus at each milestone.
2. Python is frozen. Only outage and security hotfixes. A hotfix PR must include its Gherkin scenario in the .feature file; since the TypeScript side will run that scenario red until it implements the same change, the PR also fixes the TypeScript, and the Python change is verified by the black-box acceptance runner on the real development stack. One hotfix changes both code bases in the same PR, so they cannot diverge.
3. A spec that never goes dark. Ticket 4 ports the black-box acceptance runner (integration_test/) to TypeScript first. It speaks only HTTP, so it exercises Python in production today and TypeScript at the flip. It covers the smoke path: sign in, create bot, channel, post, stream, reload.
4. Rehearsal on the real stack (7.1 step 3) before any production change, because no in-process test exercises CloudFront, a Function URL, SQS or Lambda (AGENTS.md).
5. Reversibility. The flip PR reverts cleanly; old items are retained 14 days; the dormant stack is the same code that was tested.

Accepted risk: a latent Python behavior difference that no scenario encoded and that the TypeScript port silently drops. Mitigation is the port rule "mechanical ports keep the Python file's structure and cite its line ranges", and review by a second agent per PR (AGENTS.md "Pull request review").

8. Ticket breakdown

Conventions. M = mechanical port from the named Python files, no design decisions left. P = needs a verified prototype snippet first because a library API is uncertain; the ticket's first commit is a vitest or script that proves the call and is pasted into the ticket as the reference. N = new, fully specified here. Every ticket writes or extends its Gherkin first, then steps, then code. "Features" are the existing features/*.feature that must pass under cucumber-js when the ticket closes; moving them to cucumber-features.txt and deleting their exclusive Python steps is part of the ticket. Paths are under control-plane/src/ unless stated. Any ticket whose Python source is over about 600 lines is split by file as shown.

Phase 0: foundation

Phase 1: auth and organizations

Phase 2: Pi core

Phase 3: policy

Phase 4: workers and the computer

Phase 5: infra, migration, flip

Parallelism: after 3, the groups {6 to 12}, {13 to 23}, {24 to 26} and {28} are independent until ticket 26 joins policy to the executor and ticket 29 joins the computer to it. Ticket 28 (snapshots, a leaf) can start any time after 1.

9. Decisions

The product owner settled every question this design raised. None is open.

1. Second addressed post during an active turn: steer. It is added to the running turn through Pi's whenBusy: "steer". The POST returns the same active turn_id and the turn stream continues (change 1, sections 2.5 and 3.3). The web client sees no error and no new turn. The voice client's per-channel queue is removed in the same cutover (ticket 40).
2. Final text only is accepted for the committed message (change 3).
3. Customer-account computers never get Pi access. The HTTP host protocol (section 4.3) is the permanent boundary.
4. wiki_publish and channel_migration are dropped. They are not in the port plan or the ticket list and are deleted with the Python (ticket 40).
5. 14-day retention of the old Messaging conversation items, then purge (2.7, 7.1).
6. Membership cache stays at 30 s (section 5).
7. Pi experimental risk is accepted. Exact versions are pinned and storage conformance runs in CI.
8. Waitlist items stay untouched in Messaging for the private repo.

Remaining open questions: none.